Mirrors 开发者发布指南
团队权限、项目创建、制品上传、灰度发布、Webhook、更新 API 与安全回滚。
本页目录
开发者中心支持团队项目、公开或私有可见性、浏览器/CI 托管上传、外部 CDN 地址、发布 Token、Webhook 和审计记录。
发布前检查
在创建项目或版本前先明确项目所有者、发布渠道、支持的平台与架构,以及谁有权审批正式发布。开发者中心和 CI 中的私有或付费项目必须使用托管上传;外部 HTTPS CDN 地址只适用于公开免费项目。
- Owner 管理团队成员和令牌,并审批发布、执行回滚。
- Editor 创建项目和发布草稿。
- Viewer 可以读取团队私有项目,没有创建草稿或审批权限。
遵循最小权限:自动化使用独立发布 Token,不使用 Owner 的浏览器会话;人员离开团队后,由 Owner 审核团队权限并撤销相关 Token。发布 Token 绑定一个团队,上传接口按所属团队核对项目,并检查到期和撤销状态。当前没有可依赖的可配置细粒度 scope 校验,不应据此扩大自动化权限。
创建项目和版本
- 在开发者中心选择团队并创建项目;
- 设置公开或私有可见性;需要付费访问时,由管理员另行配置访问模式与商品;
- 创建版本草稿,填写版本号、渠道和发布说明;
- 分别上传各平台和架构的制品;
- 核对文件大小、服务端 SHA-256 和下载名称;
- 由团队 Owner 审批并发布。
版本号应保持一致规则,避免同时出现 v1.2.0 与 1.2.0。发布说明至少包含主要变化、兼容性、升级步骤和已知问题。
CI 托管上传
在开发者中心生成发布 Token 后,将它保存为 CI 的受保护 Secret。托管上传接口是 POST /api/v1/developer/releases/upload,使用 Authorization: Bearer mdp_…,与账户页的 mat_… 更新 Token 分开使用。
官方示例提供 GitHub Actions、GitLab CI,以及 Python、JavaScript、Go 三种上传器。先在自己的构建流程中准备制品,再填写项目、版本和文件路径;示例不会替你构建软件。Python 和 JavaScript 示例支持通过环境变量设置通道、平台、架构和灰度比例;Go 示例使用 stable、any / any、100% 的默认值,需要其他值时先调整示例。
上传器负责提交文件,服务端在托管上传时计算文件大小和 SHA-256,并在 API 响应中返回结果。应核对服务端结果;外部 CDN 地址及其哈希由发布者提供,不能将它们当成平台重新下载验证过的文件。
网页和 CI 上传均先进入 draft,Owner 审批后才进入项目页与更新 API。管理员直接发布属于另一条流程,不应当作 CI 绕过审批的方法。
网页与 CI 托管上传、管理员直接上传均使用独立的随机存储路径。同项目、版本或文件名的重复上传不会覆盖旧文件,跨通道草稿也不会改写已发布文件。完整写入后才登记制品,下载文件名和 SHA-256 保持不变,已有存储路径继续可用。管理员直接上传仍使用本地存储。
重复使用相同项目、版本和通道会把该版本重新设为草稿,可能影响当前可见性。修复版应使用新版本号,避免将“不会覆盖旧文件”误解为“不会改变发布状态”。
灰度发布与回滚
创建草稿时可设置 1–100% 灰度比例。更新客户端应为每台安装生成稳定、随机且不含个人信息的 client_id,检查更新时附带该值;没有 client_id 的客户端只会匹配 100% 发布的版本。
灰度只筛选 GET /api/v1/projects/{slug}/latest 返回的版本,不是项目访问权限,也不阻止有权限用户在项目页直接下载已发布制品。更新接口可传 channel、system(或 os_name)、arch、current 和 client_id;update_available 只判断版本字符串是否不同,客户端需自行处理升级、降级和数据兼容性。
建议先评估测试通道和较小比例,观察下载成功率、更新失败率、崩溃和用户反馈。当前开发者界面在草稿中设置比例,没有已发布版本的调比例入口;需要扩大范围时,先由 Owner 确定发布方案。不要仅因为下载次数增长就扩大灰度。
发现严重问题时由 Owner 执行快速回滚,并确认项目页、Mirrors 下载入口和更新 API 都不再返回问题版本。已经取得的 S3/R2 或边缘节点短期签名地址可能仍可用到有效期结束,已下载的副本也不会被撤回。回滚后保留审计记录,修复版使用新版本号。
私有对象存储
开发者中心和 CI 中的私有或付费制品必须使用托管上传。本地存储和 S3/R2 均先由 Mirrors 检查访问权限;S3/R2 下载通过短期签名 URL 返回文件,不向浏览器提供永久公开对象地址。
新上传在未配置可用对象存储凭据时回退到本地存储;已登记为 S3/R2 的文件不会因此自动转成本地文件,下载时对象存储不可用可能返回 503。
私有项目的访问依据团队成员权限,购买公开商品不会自动授予私有项目成员身份。更新客户端使用账户页的 mat_… Bearer Token,并在请求返回的 Mirrors 机器下载地址时继续携带它;该地址中的短期 token 不代替账户授权。跳转到对象存储时,不要向其他域名转发该 Bearer Token。
此上传策略不会回溯修复已被覆盖的文件。普通上传异常会清理本地临时文件;进程意外退出,或 S3/R2 上传成功后数据库写入失败,仍可能留下未引用对象,应交由平台维护者单独审核。
发布通知边界
公开项目审批后,在配置 Hub 事件密钥时会尝试发送 Hub 通知。私有项目不发送 Hub 广播,因为 Hub 尚无团队成员级通知路由;项目自身已配置的 Webhook 仍会尝试接收签名事件,其中 visibility 与 audience 为 private。通知发送不改变项目访问权限,也不会回溯撤回历史广播。
Webhook 安全清单
- Webhook 使用 HMAC-SHA256,对原始请求体计算摘要,与
x-matchall-signature中的sha256=…值进行安全比较,不要先重新序列化 JSON; - 校验事件类型和事件 ID;事件 ID 采用
release:{项目标识}:{通道}:{版本},请求头x-matchall-event-id应与签名请求体中的id一致; created_at是事件创建时间,当前没有独立的投递时间戳或已提供的防重放时间窗口;以签名和事件 ID 去重为基础,不要把发布时间当成网络到达时间;- 记录事件 ID,让重复事件安全返回成功,并在验证后按自己的项目权限处理私有内容;
- Secret 只保存在密钥管理或 CI Secret 中;
- 日志不得记录签名 Secret、发布 Token 或完整授权头;
- 接收端失败时返回明确状态码。通知重试能力取决于当前部署版本:旧版只尝试一次,支持持久队列的版本最多尝试 8 次,并在重启后恢复未完成任务;重试仍使用同一事件 ID。不要把“已发布”当成“通知已到达”,失败任务仍需维护者检查。
发布失败排查
浏览器上传失败时记录项目、版本、文件大小和时间。CI 失败时先区分 401/403 权限问题、409 状态冲突、413 大小限制和 5xx 服务异常。不要通过无限重试绕过审批或重复创建版本。
发布完成后,从未登录窗口检查公开项目;对私有项目使用普通 Viewer 账户验证授权边界,并下载一次制品核对 SHA-256。