博客热部署指南：Push 代码自动更新到服务器

Wed, 12 Aug 2026 00:00:00 GMT

背景#

本博客基于 Astro 静态站点框架，部署在自有服务器上(Ubuntu22.04)。之前每次更新内容都需要手动 SSH 连上服务器，拉代码、构建、拷贝文件，非常繁琐。

引入 GitHub Actions 自动化部署后，只需本地 git push，云端自动构建并将 dist/ 推送到服务器，Nginx 直接返回新内容，真正实现”写完就发”。

整体架构#

1
┌──────────────┐   git push   ┌───────────────┐   SSH+rsync   ┌──────────────┐
2
│  本地电脑      │ ──────────> │  GitHub 仓库    │ ────────────> │  自有服务器    │
3
│  (写代码)      │             │  Actions 构建   │               │  Nginx 返回   │
4
└──────────────┘             └───────┬───────┘               └──────────────┘
5
                                     │
6
                              云端 Ubuntu 环境
7
                              - checkout 代码
8
                              - 安装 pnpm + 依赖
9
                              - pnpm build 构建
10
                              - rsync dist/ → 服务器

核心优势：服务器上不需要安装 Git、Node.js、pnpm 等任何开发环境，只需要 Nginx 和 rsync。

第一步：服务器生成 SSH 密钥#

SSH 连上服务器，生成一组供 GitHub Actions 使用的密钥对：

Terminal window

1
ssh-keygen -t ed25519 -f /root/.ssh/github-actions -N ""
2

3
# 公钥（锁）装到服务器
4
cat /root/.ssh/github-actions.pub >> /root/.ssh/authorized_keys
5

6
# 私钥（钥匙）复制下来，稍后填入 GitHub
7
cat /root/.ssh/github-actions

公钥和私钥的区别：公钥是”锁”，装在服务器上，谁都可以看；私钥是”钥匙”，必须保密。GitHub Actions 拿着钥匙去开服务器的锁，匹配成功就能免密登录。

第二步：GitHub 仓库添加 Secrets#

打开 GitHub 仓库 → Settings → Secrets and variables → Actions → New repository secret，添加三个：

Secret 名称	示例值	说明
`SERVER_HOST`	`162.211.183.61`	服务器 IP 地址
`SERVER_USER`	`root`	SSH 登录用户名
`SERVER_SSH_KEY`	`-----BEGIN OPENSSH PRIVATE KEY-----`…	第一步复制的完整私钥（含头尾）

添加时注意私钥必须包含 -----BEGIN OPENSSH PRIVATE KEY----- 和 -----END OPENSSH PRIVATE KEY-----，缺一不可。确保https://github.com/用户名称/仓库名称/settings/actions的Actions permissions是Allow all actions and reusable workflows。

第三步：创建 deploy.yml#

在项目根目录创建 .github/workflows/deploy.yml：

1
name: Deploy to Server
2

3
on:                          # 触发条件
4
  push:
5
    branches: [master]        # 推送到 master 分支时触发
6
  workflow_dispatch:          # 允许在网页上手动触发
7

8
concurrency:
9
  group: "deploy"
10
  cancel-in-progress: false
11

12
jobs:
13
  build-and-deploy:
14
    runs-on: ubuntu-latest    # GitHub 提供的一台临时云服务器
15
    steps:
16
      # ① 拉代码
17
      - name: Checkout
18
        uses: actions/checkout@v4
19

20
      # ② 装 Node.js 22
21
      - name: Setup Node.js
22
        uses: actions/setup-node@v4
23
        with:
24
          node-version: "22"
25

26
      # ③ 装 pnpm 9.14.4
27
      - name: Setup pnpm
28
        uses: pnpm/action-setup@v4
29
        with:
30
          version: 9.14.4
31
          run_install: false
32

33
      # ④ 装项目依赖
34
      - name: Install dependencies
35
        run: pnpm install --no-frozen-lockfile
36

37
      # ⑤ 构建 → 生成 dist/ 目录
38
      - name: Build site
39
        run: pnpm run build
40

41
      # ⑥ 把 dist/ 推送到你的服务器 /var/www/html/
42
      - name: Deploy to server
43
        uses: easingthemes/ssh-deploy@v5.1.2
44
        with:
