借助 GitHub Actions 自动化部署 Hugo 网站到自有服务器

目录

从手动部署到自动化的工作流演进

在网站开发的初期阶段,为了深入理解整个发布流程,我一直在本地环境中使用 Hugo 手动生成静态网站。这个过程包括:运行 hugo 命令生成静态文件,手动打包 public 目录,然后通过 SCP 或 FTP 上传到服务器,最后在服务器上解压并配置。虽然这种方法让我对网站部署的每个环节都有了清晰的认识,但随着内容的增多,这种重复性工作变得越来越耗时。

虽然现在有 Vercel、Netlify 等优秀的静态网站托管平台,但由于我已经拥有一台国内的轻量级云服务器(主要用于 frp 内网穿透服务),我决定充分利用现有资源,直接在这台服务器上托管我的 Hugo 网站。

自动化部署方案设计

最终实现的解决方案是:通过 GitHub 私有仓库存储 Hugo 源码,利用 GitHub Actions 实现自动化构建和部署,使用 rsync 将生成的静态文件同步到自己的服务器

这种方案的优势在于:

  • 自动化:代码推送后自动完成整个构建和部署流程
  • 版本控制:所有变更都有完整的历史记录
  • 安全性:私有仓库保护源代码,SSH 密钥保证传输安全
  • 成本效益:充分利用现有服务器资源

服务器端配置

环境准备

我使用 1Panel 面板管理服务器,网站目录为:

/opt/1panel/apps/openresty/openresty/www/sites/xiaoten.com/index

安装 rsync

由于同步方案使用 rsync,需要在服务器上安装:

# CentOS/RHEL 系统
sudo yum install -y rsync

# Ubuntu/Debian 系统  
sudo apt-get update && sudo apt-get install -y rsync

安全配置:SSH 密钥认证

为了实现安全的自动化部署,需要配置 GitHub Actions 对服务器的访问权限。

生成 SSH 密钥对

ssh-keygen -t ed25519 -C "github-actions" -f ~/.ssh/github-actions_id

这个命令会在 ~/.ssh/ 目录生成一对密钥:

  • github-actions_id:私钥(保密)
  • github-actions_id.pub:公钥

配置服务器授权

  1. 添加公钥到授权列表
cat ~/.ssh/github-actions_id.pub >> ~/.ssh/authorized_keys
  1. 设置正确的文件权限
# 设置目录权限
chmod 700 ~/.ssh

# 设置文件权限
chmod 600 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/github-actions_id

# 验证权限设置
ls -la ~/.ssh/

正确的权限配置应该是:

drwx------ 2 root root 4096 ... .ssh/
-rw------- 1 root root  411 ... authorized_keys
-rw------- 1 root root  411 ... github-actions_id
-rw-r--r-- 1 root root   99 ... github-actions_id.pub

配置 GitHub Secrets

获取私钥内容:

cat ~/.ssh/github-actions_id

在 GitHub 仓库中配置以下 Secrets:

  • SERVER_SSH_KEY:完整的私钥内容
  • SERVER_HOST:服务器 IP 地址或域名
  • SERVER_USER:SSH 连接用户名(如 root

GitHub Actions 工作流配置

创建工作流文件

在 Hugo 项目根目录创建 .github/workflows/deploy.yml 文件。

完整的工作流配置

name: Deploy Hugo Site to My Server

on:
  push:
    branches: [ "main" ] # 根据实际情况调整分支名称

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      # 1. 检出代码
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          submodules: recursive # 重要:如果使用 Git 子模块管理主题
          fetch-depth: 0

      # 2. 设置 Hugo 环境
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.151.0'
          extended: true # 如果主题需要扩展版本

      # 3. 构建 Hugo 网站
      - name: Build Hugo
        run: hugo --minify # 生成优化后的静态网站

      # 4. 设置 Node.js 环境(用于 Pagefind)
      - name: Setup Node.js for Pagefind
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      # 5. 生成全文搜索索引
      - name: Install and Run Pagefind
        run: |
          npm install -g pagefind
          pagefind --site ./public

      # 6. 配置 SSH 连接
      - name: Setup SSH key and known_hosts
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.SERVER_SSH_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan -H ${{ secrets.SERVER_HOST }} >> ~/.ssh/known_hosts

      # 7. 安装 rsync
      - name: Install rsync
        run: sudo apt-get update && sudo apt-get install -y rsync

      # 8. 部署到服务器
      - name: Deploy to Server with Rsync
        run: |
          rsync -avz --delete ./public/ ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_HOST }}:/opt/1panel/apps/openresty/openresty/www/sites/xiaoten.com/index/

工作流步骤详解

这个自动化流程包含 8 个关键步骤:

  1. ✅ 检出代码:获取最新的源码和子模块
  2. ✅ 设置 Hugo 环境:安装指定版本的 Hugo
  3. ✅ 构建网站:生成优化的静态文件
  4. ✅ 设置 Node.js 环境:为 Pagefind 准备运行环境
  5. ✅ 生成搜索索引:创建全文搜索功能所需的数据
  6. ✅ 配置 SSH 连接:建立安全的服务器连接
  7. ✅ 安装 rsync:确保文件同步工具可用
  8. ✅ 服务器部署:使用 rsync 高效同步文件

技术要点说明

rsync 参数说明

  • -avz:归档模式、显示详细信息和压缩传输
  • --delete:删除目标目录中源目录不存在的文件
  • ./public/:注意结尾的斜杠,表示同步目录内容而非目录本身

安全性考虑

  • 使用 ED25519 算法生成密钥,安全性更高
  • 私钥通过 GitHub Secrets 管理,不会暴露在日志中
  • 严格的文件权限设置防止未授权访问
💬 评论