☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
OmniRoute 发布检查清单（Release Checklist）：从版本号到发布工件的全流程质量门禁指南
2026/9/13 19:43:21 网站建设 项目流程

OmniRoute 发布检查清单（Release Checklist）：从版本号到发布工件的全流程质量门禁指南

【免费下载链接】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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

本文是 OmniRoute 开源仓库发布流程的完整实操指南，以 docs/i18n/nl/docs/ops/RELEASE_CHECKLIST.md（荷兰语翻译版）及其英文源文档 docs/ops/RELEASE_CHECKLIST.md 为主体，结合仓库内真实脚本、Husky Hooks、CI 配置与源码常量展开。读完本文，你将掌握 OmniRoute 在打 tag 或发布新版本前必须完成的全部检查项：版本号与 CHANGELOG 同步、API/运行时文档一致性、Node.js 安全版本合规、npm 发布工件验证、自动化文档同步检查，以及一套可直接复用的发布命令序列。

一、检查清单的定位与触发时机

OmniRoute 的发布检查清单（Release Checklist）是仓库中负责"打 tag 或发布新版本之前"的统一校验流程。英文源文档明确说明：在打 tag（tagging）或发布（publishing）一个新的 OmniRoute 版本之前，必须执行本清单（"Use this checklist before tagging or publishing a new OmniRoute release."）。

当前仓库根目录 package.json 版本为3.8.51，electron/package.json 版本同为3.8.51；docs/openapi.yaml 的info.version亦为3.8.51，三者保持一致，这正是本清单"版本一致性"规则落地的直接证据。

整体发布流程可以用一段 TL;DR 概括（源自英文源文档）：

# 1. 升级版本号 + 生成 CHANGELOG（Claude Code skill） /version-bump-cc patch # 或 minor / major # 2. 本地运行质量门禁 npm run check # lint + 测试 npm run test:coverage # 完整覆盖率门禁（60/60/60/60） # 3. 构建与冒烟 npm run build npm run test:e2e # 可选但推荐 # 4. 生成发布（skill） /generate-release-cc # 5. 部署（skill） /deploy-vps-both-cc # 或 akamai-cc / local-cc # 6. 采集发布证据（skill） /capture-release-evidences-cc

二、版本号与变更日志（Version and Changelog）

英文源文档中"Version & Changelog"一节列出了四条硬性操作，翻译版 docs/i18n/nl/docs/ops/RELEASE_CHECKLIST.md 完整保留了这四条：

  1. 升级package.json版本号（x.y.z），且必须在 release 分支上执行；
  2. 将 CHANGELOG.md 中## [Unreleased]的内容移动到带日期的版本小节，格式为## [x.y.z] — YYYY-MM-DD；
  3. 保留## [Unreleased]作为变更日志第一节，供后续迭代继续累积；
  4. 确保 CHANGELOG.md 中最新的 semver 小节等于package.json版本号。

当前仓库的 CHANGELOG.md 以## [Unreleased]开头，其下累积了大量未发布的新功能条目（如feat(dashboard)、feat(sse)等），完全符合"Unreleased 作为第一节"的约定。

在 OmniRoute 的实际流程中，版本号升级通过 Claude Code skill/version-bump-cc <patch|minor|major>完成，它会：

  • 同时升级根目录 package.json 与 electron/package.json（两个版本必须相等，这是桌面端发布的前提）；
  • 根据上一次 tag 之后的 git 提交重新生成 CHANGELOG.md；
  • 更新 README 徽章。

完成自动化后还需要人工审阅 CHANGELOG.md 并清理提交信息，因为 git 提交信息质量参差。

三、API 文档同步（API Docs）

发布前需要更新 docs/openapi.yaml，其硬性约束是：

info.version必须等于package.json版本号。

我们可以在仓库中验证这一约束：当前docs/openapi.yaml顶部info.version为3.8.51，与根package.json一致。如果 API 契约发生了变化（新增端点、修改请求/响应结构），还应**验证端点示例（endpoint examples）**的有效性。

