# mkdocs_deploy

**Repository Path**: little77/mkdocs_deploy

## Basic Information

- **Project Name**: mkdocs_deploy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MkDocs（Material）安装与部署脚本

目录：`~/document/mcdoc_install/`（下文 `$MCD` 表示该路径，可按实际安装位置替换）

## 文件说明

| 文件 | 作用 |
|------|------|
| `config.env.example` | 配置模板，复制为 `config.env` |
| `install_env.sh` | 创建 venv，安装 `mkdocs-material` |
| `init_project.sh` | 在 `DOCS_ROOT` 执行 `mkdocs new`，并套用 Material 示例 `mkdocs.yml` |
| `deploy.sh` | 可选预拉取 → `mkdocs build` → rsync；`DEPLOY_CONFIG_ENV` 可指定环境文件 |
| `setup_nginx_docker.sh` | 启动 Nginx 容器：有 Compose 则用 compose，否则自动 `docker run` |
| `docker_nginx.sh` | 供脚本 source：Compose / 纯 docker 共用逻辑，勿直接执行 |
| `docker-compose.yml` | 有 Compose 时使用；服务名 `nginx` |
| `nginx/docker-mkdocs.conf` | 容器内站点配置 |
| `setup_nginx.sh` | **备选**：宿主机 apt 安装 Nginx |
| `link_doc.sh` | 在 `DOCS_ROOT/docs/` 下创建软链 |
| `prefetch_doc_assets.py` | 构建前从上游 raw 补全知识库内缺失的相对资源 |
| `prefetch_assets.yaml.example` | 预拉取配置示例 → 复制为 `prefetch_assets.yaml` |
| `mkdocs.material.yml.example` | Material 示例 `mkdocs.yml` |
| `nginx.example.conf` / `caddyfile.example` | 手工反代参考 |

---

## 场景与示例命令

以下均在 `mcdoc_install` 目录执行（`cd ~/document/mcdoc_install` 或你的 `$MCD`）。

### 场景 1：从零部署（新机器、要跑 Docker Nginx）

```bash
export MCD=~/document/mcdoc_install
cd "$MCD"

chmod +x install_env.sh init_project.sh deploy.sh setup_nginx_docker.sh setup_nginx.sh \
  link_doc.sh prefetch_doc_assets.py

cp config.env.example config.env
# 编辑 config.env：至少检查 DOCS_ROOT、WEB_ROOT、NGINX_HTTP_PORT

./install_env.sh
./init_project.sh
# 编辑 DOCS_ROOT 下的 docs/、mkdocs.yml（含 nav）

./setup_nginx_docker.sh
./deploy.sh
```

浏览器（无域名时）：`http://<本机IP>:8080/`（端口以 `config.env` 里 `NGINX_HTTP_PORT` 为准）。

### 场景 2：已有 MkDocs 工程，只接脚本与发布

```bash
cd ~/document/mcdoc_install
cp config.env.example config.env
```

在 `config.env` 中设置（示例路径请改成你的）：

```bash
export DOCS_ROOT="$HOME/document/mkdocs-docs"
export WEB_ROOT="$HOME/document/mkdocs-site"
export USE_DOCKER_NGINX=1
```

然后：

```bash
./install_env.sh          # 若尚未有 .venv
./setup_nginx_docker.sh   # 首次或改端口/镜像后
./deploy.sh
```

**不要**再执行 `init_project.sh`（会拒绝覆盖已有 `mkdocs.yml`）。

### 场景 3：单次部署时临时覆盖变量（不写进 config.env）

```bash
cd ~/document/mcdoc_install
source config.env 2>/dev/null || true

DOCS_ROOT=/opt/my-docs \
WEB_ROOT=/opt/my-site \
NGINX_HTTP_PORT=5080 \
./deploy.sh
```

仅当次 shell 生效；持久化请写入 `config.env`。

### 场景 4：`mkdocs build --strict` 暂时过不去

持久关闭（写入 `config.env`）：

```bash
echo 'export MKDOCS_STRICT=0' >> ~/document/mcdoc_install/config.env
```

仅本次：

```bash
cd ~/document/mcdoc_install
MKDOCS_STRICT=0 ./deploy.sh
```

### 场景 5：Docker Nginx —— 升级镜像 / 停服务

