kurihada
88967a238f
P0（必须修复）: - 技术/index.md: Web 服务 NPM → Caddy，补充服务列表和域名 - 旁路由部署.md: VPS OS CentOS → Debian，补全安装命令 - 旁路由部署.md: 新增 systemd-resolved DNS 端口冲突解决步骤 - mkdocs.yml: 删除冗余 index.md 子项，空分类用简单链接 - artalk评论系统.md: docker-compose.yml 补全环境变量 P1（建议修复）: - Linux.md: 区分旁路由本机 vs 局域网其他机器两种场景 - Android.md: 移除不支持的 Clash Meta，添加私人 DNS 冲突警告 - macOS.md: 终端命令补注视说明占位符需替换 - 旅行/index.md: 添加赛里木湖 2026 游记链接 - mkdocs部署.md: 补充 Docker 网络创建、首次启动、LE 邮箱配置 - artalk评论系统.md: 修正环境变量与配置文件矛盾说明 P2（优化）: - 首页: 添加评论区说明、修正 Immich 链接为公网域名 - 旁路由部署.md: 加固有章节目录（无锚点纯文本） - 摄影/3D打印/日记 index.md: 充实引导内容 - 新增 Immich 部署文档 - 统一 callout 风格: ?> 改为 !!! tip - GitHub Stars 加时间限定 (截至 2026 年 6 月)
225 lines
4.8 KiB
Markdown
225 lines
4.8 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 网络
|
||
|
||
```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
|
||
```
|