API 文档

面向用户的公共 API

GET/api/public/v1/projects

查询已启用且至少存在可展示 Release 的项目列表。

参数	类型	描述
无

Example Request

GET /api/public/v1/projects

Example Response

{
  "status": "success",
  "message": "查询成功",
  "request_id": "req_...",
  "data": {
    "projects": [
      {"project_id": "example", "display_name": "示例项目", "available": true}
    ]
  }
}

GET/api/public/v1/projects/{project_id}/assets

查询项目资产，返回版本、文件名、架构、可选系统、大小、SHA-256 摘要和可用状态。

参数	类型	描述
project_id	Path	项目标识

Example Request

GET /api/public/v1/projects/example/assets

Example Response

{
  "status": "success",
  "data": {
    "assets": [
      {"asset_id": "asset_123", "file_name": "example.zip", "architecture": "amd64", "system": "win", "available": true}
    ]
  }
}

POST/api/public/v1/api/challenges

为指定资产创建 SHA-256 前导零 PoW 挑战。

参数	类型	描述
asset_id	JSON	要下载的资产标识

Example Request

POST /api/public/v1/api/challenges
{"asset_id":"asset_123"}

Example Response

{
  "status": "success",
  "data": {
    "challenge_id": "challenge_123",
    "algorithm": "sha256",
    "leading_zero_bits": 23,
    "canonical_format": "download.v1:{challenge_id}:{asset_id}:{nonce_seed}:{nonce}"
  }
}

POST/api/public/v1/api/authorizations

提交 PoW 结果并领取短时、单节点绑定的下载授权。

参数	类型	描述
challenge_id	JSON	挑战标识
asset_id	JSON	资产标识
nonce	JSON	满足前导零要求的 nonce

Example Request

POST /api/public/v1/api/authorizations
{"challenge_id":"challenge_123","asset_id":"asset_123","nonce":"456789"}

Example Response

{
  "status": "success",
  "data": {
    "authorization_id": "auth_123",
    "download_url": "https://node.example/downloads/asset_123",
    "expires_at": "2026-05-28T12:05:00Z"
  }
}

GET/api/public/v1/authorizations/{authorization_id}

查询授权状态、过期时间、脱敏节点标识和已入账真实发送字节。

参数	类型	描述
authorization_id	Path	授权标识

Example Request

GET /api/public/v1/authorizations/auth_123

Example Response

{
  "status": "success",
  "data": {
    "authorization_id": "auth_123",
    "state": "issued",
    "bytes_accounting_enabled": true,
    "sent_bytes": 1048576
  }
}

GET/downloads/{asset_id}

下载节点文件服务地址由授权响应的 download_url 决定，支持单段 HTTP Range。

参数	类型	描述
Authorization	Header	`Bearer <download_token>`
Range	Header	可选，例如 `bytes=0-1048575`

Example Request

GET /downloads/asset_123
Authorization: Bearer <download_token>
Range: bytes=0-1048575