发布下载

把 GitHub 仓库 (含私有仓库) 的 Release 附件通过 CZL Connect 的固定地址对外分发。仓库不必公开,也不用为每个应用单独部署下载后端:下载请求由 CZL Connect 换成短时效签名链接后 302 跳转,文件流经国内可访问的加速域名,不经过 CZL Connect 服务器。

适用场景

• 客户端软件的源码在私有仓库,但构建产物需要公开下载
• 官网"下载最新版"按钮需要一个不随版本变化的地址
• 客户端自动更新需要读取最新版本号、更新说明与各平台安装包地址

开通条件

发布下载按应用所有者的套餐开放,发布源数量为账户内所有应用合计:

套餐到期降级到 Lite 后,已配置的下载地址返回 403 source_disabled,配置保留,续费后自动恢复。应用被停用时同样不可下载。

配置发布源

进入应用详情 → "发布下载",点击"添加发布源":

保存时会用令牌实际访问一次仓库,无权访问则无法保存。新建、修改、删除都需要通行密钥确认,并记入操作日志。

访问令牌

推荐使用 GitHub Fine-grained personal access token:

1. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token
2. Repository access 选择 Only select repositories,只勾选需要分发的仓库
3. Permissions → Repository permissions → Contents 设为 Read-only,其它保持 No access
4. 设置合适的有效期;到期前在发布源编辑页填入新令牌即可,留空表示沿用原令牌

令牌加密存储,保存后不再回显,列表只展示末 4 位。令牌失效或失去仓库权限时,发布源卡片会显示错误提示,下载地址返回 503 source_unavailable,更新令牌后恢复。

公开仓库留空令牌即走匿名访问。匿名访问的版本信息查询额度由所有匿名发布源共享且很低,版本信息会缓存更久 (最新版约 5 分钟可见);下载量较大时仍建议填写令牌。

别名

只有别名指向的文件会公开:下载地址、版本清单与下载页都只认别名,未配置别名的构建产物 (调试包、内部工具、更新元数据等) 一律无法下载,也不会出现在任何公开接口中。

别名有两种来源:

Release 附件

每个版本的附件名通常带版本号,例如 myapp-1.2.3-windows-amd64.zip。为附件配置别名后,对外地址固定不变:

匹配规则支持 * (任意字符) 与 ? (单个字符),按附件顺序取第一个命中,规则尽量写精确,避免同时命中多个文件。"预览"按钮会读取最新版本,列出仓库全部附件并标出哪些会公开 (仅你可见),便于核对规则。

仓库文件

有些项目把更新清单作为普通文件提交在仓库分支里 (而不是 Release 附件),例如 CI 每次发版后提交一个签名过的 latest.json。为它配置仓库文件别名:

• /dl/{标识}/latest/update-manifest 读取所配分支 (留空为仓库默认分支) 上的最新内容,约 1 分钟内反映新提交;/dl/{标识}/{tag}/update-manifest 读取该 tag 下的文件
• 内容逐字节原样返回,不做任何改写,客户端用自己的公钥验签不受影响
• .json 按 application/json 返回,.txt / .sig / .sha256 等文本类按纯文本返回,其它类型一律以附件下载
• 仓库文件不计入下载次数 (客户端会频繁轮询清单),也不出现在版本清单与下载页中
• 私有仓库用访问令牌读取;公开仓库匿名读取,内容缓存约 5 分钟

签名清单与下载加速:清单是签名的,CZL Connect 不能也不应改动其中的下载地址。若希望客户端经 CZL Connect 下载安装包,请在 CI 签名之前把下载地址写进清单,例如 downloadUrls 首位放 https://connect.czl.net/dl/{标识}/{tag}/{安装包别名},GitHub 直链留作备用。

下载地址

以下载标识 myapp 为例:

• "最新正式版"与 GitHub 的 latest 语义一致:不含草稿 (draft) 与预发布 (prerelease) 版本
• 发布新版本后,latest 约 1 分钟内指向新版本
• Release 附件别名返回 302,跳转目标是有效期约 5 分钟的签名链接,不要缓存或转存跳转后的地址,每次下载都请求 /dl/...
• 公开端点免登录,按 IP 限速;请求过于频繁返回 429

公开下载页

每个发布源自带一个可直接分享的下载页 https://connect.czl.net/download/{标识},适合没有独立产品页的应用:

• 展示应用名称、图标、简介、官网链接,以及最新正式版的版本号、发布时间与更新说明
• 主按钮下方显示安装包的 SHA-256,点击即可复制,方便用户自行核对
• 自动识别访客的操作系统与架构 (含 Apple Silicon、Windows ARM),主按钮直接下载对应安装包,其它系统的下载入口列在下方
• 只展示别名命中的附件,按别名顺序排列;更新包、签名文件等只给客户端用的附件,可在别名旁点眼睛图标设为"不在下载页显示",其下载地址与版本清单不受影响
• 平台识别依据别名与附件名中的关键词:windows / win / .exe / .msi、mac / macos / darwin / .dmg、linux / .AppImage / .deb、android / .apk 等;架构识别 x64 / amd64、arm64 / aarch64、universal 等。附件命名包含这些关键词即可被正确归类

下载页地址可在应用详情 → "发布下载"的发布源卡片中复制。

版本清单

GET /dl/{标识}/latest.json 返回最新正式版信息,适合客户端自动更新检查:

{
  "tag": "v1.2.3",
  "name": "v1.2.3",
  "notes": "## 更新内容\n- 修复若干问题",
  "prerelease": false,
  "publishedAt": "2026-10-30T08:00:00Z",
  "aliases": {
    "windows-x64": {
      "name": "myapp-1.2.3-windows-amd64.zip",
      "size": 18350080,
      "contentType": "application/zip",
      "sha256": "9f2c1a…(64 位十六进制)",
      "url": "https://connect.czl.net/dl/myapp/v1.2.3/windows-x64"
    }
  }
}

清单里的下载地址一律指向固定版本,避免检查更新与实际下载之间恰好发布新版本导致版本错位。notes 是 Release 正文 (Markdown)。aliases 只包含本版本有命中的别名,清单不列出别名之外的任何附件。

sha256 是 GitHub 为该附件计算的 SHA-256 摘要 (小写十六进制),用于下载后校验文件完整性。GitHub 未提供摘要的早期附件省略该字段,客户端应把"字段缺失"与"校验不通过"区别处理。

自动更新推荐流程

1. 启动时或定时请求 latest.json,用 tag 与本地版本做语义化版本比较
2. 有新版本时展示 notes,用户确认后下载 aliases[当前平台].url (跟随 302 跳转) 到临时文件
3. 校验文件大小 (size) 与 SHA-256 (sha256),任一不符即删除临时文件并提示重试,不要安装校验失败的文件
4. 校验通过后再替换 / 启动安装程序

哈希校验能发现传输中断、缓存或线路导致的文件损坏与篡改;它与下载地址同源,不能替代代码签名 (Windows Authenticode、macOS Developer ID 签名与公证) 对发布者身份的证明。

错误码

错误响应体为 {"error": "<错误码>"}: