S01-A03 · 文档与知识库平台架构

适用读者：要为团队/个人知识库选型并长期维护的人。
前置：S01-B10（Git）、S01-J02（流程）。
版本基线：docsify 4.x、VitePress 1.x、Docusaurus 3.x、Astro 5.x（本博客当前栈）。
覆盖旧文：A-1867（docsify + Git + GitHub + 码云 + 阿里云服务器搭建知识库，118 点）。
新增扩展：E-S01-031（四方案取舍）。
上一篇：S01-A02 · 制品仓库与供应链安全
下一篇：S01-A04 · 工具选型的 ADR 与工程效能度量。

1. 业务目标与约束

目标	判据
内容可查	站内搜索能在 1 秒内出结果；新内容 3 分钟内可被检索
可维护	写文档 = `git commit`，不需要登录后台点按钮
可迁移	换平台时 URL 能 301、内容能整站导出
成本可控	静态托管：近乎零；SSR + 数据库：每月固定成本

约束	影响
内容是否公开	公开 → 静态托管/CDN；内部 → 必须鉴权，静态托管不合适
是否需要评论/登录/权限	需要 → 后端服务，不再是"纯静态站"
是否需要中文搜索	影响方案：Algolia 中文支持一般，自建索引更可控
团队规模	1 人 → 越轻越好；10+ 人 → 构建时长与评审流程要设计

判据一句话："文档是产品还是资产？" 产品（对外获客）→ 追求 SEO/性能/设计；资产（内部知识）→ 追求可维护、可搜索、可控权限。

2. 旧文的真实迁移史（A-1867 的架构价值）

A-1867 记录了一条很典型的演进路线，它的价值不在 docsify，而在于"托管方式的约束如何逼着人换架构"：

阶段	架构	触发变化的原因
①	GitHub 仓库（md + 图片 + docsify 配置）	起点：内容即代码
②	码云 Pages 托管	国内访问 GitHub Pages 慢
③	换自建服务器 + 自定义域名	码云 Pages 不支持自定义域名
④	自建 Nginx 托管静态产物，绑域名	掌控域名、CDN、HTTPS

这条历史给出的结论：

"内容即 Git 仓库"是最值钱的决定——换托管方式时内容一行不用改。
托管平台的限制（自定义域名、HTTPS、访问速度）往往是换架构的真实原因，而不是"技术更先进"。
静态站 + 自建 Nginx 是成本最低的可控方案，代价是要自己管证书与备份。

3. 四方案对比

维度	docsify	VitePress	Docusaurus	Astro（本博客）
渲染方式	浏览器端运行时把 md 转 HTML	构建期生成静态 HTML	构建期生成静态 HTML	构建期（可 SSR）
构建时长（500 篇）	0（无构建）	快（秒级）	中（十几秒~分钟）	中（取决于集成）
SEO	❌ 差（内容不在 HTML 里）	✅	✅	✅
首屏性能	中（要下载 md + JS）	好	好	好
搜索	内置（简单）	内置本地索引 / Algolia	Algolia / 本地	需集成（Pagefind 等）
版本化文档	❌	手动	✅ 内置	插件
生态/插件	少	中	多（文档站专用）	多（通用 Web）
学习成本	最低（会写 md 就行）	低	中	中高
适合	个人笔记、内部 wiki、快速上线	技术文档、开源项目	产品文档、多版本文档	内容站 + 应用混合

结论（按场景）：

场景	选
个人知识库、要"写完就发"	docsify
开源项目文档（要 SEO、要好搜索）	VitePress
产品文档（多版本、多语言、博客+文档）	Docusaurus
内容站与站点其他功能（动态页面、API）同栈	Astro

4. 架构与关键组件

4.1 静态托管型（docsify / VitePress / Docusaurus / Astro 静态）

Git 仓库（md + 配置）
   │  push 触发 CI
   ▼
构建（可选：VitePress/Docusaurus/Astro）
   │  产物：dist/
   ▼
Nginx / CDN（HTTPS、缓存、gzip/brotli）
   ▼
浏览器

组件	关键决策
构建	是否上构建？上构建 = 换来 SEO 与性能，代价是 CI 时长
缓存	静态资源长缓存（`immutable`），HTML 短缓存（避免内容不更新）
搜索	小站：本地索引（Pagefind / docsify 内置）；大站：外部搜索服务
图片	放仓库（小）/ 对象存储 + CDN（大，避免仓库膨胀，见 S01-J01 §6.1）

4.2 需要鉴权的内部文档

静态站没有真正的权限控制（HTML 一旦下发，谁拿到都能看）。内部文档三条路：

