跳转至

编写GitHub Actions工作流实现MkDocs网站自动化部署到云服务器

约 3273 个字 • 167 行代码

由于之前Gitee停止了Pages服务，国内访问Github Pages页面比较慢，所以想将用MkDocs生成的blog网页部署到之前买的云服务器上（就能方便在国内进行访问）。但是blog又不时会进行更新，所以询问DeepSeek是否有比较方便的部署方法

对话记录

You:

mkdocs-material如何将生成的网页部署到云服务器上？

 

DeepSeek:

已深度思考（用时 39 秒）

嗯，我现在需要把用mkdocs-material生成的网站部署到云服务器上。我之前用过mkdocs-material来写文档，生成了静态网站，现在要放到云服务器上让别人也能访问。不过我对这个过程不太熟悉，得一步步来想。

首先，我应该确认生成的网站文件在哪里。mkdocs build之后默认是在site目录下对吧？所以生成的是静态文件，像HTML、CSS、JS这些。接下来，我需要把这些文件上传到云服务器上。云服务器的话，可能用的是阿里云、腾讯云或者AWS之类的，不管哪个，应该都需要通过SSH连接上去操作。

然后，云服务器上需要安装一个Web服务器软件，比如Nginx或者Apache。我之前用过Nginx，可能更熟悉一点。所以步骤大概是：在服务器上安装Nginx，配置服务器块（server block），把网站文件放到Nginx的默认目录，比如/var/www/html/下面，然后设置权限，重启Nginx服务。

不过具体的步骤可能需要注意几点。比如，服务器需要开放80和443端口，确保防火墙设置允许HTTP和HTTPS流量。如果使用域名的话，可能还需要配置DNS解析，把域名指向服务器的IP地址。另外，可能需要申请SSL证书，用Let's Encrypt来启用HTTPS，这样更安全。

