企业官网建设流程全解析

Argos REST API 完全参考：快速掌握 Build 两段式上传协议、签名 S3 URL 与并行分片上传

【免费下载链接】argosArgos detects unintended visual changes in your UI, helping teams maintain high product quality as they ship faster.项目地址: https://gitcode.com/gh_mirrors/arg/argos

Argos 是一个开源的 UI 视觉回归测试工具，帮助团队在快速交付的同时及时发现界面中不预期的视觉变化。它的 REST API 采用经典的「两段式上传协议」处理截图：第一次请求创建 Build 并换回签名 S3 URL，第二次请求上传截图并确认完成；API 还支持并行分片上传，把数千张截图拆分到多个 CI 工作节点。本文用最少代码讲透 Argos REST API 的完整调用链路。

🧭 什么是 Argos REST API

Argos REST API 是 CI 脚本、SDK 和自定义上传器与 Argos 服务交互的入口。所有接口都基于 OpenAPI 规范定义，并直接在服务上以 YAML 形式暴露（GET /openapi.yaml），可以直接粘到任何 API 调试工具里查看完整字段说明。

API 提供三种身份认证方式，都通过Authorization: Bearer <token>请求头传递，定义见 security.ts：

🚀 Build 两段式上传协议如何工作

整个 Build 上传流程分为三步，这也是 Argos API 设计文档 apps/backend/src/api/README.md 中描述的核心流程：

第一步：POST /builds 创建 Build 并获取签名上传地址

客户端把截图文件的 SHA-256 摘要（key）和当前 commit、分支信息发给POST /builds，服务端创建 Build，并只为 Argos 尚未持有的文件签发上传目标。响应形如：

{ "build": { "id": "...", "number": 42, "status": "in-progress" }, "screenshots": [ { "key": "<sha256>", "postUrl": "https://...s3...", "fields": { "key": "...", "policy": "..." } } ] }

请求体支持的关键字段（完整 Zod 校验见 createBuild.ts）：

• commit、branch：必填，构建所在的提交与分支；
• screenshots：新式上传，每项包含key（SHA-256）与contentType；
• screenshotKeys：旧式兼容字段，仅传 key 数组；
• parallel+parallelNonce：开启并行分片上传的开关（下文详述）；
• referenceCommit/referenceBranch：指定作为基线的参考提交或分支。

服务端用 Redis 锁 +externalId查重保证同一parallelNonce的重复创建请求是幂等的；若 Build 已定稿则返回409 Conflict。

第二步：把截图直接上传到签名 S3 URL

拿到上传目标后，客户端绕过 Argos 服务、直传对象存储，网络流量不经过 API 服务：

• 新式：把fields中的每个键值对作为表单字段（先于file字段）以multipart/form-dataPOST 到postUrl；
• 旧式：直接 PUT 二进制到putUrl（已标记 deprecated，仅兼容老客户端）。

第三步：PUT /builds/{buildId} 推送截图清单并定稿

上传完成后，客户端调用PUT /builds/{buildId}提交截图清单（每项含key与name测试名）。服务端校验文件确实存在于存储中，然后标记 Build 完成并触发像素比对。该接口对重试是幂等的：重复请求若所有截图都已入库，会直接返回 Build 而不是报错（见 updateBuild.ts）。

手动定稿并行分片：POST /builds/finalize

当某个分片因超时等原因无法正常收尾时，可显式调用POST /builds/finalize并传入parallelNonce，服务端会把该 nonce 下所有并行分片一次性标记为完成，随后开始聚合比对（实现见 finalizeBuilds.ts）。

🔒 签名 S3 URL 详解：postUrl 与 fields 的优势

新式上传使用 AWS 预签名 POST 策略（createPresignedPost），每个策略里嵌入了两条由 S3 在上传时强制执行的 Condition（源码见 createBuild.ts）：

1. content-length-range：请求体大小必须在[1, 50MB]之间——单文件 50MB 上限由存储层直接兜底；
2. eq $Content-Type：上传时必须携带与创建 Build 时声明完全一致的 Content-Type，杜绝"登记为图片、实际传别的东西"的注入风险。

签名有效期为30 分钟，过期后需重新调用POST /builds。相比旧式putUrl，预签名 POST 把大小与类型约束写进了签名本身，即使 URL 泄露也无法被用来上传超大文件或篡改内容类型。

⚡ 并行分片上传：parallelNonce、parallelTotal 与 parallelIndex

单个非并行 Build 最多注册5000 张截图。更大的测试套件请开启并行模式：

并行模式的使用规则（createBuild.ts 与 updateBuild.ts）：

1. 每个 worker 调用POST /builds时必须传parallel: true和唯一的parallelNonce（同一 CI 流水线各 worker 共享该 nonce）；
2. 每个 worker 上传完自己那批截图后调用PUT /builds/{buildId}，并携带：
   • parallelTotal：分片总数（各分片必须一致，否则400）；
   • parallelIndex：当前分片序号；
   • final：该分片是否还有后续请求，默认true；
3. 服务端每收到一个完整分片就把batchCount + 1，当batchCount == parallelTotal时自动定稿整个 Build 并触发比对；
4. 若个别分片丢失或超时，用POST /builds/finalize兜底强制收尾。

单个分片内部若截图过多装不进一个请求，也可以把final设为false连续多次PUT，只在最后一批传final: true。

📋 Argos REST API 端点速查表

⚠️ 常见限制与错误码速览

🗺️ 去哪里看完整规范与源码

• 运行时 OpenAPI 文档：GET /openapi.yaml（路由注册见 index.ts）；
• API 整体设计说明：apps/backend/src/api/README.md；
• Build 创建与签名 URL 签发：createBuild.ts；
• 分片定稿与幂等重试逻辑：updateBuild.ts、finalizeBuilds.ts；
• 认证方案定义：security.ts；
• 独立媒体（图片/视频）上传协议：media.ts。

掌握「创建 Build → 签名上传 → 定稿比对」这条两段式主链路，再加上parallelNonce/parallelTotal/parallelIndex三个并行参数，你就拥有了对接 Argos REST API 所需的全部知识——无论是写 CI 脚本还是自研上传器，都能快速跑通 🎉

【免费下载链接】argosArgos detects unintended visual changes in your UI, helping teams maintain high product quality as they ship faster.项目地址: https://gitcode.com/gh_mirrors/arg/argos