与之配套的还有 OpenAPI 专项检查脚本，见 package.json 中scripts区：check:openapi-coverage（OpenAPI 覆盖度）、check:openapi-security-tiers（安全分级）、check:openapi-routes（路由一致）、check:openapi-breaking（破坏性变更检测）等，这些都在 CI 中强制执行。若新功能有 API，则 docs/reference/API_REFERENCE.md 与docs/openapi.yaml必须同步更新（英文源文档 Documentation 一节明确列出）。

四、运行时文档与 Node.js 安全版本合规（Runtime Docs）

4.1 检查哪些文档

发布前需人工复核以下两份运行时文档是否存在漂移：

  • docs/architecture/ARCHITECTURE.md：检查存储与运行时设计是否与实际实现脱节（storage/runtime drift）；
  • docs/guides/TROUBLESHOOTING.md：检查环境变量与运维行为描述是否漂移。

4.2 Node.js 安全版本下限

这是运行时检查中最容易出问题的一项。发布时使用的 Node.js 版本必须满足仓库的"安全版本下限"（secure floor）。仓库中实际定义于 src/shared/utils/nodeRuntimeSupport.ts：

export const SECURE_NODE_LINES = Object.freeze([ Object.freeze({ major: 22, minor: 22, patch: 2 }), Object.freeze({ major: 24, minor: 0, patch: 0 }), Object.freeze({ major: 25, minor: 0, patch: 0 }), Object.freeze({ major: 26, minor: 0, patch: 0 }), ]); export const RECOMMENDED_NODE_VERSION = "24.14.1"; export const SUPPORTED_NODE_RANGE = ">=22.22.2 <23 || >=24.0.0 <27";

即当前支持Node.js 22.22.2+（22.x LTS）、24.0.0+（24.x LTS）、25.0.0+、26.0.0+，推荐版本为 24.14.1；同时该模块兼容 Bun（Bun >= 1.1.0也会被判定为 supported）。该范围与根 package.json 的engines字段保持一致。

注意：荷兰语翻译版中记录的历史范围>=20.20.2 <21/>=22.22.2 <23已随版本演进被更新；请以 src/shared/utils/nodeRuntimeSupport.ts 中当前生效的SUPPORTED_NODE_RANGE为准（22.x / 24.x / 25.x / 26.x）。

验证命令（源码中确实存在对应脚本）：

npm run check:node-runtime

该命令执行scripts/check/check-supported-node-runtime.ts，对当前运行环境判定nodeCompatible并给出supported/below-security-floor/unsupported-major/unreleased-major等原因；低于安全补丁下限时会提示 "below the patched minimum"。

4.3 npm 发布工件验证

在构建独立发布包之后，必须验证 npm 发布产物的干净度：

npm run build:cli # 执行 scripts/build/prepublish.ts npm run check:pack-artifact

check:pack-artifact（对应scripts/build/validate-pack-artifact.ts）会检查发布包中是否残留以下本地内容：

  • app.__qa_backup（QA 备份目录）；
  • scripts/scratch（临时草稿脚本）；
  • package-lock.json（发布产物不应携带 lockfile）；
  • 其他本地残留物。

仓库还提供了更强的工件冒烟验证check:pack-boot（scripts/check/check-pack-boot.mjs）：它将打包好的 tarball 装入干净容器并真实启动，用于验证发布物可以正常 boot。

五、自动化同步检查（Automated Check / docs-sync）

荷兰语版文档（同时也是英文源文档的收尾）强调：在开 PR 之前必须在本地运行文档同步守卫：

npm run check:docs-sync

CI 也会在 .github/workflows/ci.yml 的 lint job（实际为docs-sync-strict作业）中运行该检查。我们在仓库 .github/workflows/ci.yml 第 420 行可以看到docs-sync-strict:作业定义，其通过check:docs-all执行严格同步校验。

英文源文档把文档检查扩展为一张伞形清单：

  • npm run check:docs-sync— 源码文档 ↔ i18n 文档同步（pre-commit 自动运行）；
  • npm run check:docs-all— 伞形总检，包含 docs-sync + docs-counts + env-doc-sync + deprecated-versions + doc-links + fabricated-docs 等（package.jsonscripts区可查证）；
  • 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 需提及；若是破坏性变更，docs/guides/TROUBLESHOOTING.md 需有迁移说明。

六、i18n 多语言文档同步

由于仓库维护了 50+ 语言的文档镜像（荷兰语版即其中之一，位于 docs/i18n/nl/），发布前对翻译状态有一组专门检查：

