1
2
3
4
5
6
7

写完文章 → 本地预览 → git push → SSH 登服务器 → cd 目录 → git pull → hugo 构建 → 完成

每篇文章都要重复后三步，而且：
  ✗ 容易忘（push 了但没部署，线上还是旧的）
  ✗ 多设备时混乱（公司 push 了，家里没同步）
  ✗ 服务器上手动操作易出错（命令敲错、忘记更新主题）
  ✗ 出门没电脑就改不了博客

1
2
3
4
5
6

写完文章 → git push → 自动部署 → 线上更新

  ✓ push 即部署，所见即所得
  ✓ 任何设备、任何地方都能更新
  ✓ 不用记服务器命令
  ✓ 主题更新、配置改动都自动同步

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

方案                原理                           优点               缺点
──────────────────────────────────────────────────────────────────────────────
1. Actions SSH     GitHub 通过 SSH 登服务器        复用现有流程       依赖服务器环境
   执行             执行 git pull + hugo            服务器改动小       （git/hugo）
                                                  配置简单

2. Actions 构建    GitHub 跑 Hugo，rsync 推        构建不依赖服务器   要配 rsync +
   + rsync         静态文件到服务器                环境，更标准       nginx 目录

3. 服务器 cron     服务器定时 git pull + hugo      零 GitHub 配置     有几分钟延迟
                                                   最简单

4. 托管平台        Cloudflare Pages / Vercel       免服务器、全球     要改 DNS、
   托管            / Netlify                       CDN、免费          可能不符现有架构

1
2
3
4

有自己的 VPS + 现在手动 SSH 部署  → 方案1（本文）
有自己的 VPS，想让构建脱离服务器  → 方案2
不想碰 GitHub Actions            → 方案3
没有服务器 / 想要免费 CDN         → 方案4

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

  你 push 代码到 GitHub
          │
          ▼
  ┌───────────────────┐
  │ GitHub 虚拟机       │  ← runs-on: ubuntu-latest
  │ (GitHub 免费提供)   │     这只是个"跑腿的"临时环境
  │                    │
  │  唯一的动作：        │
  │  通过 SSH 连你的服务器│
  └─────────┬─────────┘
            │ SSH
            ▼
  ┌───────────────────┐
  │ 你的 VPS (Debian等) │  ← 真正部署发生的地方
  │                    │
  │  cd 仓库目录        │
  │  git pull          │
  │  hugo 构建          │
  │  → nginx 目录更新   │
  └───────────────────┘

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

runs-on: ubuntu-latest

  这指定的是 GitHub Actions 的"执行环境"——
  GitHub 免费给你的一台临时 Ubuntu 虚拟机。

  它和你的服务器系统（Debian/CentOS 都行）无关。
  这台虚拟机只负责一件事：发起 SSH 连接到你的服务器。
  任务完成即销毁。

  打个比方：
    runs-on 的 Ubuntu = 快递员（跑腿的）
    你的服务器       = 收件人（真正干活的地方）
    快递员是谁不重要，能把包裹（SSH 命令）送到就行

1
2
3
4

✓ 一台 VPS / 云服务器，有 SSH 和 root（或 sudo）权限
✓ 已安装 git 和 hugo（手动部署过的话肯定有）
✓ Nginx（或其他 Web 服务器）已配置好，能托管静态文件
✓ 仓库已 git clone 到服务器（手动部署过的话肯定有）

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

# 1. 生成密钥对（ed25519 更安全更快，无密码）
ssh-keygen -t ed25519 -f ~/.ssh/github_actions -N "" -C "github-actions-deploy"
# 生成两个文件：
#   ~/.ssh/github_actions      私钥（给 GitHub）
#   ~/.ssh/github_actions.pub  公钥（留在服务器）

# 2. 把公钥加入授权列表（让持有私钥的 GitHub 能登录）
cat ~/.ssh/github_actions.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

# 3. 查看并复制私钥内容（下一步要填到 GitHub）
cat ~/.ssh/github_actions

1
2
3
4
5
6

复制私钥时要注意：
  ✓ 完整复制，包含 -----BEGIN/END OPENSSH PRIVATE KEY----- 两行
  ✓ 包含所有换行
  ✗ 不要漏掉任何字符

  这把私钥只填到 GitHub Secrets，绝不放进代码仓库

1
2
3

如果你的 SSH 端口不是 22：
  额外加一个 SERVER_PORT（如 2222）
  workflow 里把 port 那行的注释去掉

 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

# Hugo 自动部署：push 到 main 后，通过 SSH 登服务器执行 git pull + hugo
name: Deploy

on:
  push:
    branches: [main]          # push 到 main 时触发
  workflow_dispatch:           # 也允许在 Actions 页面手动触发

jobs:
  deploy:
    runs-on: ubuntu-latest     # GitHub 提供的执行环境（不是你的服务器）
    steps:
      - name: SSH 登录服务器并部署
        uses: appleboy/ssh-action@v1    # 成熟的 SSH Action
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          # 端口非 22 时，取消下行注释并配置 SERVER_PORT
          # port: ${{ secrets.SERVER_PORT }}
          script: |
            set -e
            cd /var/www/blog/site              # ← 改成你服务器上仓库的路径
            git pull --ff-only
            # git submodule update --init --recursive   # 更新主题时取消注释
            hugo --minify --cleanDestinationDir -d /var/www/blog/public
            echo "✅ 部署完成 $(date '+%F %T')"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

