MkDocs部署docker-compose

以下是用于在 Linux 服务器上部署 MkDocs 的 docker-compose.yml 文件。根据你的需求，这里提供两种方案：开发预览模式和生产构建模式。

方案一：开发预览模式（推荐用于内网文档）

适合服务器上需要实时预览、修改后立即生效的场景。使用 squidfunk/mkdocs-material 官方镜像，它内置了 Material 主题和常用插件。

version: "3.8"

services:
  mkdocs:
    image: squidfunk/mkdocs-material:latest
    container_name: mkdocs
    hostname: mkdocs
    # 使用 serve 命令，绑定 0.0.0.0 确保外部可访问
    command: serve --dev-addr=0.0.0.0:8000
    ports:
      - "8000:8000"
    volumes:
      # 将宿主机文档目录挂载到容器的 /docs
      # 确保宿主机目录中包含 mkdocs.yml 和 docs/ 文件夹
      - ./docs:/docs
    restart: unless-stopped

使用说明：

在服务器上创建目录（例如 /opt/mkdocs），将你的文档项目（包含 mkdocs.yml 和 docs/）放入其中。
将上述 docker-compose.yml 也放在同一目录下。
运行 docker compose up -d，访问 http://服务器IP:8000 即可看到文档站。

方案二：生产构建 + Nginx 托管（推荐用于正式发布）

MkDocs 的 serve 模式是开发预览用的，不适合直接暴露到公网。正式部署应将站点构建为纯静态文件，用 Nginx 提供服务。

version: "3.8"

services:
  # MkDocs 构建服务：将文档构建为静态 HTML
  mkdocs-builder:
    image: squidfunk/mkdocs-material:latest
    container_name: mkdocs-builder
    volumes:
      - ./docs:/docs
      # 构建输出到宿主机当前目录下的 site 文件夹
      - ./site:/docs/site
    # 执行 build 命令后容器即退出
    command: build
    # 只在需要更新时手动运行，不适合常驻
    restart: "no"

  # Nginx 服务：托管构建好的静态文件
  nginx:
    image: nginx:alpine
    container_name: mkdocs-nginx
    ports:
      - "80:80"
    volumes:
      # 将构建产物挂载到 Nginx 的网站根目录
      - ./site:/usr/share/nginx/html:ro
    restart: unless-stopped
    depends_on:
      mkdocs-builder:
        condition: service_completed_successfully

使用说明：

运行 docker compose up，mkdocs-builder 会先执行构建，完成后 nginx 启动并托管静态站点。
更新文档时，只需重新运行 docker compose run --rm mkdocs-builder build 或重启 compose 即可。

关于目录结构

无论哪种方案，你的文档项目目录结构应如下：

/opt/mkdocs/
├── docker-compose.yml
├── docs/                # 你的文档源文件目录
│   ├── index.md
│   └── ...
└── mkdocs.yml           # MkDocs 配置文件

如果 docs/ 中还没有内容，可以先运行以下命令生成脚手架：

docker run --rm -v "$(pwd):/app" -w /app squidfunk/mkdocs-material new .

MkDocs部署docker-compose

部署文件已生成并通过 YAML 语法校验。方案采用两段式部署（构建静态站 + nginx 托管），架构如下：

