docs: 新增 MkDocs 部署文档

涵盖 MkDocs Material 配置、构建流程、Caddy Docker 部署、完整工作流和维护指南
2026-06-04 11:46:27 +08:00
parent 7724af96f5
commit 155b347d3f
3 changed files with 197 additions and 0 deletions
@@ -0,0 +1,195 @@
+# MkDocs 知识库部署
+
+> `note.kurihada.com` — 基于 MkDocs Material 的个人知识库，Caddy 静态文件服务。
+
+---
+
+## 架构
+
+```mermaid
+graph LR
+    Repo["~/kb Git 仓库"]
+    Build["mkdocs build"]
+    Site["kb/site/ 静态文件"]
+    Caddy["Caddy Docker<br/>caddy:alpine"]
+    Browser["浏览器<br/>note.kurihada.com"]
+
+    Repo --> Build --> Site -->|"bind mount :ro"| Caddy --> Browser
+```
+
+整个流程：编辑 Markdown → `mkdocs build` 生成静态文件 → Caddy 直接 serve。
+
+---
+
+## 一、MkDocs 配置
+
+### 1.1 mkdocs.yml 要点
+
+```yaml
+site_name: 我的知识库
+theme:
+  name: material
+  language: zh
+  features:
+    - navigation.instant      # SPA 即时加载
+    - navigation.tabs         # 顶部标签
+    - navigation.indexes      # 分类文件夹可点击
+    - search.suggest          # 搜索建议
+    - content.code.copy       # 代码块复制按钮
+  custom_dir: docs/overrides  # Artalk 评论等自定义模板
+
+markdown_extensions:
+  - pymdownx.superfences:     # Mermaid 流程图支持
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+```
+
+### 1.2 目录结构
+
+```
+~/kb/
+├── mkdocs.yml              # 站点配置
+├── docs/                   # Markdown 源文件
+│   ├── index.md
+│   ├── overrides/          # 主题覆盖（评论系统等）
+│   │   └── partials/
+│   │       └── comments.html
+│   ├── 技术/
+│   ├── 旅行/
+│   ├── 摄影/
+│   ├── 3D打印/
+│   └── 日记/
+├── site/                   # 构建输出（.gitignore 忽略）
+└── .gitignore
+```
+
+---
+
+## 二、构建
+
+### 2.1 本地构建
+
+```bash
+cd ~/kb && mkdocs build
+```
+
+输出到 `site/` 目录，耗时 < 1 秒。
+
+### 2.2 本地预览
+
+```bash
+mkdocs serve -a 0.0.0.0:8000
+```
+
+浏览器打开 `http://localhost:8000`，修改 Markdown 后自动刷新。
+
+### 2.3 Git 工作流
+
+```bash
+cd ~/kb
+mkdocs build                 # 构建
+git add -A
+git commit -m "描述改动"      # 提交 Markdown 源码
+```
+
+> `site/` 已在 `.gitignore` 中忽略，只提交 Markdown 源文件。
+
+---
+
+## 三、Caddy 部署
+
+### 3.1 docker-compose.yml
+
+Caddy 部署在 `~/docker/caddy/`：
+
+```yaml
+services:
+  caddy:
+    image: caddy:alpine
+    container_name: caddy
+    restart: unless-stopped
+    networks:
+      - nginx
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - ./data:/data                         # TLS 证书存储
+      - /home/kurihada/kb/site:/srv/mkdocs:ro  # kb 静态文件
+
+networks:
+  nginx:
+    external: true
+```
+
+### 3.2 Caddyfile 中 kb 的配置
+
+```caddy
+note.kurihada.com {
+    handle_path /artalk* {
+        reverse_proxy artalk:23366
+    }
+    handle {
+        root * /srv/mkdocs
+        file_server
+    }
+}
+```
+
+列一下关键点：
+
+- `root * /srv/mkdocs` — 指向挂载进来的 `site/` 目录
+- `handle_path /artalk*` — Artalk 评论系统反代（详见 [Artalk 部署文档](artalk评论系统.md)）
+- `handle { ... }` — 包裹 `file_server`，保证和 `handle_path` 互斥
+- Caddy 自动申请和续期 Let's Encrypt TLS 证书，无需额外配置
+
+### 3.3 部署后重载
+
+```bash
+docker restart caddy
+```
+
+---
+
+## 四、完整工作流
+
+```
+1. 编辑 docs/ 下的 Markdown
+2. mkdocs build            # 生成 site/
+3. git add -A && git commit # 提交源码
+4. (无需重启 Caddy)         # site/ 通过 bind mount 实时生效
+```
+
+> 因为 Caddy 通过 `bind mount` 直接读取 `~/kb/site/`，`mkdocs build` 后变更即时生效，无需重启任何服务。
+
+---
+
+## 五、维护
+
+### 升级 MkDocs Material
+
+```bash
+pip install --upgrade mkdocs-material
+mkdocs build                # 确认构建无报错
+```
+
+### 检查构建状态
+
+```bash
+cd ~/kb && mkdocs build --verbose
+```
+
+### DNS 与 TLS
+
+- DNS：`note.kurihada.com` A 记录指向服务器 IP
+- TLS：Caddy 自动通过 Let's Encrypt 申请，90 天自动续期
+- 证书存储：`~/docker/caddy/data/`
+
+### Caddy 日志
+
+```bash
+docker logs caddy | grep note.kurihada.com
+```