on:
  push:
    branches: [main]     # 监听 main 分支的 push
  workflow_dispatch:     # 加这个能在 Actions 页面点按钮手动跑

  → 每次 push 文章/配置，自动触发；也能手动重跑

uses: appleboy/ssh-action@v1
  → 社区维护的 SSH Action，稳定好用，不用自己写 SSH 逻辑

set -e
  → 任何命令失败立即中止（避免 pull 失败还继续 hugo）

cd /var/www/blog/site
  → 进到服务器上的仓库目录（手动部署时你 cd 的那个）

git pull --ff-only
  → 拉最新代码，--ff-only 禁止产生 merge commit（服务器不该有本地改动）

hugo --minify --cleanDestinationDir -d /var/www/blog/public
  → 三个参数的作用见下节

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

-d /var/www/blog/public
  指定输出目录（-d = destination）
  直接输出到 nginx 的 web 根目录，省去 cp/rsync 步骤

--minify
  压缩 HTML/CSS/JS（去注释、去空白）
  省带宽、提升加载速度、对 SEO 友好
  生产环境建议加上

--cleanDestinationDir
  构建前清理目标目录里不在生成的文件
  ⚠️ 重要：如果不加，删了某篇文章后旧的 HTML 还会残留
     访问者可能撞到已删除的页面
  前提：目标目录只放 Hugo 输出（别混别的文件）

1
2
3
4
5
6
7
8

如果主题用 git submodule 管理（很多 Hugo 主题推荐这么做），
git pull 不会自动同步 themes/ 目录。

哪天你更新了主题（git submodule update --remote themes/stack），
记得把这行的注释取消：
  git submodule update --init --recursive

不更新主题就不用管，保持注释即可。

1
2
3

git add .github/workflows/deploy.yml
git commit -m "ci: 添加自动部署"
git push

1
2
3

🟢 绿色 ✓  → 成功！以后每次 push 自动部署
🔴 红色 ✗  → 失败，点进去看哪一步报错
🟡 黄色    → 正在运行

1
2
3

# 在服务器上查 hugo 的绝对路径
which hugo
# 可能输出：/usr/local/bin/hugo 或 /snap/bin/hugo

1
2
3
4
5

script: |
  set -e
  cd /var/www/blog/site
  git pull --ff-only
  /usr/local/bin/hugo --minify --cleanDestinationDir -d /var/www/blog/public

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

原因1：路径不对
  cd 的目录不是 git 仓库（没有 .git）
  → 确认服务器上仓库的真实路径

原因2：服务器仓库有本地改动
  --ff-only 会拒绝产生 merge
  → 服务器上别手动改文件，所有改动走 git push

原因3：仓库是 private
  服务器 git pull 需要认证
  → 给服务器配 deploy key，或用 https + token
  （public 仓库无此问题）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Permission denied (publickey)
  → 私钥没配对，检查 SERVER_SSH_KEY 内容是否完整
  → 公钥是否加到 authorized_keys

Connection timeout
  → 防火墙/安全组没放行 SSH 端口
  → 或 SERVER_HOST 填错

端口非 22
  → 加 SERVER_PORT secret，workflow 取消 port 行注释

1
2
3
4
5
6
7
8

可能1：浏览器缓存
  → 强制刷新（Ctrl+F5）或无痕模式

可能2：CDN 缓存
  → 清 CDN 缓存，或等缓存过期

可能3：hugo 构建输出了，但 nginx root 指向的目录不对
  → 确认 -d 的目录 = nginx server 块的 root

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

1. 用专用密钥，不共用
   给 GitHub Actions 单独一对密钥
   和你日常 SSH 的 key 分开
   万一泄露，只影响部署，且能单独撤销

2. 私钥只进 Secrets，绝不进代码
   .gitignore 不用管（Secrets 根本不在仓库里）
   别手滑把私钥贴到代码或日志

3. 最小权限（进阶）
   本文用了 root，简单但权限过大
   更安全的做法：建专用 deploy 用户，只给仓库和 nginx 目录的权限
   不能 sudo，限制 SSH 只能执行特定命令

4. 密钥可随时撤销
   怀疑泄露 → 服务器删掉 authorized_keys 里那行公钥即可
   重新生成一对，更新 GitHub Secret

5. 限制来源 IP（进阶）
   服务器防火墙只允许 GitHub IP 段 SSH（但 GitHub IP 会变）
   或用部署密钥 + 强制命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

jobs:
  deploy:
    steps:
      # ... 部署步骤 ...
      - name: 失败通知
        if: failure()
        run: |
          # 调用钉钉/飞书/企业微信 webhook
          curl -X POST "https://oapi.dingtalk.com/robot/send?access_token=XXX" \
            -H "Content-Type: application/json" \
            -d '{"msgtype":"text","text":{"content":"博客部署失败！"}}'

1
2
3
4

main 分支    → 生产服务器
dev 分支     → 测试服务器

用分支触发不同 job，或用 environment 区分 secrets

1
2
3
4
5
6
7
8

script: |
  set -e
  cd /var/www/blog/site
  git pull --ff-only
  hugo --minify --cleanDestinationDir -d /var/www/blog/public
  # 校验关键页面是否生成
  test -f /var/www/blog/public/index.html || { echo "构建失败"; exit 1; }
  echo "✅ 部署完成 $(date '+%F %T')"

1
2
3

hugo new posts/xxx.md    # 写文章
hugo server              # 本地预览
git add && git commit && git push   # 发布，自动部署