# Files 文件服务

Files 是 OPS 的公共文件服务，统一管理文件元数据，并通过阿里云 OSS 预签名地址让调用方直传文件。调用方只选择已配置的命名空间，不能指定 OSS 厂商、Bucket 或对象路径。

当前仅支持阿里云 OSS。服务不在本地保存文件，已完成上传的文件持续保留，临时文件由调用方在使用结束后主动删除；只有超时且未完成的上传会被后台任务自动清理。

## 主要能力

- 生成 OSS 预签名 PUT 地址，文件不经过 Files 服务中转。
- 校验命名空间、扩展名、文件大小和上传后的对象大小。
- 记录文件归属、状态、对象路径、ETag 和公开访问地址。
- 支持 JWT 用户调用和内部服务调用，二者数据相互隔离。
- 支持查询与删除本人或本服务创建的文件。
- 自动清理超过预签名有效期但未完成的上传。

## 运行依赖

- Go 1.25.1
- PostgreSQL
- Redis
- 阿里云 OSS Bucket

## 配置

配置文件位于 `etc`：

```text
etc/files_dev.yaml
etc/files_test.yaml
etc/files_prod.yaml
```

运行环境由 `BSM_RuntimeMode` 决定，默认值为 `dev`。服务读取 `${BSM_Prefix}/etc/files_<mode>.yaml`；开发模式未设置 `BSM_Prefix` 时，使用当前工作目录。

核心配置示例：

```yaml
ServiceClients:
  assets: <assets 调用密钥>
  dc-control: <dc-control 调用密钥>
  visual: <visual 调用密钥>

ObjectStorage:
  Provider: aliyun
  Endpoint: https://oss-cn-beijing.aliyuncs.com
  Region: cn-beijing
  Bucket: ops-app
  PublicBaseURL: https://ops-app.oss-cn-beijing.aliyuncs.com
  AccessKeyID: ${FILES_OSS_ACCESS_KEY_ID}
  AccessKeySecret: ${FILES_OSS_ACCESS_KEY_SECRET}
  PresignTTLSeconds: 600

Namespaces:
  reports:
    Prefix: reports
    MaxSizeMB: 512
    AllowedExtensions: [.csv, .xlsx, .json, .pdf, .zip]

Cleanup:
  IntervalSeconds: 600
```

配置说明：

- `ServiceClients`：允许调用内部接口的服务名和密钥，服务名必须与请求头 `Service-Name` 完全一致。
- `Provider`：当前只能填写 `aliyun`。
- `Endpoint`：OSS SDK 请求地址，不包含 Bucket 名称。
- `PublicBaseURL`：完成上传后返回给调用方的公开访问地址前缀。
- `PresignTTLSeconds`：上传地址有效期，允许范围为 60～3600 秒。
- `Namespaces`：调用方可使用的命名空间，以及对应的目录、大小和扩展名限制。
- `Cleanup.IntervalSeconds`：扫描并清理超时未完成上传的时间间隔。

OSS 凭证必须通过环境变量提供：

```powershell
$env:FILES_OSS_ACCESS_KEY_ID = '<AccessKey ID>'
$env:FILES_OSS_ACCESS_KEY_SECRET = '<AccessKey Secret>'
```

使用用户接口时，还要保证 Files 与 JWT 签发方使用相同密钥：

```powershell
$env:BSM_JwtSecretKey = '<与 JWT 签发方一致的密钥>'
```

不要将 AccessKey、数据库密码或生产环境服务密钥写入 README 或提交到代码仓库。

## 本地启动

在 `files` 目录执行：

```powershell
$env:BSM_RuntimeMode = 'dev'
go run ./cmd/main/main.go
```

默认监听配置文件中的 `12452` 端口。启动时会自动创建或更新 `files_object` 表。

如需只执行表结构迁移：

```powershell
go run ./cmd/cli/main.go migrate
```

健康检查：

```text
HEAD /
GET /Files/v1/ping/hello
```

## 构建

