发布流程 / Release Process

August 17, 2026 · View on GitHub

本文件描述 FrpGUI 从版本号到多平台发布的标准流程，确保每次发布可复现、可审计、可签名。

1. 版本号规则（语义化版本）

采用 vMAJOR.MINOR.PATCH：

MAJOR：不兼容的架构/协议变更（如破坏性配置格式变更）。
MINOR：向后兼容的功能新增（如新增代理类型、新增工具页能力）。
PATCH：向后兼容的问题修复（如 bug 修复、依赖安全更新）。

预发布示例：v1.1.0-rc.1。当前主线版本见 README 顶部。

2. 发布前检查清单

# 1) 切换到 dev 并确保与远端同步、工作树干净
git switch dev && git pull --ff-only

# 2) 全部门禁（必须与 CI 一致地全绿）
make ci

# 3) 构建产物 + SBOM + 校验和（本地复核供应链步骤）
make supply-chain        # -> build/linux-amd64/FrpGUI, build/windows-amd64/FrpGUI.exe, sbom.json, checksums.sha256

# 4) 跨平台构建（含 macOS，仅 Mac 主机）
make build-all           # linux + windows
make build-darwin        # macOS（需在 Mac 上跑）

确认 coverage 无显著回退（make coverage 查看薄弱文件）。
确认 profiles/、frpc.toml（根目录示例除外）、logs/、settings.json 等均未误提交（已被 .gitignore 排除）。

3. 打标签与构建产物

# 先在 dev 上合入发布提交，再切到发布提交打 annotated tag
git tag -a v1.1.0 -m "FrpGUI v1.1.0: <一句话亮点>"
git push origin v1.1.0

# 触发 CI 的 release 流程（或手动在 Mac 上构建 darwin 产物后补齐）

建议 tag 为 annotated tag（-a），消息写本次发布要点；CI 的 release/supply-chain 任务应绑定到 tag 事件自动产出制品。

4. 构建产物与校验

平台	产物	说明
Windows	`FrpGUI.exe`	`CGO_ENABLED=0`，`-H windowsgui`，单二进制
Linux	`FrpGUI`	`CGO_ENABLED=0`，单二进制
macOS	`FrpGUI`（.app 或二进制）	`CGO_ENABLED=1`，须 Mac + clang，走 cgo（cocoabackend）

每个产物附带：

sbom.json：CycloneDX 1.5 物料清单（make sbom）。
checksums.sha256：sha256sum 校验和（make supply-chain 生成）。
（可选）签名文件，见下。

5. 签名（占位，待 CI secrets 就绪启用）

真实签名需在仓库/组织级 secrets 配置证书或密钥后启用。流水线（.github / .gitee workflows 的 supply-chain 任务）已预留注释步骤：

Windows — Authenticode：使用代码签名证书对 FrpGUI.exe 签名；建议结合时间戳服务（RFC 3161）避免证书过期后失效。
macOS — 公证（Notarization）：codesign 签名后上传 Apple 公证，拿到票据再 stapler 装订；需 Apple Developer 账号与 notarytool。
Linux — GPG：gpg --detach-sign 生成 .sig，公钥通过项目发布页/密钥服务器分发。

本机（无证书/账号）仅产出未签名制品 + SBOM + 校验和；签名步骤缺省注释掉，避免 CI 失败。

6. 发布与同步

在 GitHub Releases 基于 tag 创建发布，上传三个平台产物 + sbom.json + checksums.sha256 +（如有）签名文件；撰写 Release Notes（按「新增 / 修复 / 已知问题」分组）。
Gitee 同步：国内镜像仓库同步 tag 与 Release 说明，便于国内用户下载。
更新 README 顶部版本号与亮点。
重大安全修复建议同步在 SECURITY.md 致谢披露者，并在 Release Notes 标注 Security 标签。

7. 回滚

发布后发现严重回归：从 dev 反合修复并打 PATCH 标签；必要时在 Release 页面标记「不推荐」并钉选上一稳定版。
不强制删除已发布制品；通过清晰的可选升级提示引导用户。

发布脚本与门禁的唯一命令源是仓库根 Makefile 与 tools/build.go，请勿在文档与 CI 间出现命令漂移。