API 令牌与 CI 部署

会话 Cookie 适用于浏览器。对于脚本、CLI 工具和 CI 运行器 —— 任何无法携带 Cookie 的场景 —— Pier 会签发 Bearer API 令牌。令牌以创建它的用户身份进行身份验证，并继承该用户的角色，因此 CI 令牌只能部署其所有者能够部署的服务。

令牌以 SHA-256 哈希形式存储；明文在创建时仅显示一次，且永远无法恢复。

创建令牌

从账户区域（或携带会话直接调用 API）：

创建 —— POST /api/v1/account/tokens，附带一个 name。响应中仅会包含一次 token 明文。请立即复制。
列出 —— GET /api/v1/account/tokens。返回每个令牌的 id、name、prefix 和 last_used_at —— 永远不返回密钥本身。
吊销 —— DELETE /api/v1/account/tokens/{id}。幂等操作；吊销在下一个请求时立即生效。

每个签发的令牌都带有 pier_npm_ 前缀，因此泄露的令牌一眼即可辨认。在 Authorization: Bearer 标头中发送它：

Authorization: Bearer pier_npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

像对待密码一样对待令牌。任何持有它的人都会以你的身份行事，权限范围与你的角色相同。请将其存储在 CI 提供商的密钥库中，切勿放在代码仓库里。

从 CI 触发部署

有两个经过身份验证的部署端点接受 Bearer 令牌。两者运行相同的流水线，并返回一个可供轮询的 deployment_id。

端点	适用于 CI 已知……
`POST /api/v1/services/{id}/deploy`	服务的 id
`POST /api/v1/projects/{id}/services/{name}/deploy`	项目 id 和服务名称

授权要求在目标服务上具有项目级 Editor 权限（即令牌所有者的项目角色）。该服务必须已配置好其 git 仓库。两个端点都按客户端 IP 进行速率限制，因为部署是一次开销很大的克隆与构建操作。

JSON 请求体为可选项。有用的字段包括：commit_sha（记录以便追溯）、branch（或其别名 ref）以及 message。如果你省略分支，Pier 会使用服务配置的分支，并回退到 main。

curl -X POST https://pier.example.com/api/v1/projects/proj_abc123/services/web/deploy \
  -H "Authorization: Bearer pier_npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "commit_sha": "'"$GIT_COMMIT"'",
        "branch": "main",
        "message": "CI deploy from pipeline #42"
      }'

成功的响应会返回部署 id 和一个状态 URL：

{
  "ok": true,
  "deployment_id": "d1e2f3...",
  "service_id": "svc_...",
  "status_url": "/api/v1/resources/svc_.../deployments/d1e2f3..."
}

轮询 GET /api/v1/resources/{id}/deployments/{deployment_id}，直到构建到达终止状态，从而让你的流水线等待结果。

API 令牌与 CI 部署

创建令牌

从 CI 触发部署

后续步骤