Linux 服务器 SSH 密钥配置 + GitHub Actions 部署操作文档

浓眉大眼朱时茂
0 阅读5分钟

一、文档说明

本文档适用于 Ubuntu/Debian 系统（阿里云 / 腾讯云等云服务器），全程以 root 用户操作为核心，完成 SSH 密钥生成、权限配置、服务配置，并对接 GitHub Actions 实现免密部署。

二、核心步骤

步骤 1：生成 SSH 密钥（服务器端）

1.1 切换到 root 用户（确保全程 root 操作）

bash

运行

su - root  # 输入 root 密码（如已在 root 下可跳过）

1.2 生成 SSH 密钥（推荐 RSA 格式，兼容性更好）

bash

运行

# 生成 RSA 密钥（全程回车，不要设置密码短语 passphrase）
ssh-keygen -t rsa -b 4096 -C "root@github-actions"

# 生成后密钥存储路径：
# 私钥（需配置到 GitHub）：/root/.ssh/id_rsa
# 公钥（需配置到服务器授权）：/root/.ssh/id_rsa.pub

步骤 2：配置 SSH 密钥权限（服务器端，关键！）

SSH 对权限要求严格，权限错误会直接导致密钥登录失败：

bash

运行

# 1. 将公钥写入授权文件（自动创建 authorized_keys）
cat /root/.ssh/id_rsa.pub >> /root/.ssh/authorized_keys

# 2. 设置 .ssh 目录权限（仅 root 可访问）
chmod 700 /root/.ssh

# 3. 设置授权文件权限（仅 root 可读写）
chmod 600 /root/.ssh/authorized_keys

# 4. 验证权限（可选，确保输出如下）
ls -l /root/.ssh/
# 正确输出：
# -rw------- 1 root root  xxx id_rsa
# -rw-r--r-- 1 root root  xxx id_rsa.pub
# -rw------- 1 root root  xxx authorized_keys

步骤 3：配置 SSH 服务（服务器端）

3.1 修改 SSH 核心配置（关闭密码登录，开启密钥登录）

bash

运行

# 编辑 SSH 配置文件
sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/g' /etc/ssh/sshd_config
sed -i 's/#PubkeyAuthentication yes/PubkeyAuthentication yes/g' /etc/ssh/sshd_config

# 重载服务缓存（解决配置文件修改后的警告）
systemctl daemon-reload

# 重启 SSH 服务（Ubuntu/Debian 专用，CentOS 用 systemctl restart sshd）
systemctl restart ssh

# 可选：设置 SSH 开机自启（避免服务器重启后服务中断）
systemctl enable ssh

3.2 验证 SSH 服务状态（确保配置生效）

bash

运行

# 查看 SSH 服务状态（需显示 active (running)）
systemctl status ssh

# 验证密钥登录配置（需输出如下）
sshd -T | grep -E 'passwordauthentication|pubkeyauthentication'
# 正确输出：
# passwordauthentication no
# pubkeyauthentication yes

3.3 本地测试密钥登录（可选，验证有效性）

bash

运行

# 在服务器本地测试免密登录
ssh -i /root/.ssh/id_rsa root@localhost

# 成功表现：无需输入密码，直接进入 root 家目录（/root）
# 退出登录：执行 exit 即可

步骤 4：配置 GitHub Actions Secrets（GitHub 端）

4.1 提取服务器私钥（复制完整内容）

bash

运行

# 查看并复制私钥（全选，包括首尾标识）
cat /root/.ssh/id_rsa

✅ 正确私钥格式（必须完整复制，无修改）：

plaintext

-----BEGIN RSA PRIVATE KEY-----
xxxxxxxxxabcdefghijklmnopqrstuvwxyz1234567890xxxxxxxxx
xxxxxxxxxabcdefghijklmnopqrstuvwxyz1234567890xxxxxxxxx
-----END RSA PRIVATE KEY-----