npm run i18n:check # 翻译漂移检查（.i18n-state.json 与源文档同步） npm run i18n:check-ui-coverage # 每个 UI locale 达到 80% 覆盖下限 npm run i18n:sync-ui:dry # 报告 42 个 locale 的缺失 key

如果英文源文档发生显著变化，需要在打 tag 前运行npm run i18n:run（需要.env中配置OMNIROUTE_TRANSLATION_API_KEY）触发翻译；轻微翻译缺口可以推迟到下一版本，但要记录在 CHANGELOG 中。对应脚本位于 scripts/i18n/（如check-translation-drift.mjs、check-ui-keys-coverage.mjs、sync-ui-keys.mjs）。

七、代码质量门禁与测试矩阵（Code Quality & Testing）

英文源文档为发布定义了完整的质量门禁，这里列出与荷兰语版"版本与变更日志"直接衔接的核心部分：

7.1 代码质量

npm run lint # 0 error（warning 属存量问题） 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 # 运行时版本合规（见上文）

7.2 测试矩阵

npm run test:unit # 单元测试 npm run test:vitest # MCP server / autoCombo / cache npm run test:coverage # 覆盖率门禁 60/60/60/60（statements/lines/functions/branches） npm run test:integration # 改动涉及 DB / handlers 时 npm run test:combo:matrix # 19 种公开路由策略的确定性选择矩阵 npm run test:e2e # UI 改动时 npm run test:protocols:e2e # MCP/A2A 改动时 npm run test:ecosystem

覆盖率 60/60/60/60 是硬性下限（英文源文档"Hard Rules"一节再次强调："Coverage must stay ≥60/60/60/60"）。此外，combo 策略矩阵（test:combo:matrix）用于证明 19 种公开路由策略的选择决策是确定性的，凡涉及 combo 路由、策略解析或回退逻辑的改动必须运行。

7.3 Husky Hooks（不可跳过）

仓库的 .husky/ 目录包含pre-commit与pre-push两个钩子，英文源文档强调"绝不能用--no-verify绕过"。实际钩子内容（已从仓库验证）为：

  • pre-commit：npx lint-staged+node scripts/check/check-docs-sync.mjs+npm run check:any-budget:t11（外加 git 身份检查与 tracked-artifacts 检查）；
  • pre-push：刻意保持轻量（任何预算 + 已跟踪工件已在 pre-commit 执行），主要作为 PATH/npm 健全性提醒；push release 分支前应手动运行npm run test:unit。

7.4 Conventional Commits 约束

所有进入发布分支的提交必须遵循type(scope): subject格式。合法类型：feat、fix、refactor、docs、test、chore、perf、style、ci；合法 scope 覆盖db、sse、oauth、dashboard、api、cli、docker、mcp、a2a、compression、auto-combo、resilience、providers、executors、translator、domain、authz等。破坏性变更需追加BREAKING CHANGE:footer 或在 scope 后加!（如feat(api)!: drop /v0）。

八、构建布局与单构建流（Build Layout）

仓库使用三个职责完全不同的输出目录，发布时必须区分清楚：

目录用途是否入库
src/应用源码（TypeScript / TSX）是
.build/构建中间产物（next build输出，distDir）否（gitignored）
dist/可发布的 npm bundle（由assembleStandalone组装）否（gitignored）

运维注意：远端 VPS 的镜像目录始终是/usr/lib/node_modules/omniroute/app/。只有仓库内的构建输出位置从app/移到了dist/；部署 skill 会把dist/内容 rsync 到远端app/目录，VPS 路径无需改动。

发布必须使用单命令构建流，而不是npm run build后再单独跑npm run build:cli：

npm run build:release └─ rm -rf .build dist （清理） └─ 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)，然后依次构建并调用scripts/build/write-build-sha.mjs写入哨兵。

发布前的工件验证断言：

  • dist/BUILD_SHA==git rev-parse --short HEAD；
  • npm run check:pack-artifact干净（无本地残留物）；
  • dist/server.js存在。

九、打标签与发布（Tagging & Release）

推荐使用/generate-release-cc（Claude Code skill），它会：

  • 创建 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

9.1 npm 发布：Trusted Publishing（OIDC）与 staged 发布

