CI/CD / 系统课时

通过 SSH 部署 Linux 服务

通过 SSH 部署 Linux 服务

当应用已经由 GitHub Actions 完成构建,最直接的服务器发布方式之一是通过 SSH 登录 Linux 主机,上传发布物、切换版本并重启服务。本节建立一条受控的 SSH 部署链路,重点避免把私钥写入仓库,以及在更新失败时留下半部署状态。

学习目标

  • 使用 GitHub Secrets 安全保存 SSH 连接所需的敏感信息
  • 设计上传发布物、远程切换版本和重启服务的部署步骤
  • 通过严格错误处理与服务状态检查判断部署是否成功

SSH 部署链路

一次受控部署通常包含 GitHub Actions Runner、目标 Linux 主机和 systemd 服务三个主要对象。Runner 使用私钥建立 SSH 连接,将构建产物复制到服务器;随后远程命令安装新版本并重启服务。任何关键步骤失败,都应立即让 Job 失败,而不是继续执行后续步骤。

SSH 部署的数据流与执行顺序

这里不应把 SSH 私钥、服务器地址或用户名直接提交到工作流文件。可以分别建立 DEPLOY_HOST、DEPLOY_USER 和 DEPLOY_SSH_KEY 等 Repository 或 Environment Secret;生产部署更适合放在受保护的 Environment 中,让凭据与部署环境绑定。

上传并执行远程更新

下面假设前面的构建步骤已经在 Runner 上生成 target/app.jar,目标服务器使用 systemd 管理名为 myapp 的服务。示例使用系统自带的 ssh 和 scp,因此没有依赖第三方 Action。

yaml
- name: Configure SSH
  shell: bash
  env:
    DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
    DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
  run: |
    set -euo pipefail
    install -m 700 -d ~/.ssh
    printf '%s\n' "$DEPLOY_SSH_KEY" > ~/.ssh/id_ed25519
    chmod 600 ~/.ssh/id_ed25519
    ssh-keyscan -H "$DEPLOY_HOST" >> ~/.ssh/known_hosts

- name: Upload artifact
  shell: bash
  env:
    DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
    DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
  run: |
    set -euo pipefail
    scp target/app.jar "$DEPLOY_USER@$DEPLOY_HOST:/tmp/app.jar"

- name: Activate release
  shell: bash
  env:
    DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
    DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
  run: |
    set -euo pipefail
    ssh "$DEPLOY_USER@$DEPLOY_HOST" 'sudo install -m 0644 /tmp/app.jar /opt/myapp/app.jar && sudo systemctl restart myapp && sudo systemctl is-active --quiet myapp'

预期结果:三个 Step 均以退出码 0 完成,最后的 systemctl is-active --quiet 不输出文本;GitHub Actions 将这些 Step 标记为成功。服务器路径、服务名和实际日志会随项目不同而变化。

text
Configure SSH   success
Upload artifact success
Activate release success

set -euo pipefail 会让未处理的命令错误尽早终止 Step。远程命令使用 && 串联,是为了确保文件安装失败时不会重启服务,而重启失败时也不会把部署误判为成功。

不要忽略主机身份验证

示例中的 ssh-keyscan 解决了无人值守 Runner 首次连接时缺少 known_hosts 的问题,但它本身并不能证明扫描到的公钥属于预期服务器。更严格的生产流程应预先核验服务器 SSH Host Key,并把确认后的公钥或指纹作为受控配置提供给工作流。

部署账号也应遵循最小权限原则。如果它只需要替换 /opt/myapp/app.jar 并重启 myapp,就不应获得不受限制的 root 权限。可以在服务器侧通过文件权限和 sudoers 精确限制允许执行的管理操作。

让发布失败得足够明确

SSH 能连接成功不代表部署成功。发布流程至少要区分上传失败、远程文件安装失败、服务重启失败和服务未进入 active 状态。scp、ssh 与 systemctl 的非零退出码都应原样传回 Runner,使工作流停止并留下可定位的失败 Step。

如果服务重启失败,可先在目标服务器查看 systemd 状态和近期日志。下面的命令适合人工排查,不应为了掩盖错误而在部署脚本后追加 || true。

bash
sudo systemctl status myapp --no-pager
sudo journalctl -u myapp -n 50 --no-pager

预期结果:正常情况下状态中可看到服务为 active (running);若启动失败,命令会展示对应状态和近期日志。PID、时间与日志正文属于动态值,实际内容可能不同。

text
Active: active (running) since <TIME>

SSH 部署适合主机数量较少、服务由 Linux 原生机制管理的场景。真正可控的关键不在于“能远程执行命令”,而在于凭据隔离、主机身份校验、最小权限、错误退出以及部署后的独立健康验证共同构成明确的成功边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

通过 SSH 部署 Linux 服务

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通