
server:
  listen: ":8080"
  host: "https://gateway.example.com"

redis:
  addr: "127.0.0.1:6379"
  password: ""
  db: 0

control:
  tokens:
    - "control-token-1"

credentials:
  s3-prod:
    access_key: "your-access-key"
    secret_key: "your-secret-key"

buckets:
  prod-assets:
    bucket: "prod-assets"
    region: "ap-guangzhou"
    endpoint: "https://cos.ap-guangzhou.myqcloud.com"
    credential: "s3-prod"
    force_path_style: false

字段说明：

server.listen：服务监听地址
server.host：对外访问地址，用于拼接返回给调用方的完整 URL
control.tokens：管理接口使用的 Bearer Token 列表
credentials：对象存储凭证
buckets：可被业务引用的桶别名。接口里传的是别名，不是原始 bucket 名

2. 启动服务


go run . -config config.yaml

3. 健康检查


curl http://127.0.0.1:8080/healthz


{
  "status": "ok"
}

接口约定

基本说明

管理接口前缀：/token
对象访问接口前缀：/object
/token 下所有接口都需要带 Authorization: Bearer <control-token>
/object 下接口只依赖路径里的临时 token，不需要管理令牌
所有错误响应都是 JSON
响应头会带 X-Request-Id

错误响应格式


{
  "code": "bad_request",
  "message": "invalid JSON body",
  "request_id": "0f4f8f4d-6d59-4df0-8a5c-f8352d2a8f47"
}

管理接口

POST `/token`

创建一个临时访问令牌。

请求头：


Authorization: Bearer control-token-1
Content-Type: application/json

请求体：


{
  "bucket": "prod-assets",
  "key": "videos/demo.mp4",
  "filename": "demo.mp4",
  "method": "GET",
  "expire_at": 1760000000,
  "max_hits": 3,
  "size": -1,
  "callback": "https://example.com/webhook/asset"
}

请求字段：

token：可选，自定义令牌；不传则自动生成
bucket：必填，桶别名
key：必填，对象 key
filename：可选，下载时用于生成 Content-Disposition
method：必填，支持 GET、HEAD、PUT
expire_at：可选，Unix 时间戳秒
max_hits：可选，最大命中次数，-1 表示不限制
size：可选，上传大小限制，单位字节，-1 表示不限制
callback：可选，请求成功后异步回调，必须是 http 或 https

默认值：

expire_at：当前时间后 1800 秒
max_hits：PUT 默认 1，其他默认 -1
size：默认 -1

成功响应：201 Created


{
  "token": "Y2x2b2xJc2hQOENWQ0trdVV6bE81",
  "method": "GET",
  "filename": "demo.mp4",
  "expire_at": 1760000000,
  "url": "https://gateway.example.com/object/Y2x2b2xJc2hQOENWQ0trdVV6bE81"
}

示例：


curl -X POST http://127.0.0.1:8080/token \
  -H 'Authorization: Bearer control-token-1' \
  -H 'Content-Type: application/json' \
  -d '{
    "bucket": "prod-assets",
    "key": "videos/demo.mp4",
    "filename": "demo.mp4",
    "method": "GET"
  }'

GET `/token/:token`

查询令牌详情。

成功响应：200 OK


{
  "token": "Y2x2b2xJc2hQOENWQ0trdVV6bE81",
  "bucket": "prod-assets",
  "key": "videos/demo.mp4",
  "filename": "demo.mp4",
  "method": "GET",
  "expire_at": 1760000000,
  "max_hits": -1,
  "used_hits": 0,
  "size": -1,
  "callback": "https://example.com/webhook/asset",
  "url": "https://gateway.example.com/object/Y2x2b2xJc2hQOENWQ0trdVV6bE81"
}

GET `/token/:token/status`

查询令牌状态，以及对象当前是否已存在。

成功响应：200 OK


{
  "token": "put-token-123",
  "bucket": "prod-assets",
  "key": "uploads/report.pdf",
  "filename": "report.pdf",
  "method": "PUT",
  "expire_at": 1760000000,
  "max_hits": 1,
  "used_hits": 0,
  "size": 10485760,
  "callback": "https://example.com/webhook/asset",
  "url": "https://gateway.example.com/object/put-token-123",
  "status_url": "https://gateway.example.com/token/put-token-123/status",
  "uploaded": true,
  "object_exists": true,
  "object_size": 83214,
  "etag": "6805f2cfc46c0f04559748bb039d69ae"
}

说明：

对象不存在时，uploaded 和 object_exists 会是 false
该接口适合轮询上传是否完成

DELETE `/token/:token`

删除令牌。

成功响应：204 No Content

对象接口

PUT `/object/:token`

使用临时令牌上传对象。

请求体就是文件内容本身，可以直接二进制上传。

示例：


curl -X PUT 'http://127.0.0.1:8080/object/put-token-123' \
  -H 'Content-Type: application/pdf' \
  --data-binary '@/path/to/report.pdf'

成功响应：200 OK


{
  "etag": "6805f2cfc46c0f04559748bb039d69ae",
  "size": 83214
}

说明：

如果 token 配置了 size，超出时返回 413 size_exceeded
PUT token 默认只允许成功上传一次
HEAD /object/:token 可用于探测上传结果，不消耗 PUT token 次数

GET `/object/:token`

使用临时令牌下载对象。

示例：


curl -L 'http://127.0.0.1:8080/object/get-token-123' -o demo.mp4

说明：

会透传对象存储返回的响应头
如果创建 token 时带了 filename，响应会带 Content-Disposition
支持 Range 请求头
成功访问后会累计 used_hits

HEAD `/object/:token`

查询对象元信息，不返回文件内容。

示例：


curl -I 'http://127.0.0.1:8080/object/get-token-123'

典型响应头：


HTTP/1.1 200 OK
Content-Length: 83214
ETag: 6805f2cfc46c0f04559748bb039d69ae
Content-Disposition: attachment; filename="report.pdf"; filename*=UTF-8''report.pdf

说明：

HEAD 不消耗命中次数
GET token 和 PUT token 都允许执行 HEAD

回调

创建 token 时传入 callback 后，GET、HEAD、PUT 成功完成都会异步发送回调。

回调示例：


{
  "event": "asset.access",
  "method": "PUT",
  "status": 200,
  "bucket": "prod-assets",
  "key": "uploads/report.pdf",
  "size": 83214,
  "etag": "6805f2cfc46c0f04559748bb039d69ae",
  "range": "",
  "client_ip": "127.0.0.1",
  "user_agent": "curl/8.7.1",
  "referer": "",
  "request_id": "0f4f8f4d-6d59-4df0-8a5c-f8352d2a8f47",
  "timestamp": 1760000000
}