4.2 添加 GitHub 仓库 Secrets

  1. 打开 GitHub 仓库 → 顶部 Settings → 左侧 Secrets and variables → Actions；
  2. 点击 New repository secret，依次添加以下 4 个密钥：

表格

Secret 名称填写内容示例
DEPLOY_HOST服务器公网 IP / 域名121.xxx.xxx.xxx
DEPLOY_USER登录用户名（本文档为 root）root
DEPLOY_KEY步骤 4.1 复制的完整私钥内容（上述 RSA 私钥全文）
DEPLOY_PATH项目部署目录/www/wwwroot/baowu.life

4.3 配置 GitHub Actions 脚本（.github/workflows/deploy.yml）

yaml

name: Build and Deploy

on:
  push:
    branches:
      - master  # 触发部署的分支

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # 以下为前端项目构建步骤（根据自身项目调整，如无需构建可删除）
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

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

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm build

      - name: Compress out directory
        run: |
          cd out  # 构建产物目录，根据自身项目调整
          zip -r ../out.zip .
          cd ..

      # 上传文件到服务器
      - name: Upload to server and deploy
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USER }}
          key: ${{ secrets.DEPLOY_KEY }}
          port: 22  # 服务器 SSH 端口，非 22 需修改
          source: "out.zip"
          target: "/tmp/"

      # 服务器端解压并部署
      - name: Extract and replace on server
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USER }}
          key: ${{ secrets.DEPLOY_KEY }}
          port: 22  # 服务器 SSH 端口，非 22 需修改
          script: |
            mkdir -p ${{ secrets.DEPLOY_PATH }}
            cd ${{ secrets.DEPLOY_PATH }}
            # 清空目录（兼容空目录场景）
            rm -rf * .[^.]* 2>/dev/null || true
            # 解压文件（-O UTF-8 避免中文乱码）
            unzip -o /tmp/out.zip -d . -O UTF-8
            # 删除临时压缩包
            rm -f /tmp/out.zip
            # 可选：还原目录权限（如 Web 目录需 www 用户）
            chown -R www:www ${{ secrets.DEPLOY_PATH }} 2>/dev/null || true

三、常见问题排查

问题 1：GitHub Actions 报错 ssh.ParsePrivateKey: ssh: no key found

  • 原因：GitHub Secrets 里的私钥格式错误 / 不完整；
  • 解决：重新复制服务器端 cat /root/.ssh/id_rsa 的完整内容，清空 Secrets 后重新粘贴（确保包含首尾 -----BEGIN/END RSA PRIVATE KEY-----，无多余空行）。

问题 2：SSH 服务重启报错 Unit sshd.service not found

  • 原因：Ubuntu/Debian 系统 SSH 服务名是 ssh，不是 sshd；
  • 解决：改用 systemctl restart ssh。

问题 3：密钥登录提示 Permission denied (publickey)

  • 原因：.ssh 目录 /authorized_keys 权限错误；
  • 解决：重新执行 chmod 700 /root/.ssh 和 chmod 600 /root/.ssh/authorized_keys。

问题 4：服务器重启后 SSH 服务未启动

  • 原因：未设置开机自启；
  • 解决：执行 systemctl enable ssh。

四、安全注意事项

  1. 私钥（id_rsa）是服务器的核心凭证，严禁明文暴露、分享；
  2. GitHub Secrets 中的内容会被 AES-256 加密存储，无需担心泄露；
  3. 生产环境建议修改 SSH 端口（非 22），并开启 GitHub 账号 2FA 验证；
  4. 若需多用户部署，建议创建普通用户（如 deploy），避免直接使用 root（最小权限原则）。

五、总结

  1. 核心流程：生成密钥 → 配置权限 → 调整 SSH 服务 → 配置 GitHub Secrets → 编写 Action 脚本；
  2. 关键控制点：SSH 权限（700/600）、私钥完整性、SSH 服务配置；
  3. 验证逻辑：先本地测试密钥登录，再触发 GitHub Actions 部署。
avatar
文章
阅读
粉丝