MkDocs 站点部署¶

预计阅读时长 : 8 分钟

MkDocs 本质上是一个用于构建静态网站的工具，它通过将 Markdown 文档转换为 HTML 页面来实现对外发布。

按照官方指南的建议，MkDocs 的站点部署推荐使用 Github 集成，这样就可以利用 Github 的 Pages 服务来托管静态网站。但是，身在国内环境下，使用 Github 必然导致访问速度慢，甚至无法访问。

所以，国内网络环境下的最佳实践是构建 MkDocs 的 Docker 容器，然后映射文档所在的目录，并通过 Drone 的 Webhook 机制来触发构建和发布。

构建 Docker 镜像¶

构建 Docker 的镜像的基础是 Material for MkDocs insider 版本，这个版本是以 Github Sponsor 方式收费的，如果有需要可以根据自己的实力进行赞助获取访问权限。

除了默认的代码外，这个镜像中我们还需要补充安装 mkdocs.yml 文件中用到的依赖包（也就是配置文件中提到的各种插件）。

以下常用的依赖包需要添加到 user-requirements.txt 文件中。

插件列表

beautifulsoup4
cairosvg
jieba
neoteroi-mkdocs
pillow
termynal
mdx_truly_sane_lists
mergedeep
mkdocstrings
mkdocstrings-python
mkdocs-asciinema
mkdocs-badges
mkdocs-encryptcontent-plugin
mkdocs-git-revision-date-localized-plugin
mkdocs-glightbox
mkdocs-img2figv2-plugin
mkdocs-image-formatter-plugin
mkdocs-link-marker
mkdocs-link-preview-plugin
mkdocs-literate-nav
mkdocs-macros-plugin
mkdocs-mermaid2-plugin
mkdocs-markmap
mkdocs-meta-descriptions-plugin
mkdocs-minify-plugin
mkdocs-open-in-new-tab
mkdocs-kroki-plugin
mkdocs-resize-images
mkdocs-redirects
mkdocs-revealjs
mkdocs-toggle-sidebar-plugin
mkdocs-video

跨平台构建

构建镜像最常用的方法是使用手动构建，先在本地进行编译构建，然后复制到 VPS 上之后再进行导入。

由于构建的过程在 Mac arm64 设备平台上执行，因此需要使用 docker buildx 命令来构建指定平台（主要是 amd64）的镜像。

docker buildx build --platform linux/amd64 -t mkdocs-material:20241114-amd64 .

然后，我们需要将镜像打包成压缩包，并上传到服务器上。

docker save -o mkdocs-material:20241114-amd64.tar mkdocs-material:20241114-amd64

在服务器上，我们需要将压缩包解压，并导入到 Docker 中。

docker load -i mkdocs-material:20241114-amd64.tarba

不过，由于我们会使用 Drone 来完成全部的自动化部署工作，因此这个手动构建的过程可以省略，仅供参考。

创建 Docker 容器¶

准备好了 Dcoker 镜像的源代码之后，我们接下去来创建容器使用的 docker-compose.yml 文件。

为了兼顾本地和服务器两个环境，我们为容器配置了两套 docker-compose.yml 文件。

两者之间的主要差别是使用的镜像不同，以及文档的映射目录不同。

本地部署服务器部署

docker-compose.yml
services:
  mkdocs:
    image: mkdocs:20241114-arm64
    container_name: mkdocs_libukai
    ports:
      - "8005:8000"
    restart: always
    network_mode: bridge
    volumes:
      - .:/docs
    environment:
      - TZ=Asia/Shanghai
      - CI=${CI}

docker-compose.deploy.yml
services:
  mkdocs:
    image: mkdocs:latest-amd64
    container_name: mkdocs_libukai
    ports:
      - "8005:8000"
    volumes:
      - /home/git/mkdocs/libukai:/docs
    environment:
      - TZ=Asia/Shanghai
      - CI=${CI}
    restart: always
    network_mode: bridge

使用 Drone 自动化部署¶

通过在 VPS 上部署 Drone 服务，并集成 Github 作为远端存储库，我们可以实现文档的全自动化部署。

创建项目并激活¶

首先，推送文档项目到 Github 上创建远程存储库，然后在 Drone 中激活项目并在配置中打开 Trusted 选项。

然后，在项目中新建一个 .drone.yml 文件，并添加以下内容：

同步更新脚本
kind: pipeline
type: docker
name: sync-libukai

trigger:
  branch:
    - main
  event:
    - push
    - cron

steps:
  - name: sync-repo
    image: alpine/git
    volumes:
      - name: docs-directory
        path: /docs
    commands:
      - cd /docs
      - git config --global --add safe.directory /docs
      - git fetch origin main
      - git reset --hard origin/main

volumes:
  - name: docs-directory
    host:
      path: /home/git/mkdocs/libukai

初始化目标目录¶

接下去，我们需要在 VPS 上初始化目标目录，并绑定远程存储库。

首先，创建项目目录，需要和 Drone 中配置的 docs-directory 目录一致。

1	`mkdir -p /home/git/mkdocs/libukai`

然后，进入目录中初始化 Git 本地存储库，并添加远程存储库。

git init
git remote add origin https://github.com/libukai/awesome.git

推送更新文档内容¶

然后，我们就可以推送文档更新到 Github，并触发在 VPS 上触发 Drone ，完成自动化的部署和更新。

在一步当中，最终的效果是让 VPS 上的文档目录保持和本地/Github 上的文档目录完全一致。

构建并更新容器¶

最后，我们使用推送 MdDocs 源代码项目的方式，来使用 Drone 构建容器并更新 Docker 容器。

kind: pipeline
type: docker
name: mkdocs-docker-build

steps:
  - name: build-docker-image
    image: docker
    volumes:
      - name: docker_socket
        path: /var/run/docker.sock
      - name: aikebang
        path: /aikebang
      - name: libukai
        path: /libukai
    commands:
      - cd /aikebang
      - docker-compose -f docker-compose.deploy.yml down
      - cd /libukai
      - docker-compose -f docker-compose.deploy.yml down
      - cd /aikebang
      - docker-compose -f docker-compose.deploy.yml up -d --force-recreate
      - cd /libukai
      - docker-compose -f docker-compose.deploy.yml up -d --force-recreate
      - docker image prune -f

volumes:
  - name: docker_socket
    host:
      path: /var/run/docker.sock
  - name: aikebang
    host:
      path: /home/git/mkdocs/aikebang
  - name: libukai
    host:
      path: /home/git/mkdocs/libukai

代理设置

在构建 Docker 镜像时，如果需要使用代理，可以在 commands 中的 docker build 命令中添加代理参数：

docker build --build-arg HTTP_PROXY=http://xxx.xxx.xxx.xxx:xxxxx --build-arg HTTPS_PROXY=http://xxx.xxx.xxx.xxx:xxxxx --build-arg NO_PROXY=localhost,drone-server,drone-agent -t mkdocs:latest-amd64 .

然后，当我们进行推送更新时，Drone 会自动触发镜像的重新构建，并且更新 MdDocs 服务对应容器中的镜像。