自 v3.8.51 起，npm-publish.yml默认通过npm Trusted Publishing（OIDC）发布：stage-npm作业用 GitHub 的 id-token 换取当次运行的短期 npm 凭证——仓库 secrets 中不再存长效 npm token、无 2FA 提示、附带 provenance（来源证明）。这既恢复了 v3.8.48 之前的全自动流程，又保留了 WS1.3 保证（泄漏的 token 无法单独发布，因为根本没有 token）。

一次性配置（owner）：npmjs.com → 包omniroute→ Settings →Trusted Publisher→ GitHub：owner / repo / workflownpm-publish.yml。配置缺失时自动发布会以ENEEDAUTH失败，此时改用publish_mode=staged或direct重新调度。

Staged 发布（按需，publish_mode=staged）将人工 2FA 门槛移动到"证据之后"：

  1. npm stage list omniroute找到 stage id；
  2. 验证 staged 字节（推荐）：npm stage download <id>，装入临时 prefix 并 boot（CI 中check:pack-boot自动化同样的 pack→install→boot 判定）；
  3. npm stage approve <id>— 2FA 提示即发布；npm stage reject <id>丢弃；
  4. 发布后验证器（WS1.4）会在干净容器中从公共 registry 安装已发布版本并 boot。

紧急回退：workflow_dispatch传publish_mode=direct恢复传统即时npm publish（仅当 staging 自身异常时使用，并记录原因）。

Docker Hublatest规则：docker-publish工作流在每个稳定 SemVer 发布时必须同时打X.Y.Z标签；当should-promote-latest.sh判定这是最高稳定版本时，还要用同一 digest打:latest。发布后 Hub 上latest的 digest 必须等于新 SemVer 的 digest。Compose 快速上手使用:latest；GitOps 应坚持锁定X.Y.Z。详见 docs/guides/DOCKER_GUIDE.md。

十、部署与冒烟测试（Deploy & Smoke）

部署采用轻量 rsync 流程——不执行npm pack，不执行npm i -g。按目标选择部署 skill：

  • /deploy-vps-local-cc— 本地 VPS（192.168.0.15）；
  • /deploy-vps-akamai-cc— Akamai VPS；
  • /deploy-vps-both-cc— 两者同时。

部署前必须确认dist/BUILD_SHA==git rev-parse --short HEAD；构建必须在node_modules真实存在的环境执行（主 checkout 或执行过npm ci的 worktree，而非符号链接 worktree）。

部署后的冒烟检查：

  • 打开/dashboard/health，确认版本字符串与本次发布一致；
  • 对已知 provider 发起一次/v1/chat/completions请求；
  • 验证/api/monitoring/health返回CLOSED熔断器状态；
  • 确认 MCP 传输通道响应（/mcpHTTP、/mcp-sseSSE）。

十一、回滚预案与硬性规则（Rollback & Hard Rules）

11.1 回滚步骤

发布出现严重问题时按顺序执行：

  1. gh release edit vX.Y.Z --prerelease（标记为 not latest）；
  2. 若用户尚未采用：git tag -d vX.Y.Z && git push --delete origin vX.Y.Z；
  3. 或：在release/vX.Y.0上出 hotfix → 补丁版本vX.Y.(Z+1)；
  4. 立即在 GitHub Discussions 与 Discord 同步说明。

npm 产物回滚的默认动作是npm deprecate omniroute@<bad> "<reason> — use <fixed>"（分钟级、可逆）；npm unpublish仅限 72 小时/无依赖窗口内，且永远不作为第一动作。Docker 侧绝不重写版本 tag——回滚是把latest重新指向最后一个好 digest。