<html style="margin:0;padding:0;">
<title>MkDocs Docker 两段式部署架构</title>
<div style="width:100%;box-sizing:border-box;max-width:960px;background:#fbfcfe;border:1px solid #e3e8ef;border-radius:12px;padding:16px 18px 14px;font-family:-apple-system,'PingFang SC','Microsoft YaHei',sans-serif;color:#1f2937;">
  <div style="font-size:16px;font-weight:700;margin-bottom:10px;">MkDocs Docker 部署架构（两段式）</div>
  <div style="display:flex;align-items:stretch;gap:0;flex-wrap:wrap;">
    <div style="flex:1.1;min-width:190px;background:#eff6ff;border:1px solid #bfdbfe;border-radius:10px;padding:12px;">
      <div style="font-size:12px;color:#6b7280;margin-bottom:4px;">你的项目目录（构建上下文）</div>
      <div style="font-size:13px;font-weight:700;color:#1e40af;">docs/ + mkdocs.yml</div>
      <div style="font-size:12px;color:#374151;line-height:1.6;margin-top:4px;">Markdown 源文件<br>导航/主题配置</div>
    </div>
    <div style="width:24px;display:flex;align-items:center;justify-content:center;color:#94a3b8;font-size:18px;">→</div>
    <div style="flex:1.2;min-width:190px;background:#f0fdf4;border:1px solid #bbf7d0;border-radius:10px;padding:12px;">
      <div style="font-size:12px;color:#6b7280;margin-bottom:4px;">阶段 1 · 构建（Dockerfile）</div>
      <div style="font-size:13px;font-weight:700;color:#166534;">squidfunk/mkdocs-material</div>
      <div style="font-size:12px;color:#374151;line-height:1.6;margin-top:4px;">mkdocs build 生成静态 HTML → /site</div>
      <div style="font-size:12px;color:#16a34a;font-weight:600;margin-top:3px;">临时构建容器，用完即弃</div>
    </div>
    <div style="width:24px;display:flex;align-items:center;justify-content:center;color:#94a3b8;font-size:18px;">→</div>
    <div style="flex:1.2;min-width:190px;background:#fffbeb;border:1px solid #fde68a;border-radius:10px;padding:12px;">
      <div style="font-size:12px;color:#6b7280;margin-bottom:4px;">阶段 2 · 运行（nginx:alpine）</div>
      <div style="font-size:13px;font-weight:700;color:#92400e;">nginx 托管静态站</div>
      <div style="font-size:12px;color:#374151;line-height:1.6;margin-top:4px;">只含静态文件，镜像极小<br>无 Python/运行时依赖</div>
    </div>
    <div style="width:24px;display:flex;align-items:center;justify-content:center;color:#94a3b8;font-size:18px;">→</div>
    <div style="flex:0.9;min-width:140px;background:#fef2f2;border:1px solid #fecaca;border-radius:10px;padding:12px;">
      <div style="font-size:13px;font-weight:700;color:#991b1b;">[http://localhost:8000](http://localhost:8000)</div>
      <div style="font-size:12px;color:#374151;line-height:1.6;margin-top:4px;">映射 8000:80</div>
    </div>
  </div>
</div>

核心文件内容：

docker-compose.yml

services:
  mkdocs:
    build: .
    image: mkdocs-site:latest
    container_name: mkdocs-site
    restart: unless-stopped
    ports:
      - "8000:80"
    environment:
      TZ: Asia/Shanghai

Dockerfile

# ============ 阶段 1：构建静态站点 ============
FROM squidfunk/mkdocs-material:latest AS builder
WORKDIR /docs
COPY . .
RUN mkdocs build --site-dir /site

# ============ 阶段 2：nginx 托管静态站 ============
FROM nginx:alpine
COPY --from=builder /site /usr/share/nginx/html
EXPOSE 80

使用方式：把 docker-compose.yml、Dockerfile、.dockerignore 放进你的 MkDocs 站点根目录（与 docs/、mkdocs.yml 同级），然后：

docker compose up -d --build   # 构建并启动，访问 [http://localhost:8000](http://localhost:8000)
docker compose up -d --build   # 以后每次改文档，重新构建即可生效

另外 README 里附带了本地预览模式（mkdocs serve 热更新，改文档即时刷新，适合开发期）。整套文件已交付给你：

部署文件已生成并通过 YAML 语法校验。方案采用两段式部署（构建静态站 + nginx 托管），架构如下：

<html style="margin:0;padding:0;">
<title>MkDocs Docker 两段式部署架构</title>
<div style="width:100%;box-sizing:border-box;max-width:960px;background:#fbfcfe;border:1px solid #e3e8ef;border-radius:12px;padding:16px 18px 14px;font-family:-apple-system,'PingFang SC','Microsoft YaHei',sans-serif;color:#1f2937;">
  <div style="font-size:16px;font-weight:700;margin-bottom:10px;">MkDocs Docker 部署架构（两段式）</div>
  <div style="display:flex;align-items:stretch;gap:0;flex-wrap:wrap;">
    <div style="flex:1.1;min-width:190px;background:#eff6ff;border:1px solid #bfdbfe;border-radius:10px;padding:12px;">
      <div style="font-size:12px;color:#6b7280;margin-bottom:4px;">你的项目目录（构建上下文）</div>
      <div style="font-size:13px;font-weight:700;color:#1e40af;">docs/ + mkdocs.yml</div>
      <div style="font-size:12px;color:#374151;line-height:1.6;margin-top:4px;">Markdown 源文件<br>导航/主题配置</div>
    </div>
    <div style="width:24px;display:flex;align-items:center;justify-content:center;color:#94a3b8;font-size:18px;">→</div>
    <div style="flex:1.2;min-width:190px;background:#f0fdf4;border:1px solid #bbf7d0;border-radius:10px;padding:12px;">
      <div style="font-size:12px;color:#6b7280;margin-bottom:4px;">阶段 1 · 构建（Dockerfile）</div>
      <div style="font-size:13px;font-weight:700;color:#166534;">squidfunk/mkdocs-material</div>
      <div style="font-size:12px;color:#374151;line-height:1.6;margin-top:4px;">mkdocs build 生成静态 HTML → /site</div>
      <div style="font-size:12px;color:#16a34a;font-weight:600;margin-top:3px;">临时构建容器，用完即弃</div>
    </div>
    <div style="width:24px;display:flex;align-items:center;justify-content:center;color:#94a3b8;font-size:18px;">→</div>
    <div style="flex:1.2;min-width:190px;background:#fffbeb;border:1px solid #fde68a;border-radius:10px;padding:12px;">
      <div style="font-size:12px;color:#6b7280;margin-bottom:4px;">阶段 2 · 运行（nginx:alpine）</div>
      <div style="font-size:13px;font-weight:700;color:#92400e;">nginx 托管静态站</div>
      <div style="font-size:12px;color:#374151;line-height:1.6;margin-top:4px;">只含静态文件，镜像极小<br>无 Python/运行时依赖</div>
    </div>
    <div style="width:24px;display:flex;align-items:center;justify-content:center;color:#94a3b8;font-size:18px;">→</div>
    <div style="flex:0.9;min-width:140px;background:#fef2f2;border:1px solid #fecaca;border-radius:10px;padding:12px;">
      <div style="font-size:13px;font-weight:700;color:#991b1b;">[http://localhost:8000](http://localhost:8000)</div>
      <div style="font-size:12px;color:#374151;line-height:1.6;margin-top:4px;">映射 8000:80</div>
    </div>
  </div>
</div>

核心文件内容：

docker-compose.yml

services:
  mkdocs:
    build: .
    image: mkdocs-site:latest
    container_name: mkdocs-site
    restart: unless-stopped
    ports:
      - "8000:80"
    environment:
      TZ: Asia/Shanghai

Dockerfile

# ============ 阶段 1：构建静态站点 ============
FROM squidfunk/mkdocs-material:latest AS builder
WORKDIR /docs
COPY . .
RUN mkdocs build --site-dir /site

# ============ 阶段 2：nginx 托管静态站 ============
FROM nginx:alpine
COPY --from=builder /site /usr/share/nginx/html
EXPOSE 80

使用方式：把 docker-compose.yml、Dockerfile、.dockerignore 放进你的 MkDocs 站点根目录（与 docs/、mkdocs.yml 同级），然后：

docker compose up -d --build   # 构建并启动，访问 [http://localhost:8000](http://localhost:8000)
docker compose up -d --build   # 以后每次改文档，重新构建即可生效

另外 README 里附带了本地预览模式（mkdocs serve 热更新，改文档即时刷新，适合开发期）。整套文件已交付给你：

四个文件已交付完毕（路径：mkdocs-docker/ 目录下）：

docker-compose.yml — 部署编排
Dockerfile — 两段式构建（mkdocs-material 构建 → nginx 托管）
.dockerignore — 排除 site/、.git/ 等，加快构建
README.md — 使用说明 + 本地预览模式 + 常见问题

部署三步走：放进站点根目录 → docker compose up -d --build → 访问 [http://localhost:8000](http://localhost:8000)。需要我再加上 HTTPS 反代（Caddy/Traefik）、CI 自动构建或子路径部署的配置吗？

posted @ 2026-09-30 11:33 念槐聚阅读(8) 评论(0) 收藏举报

刷新页面返回顶部

念槐聚:产品规划设计项目管理测试质量过程改进从0到1 从1到∞...

林间暖酒烧红叶石上题诗扫绿苔

MkDocs部署docker-compose

方案一：开发预览模式（推荐用于内网文档）

方案二：生产构建 + Nginx 托管（推荐用于正式发布）

关于目录结构

MkDocs部署docker-compose

公告

念槐聚:产品规划设计 项目管理 测试质量 过程改进 从0到1 从1到∞...

林间暖酒烧红叶 石上题诗扫绿苔

MkDocs部署docker-compose

方案一：开发预览模式（推荐用于内网文档）

方案二：生产构建 + Nginx 托管（推荐用于正式发布）

关于目录结构

MkDocs部署docker-compose

公告

念槐聚:产品规划设计项目管理测试质量过程改进从0到1 从1到∞...

林间暖酒烧红叶石上题诗扫绿苔