```bash
cd ~/document/mcdoc_install
source config.env  # 确保 NGINX_IMAGE、NGINX_HTTP_PORT 已加载

./setup_nginx_docker.sh pull    # 改镜像 tag 后：拉取并 up -d
./setup_nginx_docker.sh down    # 停容器（不删 WEB_ROOT）
```

本机**没有** `docker compose` 时，同一脚本仍会走 `docker run`，命令不变。

### 场景 6：不用 Docker，宿主机 apt Nginx

```bash
cd ~/document/mcdoc_install
# config.env 中: export USE_DOCKER_NGINX=0
# WEB_ROOT 与下面脚本写入的 root 一致（如 /var/www/mkdocs-site）

./setup_nginx.sh
# 与 default 站点冲突时：
./setup_nginx.sh --disable-default
```

```bash
./deploy.sh
```

### 场景 6b：只用 rsync 输出静态站，不用 Docker Nginx

适用：已有 **宿主机 Nginx/Caddy**、**反向代理** 或 **对象存储**，只需把 `mkdocs build` 的结果落到目录（或再同步到远端）；不需要 `setup_nginx_docker.sh`。

在环境文件里关闭容器步骤：

```bash
# 写入 config.env（或某份 config.env.*，见场景 10）
export USE_DOCKER_NGINX=0
export WEB_ROOT=/var/www/mkdocs-site   # 与真实 Web root 一致；或仅作本机构建输出目录
```

若 Web 服务在本机且尚未配置站点，可用 apt 版脚本生成 `server` 片段（与「场景 6」相同）：

```bash
cd ~/document/mcdoc_install
./setup_nginx.sh
./deploy.sh
```

**已自行配置** Nginx 时，只需反复：

```bash
cd ~/document/mcdoc_install
./deploy.sh
```

静态资源在**远端主机**时，可在本机构建完成后第二次 `rsync`（路径自行替换）：

```bash
cd ~/document/mcdoc_install
./deploy.sh

rsync -avz --delete \
  "$HOME/document/mkdocs-site/" \
  user@webserver.example.com:/var/www/static/docs/
```

`deploy.sh` 只会同步到本地 **`WEB_ROOT`**；上命令为额外步骤。若 `WEB_ROOT` 已是 NFS/sshfs 挂载到远端，则一次 `./deploy.sh` 即可。

### 场景 10：多份 MkDocs、多套 `config.env`

同一套 `mcdoc_install` 工具链可维护多个站点：为每个 MkDocs 工程准备一份环境文件，部署时用 **`DEPLOY_CONFIG_ENV`** 指向它（`deploy.sh` 已支持）。

初始化多份配置：

```bash
cd ~/document/mcdoc_install
cp config.env.example config.env.wiki
cp config.env.example config.env.internal
```

`config.env.wiki` 示例内容：

```bash
export DOCS_ROOT="$HOME/wiki-mkdocs"
export WEB_ROOT="$HOME/publish/wiki-site"
export PREFETCH_CONFIG="$HOME/document/mcdoc_install/prefetch_assets.wiki.yaml"
export NGINX_HTTP_PORT=8080
export USE_DOCKER_NGINX=1
export NGINX_CONTAINER_NAME=mkdocs-nginx-wiki
```

`config.env.internal` 示例内容：

```bash
export DOCS_ROOT="$HOME/internal-docs"
export WEB_ROOT="$HOME/publish/internal-site"
export PREFETCH_ASSETS=0
export NGINX_HTTP_PORT=8081
export USE_DOCKER_NGINX=1
export NGINX_CONTAINER_NAME=mkdocs-nginx-internal
```

两站**同时**启 Docker Nginx 时，须区分 **`NGINX_HTTP_PORT`** 与 **`NGINX_CONTAINER_NAME`**，且每个容器绑定**各自的 `WEB_ROOT`**（不同目录）。本目录默认只有一份 `docker-compose.yml`；第二套站点可复制整个 `mcdoc_install` 到别目录、或自建第二份 compose / 纯 `docker run`，否则端口与卷会冲突。若两站均 **`USE_DOCKER_NGINX=0`**，只靠 `deploy.sh` 的 rsync 写到不同 `WEB_ROOT`，则无容器冲突问题。

