跳到主要内容

跨平台产物、npm 包与 GitHub Release 的发布步骤。面向维护者。

发布与分发

关键事实: 最终交付物是 Go 单二进制,用户无需任何运行时依赖(Node、Python、数据库服务器都不需要)。

我们同时把这个单二进制通过 npm 包二次分发:@cloudomni/omnigate 在 postinstall 阶段按平台拉对应二进制到 node_modules/@cloudomni/omnigate/vendor/,然后 bin shim exec 出去。

即用户面对的是 npm 命令,但底层是 Go 二进制,没有任何 Node 运行时要求(安装期除外)。


1. 交付物形态​

形态说明面向
npm 包 @cloudomni/omnigatepostinstall 从 GitHub Releases 拉匹配的 Go 二进制到 vendor/,bin shim exec99% 的用户,一行命令
GitHub Release tar.gz6 平台 × tar.gz + sha256 校验和不想装 npm / 自动化脚本 / 服务器

不发布的内容:

  • Docker 镜像(用户用 npm 或本地 tar.gz 即可,无需镜像层)
  • go install(npm 包覆盖 Go 用户的安装路径,不需要再独立一个)
  • Homebrew tap(macOS 用户直接 npm i -g)

2. 数据布局(运行期)​

~/.omnigate/ # 用户主目录下集中管理
├── omnigate.db # SQLite
├── omnigate.db-wal / .db-shm # WAL 副产物
├── config.yaml # 启动层配置(自动生成)
└── omnigate.log # 结构化日志
  • 三个路径都可被 --db / --config / --log 覆盖,也接受 ~ 展开
  • 首次运行:目录不存在则自动创建;config.yaml 缺失则用模板初始化
  • 卸载:npm uninstall -g @cloudomni/omnigate + rm -rf ~/.omnigate(可选)
  • 开发模式 ./start.sh 用仓库内 ./data/、./config.yaml、./logs/backend.log,与生产路径隔离

3. 版本策略​

遵循 SemVer 2.0.0,格式 vMAJOR.MINOR.PATCH:

段触发条件
MAJOR不兼容的配置 / 数据 schema 变更,或核心架构重写
MINOR向后兼容的新功能(MCP 网关、新协议适配、新统计维度)
PATCH向后兼容的 bug 修复

预发布标签(可选):

  • v1.1.0-rc.1 / v1.1.0-beta.2 — 预发布,npm 默认不安装(@latest 仍指向上一 stable)
  • v1.1.0 — 正式版

当前版本线: v1.0.0 公开首发(设计定稿、核心功能齐备后的第一个正式版;此后按 SemVer 递增)

3.1 应用内更新对发布产物的依赖​

管理台顶栏的版本区(以及 omnigate update)会自己查询最新版本、下载归档并原地替换可执行文件 (internal/update)。它按约定拼 URL,不读 Release 的 assets 列表,因此下面这些名字一旦改动, 更新功能会静默失效(表现为"校验和文件里没有该文件条目,已拒绝更新"):

依赖约定值出处
归档名omnigate-<ver>-<os>-<arch>.tar.gz(ver 不带 v).goreleaser.yaml archives.name_template + project_name: omnigate
校验和名omnigate_<ver>_checksums.txt,行内格式 <sha256> <文件名>.goreleaser.yaml checksum.name_template
归档内可执行文件根目录下的 omnigate(windows 为 omnigate.exe),不嵌套子目录archives.wrap_in_directory: false
npm 包版本与 GitHub tag 一致(postinstall 按版本号拼下载地址)npm/scripts/postinstall.js

版本比较用 semver:本地构建的 dev 不具备可比性,因此不会显示"有新版本"红点(避免开发期常驻), 但仍可通过 omnigate update 手动安装最新发布版。v1.1.0-rc.1 这类预发布同号时不视为升级目标。


4. 发布流程​

4.1 准备发版​

# 1. 切到 main 分支并拉新
git checkout main && git pull

# 2. 跑一遍测试
go test ./...

# 3. 确认 web 产物是最新的(开发期改动 web 必须重 build)
(cd web && npm ci --no-audit --no-fund && npm run build)

# 4. 检查 git 状态(应该没有 webui/dist 的改动;若有 revert)
git status

4.2 打 tag 触发自动发布​

# 打 tag(annotated tag 携带发版说明)
git tag -a v0.1.0 -m "v0.1.0: initial public release"

# 推 tag,触发 .github/workflows/release.yaml
git push origin v0.1.0

CI 会自动(.github/workflows/release.yaml,三个 job 串行):

  1. test — ubuntu / macOS / Windows 三平台矩阵跑 go vet ./... + go test ./... -count=1,外加 web 端 tsc --noEmit 类型检查(vite build 本身不查类型)
  2. release — goreleaser 交叉编译 6 目标(3 平台 × amd64/arm64)+ 打包 + 生成 changelog,创建 GitHub Release 并上传 tar.gz + sha256 校验和;发布前先跑一次 snapshot dry-run 校验
  3. npm-publish — 把 npm/package.json 版本号同步为 tag 版本后发布到 npm;-rc/-beta 等预发布 tag 发到 @next dist-tag(@latest 保持 stable)。认证走 Trusted Publishing(OIDC),无需任何令牌

前置配置(一次性,npmjs.com 网页操作):

