GitHub Actions 自动部署与 CI/CD 入门

CI/CD 是运维、DevOps 和 SRE 工作中非常重要的一类自动化流程。它的核心目标是减少重复手动操作，让代码从提交到构建、测试、部署尽可能自动完成。

对于静态网站部署场景，传统流程通常是：

1
本地修改文章或代码
2
  ↓
3
本地执行 pnpm build
4
  ↓
5
压缩 dist 目录
6
  ↓
7
手动上传服务器
8
  ↓
9
服务器手动解压
10
  ↓
11
修复权限
12
  ↓
13
reload Nginx

GitHub Actions 可以将这条流程自动化：

1
git push
2
  ↓
3
GitHub Actions 自动构建
4
  ↓
5
上传构建产物到服务器
6
  ↓
7
服务器自动替换旧版本
8
  ↓
9
Nginx 重新加载
10
  ↓
11
网站完成更新

本文整理 GitHub Actions 自动部署的核心概念、配置结构和常见排障方法。

CI/CD 是什么#

CI/CD 通常包含两个部分：

名称	含义	作用
CI	Continuous Integration，持续集成	自动安装依赖、检查、测试、构建
CD	Continuous Deployment / Delivery，持续部署或持续交付	自动发布构建产物到目标环境

在个人静态网站场景中，可以简单理解为：

1
CI：自动 pnpm install 和 pnpm build
2
CD：自动上传 dist 并部署到服务器

CI/CD 的价值在于：

减少手动部署步骤；
降低操作失误概率；
每次发布流程一致；
构建失败时能及时发现；
部署过程有日志可追踪。

GitHub Actions 的核心概念#

Workflow#

Workflow 是一整套自动化流程，通常写在：

1
.github/workflows/deploy.yml

一个仓库可以有多个 workflow，例如：

1
build.yml     用于检查和构建
2
deploy.yml    用于部署

Event#

Event 是触发 workflow 的事件。

例如：

1
on:
2
  push:
3
    branches: [master]

表示当代码 push 到 master 分支时，自动触发该 workflow。

也可以添加：

1
workflow_dispatch:

表示允许在 GitHub 页面手动点击运行。

Job#

Job 是 workflow 里的一个任务。

例如：

1
jobs:
2
  deploy:
3
    runs-on: ubuntu-latest

表示定义一个名为 deploy 的任务，并在 GitHub 提供的 Ubuntu 环境中运行。

Step#

Step 是 job 中按顺序执行的具体步骤。

例如：

1
- name: Build site
2
  run: pnpm build

表示执行一次构建命令。

Secrets 的作用#

自动部署通常需要连接服务器，这会涉及敏感信息：

服务器 IP；
服务器用户名；
SSH 私钥；
访问令牌；
密码。

这些内容不能直接写进代码仓库，否则会产生安全风险。

GitHub 提供 Secrets 用于保存敏感信息：

1
Settings
2
  ↓
3
Secrets and variables
4
  ↓
5
Actions
6
  ↓
7
Repository secrets

常见配置：

Secret 名称	作用
`SERVER_HOST`	服务器 IP 或域名
`SERVER_USER`	SSH 登录用户
`SERVER_SSH_KEY`	SSH 私钥内容

在 workflow 中使用：

1
host: ${{ secrets.SERVER_HOST }}
2
username: ${{ secrets.SERVER_USER }}
3
key: ${{ secrets.SERVER_SSH_KEY }}

这样既能让 Actions 使用这些信息，又不会把敏感内容暴露在仓库文件里。

SSH 密钥登录原理#

GitHub Actions 需要通过 SSH 登录服务器。

SSH 密钥通常包含两个文件：

1
私钥：github_actions_deploy
2
公钥：github_actions_deploy.pub

它们的用途不同：

文件	放置位置	说明
私钥	GitHub Secrets	GitHub Actions 用它证明身份
公钥	服务器 `~/.ssh/authorized_keys`	服务器用它判断是否允许登录

生成密钥示例：

1
ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/github_actions_deploy

将公钥写入服务器：

1
mkdir -p ~/.ssh
2
nano ~/.ssh/authorized_keys
3
chmod 700 ~/.ssh
4
chmod 600 ~/.ssh/authorized_keys

本地测试：

1
ssh -i ~/.ssh/github_actions_deploy ubuntu@服务器IP

如果本地测试成功，说明服务器已经信任这把公钥。

自动部署 workflow 示例#

下面是一个静态网站部署到云服务器的 workflow 结构：

1
name: Deploy to Tencent Cloud
2

3
on:
4
  push:
5
    branches: [master]
6
  workflow_dispatch:
7

8
concurrency:
9
  group: deploy-production
10
  cancel-in-progress: true
11

12
permissions:
13
  contents: read
14

15
jobs:
16
  deploy:
17
    runs-on: ubuntu-latest
18

19
    steps:
