release-publish

CI 自动发布

在流水线的最后一步把构建产物发布到 relhub。CI 机器上不需要装 relhub,一条 curl 就够;已经有 relhub 可执行文件或在用 Go/C# SDK 的话,也可以用它们。

准备

  1. 管理员给这个应用签发一个应用专用 token(不要把管理员 token 放进 CI):

    relhub token create -name ci-nightdesk -app nightdesk
    
  2. 把两个值存进 CI 的密钥库:

    • RELHUB_URL:服务器基础地址,例如 https://host/release;
    • RELHUB_TOKEN:上一步输出的 rl_…(只显示一次)。
  3. 确保 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 更高的修复版。