如何使用 GitHub Actions 搭建 VPS 自动部署流水线：从代码提交到上线全自动化

过去开发者部署网站或应用时，往往需要依赖 FTP 工具手动上传文件。修改代码后，需要打开 FileZilla，定位服务器目录，将文件逐个拖入，再刷新页面确认效果。一旦上传遗漏、配置错误或者版本不一致，就可能造成线上故障。

这种传统部署方式不仅效率低，而且高度依赖人工操作。随着项目规模扩大，频繁发布版本会消耗大量时间，也增加人为失误的概率。

如今，借助 GitHub Actions，可以轻松建立一套自动化 CI/CD（持续集成与持续部署）流程。开发者只需要将代码提交到 GitHub，系统便能够自动完成代码检测、依赖安装、项目构建以及部署到 VPS 等操作。

如果你正在使用天下数据提供的 VPS 或独立服务器托管网站、应用程序，那么结合 GitHub Actions 后，可以进一步释放服务器能力，让开发、测试和上线流程更加高效稳定。

本文将从基础概念开始，详细介绍如何搭建 GitHub Actions 自动部署环境，包括 Workflow 配置、SSH 安全认证、多环境发布、版本回滚以及性能优化方案。

一、GitHub Actions 基础概念解析

在创建自动部署文件之前，需要先理解 GitHub Actions 中几个核心组成部分。只有掌握这些基础概念，后续配置流水线时才能更加清晰。

1. Workflow（工作流）

Workflow 是 GitHub Actions 自动化流程的整体定义文件，通常以 YAML 格式存放于项目目录中的：

.github/workflows/

一个项目可以同时拥有多个 Workflow，例如分别负责代码测试、自动部署、版本发布等不同任务。

2. Job（任务单元）

Job 是 Workflow 中独立执行的工作模块。一个 Workflow 可以包含多个 Job，这些 Job 默认情况下可以并行运行，也可以通过 needs 参数设置执行依赖关系。

每个 Job 都会运行在一个独立 Runner 环境中，用于完成指定任务。

3. Step（执行步骤）

Step 是 Job 内部最具体的操作流程，可以是一条 Shell 命令，也可以调用 GitHub 社区提供的 Action 插件。

多个 Step 会按照设定顺序依次执行，例如：

• 拉取代码
• 安装运行环境
• 安装项目依赖
• 执行自动测试
• 构建项目文件
• 发布到 VPS

4. Runner（运行环境）

Runner 是实际执行 Job 的服务器环境。GitHub 官方提供多种托管 Runner，例如：

• ubuntu-latest
• windows-latest
• macos-latest

此外，用户也可以配置自托管 Runner，将任务运行在自己的服务器环境中。

简单来说，它们之间的关系如下：

GitHub Actions 免费额度说明

对于公开仓库，GitHub Actions 可以免费使用。私有仓库则提供每月 2000 分钟 Linux Runner 免费额度。

对于个人开发者以及中小型团队来说，这一额度通常已经能够满足日常自动化测试和部署需求。

相比 Jenkins 等需要自行维护服务器的软件方案，GitHub Actions 最大优势在于无需额外维护 CI/CD 环境，可以有效降低运维成本。

二、使用 GitHub Actions 创建 VPS 自动部署流程

下面以一个典型前端项目为例，演示如何通过 GitHub Actions 完成项目构建，并自动发布到 VPS 服务器。

2.1 创建 deploy.yml 工作流文件

首先，在项目根目录创建以下文件：

.github/workflows/deploy.yml

示例配置如下：

name: Deploy to VPS

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build project
        run: npm run build

      - name: Deploy to VPS via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/myapp
            git pull origin main
            npm ci --production
            npm run build
            pm2 restart myapp

2.2 deploy.yml 配置逐项解析

上面的 Workflow 文件完成了一套完整的自动部署流程。下面对其中关键配置进行拆解，帮助你理解每一步具体作用。

• on: push → branches: main
  表示只有当代码提交并推送到 main 分支时，才会自动触发部署流程。这样可以避免开发过程中的频繁提交影响正式环境。
• actions/checkout@v4
  该 Action 会自动将 GitHub 仓库中的代码下载到 Runner 工作目录，方便后续执行安装、测试和构建操作。
• actions/setup-node@v4
  用于安装指定版本的 Node.js 环境，同时开启 npm 缓存功能，加快后续依赖安装速度。
• npm ci
  该命令会根据 lock 文件严格安装依赖，相比 npm install 更适合持续集成环境，能够保证每次构建环境一致。
• npm test
  执行项目测试流程。如果测试未通过，后续部署步骤会自动停止，避免错误代码进入生产环境。
