docs: fill phase 2 final 9 docs (deployment 6 + architecture 6C, #167)#188
Merged
Conversation
…tps-proxy (#167) 补齐部署指南第二批前 3 篇正文： - github-actions：覆盖 release.yml / deploy-personal.yml / verify.yml / docs.yml / dependabot-fix.yml 的触发方式、镜像 tag 规则、远端 smoke 与 secrets 清单，并给出首次配置的 6 步流程。 - database：澄清 PG/SQLite 不可互替（PERCENTILE_CONT 等 SQL 在 SQLite 上直接报错），列出 DB_TYPE 自动推断与生产 fail-fast 行为，区分 db:generate 与 db:push 的取舍，并对照 CI 的 migration job。 - https-proxy：给出 Nginx / Caddy / 1Panel 三种形态的最小反代配置， 覆盖 SSE 流式响应所需的 proxy_buffering off 与 flush_interval -1， 并显式声明当前代码不输出任何 CORS 响应头，跨域必须在反代层处理。 完成 issue #167 Phase 2 部署指南 3/6 篇。
…rade-rollback + troubleshooting (#167) 补齐部署指南最后 3 篇正文： - persistence-backup：把运行状态拆为 PG / autorouter-data / cliproxy-auth / cliproxy-logs / 录制目录 / .env 六处，逐项给出在线热备与恢复样例； 明确「单独备份 PG 不足以恢复全部状态」，.env 必须独立纳入备份。 - upgrade-rollback：围绕 AUTOROUTER_IMAGE 切换给出 A/B 两条路径的命令， 按 schema 兼容性区分前向迁移与破坏性迁移的升级顺序，以及破坏性回滚 必须依赖 pg_dump 离线备份。 - troubleshooting：按部署阶段从前向后排查容器启动、healthcheck、 localhost vs 服务名、ENCRYPTION_KEY 丢失四类常见故障，每项给出 诊断与修复路径。 完成 issue #167 Phase 2 部署指南剩余 6/6 篇。
…release (#167) 补齐架构介绍最后 3 篇正文（协作面）： - testing：把 tests/ 目录按 Vitest（unit + components）与 Playwright （e2e / a11y / visual）两条轴划分，澄清「tests/integration/ 当前 不存在」，并把 verify.yml 的 6 个 job 拓扑与本地复现 CI 流程串起来。 - contributing：从分支命名 / Conventional Commits / Prettier+ESLint +TS 的 strict / pre-commit Python 框架四段切入，给出 PR 流程与 OpenSpec 提案的适用边界，并把 CLAUDE.md 的提交边界规则落到具体 情形。 - release：用 SemVer + alpha/beta 渠道、release.yml 的 tag 正则与 ancestor 校验、git-cliff 基线计算、docker/metadata-action 的镜像 tag 矩阵、package.json version 与 tag 的关系串成完整发布链路。 完成 issue #167 Phase 2 架构介绍剩余 3/3 篇。
VitePress 把 markdown 中的 `\$\{\{ ... \}\}` 当成 Vue 模板插值解析，
即便位于 inline code 内也会进入编译期 SSR；命中后 release.yml 的
`\$\{\{ github.ref_name \}\}` 与 docker/metadata-action 的
`\{\{version\}\}` / `\{\{major\}\}.\{\{minor\}\}` 都会在 docs:build
渲染期抛 `Cannot read properties of undefined (reading 'ref_name')`。
把 github-actions.md 与 release.md 中受影响的表格替换为不含双花括号
的等价描述（用 `<ref_name>` / `<version>` / `<major>.<minor>` 占位
符表达，并显式回引仓库内的 yaml 源文件位置）。yaml fenced code
block 中的原始写法保持不变，那里 VitePress 不会解析双花括号。
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #188 +/- ##
=======================================
Coverage 74.05% 74.05%
=======================================
Files 147 147
Lines 11114 11114
Branches 3846 3846
=======================================
Hits 8231 8231
Misses 1682 1682
Partials 1201 1201
🚀 New features to boost your workflow:
|
…卷挂载现状 (#167, #188) Self-review 抽读时发现四处与仓库现状不符的事实陈述，本次一并修正： 1. database.md / upgrade-rollback.md 关于「容器不会自动跑迁移」「需要部署人手工触发 pnpm db:migrate」的描述与 scripts/docker-entrypoint.sh 现状矛盾。 该 entrypoint 在应用启动前会自动跑一遍内嵌的 migration runner（不依赖 drizzle-kit，按文件名顺序 apply drizzle/*.sql、用 __drizzle_migrations 表去重）。改为说明自动 apply 行为，并把破坏性迁移段重写为「entrypoint 仍 forward apply，回滚必须靠 pg_dump」。 2. database.md / upgrade-rollback.md 建议的 `docker compose exec autorouter node node_modules/drizzle-kit/bin.cjs migrate` 在生产镜像内无法执行。 Dockerfile standalone runner stage 只 copy postgres 这一个 node_modules 子包，drizzle-kit 是 devDependency 不进镜像。改为推荐「重启 autorouter 让 entrypoint 重跑」或「docker run --rm --entrypoint /app/docker-entrypoint.sh ghcr.io/g1331/autorouter:vN.N.N true」这种把 entrypoint 与 server.js 解耦的临时容器写法。 3. persistence-backup.md 关于「RECORDER_FIXTURES_DIR 通常会挂入 autorouter-data named volume（如默认编排）」的描述错误。 docker-compose.yml 中 RECORDER_FIXTURES_DIR 默认值是 `tests/fixtures`，相对容器内 /app/，实际写到 /app/tests/fixtures，不在任何 named volume 上——容器重建即丢。补 ::: danger ::: 容器警告，并显式给出「显式把 RECORDER_FIXTURES_DIR 指到 /app/data/...」的修复路径。 4. contributing.md 关于「推荐用 squash merge」与仓库实际 merge commit 历史（PR #184/#185/#186 都是 Merge pull request 形态）冲突。改为陈述「近期实际历史以 merge commit 为主，cliff.toml 显式 skip 这类 commit」，把策略选择留给 reviewer。 来源对照段同步补 scripts/docker-entrypoint.sh 与 Dockerfile 两项依据。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
补齐 issue #167 Phase 2 剩余 9 篇文档正文，关闭部署指南与架构介绍的两条收尾项。
github-actions+database+https-proxy+persistence-backup+upgrade-rollback+troubleshootingtesting+contributing+release至此 Phase 2 文档主体 24/24 全部合入。
docs/.vitepress/config.ts的 sidebar 在 Phase 1 scaffold 阶段已经预先包含全部 9 篇链接，无需再改导航。关键事实依据
所有正文都按「直接对照仓库源文件」的方式撰写，每篇结尾附 `来源对照` 段：
VitePress 渲染兼容
最后一个 commit `241d6b8` 修了 VitePress 把 markdown 里的 `${{ github.ref_name }}` 当成 Vue 模板插值进而 SSR 报错的问题。修法是把表格里出现的双花括号占位符替换为 `<ref_name>` / `` 之类的尖括号表述，并显式回引 `.github/workflows/release.yml:96-100` 让读者拿到原始 yaml。yaml fenced code block 中的原始写法保持不变。
Test plan
关联
Closes part of #167 — Phase 2 文档主体合计 24/24 全部到位。Phase 3 UI 内嵌指南、Phase 1 收尾的 README 减负与英文翻译滚动补齐仍在 issue 中。