还有，上传文件到服务器的方法，可以用scp命令或者rsync，比如从本地把site目录下的所有文件传到服务器的/var/www/html/目录下。比如执行 scp -r site/* user@server_ip:/var/www/html/。不过要确保服务器上的目录正确，并且有写入权限。

或者，可能使用Git来管理，在服务器上配置Git钩子，当本地push到服务器时自动拉取文件并部署。不过可能对于静态网站来说，直接scp更简单。

另外，服务器上的文件权限问题，可能需要把文件的所有权改为Nginx的用户，通常是www-data或者nginx用户，避免权限问题导致无法访问。

可能还需要检查Nginx的配置文件，确保root目录指向正确的路径，并且处理了index.html和其他文件的访问规则。如果有多个站点，可能需要配置虚拟主机。

不过，我是不是漏掉了什么步骤？比如生成静态文件是否正确，服务器上的Nginx是否已经正确安装并运行，防火墙设置是否正确，域名解析是否生效，还有是否需要配置重定向或者缓存之类的。

或者，是否可以使用自动化工具，比如GitHub Actions或者GitLab CI/CD，在代码提交后自动构建并部署到服务器？不过这可能属于更高级的持续部署流程，对于刚开始可能手动上传更简单。

总结一下步骤应该是：

  1. 本地使用mkdocs build生成静态网站到site目录。

  2. 确保云服务器已经安装并运行了Nginx或Apache。

  3. 配置服务器的防火墙，开放HTTP/HTTPS端口。

  4. 使用scp或rsync将site目录下的文件上传到服务器的Web目录。

  5. 设置服务器上的文件权限，确保Web服务器有读取权限。

  6. 配置Nginx的服务器块，指定正确的root目录和域名。

  7. 重启Nginx服务使配置生效。

  8. 测试访问，可能还需要设置域名解析和HTTPS。

可能遇到的错误包括权限问题，比如上传的文件属于普通用户，而Nginx没有权限读取；或者Nginx配置错误，比如root路径写错，或者端口被占用；防火墙没有开放端口导致无法访问；还有可能域名解析未生效，导致无法通过域名访问。

需要逐一检查这些步骤，确认每个环节都正确。例如，上传文件后，可以登录服务器检查文件是否存在，权限是否正确；用curl localhost看看服务器是否返回正确的页面；检查Nginx的error日志查找问题原因。

另外，如果使用Apache的话，步骤类似，但配置方式不同，可能需要编辑虚拟主机文件，启用站点，重启Apache服务。

总之，关键步骤是生成静态文件、上传到服务器、配置Web服务器、处理权限和网络设置，最后测试访问。

将使用mkdocs-material生成的静态网站部署到云服务器的步骤如下：

1. 生成静态网站文件

在本地项目目录执行：

mkdocs build

生成的静态文件位于 site/ 目录。

2. 准备云服务器环境

  • 连接到服务器：使用SSH登录：

    ssh username@server_ip

  • 安装Web服务器（以Nginx为例）：

    sudo apt update && sudo apt install nginx -y

  • 配置防火墙：

    sudo ufw allow 'Nginx Full'  # 允许HTTP(80)和HTTPS(443)

3. 上传文件到服务器

  • 使用SCP上传（本地终端执行）：

    scp -r site/* username@server_ip:/var/www/html/

    或使用 rsync 增量同步：

    rsync -avz site/ username@server_ip:/var/www/html/

4. 配置Nginx

  • 编辑默认站点配置：

    sudo nano /etc/nginx/sites-available/default

    修改 root 路径并配置域名（示例）：

    server {
    listen 80;
    server_name your_domain.com;
    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

  • 检查配置并重启Nginx：

    sudo nginx -t          # 检查语法
sudo systemctl restart nginx

5. 设置文件权限

确保Nginx有权限访问文件：

sudo chown -R www-data:www-data /var/www/html/
sudo chmod -R 755 /var/www/html/

6. 配置域名和HTTPS（可选）

  • 域名解析：在DNS服务商处将域名A记录指向服务器IP。

  • 安装SSL证书（使用Certbot）：

    sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your_domain.com

7. 验证访问

  • 浏览器访问 http://server_ip 或 https://your_domain.com。

  • 若出现错误，检查Nginx日志：

    sudo tail -f /var/log/nginx/error.log

自动化部署（可选）

使用CI/CD工具（如GitHub Actions）自动化构建和部署：

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: mkdocs build
      - name: Deploy to Server
        uses: appleboy/scp-action@v0.1.3
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_KEY }}
          source: "site/*"
          target: "/var/www/html"

常见问题排查

  • 权限问题：确保 /var/www/html 归属 www-data。
  • Nginx配置错误：运行 sudo nginx -t 检查配置。
  • 端口冲突：确保无其他程序占用80/443端口。
  • 缓存问题：浏览器强制刷新（Ctrl+F5）或清除缓存。

完成以上步骤后，你的mkdocs-material网站即可通过云服务器访问。

 

You:

你可以给我详细介绍一下如何进行“自动化部署”吗？（利用github actions）

 

DeepSeek:

已深度思考（用时 23 秒）

好的，用户之前已经询问过如何将mkdocs-material生成的网站部署到云服务器，现在他特别想了解如何通过GitHub Actions实现自动化部署。我需要详细解释这一部分，但首先得理解他的需求。

用户可能已经按照之前的步骤手动部署过，现在想自动化，节省时间，减少错误。他可能是个开发者，或者刚开始接触CI/CD，需要一步步的指导。需要确保提供的步骤清晰，并且涵盖常见问题。

首先，我应该回顾一下GitHub Actions的基本概念，比如工作流文件的结构、触发条件、步骤等。然后具体到部署mkdocs项目，需要安装依赖，构建静态网站，然后传输到服务器。用户可能对SCP或者rsync比较熟悉，但GitHub Actions需要特定的action，比如appleboy/scp-action，或者其他方法如SSH。

需要注意安全，比如如何存储敏感信息如服务器IP、用户名、SSH密钥。这时候需要介绍GitHub Secrets的设置，确保用户不会将敏感信息暴露在代码库中。

另外，用户可能关心后续的维护，比如如何触发部署，是否只在主分支推送时触发，或者是否需要处理多个环境。可能还需要提到如何处理构建失败的情况，或者添加通知机制。

需要详细解释每个步骤的作用，例如安装Python和mkdocs-material，构建站点，然后使用SCP上传。同时，可能要考虑rsync作为替代方案，因为如果站点文件较多，rsync可能更高效。

用户可能遇到的问题包括权限问题，比如服务器上的目录权限是否正确，或者SCP上传时路径错误。此外，防火墙设置是否正确，SSH连接是否允许，这些都需要在注意事项中提到。

最后，可能需要提供一个完整的YAML示例，并解释每个部分的含义，让用户可以复制粘贴并根据自己的情况修改。同时，提醒用户替换占位符，如域名、服务器路径等。

总结下来，回答的结构应该是：先介绍GitHub Actions的基本概念，然后分步骤详细说明如何配置工作流文件，设置Secrets，处理构建和部署步骤，最后提供常见问题排查和优化建议。确保内容全面，易于理解，同时避免技术术语过于复杂，适合不同层次的用户。

以下是利用 GitHub Actions 实现 MkDocs 网站自动化部署的详细步骤：

1. 准备工作

1.1 本地项目配置

  • 确保项目已推送到 GitHub 仓库。
  • 在项目根目录创建 .github/workflows/deploy.yml 文件（用于定义自动化流程）。

1.2 服务器端准备

  • 服务器已安装并运行 Web 服务（如 Nginx/Apache），且静态文件目录为 /var/www/html（默认路径）。
  • 服务器已开启 SSH 服务，并允许通过密钥对登录（推荐使用密钥认证，而非密码）。

2. 配置 GitHub Secrets

在 GitHub 仓库中存储敏感信息（如服务器 IP、SSH 私钥）：

  1. 进入仓库页面，点击 Settings → Secrets → Actions → New repository secret。
  2. 添加以下 Secrets：
    • SERVER_IP：云服务器的公网 IP 地址。
    • SERVER_USER：服务器登录用户名（如 root 或 ubuntu）。
    • SSH_KEY：本地生成的 SSH 私钥（用于登录服务器）。

如何生成 SSH 密钥对？

  • 本地生成密钥：

    ssh-keygen -t ed25519 -C "your_email@example.com"

  • 将公钥（id_ed25519.pub）添加到服务器的 ~/.ssh/authorized_keys 文件。

  • 将私钥（id_ed25519）的内容复制到 GitHub Secrets 的 SSH_KEY 字段。

3. 编写 GitHub Actions 工作流

编辑 .github/workflows/deploy.yml 文件，内容如下：

name: Deploy MkDocs Site
on:
  push:
    branches: [ "main" ]  # 仅在 main 分支推送时触发

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest  # 使用 GitHub 提供的 Ubuntu 环境

    steps:
      # 步骤 1：拉取代码到虚拟环境
      - name: Checkout Repository
        uses: actions/checkout@v4

      # 步骤 2：安装 Python 和 MkDocs
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      # 步骤 3：安装 MkDocs 及主题插件
      - name: Install Dependencies
        run: |
          pip install mkdocs-material
          pip install mkdocs-redirects  # 可选：安装其他插件

      # 步骤 4：构建静态网站
      - name: Build Site
        run: mkdocs build --strict

      # 步骤 5：通过 SCP 上传到服务器
      - name: Deploy to Server
        uses: appleboy/scp-action@v0.1.3
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_KEY }}
          source: "site/*"          # 本地构建的目录
          target: "/var/www/html"   # 服务器目标路径
          overwrite: true            # 覆盖旧文件

4. 工作流详解

关键步骤说明

  1. 触发条件 (on.push)：

    • 当代码推送到 main 分支时自动触发流程。

  2. 虚拟环境 (runs-on)：

    • 使用 GitHub 托管的 Ubuntu 服务器环境。

  3. 依赖安装：

    • 安装 Python 和 MkDocs 插件，确保与本地环境一致。

  4. 文件传输：

    • 使用 appleboy/scp-action 将 site/ 目录下的文件上传到服务器的 /var/www/html。

    • 若需增量同步（仅传输修改的文件），可使用 rsync 替代 SCP：

      - name: Deploy via Rsync
  uses: burnett01/rsync-deployments@5.2.3
  with:
    switches: -avz --delete
    path: site/
    remote_path: /var/www/html/
    remote_host: ${{ secrets.SERVER_IP }}
    remote_user: ${{ secrets.SERVER_USER }}
    remote_key: ${{ secrets.SSH_KEY }}

5. 高级配置

5.1 自定义域名和 HTTPS

  • 在服务器上配置 Nginx 并绑定域名（参考之前的步骤）。
  • 使用 Certbot 自动续签 SSL 证书，或在 GitHub Actions 中集成 Let's Encrypt。

5.2 多环境部署

为 dev/prod 环境配置不同的目标目录：

target: |
  {% if github.ref == 'refs/heads/main' %}
    /var/www/prod
  {% else %}
    /var/www/dev
  {% endif %}

5.3 添加部署后检查

在流程末尾添加 HTTP 状态检查：

- name: Check Site Availability
  run: |
    curl -sSfL http://${{ secrets.SERVER_IP }} > /dev/null
    echo "Deployment successful!"

6. 常见问题排查

6.1 SSH 连接失败

  • 检查服务器的 sshd_config 是否允许密钥登录：

    sudo nano /etc/ssh/sshd_config
# 确保以下配置存在：
PubkeyAuthentication yes
PasswordAuthentication no

  • 重启 SSH 服务：

    sudo systemctl restart sshd

6.2 文件权限问题

确保服务器目标目录权限正确：

sudo chown -R $USER:www-data /var/www/html
sudo chmod -R 755 /var/www/html

6.3 查看 GitHub Actions 日志

  • 进入仓库的 Actions 选项卡，点击具体任务查看实时日志。
  • 若报错 Permission denied (publickey)，检查 SSH 私钥格式是否正确（需包含完整的 -----BEGIN OPENSSH PRIVATE KEY----- 头尾）。

7. 完整示例代码

访问以下仓库获取完整模板：

通过以上步骤，每次推送代码到 main 分支时，GitHub Actions 会自动构建 MkDocs 网站并部署到云服务器，实现完全自动化。

从Github中把生成的页面部署到服务器中

然后我按照DeepSeek告诉我的方法，在github仓库中创建 .github/workflows/deploy.yml ，并将需要使用的插件都添加上

github_actions_deploy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
name: Deploy MkDocs Site
on:
  push:
    branches: [ "main" ]  # 仅在 main 分支推送时触发

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest  # 使用 GitHub 提供的 Ubuntu 环境

    steps:
      # 步骤 1：拉取代码到虚拟环境
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # 步骤 2：安装 Python 和 MkDocs
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      # 步骤 3：安装 MkDocs 及主题插件
      - name: Install Dependencies
        run: |
          pip install mkdocs==1.5.3
          pip install mkdocs-material==9.4.6
          pip install mkdocs-redirects  # 可选：安装其他插件
          pip install mkdocs-get-deps==0.2.0
          pip install mkdocs-glightbox==0.3.7
          pip install mkdocs-git-revision-date-localized-plugin==1.2.5
          pip install mkdocs-static-i18n==1.2.3
          pip install mkdocs-statistics-plugin==0.1.2

      # 步骤 4：构建静态网站
      - name: Build Site
        run: mkdocs build --strict

      # 步骤 5：通过 SCP 上传到服务器
      - name: Deploy to Server
        uses: appleboy/scp-action@v0.1.3
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_KEY }}
          source: "site/*"          # 本地构建的目录
          target: "/www/wwwroot/blog"   # 服务器目标路径
          overwrite: true            # 覆盖旧文件

Tip

fetch-depth 设置为 0 是为了能让Github Actions获取到仓库的整个历史记录(否则Github Actions部署的mkdocs网页中，最后更新: 和 创建日期: 显示的日期可能显示的是不正确的时间)

14
15
16
17
18
      # 步骤 1：拉取代码到虚拟环境
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

关于 fetch-depth 更详细的说明可以参考stackoverflow的这篇帖子

然后在Settings中添加Secrets

github_secrets_1

github_secrets_2

这里需要注意 SSH_KEY 填的应该是云服务器控制台中创建的密钥对（并且由于之前我创建并绑定过密钥对，所以云服务器中的 ~/.ssh/authorized_keys 文件就不需要更改了）。

然后commit这个文件，就会开始自动部署了

github_actions_deploy_2

在宝塔面板上添加html项目

最后在服务器的宝塔控制面板中添加html项目，根目录选择在deploy.yml设置的目录即可

bt_html

最后更新: 2025-03-09
创建日期: 2025-02-22

评论