• appleboy/ssh-action
  这是 GitHub 社区中应用较广泛的 SSH 部署 Action，可以通过 SSH 登录 VPS，并远程执行服务器命令。

2.3 使用 rsync 同步构建文件

除了通过 SSH 登录 VPS 后执行构建任务之外，还有另一种更加轻量的部署方式：先在 GitHub Runner 环境完成项目构建，再利用 rsync 工具同步最终生成文件。

这种方式特别适合静态网站，例如企业展示站、博客系统以及前端单页应用。

- name: Deploy build artifacts via rsync
  uses: burnett01/rsync-deployments@7.0.1
  with:
    switches: -avzr --delete
    path: ./dist/
    remote_path: /var/www/myapp/dist/
    remote_host: ${{ secrets.SERVER_HOST }}
    remote_user: ${{ secrets.SERVER_USER }}
    remote_key: ${{ secrets.SSH_PRIVATE_KEY }}

采用 rsync 部署后，VPS 服务器无需重复执行构建操作，只需要通过 Nginx 指向对应目录即可完成网站访问。

对于使用天下数据 VPS 部署静态网站的用户，这种方案可以减少服务器 CPU 消耗，提高发布效率。

三、GitHub Actions 安全配置：Secrets、SSH Key 与 known_hosts

自动部署流程涉及服务器 IP、登录账号以及 SSH 私钥等敏感信息。如果直接写入 YAML 文件，一旦代码仓库泄露，服务器安全可能受到影响。

因此，GitHub 提供了 Secrets 功能，用于安全保存部署凭据。

3.1 创建 SSH 密钥

首先，需要在本地电脑生成专门用于 GitHub Actions 部署的 SSH 密钥。

ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/deploy_key -N ""

执行完成后，会生成两个文件：

• deploy_key：私钥文件，需要保存到 GitHub Secrets 中。
• deploy_key.pub：公钥文件，需要添加到 VPS 服务器授权列表。

3.2 配置 VPS SSH 授权

将生成的公钥添加到 VPS 用户 SSH 授权文件：

cat ~/.ssh/deploy_key.pub >> ~/.ssh/authorized_keys

chmod 600 ~/.ssh/authorized_keys

如果 VPS 服务商提供可视化管理面板，也可以直接通过控制面板添加 SSH Key，降低操作复杂度。

例如，天下数据 VPS 用户可以通过服务器管理环境完成 SSH 相关配置，再结合 GitHub Actions 实现自动化发布。

3.3 添加 GitHub Secrets

进入 GitHub 仓库：

Settings → Secrets and variables → Actions

然后添加以下三个变量：

3.4 配置 known_hosts 防止中间人攻击

为了提高 SSH 连接安全性，建议固定服务器指纹，避免连接到恶意服务器。

ssh-keyscan -H 123.45.67.89 >> ~/.ssh/known_hosts

随后，将输出结果保存为 GitHub Secret：

KNOWN_HOSTS

Workflow 中可以通过以下方式调用：

- name: Setup SSH known hosts
  uses: webfactory/ssh-agent@v0.9.0
  with:
    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
    ssh-known-hosts: ${{ secrets.KNOWN_HOSTS }}

四、进阶方案：多环境部署与自动回滚

随着项目规模扩大，通常需要区分测试环境和正式生产环境。

例如：

• staging：预发布环境，用于测试新版本功能。
• production：正式生产环境，面向真实用户访问。

GitHub Actions 提供 Environment 功能，可以帮助开发团队实现环境隔离和权限控制。

4.1 多环境 Workflow 配置

name: Multi-Environment Deploy

on:
  push:
    branches:
      - develop
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    environment:
      ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}

完整部署逻辑可以根据分支自动判断：

• develop 分支 → 自动部署到 staging 测试环境。
• main 分支 → 部署到 production 正式环境。

在 GitHub 仓库 Settings → Environments 中，可以分别创建 staging 和 production 环境。

对于 production 环境，还可以开启审批保护机制，让正式上线前必须经过指定人员确认。

4.2 VPS 项目版本回滚方案

即使拥有自动化测试流程，线上环境仍可能因为配置变化、第三方依赖或者业务逻辑问题出现异常。因此，完善的回滚机制非常重要。

方案一：Git Commit 回滚

cd /var/www/myapp

git log --oneline -5

git reset --hard abc1234

npm ci --production

npm run build

pm2 restart myapp

方案二：Release Tag 发布

另一种方式是使用 Git Tag 管理版本。

每次正式发布创建对应版本标签，例如：

v1.0
v1.1
v2.0

部署触发规则修改为：

on:
  push:
    tags:
      - 'v*'

这样，当出现问题时，只需要切换到指定 Tag，即可快速恢复稳定版本。