notebook/docs/技术/mkdocs部署.md

MkDocs 知识库部署

note.kurihada.com — 基于 MkDocs Material 的个人知识库，Caddy 静态文件服务。

---

架构

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 要点

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 本地构建

cd ~/kb && mkdocs build

输出到 site/ 目录，耗时 < 1 秒。

2.2 本地预览

mkdocs serve -a 0.0.0.0:8000

浏览器打开 http://localhost:8000，修改 Markdown 后自动刷新。

2.3 Git 工作流

cd ~/kb
mkdocs build                 # 构建
git add -A
git commit -m "描述改动"      # 提交 Markdown 源码

site/ 已在 .gitignore 中忽略，只提交 Markdown 源文件。

---

三、Caddy 部署

3.1 前置：创建 Docker 网络

docker network create nginx

所有通过 Caddy 反代的服务都加入 nginx 网络，容器间通过容器名互相访问。

3.2 docker-compose.yml

Caddy 部署在 ~/docker/caddy/：

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.3 首次启动

cd ~/docker/caddy && docker compose up -d

启动前确认 ~/kb/site/ 目录存在（需先执行过 mkdocs build），否则 bind mount 会创建一个空目录导致 404。

3.4 Caddyfile 中 kb 的配置

Caddyfile 开头有全局块配置 Let's Encrypt 通知邮箱：

{
    email kurihada@qq.com
}

kb 站点的配置：

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 部署文档）
• handle { ... } — 包裹 file_server，保证和 handle_path 互斥
• Caddy 自动申请和续期 Let's Encrypt TLS 证书，无需额外配置

3.5 部署后重载

修改 Caddyfile 后重载（两种方式）：

docker restart caddy                        # 简单粗暴，短暂中断
docker exec caddy caddy reload --config /etc/caddy/Caddyfile  # 零停机

---

四、完整工作流

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

pip install --upgrade mkdocs-material
mkdocs build                # 确认构建无报错

检查构建状态

cd ~/kb && mkdocs build --verbose

DNS 与 TLS

• DNS：note.kurihada.com A 记录指向服务器 IP
• TLS：Caddy 自动通过 Let's Encrypt 申请，90 天自动续期
• 证书存储：~/docker/caddy/data/

Caddy 日志

docker logs caddy | grep note.kurihada.com