引言：为什么要进行自动化部署？

在开发和维护静态博客或文档站时，手动部署是一个重复且容易出错的过程。随着项目规模的增长和发布频率的增加，手动操作不仅耗费时间，还可能导致人为错误，影响用户体验。通过引入自动化部署，我们可以显著提升开发效率，减少错误率。

手动部署的痛点

在引入自动化部署之前，手动部署通常包括以下步骤：

1. 本地生成静态文件：
   • 在本地运行 hexo clean && hexo g 生成静态文件。
   • 检查生成结果，确保 public 目录存在且内容正确。
2. 上传到服务器：
   • 使用 scp 或 FTP 手动上传文件到服务器目标路径。
   • 确保上传的文件完整无误。
3. 服务器配置检查：
   • 检查 Web 服务器（如 Nginx）是否正常运行。
   • 确保文件权限和路径配置正确，避免访问被拒绝。
4. 访问验证：
   • 手动访问服务器地址，确认页面加载正常。
   • 如果出现问题，需要回溯到生成或上传步骤逐一排查。

这些步骤虽然看似简单，但在频繁发布或团队协作时，容易出现以下问题：

• 耗时：每次发布都需要手动执行多个步骤，效率低下。
• 易错：手动操作容易导致文件遗漏、路径错误或权限问题。
• 效率低下：无法快速响应需求变化，影响项目迭代速度。

自动化部署的优势

引入自动化部署后，上述问题可以得到显著改善：

1. 提升效率：
   • 所有部署步骤由 CI/CD 系统自动执行，开发者只需推送代码即可。
   • 减少重复操作，节省时间。
2. 降低错误率：
   • 自动化流程减少了人为操作，避免遗漏或配置错误。
   • 可通过日志监控部署状态，快速定位问题。
3. 可重复性和一致性：
   • 每次部署都遵循相同的流程，确保结果一致。
   • 易于维护和扩展。

自动化部署的目标

通过本文的指南，你将学会如何基于以下工具实现 Hexo 的自动化部署：

• GitHub Actions：作为 CI/CD 工具，自动触发部署流程。
• SCP/SFTP：将生成的静态文件自动传输到服务器。
• Web 服务器（Nginx/Apache）：提供静态文件服务，确保访问体验。

一、配置步骤

1. 本地环境配置

2. 服务器环境配置

1
2
3
4
5
6
7

# 安装Nginx（Ubuntu示例）
sudo apt install nginx -y
sudo systemctl start nginx

# 创建目标目录并授权
sudo mkdir -p /opt/hexo_blog/public
sudo chown -R www-data:www-data /opt/hexo_blog

3. GitHub Actions 配置

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
49
50
51
52
53
54
55
56

# .github/workflows/deploy.yml
name: Hexo自动部署到阿里云

on:
  push:
    branches: [main] # 只监听main分支的代码推送

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

    steps:
      # ============== 步骤1：拉取代码 ==============
      - name: 拉取仓库代码
        uses: actions/checkout@v4

      # ============== 步骤2：设置Node环境 ==============
      - name: 配置Node.js环境
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      # ============== 步骤3：安装Hexo及依赖 ==============
      - name: 安装Hexo及依赖
        run: |
          npm install hexo-cli -g
          npm install

      # ============== 步骤4：生成静态文件 ==============
      - name: 生成网站文件
        run: |
          hexo generate

      # ============== 步骤5：验证服务器连接 ==============
      - name: 服务器连接测试
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            mkdir -p /opt/hexo_blog/public
            chmod 755 -R /opt/hexo_blog

      # ============== 步骤6：传输文件到服务器 ==============
      - name: 部署到阿里云
        uses: appleboy/scp-action@v0.1.4
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_KEY }}
          port: 22
          source: "public/"
          target: /opt/hexo_blog/
          rm: true
          overwrite: true

GitHub Secrets 配置

在使用 GitHub Actions 部署时，需要配置以下 Secrets 以确保安全性和功能正常：

1. SSH_HOST：服务器的 IP 地址或域名。
2. SSH_USER：用于连接服务器的用户名。
3. SSH_KEY：私钥内容，需为 OpenSSH 格式。
4. SSH_PORT（可选）：SSH 连接端口，默认为 22。

配置步骤：

1. 打开 GitHub 仓库页面，点击 Settings。
2. 在左侧菜单中选择 Secrets and variables -> Actions。
3. 点击 New repository secret，依次添加上述 Secrets。

Nginx 配置示例

以下是一个简单的 Nginx 配置示例，用于部署 Hexo 静态文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# filepath: /etc/nginx/sites-available/hexo_blog
server {
    listen 80;
    server_name example.com; # 替换为你的域名或 IP 地址

    root /opt/hexo_blog/public;
    index index.html;

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

    error_page 404 /404.html;
}

配置步骤：

1. 将上述配置保存为 /etc/nginx/sites-available/hexo_blog。
2. 创建符号链接到 sites-enabled：

   1	sudo ln -s /etc/nginx/sites-available/hexo_blog /etc/nginx/sites-enabled/

3. 测试 Nginx 配置是否正确：

   1	sudo nginx -t

4. 重启 Nginx 服务：

   1	sudo systemctl restart nginx

部署流程图更新

  graph LR
A[代码推送] --> B{触发 Actions}
B --> C[拉取最新代码]
C --> D[安装 Node.js]
D --> E[安装 Hexo 依赖]
E --> F[生成静态文件]
F --> G[SCP 传输到服务器]
G --> H[重启 Nginx]
H --> I[访问更新后的网站]
I --> J[验证部署成功]
  

二、常见问题解答

1. GitHub Actions 无法连接服务器

• 问题描述：部署时提示 Permission denied 或 Connection refused。
• 解决方法：
  1. 确保服务器的 SSH 服务已启动，并允许 GitHub Actions 的 IP 地址访问。
  2. 检查 secrets.SSH_KEY 是否正确配置，格式需为 OpenSSH 私钥。
  3. 验证服务器的防火墙规则，确保 22 端口开放。

2. Hexo 生成失败

• 问题描述：执行 hexo generate 时出现错误。
• 解决方法：
  1. 检查 package.json 中的依赖是否完整，尝试运行 npm install。
  2. 确保 Node.js 版本与 Hexo 兼容，推荐使用 LTS 版本。
  3. 查看 Hexo 配置文件 _config.yml 是否存在语法错误。

3. 部署后页面无法访问

• 问题描述：部署完成后，访问网站时出现 404 或空白页面。
• 解决方法：
  1. 确认静态文件已正确传输到服务器目标目录。
  2. 检查 Nginx 配置文件，确保 root 指向正确的路径。
  3. 查看 Nginx 日志（/var/log/nginx/error.log）以排查问题。

三、附录

1. 常用命令

1
2
3
4
5
6
7
8

# 清理 Hexo 缓存
hexo clean

# 生成静态文件
hexo generate

# 本地启动预览
hexo server

2. 参考资源

• Hexo 官方文档
• GitHub Actions 指南
• Nginx 配置示例
• Appleboy GitHub Actions 插件