构建当前 Windows 环境程序：

```powershell
go build -o build/files.exe ./cmd/main/main.go
```

打包 Linux amd64 程序：

```powershell
powershell -ExecutionPolicy Bypass -File ./scripts/pack.ps1
```

产物为 `build/ops-files`。

## 调用鉴权

文件接口提供两套路径，功能和请求结构相同。

用户接口使用 JWT：

```text
Authorization: <JWT 原始字符串>
```

JWT 直接放入 `Authorization`，不要添加 `Bearer ` 前缀。

内部服务接口使用服务名和独立密钥：

```text
Service-Name: assets
Secret-Key: <与 ServiceClients.assets 一致的值>
```

服务密钥只用于服务之间调用，不是阿里云 AccessKey。调用方不能通过请求选择 OSS 厂商或 Bucket。

## 文件接口

| 操作 | 用户接口 | 内部服务接口 |
| --- | --- | --- |
| 初始化上传 | `POST /Files/v1/uploads/init` | `POST /Files/v1/internal/uploads/init` |
| 确认上传完成 | `POST /Files/v1/uploads/:file_id/complete` | `POST /Files/v1/internal/uploads/:file_id/complete` |
| 查询文件 | `GET /Files/v1/files/:file_id` | `GET /Files/v1/internal/files/:file_id` |
| 删除文件 | `DELETE /Files/v1/files/:file_id` | `DELETE /Files/v1/internal/files/:file_id` |

同一个文件只能由创建它的用户或内部服务访问。用户接口和内部服务接口之间不能交叉访问文件。

### 上传流程

1. 调用初始化接口：

```http
POST /Files/v1/internal/uploads/init
Content-Type: application/json
Service-Name: assets
Secret-Key: <服务密钥>

{
  "namespace": "assets",
  "filename": "example.png",
  "size": 102400,
  "content_type": "image/png"
}
```

成功结果的 `details` 中包含：

```json
{
  "file_id": "文件标识",
  "object_key": "assets/年/月/文件标识.png",
  "upload": {
    "method": "PUT",
    "url": "OSS 预签名地址",
    "headers": {
      "接口返回的请求头": "接口返回的值"
    },
    "expires_at": "过期时间"
  }
}
```

2. 使用 `upload.method` 和 `upload.url` 将文件内容直接上传到 OSS，并原样携带 `upload.headers`。此请求不携带 Files 的 JWT、`Service-Name` 或 `Secret-Key`。

3. OSS 上传成功后调用确认接口：

```http
POST /Files/v1/internal/uploads/<file_id>/complete
Service-Name: assets
Secret-Key: <服务密钥>
```

确认接口会检查 OSS 对象是否存在以及实际大小是否与初始化请求一致。成功后返回文件信息，其中 `url` 是公开访问地址。

### 查询和删除

```http
GET /Files/v1/internal/files/<file_id>
DELETE /Files/v1/internal/files/<file_id>
```

删除接口同时删除 OSS 对象和文件元数据。处于 `ready` 状态的临时文件不会自动删除，调用方必须在业务使用结束后主动调用删除接口。

## 响应约定

业务接口使用统一响应结构：

```json
{
  "code": 0,
  "message": "",
  "details": {},
  "timeseq": 0
}
```

- `code = 0` 表示成功。
- 业务错误通常仍返回 HTTP 200，通过非零 `code` 判断失败。
- JWT 或内部服务鉴权失败返回 HTTP 401。

## OSS 前置设置

当前 `PublicBaseURL` 使用 OSS Bucket 公网域名，因此 Bucket 需要设置为“公共读”，不能设置为“公共读写”。如果由浏览器直接上传，还需要给 Bucket 配置 CORS：

```text
来源：实际前端域名
Methods：PUT、GET、HEAD
允许 Headers：*
暴露 Headers：ETag、x-oss-request-id
```

生产环境应使用 RAM 用户的 AccessKey，并只授予目标 Bucket 所需的对象上传、查询和删除权限。