GitHub Actions 自动部署

实现 git push 之后无需登录服务器手动构建，全自动完成发布。

部署链路

git push → GitHub Actions → npm ci → npm run docs:build → rsync → 服务器 /www/server/ljdou-docs/dist/

构建在 CI 完成，服务器只接收最终静态产物，不依赖服务器上的 Node 环境。

Workflow 完整示例

.github/workflows/deploy.yml：

name: Build and Deploy to Server

on:
  push:
    branches: [main]
  workflow_dispatch:

concurrency:
  group: docs-deploy
  cancel-in-progress: false

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build with VitePress
        run: npm run docs:build

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

      - name: Deploy to server
        run: |
          rsync -avz --delete \
            -e "ssh -o StrictHostKeyChecking=no -o ConnectTimeout=30 -p ${{ secrets.SSH_PORT }}" \
            docs/.vitepress/dist/ \
            ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:/www/server/ljdou-docs/dist/

要点：

• npm ci 需要提交 package-lock.json，保证依赖可复现
• rsync --delete 清理旧哈希资源，避免产物累积
• 目标目录末尾 / 表示同步内容到该目录

部署密钥准备

生成密钥（不要复用个人密钥）：

ssh-keygen -t ed25519 -f /www/server/ljdou-docs/.deploy/deploy_key -N "" -C "github-actions-deploy"
cat /www/server/ljdou-docs/.deploy/deploy_key.pub >> ~/.ssh/authorized_keys

验证密钥可用：

ssh -i /www/server/ljdou-docs/.deploy/deploy_key -p <端口> <用户>@127.0.0.1 'echo OK'

GitHub Secrets 配置

在仓库 Settings → Secrets and variables → Actions 添加：

Secret 名	值	说明
SSH_HOST	服务器公网 IP	如 111.228.12.151
SSH_USER	登录用户	如 ljdou
SSH_PORT	SSH 端口	如 122
SSH_PRIVATE_KEY	私钥全文	仅存 Secret，勿提交仓库

SSH 端口

默认 22 常被改掉，务必与 /etc/ssh/sshd_config 的 Port 一致，且云安全组需放行该端口。

排障

失败：ssh-private-key argument is empty

说明 SSH_PRIVATE_KEY Secret 未配置或名字写错，检查 workflow 引用的 Secret 名与仓库中配置的是否一致。

失败：SSH 连接超时

从 GitHub runner（海外）到国内服务器可能不稳定，检查：

1. 云安全组是否放行 SSH 端口
2. 若长期不通，可改用自托管 runner（部署在服务器本机，走出站连接，更适合国内环境）

查看运行日志

GitHub 仓库 → Actions → 选择失败的 run → 展开具体 step 查看报错。