方案	说明	代价
反向代理 + SSO（Nginx `auth_request` / OAuth2 Proxy）	静态站外面套一层鉴权	需要 IdP 集成
后端渲染（SSR）+ 会话	权限在服务端判断	有状态，运维成本高
现成平台（Confluence / 飞书文档）	权限开箱可用	内容锁定，迁移困难

判据：文档里有没有"不能给外人看"的内容？ 有 → 不要用裸静态站。

5. 容量与成本估算（量纲估算，非实测）

规模	页面数	月 PV	带宽/月	方案	月成本量级
个人	100–500	1 万	~5 GB	GitHub Pages / Vercel 免费	0
小团队	500–2000	10 万	~50 GB	云主机 + CDN	几十元~百元级
中型	2000+	100 万	~500 GB	CDN + 对象存储	百元~千元级

成本结构：静态托管的主要成本是带宽，不是算力。所以：

图片必须走 CDN + 压缩（WebP/AVIF），否则带宽被图片吃掉；
构建产物不要塞大文件（仓库也会膨胀）。

构建时长（影响"写完多久能看到"）：

页面数	VitePress	Docusaurus	Astro
500	秒级	十几秒	十几秒
5000	十几秒~分钟	分钟级	分钟级

判据：构建超过 5 分钟就要考虑增量构建或拆分站点，否则写文档的人会失去耐心。

6. 迁移与回滚（最容易出事故的部分）

6.1 URL 是契约

变化	影响
路径规则变化（`/a/b.html` → `/a/b/`）	外部链接全 404，SEO 归零
锚点（`#section`）变化	文档内跳转失效
域名变化	需要 301，且要保留至少一年

迁移三件套：

# ① 旧路径 301 到新路径（示例：从 .html 到目录形式）
location ~ ^/(?<p>.+)\.html$ { return 301 /$p/; }

# ② 保留 sitemap 与 RSS 的稳定 URL
# ③ 旧域名整体 301（一年后再考虑下线）
server { server_name old.example.com; return 301 https://new.example.com$request_uri; }

6.2 迁移检查单

旧 URL 清单导出（从 Nginx access log 或 sitemap）
新站 URL 映射表（可脚本生成）
301 规则覆盖 Top 100 访问路径
sitemap 提交搜索引擎
站内搜索索引重建
回滚方案：旧站产物保留，DNS/Nginx 可一键切回

6.3 回滚

层	回滚方式	时间
内容	`git revert` + 重新构建	分钟级
构建产物	保留上一版 `dist`（带时间戳）	秒级（切软链）
域名/证书	保留旧配置	分钟级
平台	旧站并行运行 1 个月	即时

7. 可观测性

指标	采集	阈值
404 率	Nginx 日志	> 5% → 迁移有漏
搜索零结果率	前端埋点	> 20% → 索引/词表有问题
构建时长	CI	> 5 分钟 → 优化
首屏 TTFB / LCP	RUM / Lighthouse	TTFB > 500 ms 查 CDN
证书到期	定时检查	< 30 天告警

搜索零结果率是最被忽略的指标：它直接反映"文档写了但用户找不到"，比 PV 更有诊断价值。

8. 旧文对照

旧文内容（A-1867）	本篇处理
docsify 的目录结构（`index.html`、`_sidebar.md`、md 文件）	§3 归入"运行时渲染"一类；指出 SEO 缺陷是它的根本代价
GitHub 仓库作为内容源	§2 提炼为"内容即 Git 仓库是最值钱的决定"
码云 Pages 托管 + 无法自定义域名	§2 作为"平台限制驱动架构变更"的真实案例保留
自建阿里云服务器 + Nginx + 域名	§4.1 归入静态托管架构；补缓存/搜索/图片三项决策
无	新增 §5 容量成本、§6 迁移回滚（301/sitemap/回滚层）、§7 可观测、§3 四方案横向对比

9. 自测（架构师版）

docsify 与 VitePress 的根本差异是什么？它在什么场景下是"优点"？
内部文档为什么不能用裸静态站？三条替代路径各有什么代价？
迁移文档站时，最先要保护的三样东西是什么？
为什么"搜索零结果率"比"PV"更能反映文档质量？
你会怎么向老板解释"文档站不需要买数据库"？

10. 下一篇

S01-A04 · 工具选型的 ADR 与工程效能度量

四篇架构师文讲了三块（环境、制品、文档），最后一篇讲"怎么把决策本身管起来"：ADR 怎么写、被否方案怎么记、度量指标怎么定才不会变成 KPI 游戏。这一篇同时是本系列的方法论收尾。

本篇属于系列《S01 · 开发环境与工具链》，架构师层第 3 篇。旧文来源：A-1867；扩展点 E-S01-031。