196 lines
4.1 KiB
Markdown
196 lines
4.1 KiB
Markdown
# 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
|
||
```
|