20
      - name: Checkout repository
21
        uses: actions/checkout@v4
22

23
      - name: Setup pnpm
24
        uses: pnpm/action-setup@v4
25
        with:
26
          version: 9.14.4
27

28
      - name: Setup Node.js
29
        uses: actions/setup-node@v4
30
        with:
31
          node-version: 22
32
          cache: pnpm
33

34
      - name: Install dependencies
35
        run: pnpm install --no-frozen-lockfile
36

37
      - name: Build site
38
        run: pnpm build
39

40
      - name: Pack dist
41
        run: tar -czf firefly-dist.tar.gz -C dist .
42

43
      - name: Upload package to server
44
        uses: appleboy/scp-action@v0.1.7
45
        with:
46
          host: ${{ secrets.SERVER_HOST }}
47
          username: ${{ secrets.SERVER_USER }}
48
          key: ${{ secrets.SERVER_SSH_KEY }}
49
          source: firefly-dist.tar.gz
50
          target: /tmp
51

52
      - name: Deploy on server
53
        uses: appleboy/ssh-action@v1.0.3
54
        with:
55
          host: ${{ secrets.SERVER_HOST }}
56
          username: ${{ secrets.SERVER_USER }}
57
          key: ${{ secrets.SERVER_SSH_KEY }}
58
          script: |
59
            set -e
60
            WEB_DIR="/var/www/firefly"
61
            PACKAGE="/tmp/firefly-dist.tar.gz"
62
            RELEASE_DIR="/tmp/firefly-release"
63

64
            rm -rf "$RELEASE_DIR"
65
            mkdir -p "$RELEASE_DIR"
66
            tar -xzf "$PACKAGE" -C "$RELEASE_DIR"
67

68
            sudo mkdir -p "$WEB_DIR"