部署指定站点：

```bash
cd ~/document/mcdoc_install
DEPLOY_CONFIG_ENV="$PWD/config.env.wiki" ./deploy.sh
```

```bash
DEPLOY_CONFIG_ENV="$PWD/config.env.internal" ./deploy.sh
```

首次为某站点启动容器时，需让 `setup_nginx_docker.sh` 读到**同一份**变量（该脚本默认只读 `config.env`，不显式支持 `DEPLOY_CONFIG_ENV`）：

```bash
cd ~/document/mcdoc_install
set -a
source ./config.env.wiki
set +a
./setup_nginx_docker.sh
```

或使用一行：

```bash
cd ~/document/mcdoc_install && bash -c 'set -a && source ./config.env.wiki && set +a && ./setup_nginx_docker.sh'
```

`link_doc.sh` / 手动预拉取时，同样 **`source` 对应 `config.env.*`**，保证 `DOCS_ROOT`、`PREFETCH_CONFIG` 与本次站点一致：

```bash
cd ~/document/mcdoc_install
set -a && source ./config.env.wiki && set +a
./link_doc.sh /srv/note.md wiki/笔记.md
./prefetch_doc_assets.py --docs-root "$DOCS_ROOT/docs" --config "$PREFETCH_CONFIG"
```

未设置 `DEPLOY_CONFIG_ENV` 时，默认仍加载 **`$MCD/config.env`**.

### 场景 7：本机预览，不写 WEB_ROOT、不启容器

```bash
source ~/document/mcdoc_install/.venv/bin/activate
export DOCS_ROOT=~/document/mkdocs-docs   # 与 config.env 一致
cd "$DOCS_ROOT"
mkdocs serve -a 0.0.0.0:8000
```

### 场景 8：放行端口（云主机 / ufw 示例）

```bash
# Ubuntu ufw 示例（端口按 NGINX_HTTP_PORT）
sudo ufw allow 8080/tcp
sudo ufw reload
```

---

## `config.env` 变量与示例片段

复制模板后常用项如下（值按环境修改）。

```bash
# Python / 文档根
export MKDOCS_VENV="$HOME/document/mcdoc_install/.venv"
export DOCS_ROOT="$HOME/document/mkdocs-docs"
export WEB_ROOT="$HOME/document/mkdocs-site"

# 构建
export MKDOCS_STRICT=1

# 预拉取（见下节）
export PREFETCH_ASSETS=1
export PREFETCH_CONFIG="$HOME/document/mcdoc_install/prefetch_assets.yaml"
export PREFETCH_STRICT=0

# Docker Nginx
export USE_DOCKER_NGINX=1
export NGINX_HTTP_PORT=8080
export NGINX_IMAGE=nginx:1.27-alpine
```

多站点切换环境文件时，使用 **`DEPLOY_CONFIG_ENV=/绝对路径/config.env.xxx ./deploy.sh`**（变量放在**命令前**，不要写进被 `source` 的 `config.env` 自身）。示例见「场景 10」。

---

## 预拉取 `prefetch_assets.yaml` 与 `prefetch_doc_assets.py`

### 作用摘要

- **`prefetch_assets.yaml`**：配置 **知识库根**、**哪些路径前缀走哪条上游 raw**，见 `prefetch_assets.yaml.example`。
- **不维护缺失清单**：脚本扫描 `docs` 下 `.md`（`followlinks` 进软链），对 **本地不存在** 的相对资源按规则下载到 **知识库真实路径**。
- **无该文件**：`deploy.sh` 仅打印跳过提示，不报错。

### 首次启用

```bash
cd ~/document/mcdoc_install
cp prefetch_assets.yaml.example prefetch_assets.yaml
nano prefetch_assets.yaml   # 或 vim：改 knowledge_root、rules
```

### 仅查看将请求哪些 URL（不写盘、不改 Markdown）

```bash
cd ~/document/mcdoc_install
source config.env 2>/dev/null || export DOCS_ROOT=~/document/mkdocs-docs

./prefetch_doc_assets.py \
  --docs-root "$DOCS_ROOT/docs" \
  --config "$PWD/prefetch_assets.yaml" \
  --dry-run
```

### 单独执行预拉取（不跑 mkdocs）

