OmniRoute 发布检查清单实战指南：从版本号提升、npm 可信发布到回滚的完整发布流程

OmniRoute 发布检查清单实战指南从版本号提升、npm 可信发布到回滚的完整发布流程【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute导读OmniRoute 是一个单端点接入 350 提供方、1200 模型的 MIT 开源 AI 网关当前仓库版本 v3.8.51。本文以仓库 docs/ops/RELEASE_CHECKLIST.md官方发布检查清单为骨架完整梳理每一次给 OmniRoute 打标签、发布版本前必须通过的检查项版本与 Changelog 同步、API 文档一致性、Node.js 运行时支持边界、npm Trusted PublishingOIDC与 staged 发布模式、hotfix 快速通道、质量门禁、数据库迁移、构建布局与回滚策略。读完本文你将能够按清单一步步走完一次从「版本号提升」到「部署与发布证据采集」的完整发布闭环。一、发布流程总览TL;DROmniRoute 的发布流程已被高度自动化核心是围绕 Claude Code 技能skill与本地质量门禁命令组织的六步流程来自 docs/ops/RELEASE_CHECKLIST.md 的 TL;DR 段落# 1. Bump version generate CHANGELOG (skill) /version-bump-cc patch # or minor/major # 2. Run quality gate locally npm run check # lint tests npm run test:coverage # full coverage gate (60/60/60/60) # 3. Build smoke npm run build npm run test:e2e # optional but recommended # 4. Generate release (skill) /generate-release-cc # 5. Deploy (skill) /deploy-vps-both-cc # or akamai-cc / local-cc # 6. Capture release evidences (skill) /capture-release-evidences-cc其中npm run check、npm run test:coverage、npm run build、npm run test:e2e均已在仓库根 package.json 的scripts段中定义例如check: npm run lint npm run test、test:coverage通过 c8 执行--statements 60 --lines 60 --functions 60 --branches 60的 60/60/60/60 覆盖率门禁。除了这个快速路径官方清单还强调一个前置原则保持队列/分支在两次发布之间保持绿色。参见 docs/ops/RELEASE_GREEN.md通过/green-prs系列命令、npm run check:release-green、/babysit与 nightly 任务周期性执行尤其是在执行本清单之前执行一次可以让发布 PR 从一开始就是绿色状态。对应脚本npm run check:release-green指向scripts/quality/validate-release-green.mjs。二、npm 可信发布Trusted PublishingOIDC与 staged 发布模式自 v3.8.51 起npm 发布默认走npm Trusted PublishingOIDC机制这是本清单最重要的发布通道变化npm-publish.yml工作流中的stage-npm任务github-hosted用 GitHub 的 id-token 向 npm 换取单次运行的短期凭证——仓库 secrets 中不再存放长期 npm token无 2FA 提示且发布产物自动附带 provenance出处证明。这既绕过了 npm 对跳过 2FA 令牌的回收策略恢复了项目在 v3.8.48 之前的全自动发布流程又保留了 WS1.3 保证即使令牌泄露也无法单独完成发布——因为根本不存在令牌。一次性配置仅仓库所有者在 npmjs.com → 包omniroute→ Settings → Trusted Publisher 中配置GitHub 所有者diegosouzapw、仓库OmniRoute、工作流npm-publish.ymlenvironment: none。若未配置自动步骤会以ENEEDAUTH失败此时可用publish_modestaged或direct重新触发工作流。Staged 发布按需publish_modestagednpm-publish 工作流不再直接发布它先启动打包产物check:pack-boot然后执行npm stage publish——确切的字节先暂存在 registry 上所有者批准前不可安装。人工 2FA 门禁被移动到「证据之后」而不是之前。所有者流程npm stage list omniroute—— 找到 stage id工作流摘要中也会打印。推荐验证暂存字节npm stage download id把下载的 tarball 装进临时 prefix 并启动。CI 中的npm run check:pack-boot自动完成同样的 pack→install→boot 判定对应脚本 scripts/check/check-pack-boot.mjs。npm stage approve id—— 2FA 提示本身就是发布动作npm stage reject id丢弃。发布后的净额校验v3.8.49 计划的 WS1.4在干净容器中从公共 registry 安装刚发布的版本并启动验证。紧急回退与加固紧急回退workflow_dispatch传publish_modedirect恢复旧式立即npm publish仅在 staging 本身出问题时使用并需记录原因。一次性加固所有者npmjs.com为omniroute配置仅 stage 模式的 Trusted Publisher使泄露的长期 token 也无法从任何位置直接npm publish——CI 只能 stage只有所有者的 2FA 才能放行。损坏产物处理手册与 Dockerlatest语义默认反射npm deprecate omniroutebad reason — use fixed几分钟内可逆npm unpublish仅在 72 小时/无依赖方窗口内使用且绝不作第一选择。Docker绝不重写版本标签回滚即把latest重新指向最后一个好 digest。每次稳定 SemVer 发布docker-publish工作流必须同时打X.Y.Z与:latest当should-promote-latest.sh判定这是最高稳定 SemVer 时且两者同一 digest。发布后 Hub 上latest的 digest 应等于新 SemVer digest 且last_updated已更新。Compose 快速启动用:latestGitOps 应继续固定X.Y.Z。详见 Docker release channels。三、Hotfix 快速通道hotfix标签带hotfix标签的 PR 跳过重型 CI 矩阵9 分片 E2E、覆盖率棘轮、quality-gate、quality-extended只保留快速高信号门禁build、unit 分片、integration、vitest、lint/typecheck、docs-sync、check:pack-artifact与 tarball 启动冒烟check:pack-boot。目标≤15 分钟全绿正常约 33 分钟。入口策略要求同时满足以下四条仿照 Chromium / VS Code / Node 的应急通道严重性生产已损坏——已发布产物启动即崩 / 安全修复 / 所有该版本用户都受影响。「重要」不等于「损坏」。授权只有仓库所有者能打hotfix标签。标签本身就是批准——严禁在 campaign PR 上自行贴标。证据PR 正文需链接上一次完全通过的重型运行被跳过任务本应重新验证的那套以及该修复自身的「先失败后通过」测试。范围仅 cherry-pick——最小修复无重构、无顺带改动。被跳过的覆盖率/棘轮面由发布分支上的下一次完整运行重新验证持续 release-green——快速通道跳过的是等待不是验证。另外纯测试 diff全部在tests/下且不含tests/e2e/无需任何标签即自动跳过 E2E 矩阵。四、详细检查清单逐项执行4.1 Pre-release本版本所有 PR 均已合并到release/vX.Y.0本版本的 Linear/issue 条目均已关闭或推入下一里程碑release/vX.Y.0分支 CI 全绿代码中无TODO(release)标记grep -r TODO(release) src/ open-sse/Docker 基础镜像保持最新当前为node:24.15.0-trixie-slim4.2 版本与 Changelog运行/version-bump-cc patch|minor|majorClaude Code 技能提升package.json与electron/package.json版本基于最近 tag 以来的 git 提交重新生成CHANGELOG.md更新 README 徽章。人工审阅CHANGELOG.md必要时清理提交信息。确保CHANGELOG.md中最新的 semver 小节与package.json版本一致。保持## [Unreleased]为 changelog 第一个小节供后续工作使用。更新docs/openapi.yamlinfo.version必须等于package.json版本。API 契约有变化时验证示例端点。4.3 代码质量门禁命令含义npm run lint0 错误warning 属历史存量npm run typecheck:core干净npm run typecheck:noimplicit:core干净严格 noImplicitnpm run check:cycles无循环依赖npm run check:any-budget:t11预算内npm run check:route-validation:t06干净npm run check:node-runtime支持的运行时下限达标其中check:node-runtime的实现证据在 src/shared/utils/nodeRuntimeSupport.tsSUPPORTED_NODE_RANGE 22.22.2 23 || 24.0.0 27与 package.json 的engines字段node: 22.22.2 23 || 24.0.0 27中两者保持严格一致。注意英文版清单给出的范围是20.20.2 21或22.22.2 23而当前仓库实际代码已经前移为22.22.2 23 || 24.0.0 27支持 22.x LTS、24.x LTS、25.x、26.x以当前仓库源码为准。4.4 测试门禁npm run test:unit通过npm run test:vitest通过MCP server、autoCombo、cachenpm run test:coverage满足 60/60/60/60statements/lines/functions/branchesnpm run test:integration通过涉及 DB / handlers 变更时npm run test:combo:matrix通过——组合策略矩阵确定性验证全部 19 个公开路由策略的选择决策改动 combo 路由、策略解析或 fallback 逻辑时运行RUN_COMBO_LIVE1 npm run test:combo:live——可选/手动受门控的真实上游冒烟读取 VPSroot192.168.0.15的只读 DB 快照命中真实 provider、消耗配额绝不在 CI 运行无门禁时干净跳过npm run test:combo:live:vps——可选/手动Phase-3 VPS 实时冒烟对线上.15服务器跑 7 个 HTTP 场景需ssh root192.168.0.15只创建/删除__live_test__*combosnpm run test:e2e通过UI 变更时npm run test:protocols:e2e通过MCP/A2A 变更时npm run test:ecosystem通过4.5 Husky HooksGit 自动化Husky hooks 位于.husky/目录git 操作时自动运行pre-commitnpx lint-stagednode scripts/check/check-docs-sync.mjsnpm run check:any-budget:t11pre-push快速确定性门禁——npm run check:any-budget:t11 npm run check:tracked-artifacts2026-06-13 启用刻意排除test:unit慢由 CI 的test-unit任务覆盖推送 release 分支前手动运行npm run test:unit。Hook 失败时必须修复底层问题不要用--no-verify绕过。4.6 Conventional Commits 规范所有发布相关提交必须遵循type(scope): subject格式合法 typefeat、fix、refactor、docs、test、chore、perf、style、ci合法 scopedb、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills、cloud-agent、guardrails、compression、auto-combo、resilience、providers、executors、translator、domain、authz破坏性变更添加BREAKING CHANGE:footer或在 scope 后加!例如feat(api)!: drop /v04.7 文档一致性npm run check:docs-sync通过pre-commit 自动运行npm run check:docs-all通过伞形docs-sync docs-counts env-doc-sync deprecated-versions doc-links见 package.json 中定义npm run check:env-doc-sync退出码 0 —— 代码 ↔.env.example↔docs/reference/ENVIRONMENT.md的环境变量契约完好npm run check:doc-links退出码 0 —— 重构后无损坏的内部 markdown 引用docs/architecture/ARCHITECTURE.md 复查 storage/runtime 漂移docs/guides/TROUBLESHOOTING.md 复查环境变量与运维漂移若.env.example变更更新 docs/reference/ENVIRONMENT.md新功能有 UIdocs/guides/USER_GUIDE.md 需提及新功能有 APIdocs/reference/API_REFERENCE.md 与docs/openapi.yaml需更新新功能是模块存在专属docs/MODULE.md破坏性变更docs/guides/TROUBLESHOOTING.md 需有迁移说明4.8 i18n 门禁npm run i18n:check退出码 0 —— 翻译状态.i18n-state.json与源文档同步strict 模式下无漂移源warn 模式可供最后时刻的文档微调但 tag 前应为 0npm run i18n:check-ui-coverage退出码 0 —— 每个 UI locale 均达到 80% 覆盖率下限npm run i18n:sync-ui:dry报告 42 个 locale 中 0 个缺失 key若英文源文档有改动tag 前运行npm run i18n:run需.env中的OMNIROUTE_TRANSLATION_API_KEY次要翻译贡献可推迟到下个版本在 CHANGELOG 中记录4.9 数据库迁移若 src/lib/db/migrations/ 有新文件每个迁移幂等CREATE TABLE IF NOT EXISTS等迁移包裹在事务中编号正确序列无缺口全新安装测试删除~/.omniroute/omniroute.db后运行npm run dev存量安装测试备份 DB → 运行迁移 → 验证 schema迁移重写表时正确处理 WAL 文件-wal、-shm4.10 Provider CatalogZod 校验src/shared/constants/providers.ts 的 Zod schema 在加载时有效所有 provider 具备必填字段id、label、kind等新免费 provider 提供freeNoteOAuth provider 在 src/lib/oauth/constants/oauth.ts 注册oauthConfig新 provider对应 executor 在 open-sse/executors/非 OpenAI 格式translator 在 open-sse/translator/模型注册于 open-sse/config/providerRegistry.tstests/unit/ 中单元测试覆盖 provider 分类与路由4.11 桌面端Electron若electron/有变更npm run electron:smoke:packaged通过至少测试:win、:mac、:linux之一的构建代码签名证书未过期若签名electron/package.json 版本与根 package.json 一致若发到stable频道更新自动更新频道指针4.12 构建布局三目录模型仓库使用三个不同输出目录切勿混淆目录用途是否跟踪src/应用源码TypeScript / TSX是.build/构建中间产物——next build输出distDir否gitignoreddist/可发布的 npm 包——由assembleStandalone组装否gitignored运维提示远程 VPS 镜像目录仍是/usr/lib/node_modules/omniroute/app/只有仓库内构建输出从app/移到了dist/。部署技能用 rsync 把dist/内容同步进远程app/目录——VPS 路径无需改动。单一构建流程禁止先npm run build再单独npm run build:cli部署npm run build:release └─ rm -rf .build dist (clean) └─ next build → .build/next/ (intermediates) └─ assembleStandalone (copies standalone static public natives → dist/) └─ writes dist/BUILD_SHA (HEAD sentinel)npm run build:release在 package.json 中定义为rm -rf .build dist OMNIROUTE_BUILD_SHA$(git rev-parse --short HEAD) npm run build npm run build:cli node scripts/build/write-build-sha.mjs一次命令完成干净重建 sentinel 写入。4.13 产物验证npm run build:release成功且dist/BUILD_SHAgit rev-parse --short HEADnpm run check:pack-artifact干净——无app.__qa_backup、scripts/scratch、package-lock.json或其它本地残留构建后存在dist/server.js4.14 打标签与发布运行/generate-release-ccClaude Code 技能创建 tagvX.Y.Z、推送 tag 与分支、以 changelog 内容打开 GitHub Release、附加 Electron 安装包如已构建或手动git tag -a vX.Y.Z -m Release vX.Y.Z git push origin vX.Y.Z gh release create vX.Y.Z --notes-from-tag4.15 部署部署技能使用轻量 rsync 流程不用npm pack、不用npm i -g选择与目标匹配的部署技能/deploy-vps-local-cc本地 VPS 192.168.0.15、/deploy-vps-akamai-ccAkamai VPS 69.164.221.35、/deploy-vps-both-cc两者部署前确认dist/BUILD_SHAgit rev-parse --short HEAD构建必须在node_modules真实存在的环境中进行主 checkout 或npm ci过的 worktree——不能是 symlink worktree冒烟测试已部署实例打开/dashboard/health确认版本字符串与发布一致对已知 provider 发一个/v1/chat/completions请求验证/api/monitoring/health返回CLOSED熔断状态确认 MCP 传输响应/mcpHTTP、/mcp-sseSSE4.16 发布后运行/capture-release-evidences-ccClaude Code 技能采集新功能的 WebP 截图/录像附到发布说明 / 博客在 GitHub Discussions / Discord 发布公告打开下一版本 milestone若重要在news.json置顶讨论或发 in-app 横幅4.17 Radar 公开上线门禁Radar 公告刻意以active: false提交。激活是单独的一次变更必须在下述每一项都有证据之后所有堆积的 Radar PR 已合并且 release-tip CI 全绿在RADAR_ENABLED默认关闭的情况下部署并冒烟 OSS Radar 路由在指定 Radar 主机上冒烟GET /planos、/termos、/privacidade、/reembolso在私有服务中记录运营者身份/联系方式/地址以及所有者批准的法务评审仅在测试模式下演练 Stripe Checkout 与签名 webhook用批准的发送方/域名演练一次加密的事务邮件投递证明备份恢复与一次受监督、有预算上限的研究运行接受捐赠证据前批准 BRL/PIX 审查政策仅在前述门禁全部通过后启用公开 Checkout然后激活新的news.jsonID验证首页横幅使用本地化文案且新 ID 在旧 ID 被关闭后重新出现五、Embedded Services 冒烟v3.8.4任何包含 embedded services 变更的版本发布前必须验证5.1 全新 DB 启动捕获迁移冲突——v3.8.4 hotfix 后新增DATA_DIR$(mktemp -d) npm start # 等待 10 秒启动 curl -s http://127.0.0.1:20128/api/services/9router/status | jq .tool # 应返回 9router sqlite3 $DATA_DIR/storage.sqlite PRAGMA table_info(version_manager); | grep -E provider_expose|logs_buffer_path|last_sync_at # 3 行 sqlite3 $DATA_DIR/storage.sqlite PRAGMA table_info(webhooks); | grep -E kind|metadata_encrypted # 2 行验证 070_webhooks_kind_metadata.sql node --import tsx/esm --test tests/unit/db/no-migration-collisions.test.ts # 防止未来冲突curl ... | jq .tool返回9router不是 404、不是 500确认迁移071_services.sql已应用且行已 seed。最后一条测试来自 tests/unit/db/专门防止未来迁移编号冲突。5.2 9Router 服务POST /api/services/9router/install2 分钟内返回 200 且带installedVersionPOST /api/services/9router/start30 秒内返回 200 且state: runningGET /api/services/9router/status报告health: healthyPOST /v1/chat/completions传model: 9router/auto/...返回 200端到端经 9Router 路由GET /dashboard/providers/services/9router/embed/dashboard在代理内渲染 9Router 原生 UI不能直接 iframe127.0.0.1:portPOST /api/services/9router/rotate-key返回{ keyRotated: true }且服务干净重启POST /api/services/9router/stop返回 200 且state: stoppedGET /api/services/9router/logs?tail50返回含snapshot事件的 SSE 流在无npm的 PATH 环境中 install 返回 500 且错误信息友好非堆栈5.3 CLIProxyAPI 服务POST /api/services/cliproxy/install2 分钟内返回 200POST /api/services/cliproxy/start30 秒内返回 200 且state: runningGET /api/services/cliproxy/status报告health: healthyPOST /api/services/cliproxy/stop返回 200 且state: stoppedGET /api/services/cliproxy/logs?tail50返回 SSE 流5.4 安全回归curl -H X-Forwarded-For: 1.2.3.4 http://localhost:20128/api/services/9router/start返回403 LOCAL_ONLYcurl -H X-Forwarded-For: 1.2.3.4 http://localhost:20128/api/services/cliproxy/start返回403 LOCAL_ONLY/api/services/*的错误响应不包含err.stack或绝对文件路径六、v3.8.0 追加检查任何 v3.8.x 版本发布前还需验证omniroute --tray在 macOS 启动systray2 装入~/.omniroute/runtime/omniroute --tray在 Linux 启动需要 DISPLAY未设置时优雅报错omniroute --tray在 Windows 启动PowerShell NotifyIcon无额外二进制omniroute config tray enable创建自启动项disable 移除它npm install -g omniroutethis-version的 postinstall 无致命退出更新路径保留可选依赖omniroute update --apply与自动更新器以npm install -g … --includeoptional执行使optionalDependenciesbetter-sqlite3、keytar、tls-client 及 llmlingua SLM 栈atjsh/llmlingua-22.0.5、js-tiktoken在更新后存活。ultramodelPathSLM 层还需 tinybert 模型首次使用时自动下载到${DATA_DIR}/models/llmlingua。postinstallscripts/build/colocateOptionals.mjs随后把 SLM 可选闭包共置到dist/node_modules使 worker 解析到单个huggingface/transformers^4.2.0 实例——standalone 产物只打包 transformers 而非动态导入的 optional若不共置worker 会拿 llmlingua-2 去对根目录的 transformers 加载SLM 层将静默 fail-openomniroute status在无.env时可用CLI token 路径仅 loopbackcurl http://localhost:20128/api/shutdown返回 401始终受保护路由curl -H host: evil.com http://localhost:20128/api/mcp/sse返回 401loopback 守卫SQLite 运行时首次运行解析为bundledbundled 二进制对平台有效删除node_modules/better-sqlite3后 SQLite 运行时回退到runtimeSmart MCP filter 压缩真实playwright-mcp browser_snapshot输出≥50% 缩减全部 10 个skills/omniroute*/SKILL.md可通过 raw GitHub URL 公开获取全新安装时 onboarding 向导显示 How It Works 分层引导首页 dashboard tier 覆盖率组件显示 configured/active 计数七、回滚策略发布出现关键问题时gh release edit vX.Y.Z --prerelease标记为非最新git tag -d vX.Y.Z git push --delete origin vX.Y.Z仅当用户尚未采用时或在release/vX.Y.0上出 hotfix → 补丁版本vX.Y.(Z1)立即在 GitHub Discussions 和 Discord 中沟通八、硬性规则Hard Rules绝不直接提交到main绝不对main或release/*分支使用git push --force绝不跳过 Husky hooks--no-verify绝不提交 secrets、credentials 或.env文件覆盖率必须保持 ≥60/60/60/60statements/lines/functions/branches修改src/、open-sse/、electron/或bin/的生产代码时必须同步包含或更新测试九、自动化同步检查打开 PR 前在本地运行文档同步守卫npm run check:docs-syncCI 也会在.github/workflows/ci.ymllint 任务中执行该检查。它对应 scripts/check/check-docs-sync.mjs与 pre-commit 钩子中的调用一致确保「多语言文档镜像」与英文源文档的翻译状态.i18n-state.json始终同步这也是印尼语等 40 locale 版本清单能够与 docs/ops/RELEASE_CHECKLIST.md 保持同源的机制。小结一次高质量发布的节奏综合清单全文一次健康的 OmniRoute 发布应该呈现这样的节奏保持 release 分支持续绿色check:release-green→ 用/version-bump-cc提升版本并生成 changelog → 本地全量质量门禁lint/typecheck/coverage 60/60/60/60/测试矩阵→npm run build:release单命令产出带BUILD_SHA哨兵的dist/→/generate-release-cc打 tag 建 Release → 按目标选择部署技能 rsync 上线并冒烟 →/capture-release-evidences-cc采集证据发生事故时严格按「deprecate 优先、unpublish 受限、hotfix 补丁回滚」的次序处理。每一步的底层命令、脚本与源码证据都可在当前仓库中直接找到确保检查项不是纸面文章而是可执行、可复现的工程事实。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考