69
            sudo rm -rf "$WEB_DIR"/*
70
            sudo cp -r "$RELEASE_DIR"/. "$WEB_DIR"/
71

72
            sudo find "$WEB_DIR" -type d -exec chmod 755 {} \;
73
            sudo find "$WEB_DIR" -type f -exec chmod 644 {} \;
74

75
            sudo nginx -t
76
            sudo systemctl reload nginx
77
            curl -I https://example.com
78

79
            rm -rf "$RELEASE_DIR" "$PACKAGE"

部署流程拆解#

拉取代码#

1
- name: Checkout repository
2
  uses: actions/checkout@v4

GitHub Actions 运行时会创建一个临时环境。这个步骤负责把仓库代码拉到临时环境中。

安装 pnpm 和 Node.js#

1
- name: Setup pnpm
2
  uses: pnpm/action-setup@v4
3

4
- name: Setup Node.js
5
  uses: actions/setup-node@v4

静态网站通常需要 Node.js 和 pnpm 才能安装依赖、执行构建。

安装依赖#

1
run: pnpm install --no-frozen-lockfile

安装 package.json 中声明的依赖。

如果项目的 lockfile 与 package 配置不一致，--no-frozen-lockfile 可以避免构建直接失败，但长期更推荐保持 lockfile 同步。

构建网站#

1
run: pnpm build

构建完成后会生成：

1
dist/

这是最终需要部署到服务器的静态网站文件。

打包构建产物#

1
run: tar -czf firefly-dist.tar.gz -C dist .

将 dist 目录内容打包成：

1
firefly-dist.tar.gz

这里使用 -C dist . 的原因是只打包 dist 里面的内容，而不是把整个 dist 文件夹套进去。

上传服务器#

1
uses: appleboy/scp-action@v0.1.7

这个步骤通过 SSH/SCP 将压缩包上传到服务器：

1
/tmp/firefly-dist.tar.gz

服务器部署#

1
uses: appleboy/ssh-action@v1.0.3

这个步骤通过 SSH 登录服务器，执行部署脚本。

核心流程：

1
rm -rf "$RELEASE_DIR"
2
mkdir -p "$RELEASE_DIR"
3
tar -xzf "$PACKAGE" -C "$RELEASE_DIR"
4

5
sudo mkdir -p "$WEB_DIR"
6
sudo rm -rf "$WEB_DIR"/*
7
sudo cp -r "$RELEASE_DIR"/. "$WEB_DIR"/
8

9
sudo nginx -t
10
sudo systemctl reload nginx
11
curl -I https://example.com

含义：

清理临时发布目录；
解压新构建产物；
清空旧网站文件；
复制新文件到 Web 目录；
修复权限；
检查 Nginx 配置；
重新加载 Nginx；
发起 HTTP 检查。

常见错误与排查#

ssh: no key found#

常见报错：

1
ssh.ParsePrivateKey: ssh: no key found

通常表示 GitHub Secrets 中的私钥内容不正确。

常见原因：

将 .pub 公钥误填到了 SERVER_SSH_KEY；
私钥没有从 BEGIN 复制到 END；
私钥内容换行丢失；
Secret 名称写错。

正确的 SERVER_SSH_KEY 应该包含：

1
-----BEGIN OPENSSH PRIVATE KEY-----
2
...
3
-----END OPENSSH PRIVATE KEY-----

而服务器的 authorized_keys 中应放置公钥：

1
ssh-ed25519 AAAA... github-actions-deploy

Permission denied#

常见原因：

公钥没有写入服务器 ~/.ssh/authorized_keys；
authorized_keys 权限不正确；
SSH 用户名写错；
Secret 中的私钥和服务器上的公钥不是一对；
服务器安全策略禁止该用户登录。

排查：

1
chmod 700 ~/.ssh
2
chmod 600 ~/.ssh/authorized_keys

本地测试：

1
ssh -i ~/.ssh/github_actions_deploy ubuntu@服务器IP

本地能登录后，再检查 GitHub Secrets。

sudo 需要密码#

部署脚本中常见命令：

1
sudo rm -rf /var/www/firefly/*
2
sudo systemctl reload nginx

如果服务器要求输入 sudo 密码，GitHub Actions 无法交互输入，部署会失败。

解决方向：

给部署用户配置必要的免密 sudo 权限；
将 Web 目录权限调整为部署用户可写；
将需要 sudo 的操作封装到服务器本地脚本中，并为特定脚本配置免密执行。

权限配置应遵循最小权限原则，不应随意给所有命令无限制免密 sudo。

构建失败#

如果失败发生在：

1
pnpm install
2
pnpm build

需要查看 Actions 日志。

常见原因：

依赖安装失败；
Node.js 版本不匹配；
lockfile 不一致；
Markdown frontmatter 格式错误；
构建时访问外部资源失败。

排查顺序：

1
本地 pnpm build 是否成功
2
Actions 中 Node/pnpm 版本是否一致
3
报错发生在哪一步
4
是否是网络资源请求失败

部署成功但网站没更新#

常见原因：

push 的不是触发分支；
Workflow 没有运行；
构建产物没有复制到正确目录；
Nginx root 指向的目录不是部署目录；
浏览器缓存旧页面；
CDN 或代理缓存。

排查：

1
ls -lah /var/www/firefly
2
curl -I https://example.com
3
sudo nginx -T | grep -n "root"

自动部署的安全注意事项#

自动部署涉及服务器权限，应注意：

私钥只放在 GitHub Secrets 中；
不要把私钥提交到仓库；
为 GitHub Actions 使用单独 SSH key；
不建议使用 root 用户部署；
服务器上只开放必要端口；
sudo 权限尽量限制到必要命令；
定期检查 GitHub Secrets 和服务器 authorized_keys。

运维视角下的意义#

GitHub Actions 自动部署不仅是“省事”，更重要的是建立标准化发布流程。

手动部署的问题在于：

1
容易漏步骤
2
容易复制错路径
3
难以追踪每次发布内容
4
失败后不知道卡在哪一步

自动部署的优势在于：

1
每次流程一致
2
每一步都有日志
3
失败点清晰
4
可以回溯提交记录
5
可以逐步加入检查和测试

这也是 DevOps 和 SRE 的核心思想之一：把重复、容易出错的人工操作变成可追踪、可复现、可自动执行的流程。

小结#

GitHub Actions 自动部署静态网站的核心链路是：

1
push 代码
2
  ↓
3
触发 workflow
4
  ↓
5
安装依赖
6
  ↓
7
构建 dist
8
  ↓
9
打包构建产物
10
  ↓
11
通过 SSH 上传服务器
12
  ↓
13
服务器替换旧文件
14
  ↓
15
检查 Nginx
16
  ↓
17
重载服务
18
  ↓
19
健康检查

掌握这条链路后，可以继续扩展：

部署前运行 pnpm check；
部署失败时发送通知；
增加回滚机制；
使用独立发布目录和软链接切换版本；
将部署流程封装成服务器本地 deploy.sh；
扩展到 Docker Compose 或 Kubernetes 部署。

CI/CD 的关键不是记住某个 YAML 写法，而是理解每一步在替代哪一个手动操作。只要能把手动部署链路拆开，再逐步写进 workflow，就能完成可靠的自动化部署。

音乐

音乐

CI/CD 是什么#

GitHub Actions 的核心概念#

Workflow#

Event#

Job#

Step#

Secrets 的作用#

SSH 密钥登录原理#

自动部署 workflow 示例#

部署流程拆解#

拉取代码#

安装 pnpm 和 Node.js#

安装依赖#

构建网站#

打包构建产物#

上传服务器#

服务器部署#

常见错误与排查#

ssh: no key found#

Permission denied#

sudo 需要密码#

构建失败#

部署成功但网站没更新#

自动部署的安全注意事项#

运维视角下的意义#

小结#

文章分享

评论区

音乐

文章目录