CI 自动发布
在流水线的最后一步把构建产物发布到 relhub。CI 机器上不需要装 relhub,一条 curl 就够;已经有 relhub 可执行文件或在用 Go/C# SDK 的话,也可以用它们。
准备
-
管理员给这个应用签发一个应用专用 token(不要把管理员 token 放进 CI):
relhub token create -name ci-nightdesk -app nightdesk -
把两个值存进 CI 的密钥库:
RELHUB_URL:服务器基础地址,例如https://host/release;RELHUB_TOKEN:上一步输出的rl_…(只显示一次)。
-
确保 CI runner 能访问
RELHUB_URL。如果服务器只在内网 / tailnet 内可达,要用能进这个网络的 self-hosted runner,或者先让 runner 加入网络。
决定 versionCode
versionCode 在同一平台内必须严格递增,被占用过的(包括已撤回的)不能再用。常见做法:
| 平台 | 建议 |
|---|---|
| Android | 必须等于 APK 的 versionCode,从 Gradle 构建里读出来再传给发布步骤 |
桌面(主.次.补丁) |
主×10000 + 次×100 + 补丁,例如 1.6.1 → 10601;relhub publish 省略 -code 时就是这么推导的 |
| 每次提交都发 nightly | CI 的递增构建号,例如 GitHub Actions 的 github.run_number,发到 nightly 渠道 |
用 curl 发布
curl --fail-with-body -sS -X POST "$RELHUB_URL/v1/apps/nightdesk/win-x64/releases" \
-H "Authorization: Bearer $RELHUB_TOKEN" \
-F versionCode=10601 \
-F versionName=1.6.1 \
-F channel=stable \
-F notes="$(cat CHANGELOG.md)" \
-F sha256="$(sha256sum dist/nightdesk.zip | cut -d' ' -f1)" \
-F fileName=nightdesk-1.6.1-win-x64.zip \
-F file=@dist/nightdesk.zip
要点:
file必须是最后一个字段。字段在前,服务端就能在接收安装包之前拒绝过低的 versionCode 或无效的 token。--fail-with-body(curl ≥ 7.76)在失败时输出服务端的{"error":{"code":…,"message":…}},方便在日志里看原因;老版本 curl 用-f也行,只是看不到正文。sha256可选:服务端核对,不一致就拒绝,防止上传过程中出错。notes最长 8192 字节。channel留空(-F channel=)表示只上传、不上线,之后再用 promote 上线;-F force=true把本次版本设为强制更新下限。- 成功返回
201。字段完整列表见 REST API 与 JSON-RPC。
用 relhub publish 发布
relhub 会读环境变量 RELHUB_URL 和 RELHUB_TOKEN:
relhub publish -app nightdesk -platform win-x64 -file dist/nightdesk.zip \
-version 1.6.1 -notes-file CHANGELOG.md
模块名 relhub 没有域名,不能 go install 远程获取。要在 CI 里用它,可以在检出本仓库后 go build -o relhub ./cmd/relhub,或者把预先构建好的二进制放进 runner。
GitHub Actions 示例
推送 v* 标签时构建并发布 Windows 版:
name: release
on:
push:
tags: ['v*']
jobs:
publish:
runs-on: ubuntu-latest # 服务器只在内网可达时换成 self-hosted runner
steps:
- uses: actions/checkout@v4
- name: Build
run: ./build.sh --target win-x64 --out dist/nightdesk.zip # 换成你的构建命令
- name: Compute version
id: ver
run: |
name="${GITHUB_REF_NAME#v}" # v1.6.1 -> 1.6.1
IFS=. read -r major minor patch <<< "$name"
echo "name=$name" >> "$GITHUB_OUTPUT"
echo "code=$((major*10000 + minor*100 + patch))" >> "$GITHUB_OUTPUT"
- name: Publish to relhub
env:
RELHUB_URL: ${{ secrets.RELHUB_URL }}
RELHUB_TOKEN: ${{ secrets.RELHUB_TOKEN }}
run: |
curl --fail-with-body -sS -X POST "$RELHUB_URL/v1/apps/nightdesk/win-x64/releases" \
-H "Authorization: Bearer $RELHUB_TOKEN" \
-F versionCode=${{ steps.ver.outputs.code }} \
-F versionName=${{ steps.ver.outputs.name }} \
-F notes="Release ${{ steps.ver.outputs.name }}" \
-F sha256="$(sha256sum dist/nightdesk.zip | cut -d' ' -f1)" \
-F fileName=nightdesk-${{ steps.ver.outputs.name }}-win-x64.zip \
-F file=@dist/nightdesk.zip
先 beta 后 stable 的流程:CI 发布时加 -F channel=beta,人工验证后再把 stable 指过去(只移动指针,不复制文件):
curl --fail-with-body -sS -X POST "$RELHUB_URL/v1/apps/nightdesk/win-x64/channels/stable" \
-H "Authorization: Bearer $RELHUB_TOKEN" -H 'Content-Type: application/json' \
-d '{"versionCode":10601}'
失败了怎么办
| 错误 | 含义 | 处理 |
|---|---|---|
conflict 409 |
versionCode 没有比已发布的大 | 不要重试。如果是同一个流水线重跑,先查一下这个版本是否已经发布成功:GET /v1/apps/{app}/{platform}/releases/{versionCode} |
unauthorized 401 |
token 缺失、写错或已吊销 | 检查密钥库里的 RELHUB_TOKEN |
forbidden 403 |
token 无权操作这个应用 | 让管理员签发包含这个应用的 token |
too_large 413 |
安装包超过服务端上限(默认 2 GiB) | 缩小产物,或让管理员调大上限 |
unavailable 503、网络错误 |
服务端或反向代理暂时不可用 | 稍后重试;重试后若得到 conflict,按第一行处理 |
所有错误码见 错误码。发布不可修改:发错了就撤回(POST …/releases/{code}/yank),再发一个 versionCode 更高的修复版。