OmniRoute 发布检查清单实战从版本号到上线部署的完整质量闸门指南【免费下载链接】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/OmniRouteOmniRoute 是一个统一的 AI 网关与路由器项目提供单一 OpenAI 兼容端点聚合数百家提供商与上千个模型并内置配额感知自动回退、RTKCaveman 压缩、MCP/A2A 等能力。本文围绕仓库中的官方发布检查清单docs/ops/RELEASE_CHECKLIST.md 及其 i18n 镜像 docs/i18n/hu/docs/ops/RELEASE_CHECKLIST.md展开完整梳理一次正规发布从版本号、CHANGELOG、OpenAPI 同步到代码质量、测试、文档/i18n、数据库迁移、Provider 目录、Electron 桌面端、构建产物校验、打标签、部署与回滚的每一个闸门。读完本文你将掌握 OmniRoute 发布全流程的可执行命令、每个检查项的底层实现与失败时的正确处置方式。一、清单的定位多语言同步的单一事实源OmniRoute 的发布检查清单以 docs/ops/RELEASE_CHECKLIST.md 为英文原版并在 docs/i18n/ 下维护了 40 个语言镜像如 匈牙利语镜像、波兰语镜像。这些镜像并非独立文档而是由同步守卫强制的翻译副本。从 scripts/check/check-docs-sync.mjs 的源码可以看到同步机制的本质脚本会读取package.json的version、docs/openapi.yaml 的info.version、CHANGELOG.md 的各个## [版本号]段落逐一比对一致性对于llm.txt这类纯镜像要求与源逐字节一致对于多语言CHANGELOG.md则校验所有版本段落完整存在且顺序一致行数偏差不超过 25%任一不满足即输出[docs-sync] FAIL - ...并以退出码 1 结束本地与 CI 都会因此红灯。这意味着清单本身也是发布质量的一部分只有npm run check:docs-sync通过版本三件套package.json / openapi.yaml / CHANGELOG与所有语言镜像才被视为就绪。二、开跑前的 TL;DR 流水线英文原版清单在开头给出了六步发布流水线其中依赖 Claude Code 技能匈牙利语镜像与之对应的是手动检查项。先看全局# 1. 升版本号 生成 CHANGELOG技能 /version-bump-cc patch # 或 minor / major # 2. 本地质量闸门 npm run check # lint tests npm run test:coverage # 完整覆盖率闸门60/60/60/60 # 3. 构建与冒烟 npm run build npm run test:e2e # 可选但推荐 # 4. 生成发布技能 /generate-release-cc # 5. 部署技能 /deploy-vps-both-cc # 或 akamai-cc / local-cc # 6. 采集发布证据技能 /capture-release-evidences-cc这套流水线的背后是一条硬性纪律保持队列/分支在两次发布之间常绿。发布前应先运行npm run check:release-green对应 scripts/quality/validate-release-green.mjs与 nightly 检查让发布 PR 从零开始就是绿色。三、版本号与 CHANGELOG三处必须对齐1. 版本号提升在发布分支中提升package.json的versionx.y.z。注意 package.json 当前版本为3.8.51且electron/package.json必须与根目录版本保持一致见下文 Desktop 章节。使用技能时/version-bump-cc patch|minor|major会同时完成提升package.json与electron/package.json、根据最近一次 tag 以来的 git 提交重新生成CHANGELOG.md、更新 README 徽章。2. CHANGELOG 格式纪律将## [Unreleased]中的发布说明移动到带日期的版本段落## [x.y.z] — YYYY-MM-DD永远保留## [Unreleased]作为第一个 changelog 段落用于承接后续工作最新的 semver 段落必须等于package.json的版本号。check-docs-sync.mjs会强校验这一点extractChangelogSections会检查第一个段落是否为Unreleased且第一个 semver 段落等于packageJson.version否则 FAIL。3. OpenAPI 版本对齐清单要求docs/openapi.yaml匈牙利语镜像中误写为docs/reference/openapi.yaml以仓库实际存在的 docs/openapi.yaml 为准的info.version必须等于package.json版本。check-docs-sync.mjs中extractOpenApiVersion会解析info:块下的version:字段并做精确比对若 API 契约有变更还需验证端点示例仍然有效仓库提供 scripts/check/check-openapi-coverage.mjs、scripts/check/check-openapi-breaking.mjs 等辅助闸门。四、运行时文档与 Node 版本安全下限1. 文档漂移审查发布前需要人工复查两类漂移docs/architecture/ARCHITECTURE.md存储/运行时结构是否有变化docs/guides/TROUBLESHOOTING.md环境变量与运维细节是否有变化。2. Node 运行时安全下限清单要求校验发布/运行所用的 Node.js 版本仍满足受支持的安全下限并运行npm run check:node-runtime该命令背后是 scripts/check/check-supported-node-runtime.ts它调用 src/shared/utils/nodeRuntimeSupport.ts 中导出的策略常量。从源码看当前受支持范围为export const SECURE_NODE_LINES [ { major: 22, minor: 22, patch: 2 }, { major: 24, minor: 0, patch: 0 }, { major: 25, minor: 0, patch: 0 }, { major: 26, minor: 0, patch: 0 }, ]; export const SUPPORTED_NODE_RANGE 22.22.2 23 || 24.0.0 27; export const RECOMMENDED_NODE_VERSION 24.14.1;这与 package.json 的engines字段node: 22.22.2 23 || 24.0.0 27一致。该模块对每个主版本维护一个安全下限secure floor低于下限即判定below-security-floor并给出明确警告同时支持 BunBun 1.1.0作为兼容运行时。发布前务必确认部署机与 CI 的 Node 版本落在该区间内。3. npm 发布产物校验构建独立包后必须校验发布产物没有本地残留npm run build:cli npm run check:pack-artifactcheck:pack-artifact对应 scripts/build/validate-pack-artifact.ts。从源码可见它执行npm pack --dry-run --json并检查四类问题意外文件如app.__qa_backup、scripts/scratch、package-lock.json、bin/*.sh等未在白名单中的内容必需运行时文件缺失dist/下的关键路径测试/规格文件泄漏*.test.*、__tests__/混入包体靠package.json的files否定规则兜底MCP 可达源码缺失--mcp场景下闭包不全会导致 404。它还执行构建溯源校验dist/BUILD_SHA必须是 release 分支的祖先提交resolveBuildProvenance防止从过期特性分支打包出假装携带修复的版本这类事故。这是 2026-08-14 网关事故之后引入的 #10427 护栏。4. 本地化文档同步若源英文文档发生显著变更需在打 tag 前更新各语言镜像。多语言同步由 scripts/i18n/ 下的工具链负责其中npm run i18n:run需要.env中的OMNIROUTE_TRANSLATION_API_KEY执行翻译npm run i18n:check校验漂移。若某语言更新量小可推迟到下一版本但需在 CHANGELOG 中记录。五、自动化检查开 PR 前的同步守卫清单的最后一步也是两个语言版本都强调的是在开 PR 前本地运行同步守卫npm run check:docs-syncCI 也会在 .github/workflows/ci.yml 的 lint 任务中运行它。如第一节所述该守卫校验版本三件套的一致性以及docs/i18n镜像的完整性——这正是匈牙利语镜像能够与英文原版保持内容同步的机制保证。check:docs-sync还包含一条反回归规则被取代的旧文档不得复活如docs/CLI-TOOLS.md这类旧路径若重新出现会直接 FAIL应以docs/reference/下的单一事实源为准。六、深入清单发布前的全量检查项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-slim见 Dockerfile。2. Code Quality代码质量npm run lint # 0 错误已有警告可接受 npm run typecheck:core # 干净 npm run typecheck:noimplicit:core # 严格模式干净 npm run check:cycles # 无循环依赖 npm run check:any-budget:t11 # 预算内 npm run check:route-validation:t06 # 干净 npm run check:node-runtime # 运行时下限达标其中typecheck:core/typecheck:noimplicit:core分别使用 tsconfig.typecheck-core.json 与 tsconfig.typecheck-noimplicit-core.jsoncheck:cycles由 scripts/check/check-cycles.mjs 实现保证src/、open-sse/等核心模块不出现循环依赖。3. Testing测试矩阵npm run test:unit # 单元测试 npm run test:vitest # MCP server、autoCombo、cache 相关vitest.mcp.config.ts npm run test:coverage # 覆盖率闸门 60/60/60/60statements/lines/functions/branches npm run test:integration # 触碰 DB / handlers 时必须 npm run test:combo:matrix # combo 策略矩阵确定性验证全部 19 个公开路由策略的选择 RUN_COMBO_LIVE1 npm run test:combo:live # 可选/手动真实上游冒烟消耗配额绝不在 CI 运行 npm run test:combo:live:vps # 可选/手动针对线上 .15 服务器的 7 个 HTTP 场景 npm run test:e2e # UI 变更时 npm run test:protocols:e2e # MCP/A2A 变更时 npm run test:ecosystem # 生态兼容测试其中test:coverage由 c8 驱动--statements 60 --lines 60 --functions 60 --branches 60是硬性下限见 package.json 的test:coverage脚本。combo 矩阵测试tests/integration/combo-matrix/*.test.ts在触碰 combo 路由、策略解析或回退逻辑时必须运行——它证明路由策略的决策具有确定性这正是 OmniRoute 自动回退可靠性的根基。4. HooksHusky 钩子钩子位于.husky/目录git 操作时自动执行pre-commitnpx lint-stagednode scripts/check/check-docs-sync.mjsnpm run check:any-budget:t11从 .husky/pre-commit 实际内容看还包括check-git-identity.sh与check-tracked-artifacts.mjspre-pushnpm run check:any-budget:t11 npm run check:tracked-artifacts自 2026-06-13 起启用。刻意排除test:unit慢交给 CI 的test-unitjob——因此推送发布分支前请手动运行npm run test:unit。钩子失败时修复根本问题不要用--no-verify绕过这是清单硬规则之一。5. Conventional Commits 纪律发布相关的所有提交必须遵循type(scope): subject格式有效类型feat、fix、refactor、docs、test、chore、perf、style、ci有效作用域db、sse、oauth、dashboard、api、cli、docker、ci、mcp、a2a、memory、skills、cloud-agent、guardrails、compression、auto-combo、resilience、providers、executors、translator、domain、authz破坏性变更在 footer 添加BREAKING CHANGE:或在 scope 后加!如feat(api)!: drop /v0。6. Documentation文档闸门npm run check:docs-sync # 文档同步pre-commit 自动运行 npm run check:docs-all # 伞形检查docs-sync docs-counts env-doc-sync deprecated-versions doc-links npm run check:env-doc-sync # 代码 ↔ .env.example ↔ docs/reference/ENVIRONMENT.md 契约完整 npm run check:doc-links # 无失效的内部 markdown 引用规则约定.env.example变更则更新 docs/reference/ENVIRONMENT.md新功能有 UI 则在 docs/guides/USER_GUIDE.md 提及新功能有 API 则更新 docs/reference/API_REFERENCE.md 与 docs/openapi.yaml新模块则建立专属docs/MODULE.md破坏性变更则在 docs/guides/TROUBLESHOOTING.md 加入迁移说明。7. i18n国际化闸门npm run i18n:check # 翻译漂移严格模式下源文档不得漂移打 tag 前应归零 npm run i18n:check-ui-coverage # 每个 UI locale 覆盖率 ≥ 80% 下限 npm run i18n:sync-ui:dry # 42 个 locale 缺键数为 0 npm run i18n:run # 源英文文档变更后重跑翻译需要 OMNIROUTE_TRANSLATION_API_KEY从 scripts/i18n/ 目录可见完整的工具链check-translation-drift.mjs、check-ui-keys-coverage.mjs、sync-ui-keys.mjs、run-translation.mjs等对应清单中的每一项。8. Database Migrations数据库迁移若 src/lib/db/migrations/ 出现新迁移文件每个迁移必须幂等CREATE TABLE IF NOT EXISTS等迁移必须包裹在事务中编号必须连续无跳号npm run check:migration-numbering可辅助校验全新安装测试删除~/.omniroute/omniroute.db后运行npm run dev既有安装测试备份 DB、运行迁移、校验 schema若迁移重写表结构需正确处理 WAL 文件-wal、-shm。9. Provider CatalogZod 校验Provider 目录在 src/shared/constants/providers.ts 中以 Zod schema 校验所有 provider 具备必填字段id、label、kind等新免费 provider 提供freeNoteOAuth provider 在 src/lib/oauth/constants/oauth.ts 注册oauthConfig新增 provider 需在 open-sse/executors/ 有对应 executor非 OpenAI 格式则需 open-sse/translator/ 翻译器模型注册于 open-sse/config/providerRegistry.tstests/unit/ 中要有覆盖 provider 分类与路由的单元测试。10. DesktopElectron若 electron/ 有变更npm run electron:smoke:packaged # 打包后冒烟至少构建并测试:win、:mac、:linux之一签名证书未过期如启用签名electron/package.json版本与根package.json一致若发布到stable频道更新自动更新频道指针。11. Build Layout构建布局仓库使用三个输出目录切勿混淆目录用途是否纳入版本控制src/应用源码TypeScript / TSX是.build/构建中间产物next build输出distDir否gitignoreddist/可发布的 npm 包体assembleStandalone组装否gitignored运维注意远程 VPS 镜像目录仍为/usr/lib/node_modules/omniroute/app/。仓库内构建输出从app/移到dist/部署技能将dist/内容 rsync 到远程app/目录VPS 路径无需变更。单一构建流程部署请勿分别执行npm run buildnpm run build:cli必须用下面这一个命令npm run build:release └─ rm -rf .build dist (clean) └─ next build → .build/next/ (中间产物) └─ assembleStandalone (standalone static public natives → dist/) └─ 写入 dist/BUILD_SHA (HEAD 哨兵)对应 package.json 中的build:release脚本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。12. Artifact Validation产物校验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.js存在。七、打标签与 GitHub Release推荐使用/generate-release-cc技能它会创建 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-tag八、npm 可信发布与 Docker 渠道v3.8.51 起1. npm Trusted PublishingOIDC默认.github/workflows/npm-publish.yml 默认通过npm Trusted PublishingOIDC发布GitHub 的 id-token 在每次运行时换取短期 npm 凭证仓库 secrets 中不再存放长期 npm token无需 2FA 提示且自动附带 provenance。这符合 npm 对跳过 2FA 的 token 的退役政策恢复了 v3.8.48 之前的全自动流程同时保留泄露的 token 无法单独发布的保证。一次性设置ownernpmjs.com → 包omniroute→ Settings → Trusted Publisher → GitHubownerdiegosouzapw、repoOmniRoute、workflownpm-publish.yml。在配置完成前自动步骤会以ENEEDAUTH失败此时可改用publish_modestaged或direct重新派发。2. Staged 发布按需publish_modestagednpm-publish 工作流不再直接发布它先启动打包好的 tarballcheck:pack-boot再运行npm stage publish——字节先停放在 registry 上不可安装直到 owner 批准。人的 2FA 闸门移到了证据之后。Owner 在工作流变绿后的流程npm stage list omniroute—— 找到 stage id工作流摘要中也会打印建议校验暂存字节npm stage download id安装下载的 tarball 并启动CI 中npm run check:pack-boot自动化同样的 pack→install→boot 判定npm stage approve id—— 2FA 提示本身就是发布npm stage reject id丢弃发布后验证post-publish verifier 在干净容器中从公共 registry 安装已发布版本并启动。紧急回退workflow_dispatch传入publish_modedirect恢复传统立即npm publish仅当 staged 本身出问题时使用并记录原因。破损产物剧本不变默认反射是npm deprecate omniroutebad reason — use fixed几分钟内可逆npm unpublish仅在 72 小时/无依赖窗口内使用且绝不作第一步。Docker 方面绝不重写版本 tag——回滚即把latest重新指向最后一个好的 digest。3. Docker Hublatest每次稳定 SemVer 发布必需.github/workflows/docker-publish.yml 必须同时打X.Y.Z与当 scripts/ci/should-promote-latest.sh 判定这是最高稳定 SemVer 时:latest且使用同一 digest。发布后 Hublatestdigest 应等于新 SemVer digestlast_updated应更新。不要把latest留在旧构建上却让 release notes 讲只存在于 git 上的修复。Compose 快速入门用:latestGitOps 应持续固定X.Y.Z。详见 docs/guides/DOCKER_GUIDE.md 的 Release Channels 章节。九、Hotfix 快车道labelhotfix带hotfixlabel 的 PR 跳过重 CI 矩阵9 分片 E2E、覆盖率棘轮、quality-gate、quality-extended保留快速高信号闸门build、unit shards、integration、vitest、lint/typecheck、docs-sync、check:pack-artifact与 tarball 启动冒烟check:pack-boot。目标≤15 分钟变绿常规约 33 分钟。进入条件四项全满足参照 Chromium/VS Code/Node 紧急通道严重性生产环境已损坏——发布产物启动即崩溃 / 安全修复 / 影响该发布的所有用户。重要不等于损坏权限仅仓库 owner 可打hotfixlabel。label 本身就是批准——不得在活动 PR 上自助申请证据PR 正文链接此前完全通过的 heavy 运行被跳过任务本会重新校验的套件以及修复自身的先失败后通过测试范围仅 cherry-pick——最小修复无重构无搭车变更。被跳过的覆盖/棘轮面由发布分支上下一次完整运行持续 release-green重新校验——快车道跳过等待从不跳过验证。纯测试变更所有文件都在tests/下、且都不在tests/e2e/下无需 label 也会自动跳过 E2E 矩阵。十、部署与冒烟部署技能采用轻量 rsync 流程无npm pack、无npm i -g按目标选择/deploy-vps-local-cc—— 本地 VPS192.168.0.15/deploy-vps-akamai-cc—— Akamai VPS/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-sseSSE。十一、嵌入式服务冒烟v3.8.4若发布涉及嵌入式服务变更需额外验证含新鲜 DB 启动捕捉迁移冲突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 行 node --import tsx/esm --test tests/unit/db/no-migration-collisions.test.ts # 防未来迁移冲突9Router 与 CLIProxyAPI 各自验证 install / start / status / stop / logs 的完整生命周期例如POST /api/services/9router/install2 分钟内返回 200 且含installedVersionPOST /v1/chat/completions携带model: 9router/auto/...端到端路由GET /api/services/9router/logs?tail50返回含snapshot事件的 SSE 流无npm环境安装返回友好非堆栈错误。安全回归curl -H X-Forwarded-For: 1.2.3.4 http://localhost:20128/api/services/9router/start必须返回403 LOCAL_ONLYCLIProxyAPI 同理/api/services/*的错误响应不得包含err.stack或绝对文件路径。十二、v3.8.x 附加检查与回滚v3.8.0 附加项节选omniroute --tray在 macOS / Linux需 DISPLAY/ Windows 均可启动omniroute config tray enable/disable创建/移除自启动项npm install -g omnirouteversion的 postinstall 不致命退出更新路径保留可选依赖--includeoptionalbetter-sqlite3、keytar、tls-client、llmlingua SLM 栈atjsh/llmlingua-22.0.5、js-tiktoken在升级后依然存活omniroute status无.env也可工作CLI token 路径、仅回环curl http://localhost:20128/api/shutdown返回 401始终受保护curl -H host: evil.com http://localhost:20128/api/mcp/sse返回 401回环守卫SQLite 运行时首跑解析为bundled删除node_modules/better-sqlite3后回退runtime。回滚剧本发布出现严重问题时gh release edit vX.Y.Z --prerelease标记为非最新git tag -d vX.Y.Z git push --delete origin vX.Y.Z仅当用户尚未采用或在release/vX.Y.0上热修复 → patch 发布vX.Y.(Z1)立即在 GitHub Discussions 与 Discord 同步沟通。十三、硬规则不可谈判绝不直接提交到main绝不git push --force到main或release/*分支绝不跳过 Husky 钩子--no-verify绝不提交 secrets、凭证或.env文件覆盖率必须保持 ≥60/60/60/60statements/lines/functions/branches修改src/、open-sse/、electron/或bin/的生产代码时必须同步新增或更新测试。十四、发布证据采集Post-release运行/capture-release-evidences-cc采集新功能的 WebP 截图/录屏附加到 release notes / 博客在 GitHub Discussions / Discord 发布公告为下一版本打开里程碑若关键置顶讨论或在 news.json 发布应用内横幅如 Radar 公共发布闸门所述active: false的公告需在全部闸门通过后单独激活。结语OmniRoute 的发布检查清单是一套可执行的工程制度从package.json版本号、docs/openapi.yaml 与 CHANGELOG.md 的机械对齐到 scripts/check/check-docs-sync.mjs 对多语言镜像的强制同步再到 npm Trusted Publishing 与 staged 发布的供应链安全设计。无论是日常小版本、hotfix快车道还是 v3.8.x 这样带嵌入式服务的复杂发布遵循清单中的每一项闸门与回滚剧本就能让每一次发布都可追溯、可验证、可回退——这正是多语言文档版本英文原版 与 匈牙利语镜像共同传达的核心纪律。【免费下载链接】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），仅供参考
