doc.kabin.fun 建站手册¶

最后变更：2026-08-05 16:03

金光知识站 doc.kabin.fun 的完整建站/更新/排障手册。最新部署方式：Cloudflare Pages + wrangler deploy（2026-08 起，替代旧 Cloudflare Tunnel 方案）。

架构总览¶

Obsidian/工作/ (源文件 — 编辑权威位置)
  │  mkdocs-build.py 复制 + 过滤 (EXCLUDE_SUBDIRS)
  ▼
mkdocs-content/ (MkDocs 源目录 — 每15分钟被 cron 清空重建)
  │  mkdocs build
  ▼
mkdocs-site/ (静态 HTML 产物)
  │
  └── npx wrangler pages deploy → Cloudflare Pages → doc.kabin.fun (生产)

关键文件¶

文件	作用
`/opt/data/Obsidian/工作/`	Obsidian 源目录（编辑必须在这里）
`/opt/data/mkdocs.yml`	MkDocs 配置 + 导航结构
`/opt/data/scripts/mkdocs-build.py`	内容复制 + 过滤 + 站点构建脚本
`/opt/data/mkdocs-content/`	构建源目录（自动生成，勿手动编辑）
`/opt/data/mkdocs-site/`	输出站点（自动生成，wrangler 部署源）
`/opt/data/scripts/evening_maintenance.sh`	Cloudflare token 实际来源

部署命令¶

cd /opt/data
export CLOUDFLARE_API_TOKEN='<token 见 evening_maintenance.sh>'
export CLOUDFLARE_ACCOUNT_ID='d141b810f1b1dddb703cd686c699200f'
npx wrangler pages deploy /opt/data/mkdocs-site --project-name=doc-kabin-fun

部署完成后返回预览 URL（https://xxxx.doc-kabin-fun.pages.dev），约 1-2 分钟后 doc.kabin.fun 同步
线上验证用 urllib 请求页面，200 即成功

构建命令¶

cd /opt/data

# 全量构建（清空 → 复制 → mkdocs build）
uv run python3 scripts/mkdocs-build.py build

# 仅生成内容（不清空，调试用）
uv run python3 scripts/mkdocs-build.py content

构建成功标志：Documentation built in XX seconds（约 20 秒），无 ERROR。

导航规则¶

导航定义在 mkdocs.yml 的 nav: 段。

每个文件夹用 📋 索引.md 作为该目录的首页（含 type: index frontmatter）
导航标签 = 文件夹名（如 01-Projects），保持与 Obsidian 源一致
新增文件夹 → 在 mkdocs.yml nav 中手动添加条目
主页 index.md 用品牌卡片式（kb-hero + kb-grid 8 卡 + 知识森林），遵循金光品牌视觉规范（#ED1C24/#00A5A1/#2E2928）

排除规则（EXCLUDE_SUBDIRS）¶

mkdocs-build.py 中定义，不发布到站点：

目录	原因
`99-Archive`	归档区
`.obsidian` / `.trash` / `.git`	Obsidian/系统内部
`work-scripts` / `_work-scripts_bak`	脚本区
`assets` / `__pycache__` / `node_modules`	资源/缓存
`_NPR_bak`	备份残留（Archive_Ref 下）

注：待OCR 已于 2026-08-05 删除（任务完成）；采购中心（筹） 2026-08-05 加回站点。

内容过滤规则¶

排除扩展名：.pdf .docx .doc .pptx .ppt .msg .ics .db .exe .msi .zip .rar 等（见脚本 EXCLUDE_EXTS）
排除目录：见上表
wiki 知识库：_wiki/ 下 concepts/、decisions/、entities/ 等正常发布

Cron 自动重建¶

mkdocs-content 每 15 分钟被 cron 清空重建（内容同步）
手动编辑源文件后，等待 cron 或手动 build
编辑源文件前先 pause 相关 cron，改完 rebuild 恢复（防构建中间态）

故障排查¶

症状	原因	处理
预览 URL 200 但 doc.kabin.fun 404	CDN 缓存未刷新	等 1-2 分钟自动同步
build 报错（页面缺失）	mkdocs.yml 导航引用了不存在的文件	检查 nav 路径与源目录一致
导航里看不到某页面	mkdocs.yml 未加 nav 条目	手动加条目
页面内容旧	mkdocs-content 被 cron 重建覆盖	编辑必须到 Obsidian 源目录，等 cron 或手动 build
中文文件名 404	URL 编码问题	用 `urllib.parse.quote(url, safe=":/")` 构造 URL

历史（2026-08 前旧方案）¶

旧方案：Cloudflare Tunnel + cloudflared + /opt/data/start_tunnel.py（HTTP 530 排查）
现方案：Cloudflare Pages + wrangler deploy（更快、更稳，2026-08 起）