GitHub Actions 自动化部署实践指南

基于 GitHub Actions + SSH 的生产级自动部署方案，安全、规范、可维护。

🎯 核心目标

实现从代码推送到服务器自动部署的完整自动化流程：

本地 git push → GitHub 更新 → Actions 触发 → SSH 连接服务器 → 执行部署脚本

📋 方案选型

方案	推荐度	说明
Webhook + 服务器监听	❌	维护成本高、安全复杂
GitHub Actions + self-hosted runner	⚠️	适合大型项目
GitHub Actions + SSH	✅	最简单、最主流、够安全

🔐 权限与身份模型（核心原则）

⚠️ 永远不要让 CI/GitHub Actions 直接使用 root

正确的用户职责划分

GitHub Actions
    ↓ (SSH)
deploy 用户
    ↓
项目目录 & 部署脚本

用户	用途
root	系统管理 / 安装软件 / 修权限
deploy	git pull / build / deploy

🚀 完整部署流程

第一步：创建部署用户（一次性）

# 创建 deploy 用户
useradd deploy
passwd deploy

# 配置项目目录权限（关键！）
chown -R deploy:deploy /path/to/your/project

第二步：配置 SSH 密钥认证

1. 生成 SSH Key（deploy 用户）

# 切换到 deploy 用户
su - deploy

# 生成 ed25519 密钥（推荐：现代、安全、速度快）
ssh-keygen -t ed25519 -f ~/.ssh/github_deploy

2. 添加公钥到 GitHub

• 位置：GitHub → Settings → SSH and GPG keys → New SSH key
• ⚠️ 注意：选择 SSH key，不是 GPG key
• 粘贴公钥内容（格式：ssh-ed25519 AAAA... deploy@server）

💡 常见错误：不要把私钥（BEGIN OPENSSH）当作公钥添加

3. 配置 SSH Config（强烈推荐）

创建 ~/.ssh/config：

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/github_deploy
  IdentitiesOnly yes

4. 修改仓库远程地址为 SSH

git remote set-url origin git@github.com:username/repo.git

5. 验证连接

ssh -T git@github.com

成功标志：You've successfully authenticated

第三步：创建部署脚本

创建 deploy.sh：

#!/bin/bash
set -e  # 遇到错误立即退出

cd /path/to/your/project

# 拉取最新代码
git fetch origin
git reset --hard origin/main

# 安装依赖并构建
yarn install
yarn docs:build

# 重启服务
pm2 reload myapp || pm2 start ecosystem.config.js

赋予执行权限：

chmod +x deploy.sh

第四步：配置 GitHub Actions Secrets

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

Name	用途
SSH_HOST	服务器 IP 地址
SSH_USER	deploy
SSH_KEY	GitHub Actions 使用的 SSH 私钥

💡 注意：SSH_KEY 是用于 GitHub Actions 连接服务器的私钥，不是 Git 认证用的密钥

第五步：创建 GitHub Actions Workflow

创建 .github/workflows/deploy.yml：

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd /path/to/your/project
            ./deploy.sh

🚧 常见问题与解决方案

问题 1：Permission denied

原因：项目目录 owner 是 root，deploy 用户无权限

解决：

chown -R deploy:deploy /path/to/your/project

问题 2：git pull 要求输入密码

原因：使用 HTTPS remote，需要密码认证

解决：配置 SSH key + 使用 SSH remote（见第二步）

问题 3：混淆 SSH key 和 GPG key

解决：只在 SSH and GPG keys → New SSH key 添加，不要添加到 GPG keys

问题 4：公钥格式错误

正确格式：

• ✅ 公钥：ssh-ed25519 AAAA... deploy@server
• ❌ 私钥：-----BEGIN OPENSSH PRIVATE KEY-----

✅ 最终检查清单

• [ ] deploy 用户已创建
• [ ] 项目目录权限已正确配置
• [ ] deploy 用户的 SSH key 已添加到 GitHub
• [ ] SSH config 已配置
• [ ] 仓库 remote 已改为 SSH 地址
• [ ] SSH 连接测试通过
• [ ] 部署脚本已创建并赋予执行权限
• [ ] GitHub Actions Secrets 已配置
• [ ] Workflow 文件已创建

📌 核心要点总结

1. 权限隔离：使用独立的 deploy 用户，避免 root 权限暴露
2. SSH 认证：deploy 用户使用独立的 SSH key 进行 Git 操作
3. 脚本化部署：部署逻辑写在 shell 脚本中，GitHub Actions 只负责触发
4. 安全配置：敏感信息存储在 GitHub Secrets 中