45
          SSH_PRIVATE_KEY: ${{ secrets.SERVER_SSH_KEY }}   # 你的私钥
46
          ARGS: "-avz --delete"                             # rsync 参数：归档+压缩+删除旧文件
47
          SOURCE: "dist/"                                   # 要上传的本地目录
48
          REMOTE_HOST: ${{ secrets.SERVER_HOST }}           # 你的服务器 IP
49
          REMOTE_USER: ${{ secrets.SERVER_USER }}           # 登录用户
50
          TARGET: "/var/www/html"                           # 服务器上的目标目录

展开收起

配置说明#

配置项	说明
`on.push.branches: [master]`	推送到 master 分支时自动触发
`workflow_dispatch`	允许手动在 Actions 页面点击触发
`runs-on: ubuntu-latest`	GitHub 提供的临时 Linux 服务器
`SOURCE: "dist/"`	本地构建产物目录
`TARGET: "/var/www/html"`	服务器上 Nginx 的根目录
`ARGS: "-avz --delete"`	rsync 参数：归档模式 + 压缩 + 删除旧文件
`--no-frozen-lockfile`	允许 pnpm 更新 lockfile，避免版本锁定导致构建失败

第四步：Nginx 配置#

确保服务器上的 Nginx 指向正确的目录：

1
server {
2
    listen 443 ssl http2;
3
    server_name www.ynnn-7.com;
4

5
    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
6
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
7

8
    root /var/www/html;
9
    index index.html;
10

11
    # 不带 www 跳转到带 www
12
    server {
13
        listen 443 ssl;
14
        server_name ynnn-7.com;
15
        return 301 https://www.ynnn-7.com$request_uri;
16
    }
17

18
    location / {
19
        try_files $uri $uri.html $uri/ /404.html;
20
    }
21

22
    # Astro 静态资源长期缓存
23
    location /_astro/ {
24
        expires 1y;
25
        add_header Cache-Control "public, immutable";
26
    }
27

28
    gzip on;
29
    gzip_types text/plain text/css application/json application/javascript
30
               text/xml application/xml text/javascript image/svg+xml;
31
}

展开收起

工作原理#

每次 git push origin master 后，GitHub Actions 自动执行以下流程：

git push

GitHub Actions 触发

拉取最新代码

安装 Node.js 22

安装 pnpm

pnpm install 装依赖

pnpm build 构建

rsync dist/ → 服务器 /var/www/html/

Nginx 返回新页面

git push

GitHub Actions 触发

拉取最新代码

安装 Node.js 22

安装 pnpm

pnpm install 装依赖

pnpm build 构建

rsync dist/ → 服务器 /var/www/html/

Nginx 返回新页面

如何使用#

以后写完文章只需要：

Terminal window

1
git add .
2
git commit -m "更新内容"
3
git push

然后打开 GitHub 仓库的 Actions 标签页，查看 Deploy to Server 运行状态。变成绿色 ✅ 后等待 1-2 分钟，刷新博客即可看到更新。

踩坑记录#

1. SSH 连接被拒#

现象：Host key verification failed

解决：确认 authorized_keys 中已添加公钥，且 GitHub Secrets 中的 SERVER_SSH_KEY 私钥内容完整（包含头尾标记）。

2. Action 版本找不到#

现象：Unable to resolve action easingthemes/ssh-deploy@v5

解决：v5 不是有效的版本 tag，必须使用具体版本号如 v5.1.2。

3. 构建失败但部署日志看不到#

现象：Actions 页面显示红色失败

解决：项目中的其他 workflow（如 Biome 代码检查）可能同时运行并失败，但它们是独立的，不影响部署 workflow。在 Actions 页面左侧点击 Deploy to Server 查看部署专属日志。

4. 部署成功但网站没变化#

解决：

检查 Nginx 的 root 是否指向 /var/www/html
检查服务器是否安装了 rsync：apt install -y rsync
清除浏览器缓存或使用无痕模式访问

总结#

做了什么	在哪里
SSH 密钥对	服务器 `/root/.ssh/`
三个 Secrets	GitHub 仓库 Settings
`deploy.yml`	项目 `.github/workflows/`
Nginx 配置	服务器 `/etc/nginx/`
本地代码	正常上传即可

Ynnn