文档库管理策略（docs-as-code 决策记录）¶
用途：回答"文档该散落文件夹 + git 管控，还是部署文档管理系统"的选型问题，并给出落地路线。 结论速览：Markdown + Git 为唯一事实源，部署轻量只读浏览站（MkDocs Material）作辅助；不引入重型文档系统。 目录：
F:\EricLiu\Docs\DocOps\创建：2026-11-11
1. 方案对比¶
| 方案 | 说明 | AI 友好度 | 版本化 | 部署成本 | 评价 |
|---|---|---|---|---|---|
| A. 文件夹 + Git（现状） | Markdown 散落在 Docs/AppDocs，git 管版本 | ★★★（grep/读写最自然） | ★★★ | 零 | 必须保留：事实源 |
| B. Git + 静态站点（MkDocs Material） | 从 Markdown 构建只读浏览站，带全文搜索/导航 | ★★★（不改写文件） | 继承 Git | 低（容器一键） | 推荐：浏览层 |
| C. Git + Wiki（Wiki.js / Outline） | 在线编辑 + git 后端存储 | ★★☆（写入格式受编辑器影响） | 继承 Git | 中 | 选备：多人协作时再上 |
| D. 文档管理系统（Confluence/语雀/SharePoint） | 独立平台，自有存储格式 | ★☆☆（AI 只能走 API，导出困难） | 平台自有 | 高（许可/运维/绑定） | 不推荐 |
2. 推荐结论与理由¶
结论：A + B 组合（docs-as-code 最佳实践）。
- AI 协作是第一约束：本库的核心用法是"AI 助手直接读写指导实验"。纯 Markdown + 文件夹结构让 AI 可以 grep/编辑/对比，任何数据库型文档系统都会显著降低 AI 效率——这是放弃 D 的决定性理由。
- Git 是版本化与回滚的根基：实验报告、经验库、SOP 都需要"谁在何时为何改了"，git diff/log 天然满足；且与 labs\ 代码同仓库管理，实验可复现。
- 浏览站只做"只读增强"：MkDocs Material 提供全文搜索、目录导航、标签页——解决"文档多了找不方便"的唯一痛点，但写入永远走文件 + git，避免双事实源。
- 不选重型系统的理由：许可成本、平台绑定、AI 只能走受限 API、导出迁移困难；且单人+AI 场景用不到其协作特性。
3. 落地路线（2026-11-11 定案执行）¶
定案：远程仓库用 Gitee 私有仓 ops-lab（不自建 Gitea，省一套运维）；浏览站 docs.nopcloud.com 部署在云服务器容器。
第 1 步（已完成） F:\EricLiu 全库 git init，.gitignore 排除 Envs\tmp\models\site 等
第 2 步（已完成） Gitee 创建私有仓库 ops-lab，本地 commit 后 push
第 3 步（本次） 部署：服务器 113.45.32.102 上用 nginx 容器托管 mkdocs build 产物，
绑定 docs.nopcloud.com（已解析）；后续随阶段完结更新
第 4 步（按需） 若未来多人协作/在线编辑需求出现，再评估 Wiki.js（git 后端模式）
认证方式：本机与服务器之间用 SSH key，不用密码（首次手动执行一次
ssh-copy-id后废弃密码）；密码不得写入任何文档与脚本。
4. git 管控细则（本库约定）¶
- 提交纪律：每个实验收尾（七步循环第⑦步后）commit 一次；文档批量更新单独 commit。
- .gitignore 必含：
labs/models/（模型权重）、*.wav、*.tar.gz、.vagrant/、tmp/、site/（MkDocs 构建产物）。 - 分支策略：单人学习场景 main 直推即可；大改（如路线图重构）开分支合并。
- 备份：Gitea 数据目录纳入 1Panel 备份计划；重要里程碑打 tag（如
v1.0-文档库建成）。
5. 市面类似的开源文档库与可借鉴点（调研日期 2026-11-11）¶
5.1 可对标的开源项目/知识库¶
| 名称 | 类型 | 对本库的参考价值 |
|---|---|---|
| GitLab Handbook（handbook.gitlab.com，全公开） | handbook-first 公司手册 | "一切决策进手册"的组织方式；公开可抄其信息架构 |
| Diátaxis（diataxis.fr） | 文档分类框架 | 教程/操作指南/参考/解释四分法——可用于校验分册内容是否放错段落 |
| trimstray/the-book-of-secret-knowledge（200k+ ★） | cheatsheets 大全 | 索引组织方式：按"工具/一行命令/手册"分类，检索优先 |
| bregman-arie/devops-exercises（85k+ ★） | 题库式学习库 | "问答+解析"形式可借鉴进里程碑自测与错题本 |
| LeCoupa/awesome-cheatsheets、christianlempa/cheat-sheets | 速查手册集 | 单页 cheatsheet 的密度控制（一页解决一类问题） |
| jaywcjlove/linux-command | 中文 Linux 命令库 | 中文命令速查的排版与检索（550+ 命令） |
| Kubernetes 官方文档（github.com/kubernetes/website） | 大型 docs-as-code 实践 | 版本化多分支（v1.3x 分支）、changelog 规范、API 参考自动生成 |
| Awesome Knowledge Infrastructure（thedelisle） | 知识基础设施精选清单 | 全景图：docs-as-code/ADR/搜索/RAG 等，找工具先查它 |
| linux-admin2026 等 runbook 仓库 | 运维 runbook 集合 | 按故障现象组织的排障文件命名（service-failures/lvm-troubleshooting） |
5.2 业界最佳实践 → 本库已具备 / 待借鉴¶
| 业界实践 | 本库状态 |
|---|---|
| Docs as Code（Markdown+Git 唯一事实源） | ✅ 已具备（本文件定案） |
版本基线/新鲜度（front-matter 标 last_verified_at，CI 检查过期） |
✅ 等价实现（分册头部"版本基线行"+ 出关核对规则；暂不引 CI，人工核对） |
| 复用资产索引（runbook 按症状组织、受控标签） | ✅ 已具备（Reusable + INDEX 受控词表） |
| ADR（架构决策记录：上下文/决策/备选/后果） | ⚠️ 部分具备——分册"推荐结论"有备选与理由；重大机制变更（如路线图重构）可补 ADR 文件，放 DocOps\adr\ |
| Diátaxis 四分法校验 | ⚠️ 可借鉴——新建分册时检查：命令速查（参考）与实验步骤（how-to）不要混写 |
| handbook-first（先写文档再做事） | ✅ 精神已体现（先读守则再操作） |
| 全文搜索浏览站 | 📋 计划中（§3 落地路线第 3 步 MkDocs） |
5. 发布 SOP（阶段完结时的标准流程，Roadmap §1"阶段完结发布"第③步展开）¶
① 本机构建： D:/python/python312/python.exe tools\build_site.py # 暂存 md → .mkdocs\docs\ 并生成 nav
D:/python/python312/python.exe -m mkdocs build --strict # 产物在 .mkdocs\site\
② 推送仓库： git add -A && git commit -m "..." && git push origin main
③ 上传站点： scp -r .mkdocs/site/* root@113.45.32.102:/opt/docs-site/
（服务器端 nginx 容器挂载 /opt/docs-site，绑定 docs.nopcloud.com:80）
④ 验证： curl -s -o /dev/null -w "%{http_code}" https://docs.nopcloud.com/ 返回 200，
抽查 1-2 篇新页面内容与本地一致
- 服务器部署形态：
nginx:alpine容器，-v /opt/docs-site:/usr/share/nginx/html:ro -p 80:80；HTTPS 后续用 certbot/acme 补证书（443 起用时 80 跳转）。 tools\build_site.py负责：把Docs\+AppDocs\的 md（排除 labs\models、大文件）暂存到.mkdocs\docs\、自动生成 nav、写 site_url/repo_url。- 构建失败（strict 模式链接断开）先修复再发布，不带病上线。
6. 更新记录¶
| 日期 | 变更 |
|---|---|
| 2026-11-11 | 建立：确定 docs-as-code 路线（Markdown+Git 事实源 + MkDocs 浏览层），拒绝重型文档系统 |
| 2026-11-11 | 新增 §5：9 个市面开源文档库对标（GitLab Handbook/Diátaxis/Book of Secret Knowledge/devops-exercises/linux-command 等）+ 业界实践对照表（已具备/待借鉴） |
| 2026-11-11 | 定案执行：远程仓库 Gitee 私有仓 ops-lab（弃自建 Gitea）；新增 §5 发布 SOP（build→push→scp→curl 验证）；新增规则"每步骤后即时更新记录"联动（Docs 总纲规则 8） |