npm 发布不用 secret。取而代之,需在 npmjs.com 上把 GitHub 仓库配置为该包的信任发布方:

  1. 登录 npmjs.com → 包 @cloudomni/omnigate → Settings → Trusted Publisher → 选 GitHub Actions
  2. 填写:Organization or user yunqilee69;Repository OmniGate;Workflow filename release.yaml(仅文件名,大小写敏感);Environment 留空;Allowed actions 勾 npm publish
  3. 保存即生效。之后 release.yaml 的 npm-publish job 凭 workflow 级 id-token: write 权限自动换取短期发布凭证(要求 npm CLI ≥11.5.1 / Node ≥22.14,job 已用 Node 24)

背景:npm 自 2026 年起逐步禁用"绕过 2FA 的令牌"直接发布(2027-01 全面生效),官方推荐的 CI 发布方式即 Trusted Publishing。本包 v0.1.0 即因旧式 Automation 令牌被 registry 拒绝,已于 2026-08 迁移至此方案。

不启用 provenance:npm provenance 只接受 public 源仓。本仓库是 private,publishConfig.provenance: true 会在 PUT 时 422(Unsupported GitHub Actions source repository visibility: "private"),v0.7.0 / v0.7.1 因此失败。发布命令固定 --provenance=false。

顺序约束: goreleaser 必须先完成(把二进制推到 GitHub Releases),npm publish 再跑;否则用户装 npm 包时 postinstall 拉不到对应版本二进制。workflow 里用 needs: release 保证。

仅补发 npm(GitHub Release 已存在,npm 失败时):

# GitHub Actions → release → Run workflow,输入 tag 如 v0.7.1
# 或 API:
# gh workflow run release.yaml -f tag=v0.7.1

该路径跳过 test / goreleaser,只 checkout 指定 tag 后 npm publish --provenance=false。

4.3 验证发布​

# npm 主渠道
npm install -g @cloudomni/omnigate
omnigate --version
omnigate # 看 ~/.omnigate/ 自动生成与否

# 直接下载校验
curl -L https://github.com/yunqilee69/OmniGate/releases/latest/download/omnigate-linux-amd64.tar.gz -o /tmp/og.tar.gz
tar tzf /tmp/og.tar.gz | head
sha256sum -c omnigate_0.1.0_checksums.txt

5. 平台矩阵​

goreleaser 当前覆盖 6 个目标:

OSArch备注
Linuxamd64主力 x86 服务器
Linuxarm64Apple Silicon Linux 服务器、ARM 嵌入式
macOSamd64Intel Mac
macOSarm64Apple Silicon
Windowsamd64x86 工作站
Windowsarm64Windows on ARM

未来按需追加:FreeBSD amd64、Linux 386。


6. 工具链​

工具用途
goreleaser交叉编译、打包、生成 changelog、创建 GitHub Release
GitHub ActionsCI/CD(tag 触发 release workflow)
npm registry@cloudomni/omnigate 包发布
Node ≥ 18仅在安装 npm 包时需要,运行期不需要

不依赖:CGO、Docker、Go 工具链(终端用户)、goproxy.io 镜像、独立前端 CDN。


7. 发布配置落点​

文件作用
.goreleaser.yaml构建矩阵、打包格式、Release notes 模板
.github/workflows/release.yamltag push 触发:全面测试 → goreleaser → npm publish;workflow_dispatch 补发 npm
npm/npm 包源(package.json / bin / postinstall)
docs/RELEASE.md本文件,流程说明

测试保护:tag 发版的 test job 已经是三平台矩阵跑 go vet + go test,外加 web tsc --noEmit。 如需在普通 PR/push 上也跑同样检查,可参照 §8 加一个 ci.yaml,两者互不影响。


8. 可选补充的 CI(未提交,可按需开启)​

ci.yaml —— 每个 PR 自动跑 go test + go vet + go build,防止主分支 broken (tag 发版流程本身已含同样的检查,这里补的是日常提交路径):

name: ci
on:
pull_request:
branches: [main]
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
cache: true
- run: go vet ./...
- run: go test ./... -count=1
- run: go build ./cmd/omnigate

加上前确保 .github/workflows/ 目录已建。


9. FAQ​

Q: 为什么不发 Docker 镜像? A: 项目定位是"本地工具 + 单一可执行文件",Docker 反而多一层间接(npm 或 tar.gz 解压一行就跑)。如果将来需要 Kubernetes 化,再讨论加 distroless 镜像。

Q: npm 包体积多大? A: 包本体仅 ~10 KB(只含 Node shim + postinstall 脚本 + README)。真正的 Go 二进制在用户安装时从 GitHub Releases 下载到 node_modules/@cloudomni/omnigate/vendor/,约 34 MB。所以 npm i -g 体感是"瞬间装好",但首次 omnigate 启动前会触发一次下载(几十秒,看网速)。

Q: 用户升级怎么处理? A:

  • npm 路径:npm update -g @cloudomni/omnigate 会触发 postinstall 下载新版二进制覆盖 vendor/,~/.omnigate/ 数据目录不动,SQLite 由 GORM 自动迁移。
  • tar.gz 路径:下载新版 tar.gz 解压,替换旧二进制;~/.omnigate/ 同样不动。

Q: macOS Apple Silicon 用户会遇到签名问题吗? A: 我们用 CGO_ENABLED=0 静态编译,二进制天然通过 xcrun Gatekeeper 的"未签名"提示(首次运行需右键打开或 xattr -d com.apple.quarantine /path/to/omnigate)。如有大量反馈再加正式签名。