# MkDocs 知识库部署
> `note.kurihada.com` — 基于 MkDocs Material 的个人知识库，Caddy 静态文件服务。
---
## 架构
```mermaid
graph LR
Repo["~/kb Git 仓库"]
Build["mkdocs build"]
Site["kb/site/ 静态文件"]
Caddy["Caddy Docker
caddy:alpine"]
Browser["浏览器
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 网络
```bash
docker network create nginx
```
所有通过 Caddy 反代的服务都加入 `nginx` 网络，容器间通过容器名互相访问。
### 3.2 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.3 首次启动
```bash
cd ~/docker/caddy && docker compose up -d
```
启动前确认 `~/kb/site/` 目录存在（需先执行过 `mkdocs build`），否则 bind mount 会创建一个空目录导致 404。
### 3.4 Caddyfile 中 kb 的配置
Caddyfile 开头有全局块配置 Let's Encrypt 通知邮箱：
```caddy
{
email kurihada@qq.com
}
```
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.5 部署后重载
修改 Caddyfile 后重载（两种方式）：
```bash
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
```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
```