11.2 硬性规则

  • 绝不直接提交到main；
  • 绝不git push --force到main或release/*分支；
  • 绝不跳过 Husky Hooks（--no-verify）；
  • 绝不提交 secrets、凭证或.env文件；
  • 覆盖率必须保持 ≥60/60/60/60；
  • 修改src/、open-sse/、electron/、bin/生产代码时必须附带或更新测试。

十二、发布前 Keep Green 与高级门禁

12.1 保持 release 队列常绿

在进入本清单之前，应周期性运行 docs/ops/RELEASE_GREEN.md 描述的流程（/green-prs系列 +npm run check:release-green+/babysit+ nightly），让 release PR 从一开始就是绿的——这能显著减少发布日的返工。

12.2 数据库迁移检查

若 src/lib/db/migrations/ 出现新迁移文件（当前编号已推进到 175 号call_logs_provider_stats_indexes.sql），必须验证：

  • 每个迁移幂等（CREATE TABLE IF NOT EXISTS等）；
  • 迁移包裹在事务中；
  • 编号连续无空洞（仓库有check:migration-numbering脚本与tests/unit/db/no-migration-collisions.test.ts防止未来冲突）；
  • 全新安装与存量升级两条路径都要测试；重写表时正确处理 WAL 文件（-wal、-shm）。

12.3 Provider Catalog（Zod 校验）

新增 provider 时，src/shared/constants/providers.ts 的 Zod schema 必须在加载时通过校验；OAuth provider 需在 src/lib/oauth/constants/oauth.ts 注册oauthConfig；对应 executor 放在open-sse/executors/，非 OpenAI 格式需在open-sse/translator/提供翻译器；模型在open-sse/config/providerRegistry.ts注册，并在tests/unit/覆盖 provider 分类与路由逻辑。

12.4 发布后收尾

  • 运行/capture-release-evidences-cc采集新功能的 WebP 截图/录屏，附到发布说明；
  • 更新 GitHub Discussions / Discord 发布公告；
  • 打开下一版本 milestone；
  • 若属关键公告，可固定讨论或在 news.json 发布应用内横幅（注意横幅 ID 采用active标志控制开关，仓库中radar-launch-2026-08即为active: false的待激活示例）。

结语：发布不是"提交 tag"而是"证明可发布"

回到荷兰语版清单的收尾——npm run check:docs-sync同时在本地与 CI lint 作业中执行。这条命令代表了整个发布哲学：OmniRoute 的发布检查清单把"人为自觉"压缩到最小，把可自动化的一致性校验（版本号、OpenAPI、文档、i18n、Node 版本、工件残留、文档同步）全部脚本化，再由 Husky Hooks 与 CI 在本地和远端双重把关。发布者需要操心的只剩真正需要判断力的部分：CHANGELOG 的语义整理、测试覆盖的真实性，以及部署后的冒烟验证。

参考路径速查：英文源清单 docs/ops/RELEASE_CHECKLIST.md · 荷兰语翻译 docs/i18n/nl/docs/ops/RELEASE_CHECKLIST.md · 运行时策略源码 src/shared/utils/nodeRuntimeSupport.ts · 钩子目录 .husky/ · CI 配置 .github/workflows/ci.yml

【免费下载链接】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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

Linux的基本指令
2026/9/13 19:41:35 网站建设

Linux的基本指令

1. ls指令语法&#xff1a;ls [选项] [目录或文件]功能&#xff1a;查看当前目录下的所有子目录和文件。对于一个文件来说&#xff1a;文件文件内容文件属性(文件名、修改时间、文件类型、文件大小等)。文件操作对文件内容的操作或对文件属性的操作。当前目录为/home/xxl&…...

阅读更多 →
Ubuntu 24.04 自托管 SpacetimeDB 完整指南：systemd 服务、Nginx 反向代理与 HTTPS 实战
2026/9/13 19:39:49 网站建设

Ubuntu 24.04 自托管 SpacetimeDB 完整指南：systemd 服务、Nginx 反向代理与 HTTPS 实战

Ubuntu 24.04 自托管 SpacetimeDB 完整指南&#xff1a;systemd 服务、Nginx 反向代理与 HTTPS 实战 【免费下载链接】SpacetimeDB Development at the speed of light 项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB 本指南以 SpacetimeDB 1.12.0 官方…...

阅读更多 →
TDengine 零代码接入 MongoDB：通过 taosExplorer 配置数据同步任务实战指南
2026/9/13 19:39:49 网站建设

TDengine 零代码接入 MongoDB：通过 taosExplorer 配置数据同步任务实战指南

TDengine 零代码接入 MongoDB&#xff1a;通过 taosExplorer 配置数据同步任务实战指南 【免费下载链接】TDengine High-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios 项目地址: https://gitcode.com/GitHub_Trending/tde/TDen…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询