```bash
cd ~/document/mcdoc_install
source config.env
./prefetch_doc_assets.py \
  --docs-root "$DOCS_ROOT/docs" \
  --config "${PREFETCH_CONFIG:-$PWD/prefetch_assets.yaml}"
```

任一下载失败仍要继续构建时：**不要**加 `--strict`（与下「严格」相反）。

### 预拉取失败即中止（与 CI 对齐）

```bash
./prefetch_doc_assets.py \
  --docs-root "$DOCS_ROOT/docs" \
  --config prefetch_assets.yaml \
  --strict
```

或在 `config.env` 中：

```bash
export PREFETCH_STRICT=1
./deploy.sh
```

### 关闭预拉取

`config.env`：

```bash
export PREFETCH_ASSETS=0
```

或临时：

```bash
PREFETCH_ASSETS=0 ./deploy.sh
```

### 使用非默认的配置路径

```bash
export PREFETCH_CONFIG=/opt/secrets/my-prefetch.yaml
./deploy.sh
```

### 多个 `knowledge_root`（多棵知识库）

- **根级 `knowledge_root`**：未写 `knowledge_root` 的规则共用此根。
- **某条 `rules[]` 内 `knowledge_root:`**：仅该条使用另一绝对路径。

无根级时，**每条** rule 都必须自带 `knowledge_root`。示例：

```yaml
knowledge_root: /home/data/knowledge
rules:
  - path_prefix: ch16-threat-intel/exploitdb/exploitdb
    remote_raw_base: https://raw.githubusercontent.com/offensive-security/exploitdb/main
  - knowledge_root: /data/other-kb
    path_prefix: notes/imported
    remote_raw_base: https://raw.githubusercontent.com/org/other-repo/main
```

规则**自上而下**匹配，更具体的前缀放前面。

### 上游 404 / 规则对不齐时建议命令流

```bash
# 1) 先看 dry-run 的 URL 是否合理
./prefetch_doc_assets.py --docs-root "$DOCS_ROOT/docs" --config prefetch_assets.yaml --dry-run

# 2) 用 curl 抽查一条
curl -sI "https://raw.githubusercontent.com/offensive-security/exploitdb/main/exploits/linux/local/foo.txt"

# 3) 修正 path_prefix / remote_raw_base（如 main 改为 master）后重试
./prefetch_doc_assets.py --docs-root "$DOCS_ROOT/docs" --config prefetch_assets.yaml
```

### 成功下载后保留 `?raw=true` 不写回 Markdown（少见）

```bash
./prefetch_doc_assets.py --docs-root "$DOCS_ROOT/docs" --config prefetch_assets.yaml \
  --no-strip-query
```

---

## 散落 Markdown：软链 `link_doc.sh`

依赖 **`config.env`** 中的 **`DOCS_ROOT`**（或先 export）。

```bash
cd ~/document/mcdoc_install
source config.env

chmod +x link_doc.sh

# 默认：docs/_linked/<文件名>
./link_doc.sh /srv/notes/guide.md

# 指定在 docs 下的相对路径
./link_doc.sh /srv/notes/guide.md myproj/指南.md

# 整目录（含子树 .md）
./link_doc.sh --dir /srv/wiki-batch cyber_knowledge_batch/wiki
```

在 **`DOCS_ROOT/mkdocs.yml`** 的 **`nav`** 里加入脚本打印的相对路径（相对 `docs/`）。

---

## Docker / Compose 说明

- 终端里没有名为 `compose` 的单独命令；应为 **`docker compose`**（插件）或旧版 **`docker-compose`**。
- 安装插件（Debian/Ubuntu）：

```bash
sudo apt-get update && sudo apt-get install -y docker-compose-plugin
docker compose version
```

---

## 依赖

- `python3`、`python3-venv`
- `rsync`
- `docker`（容器 Nginx）；Compose 可选
- 预拉取使用 **`PyYAML`**（随 `mkdocs` / `mkdocs-material` 虚拟环境已有）

---

## 已有项目（不跑 `init_project.sh`）

```bash
cd ~/document/mcdoc_install
cp config.env.example config.env
# 编辑 DOCS_ROOT、WEB_ROOT 等

./install_env.sh
./setup_nginx_docker.sh   # 若用容器
./deploy.sh
```