利用Github Action与SSH实现自动化部署的完整指南

之前在一篇博客中提到过如何使用Github Action（借助easingthemes/ssh-deploy）将Hexo静态博客同步到云服务器，从而实现自动化部署。最近在搭建Mkdocs文档站点时，再次使用了这一功能，将自动生成的静态文件部署到远程服务器。本文将详细记录这个过程，分享使用心得和注意事项。

文件同步协议选择

要将文件从本地同步到远程服务器，有多种协议可选，如FTP、SFTP或SSH。对于云服务器而言，SSH协议因其安全性和便捷性成为理想选择。本文介绍的easingthemes/ssh-deploy工具正是基于Linux/Unix下的rsync（远程同步）工具，通过SSH协议实现Github与云服务器之间的文件同步。

在Github Marketplace中，可以找到许多与ssh-deploy功能相似的同步工具，它们在原理和使用方法上大同小异。

SSH部署代码示例

以下是通过ssh-deploy同步文件的Github Action配置示例（可保存为.github/workflow/ci.yml文件）：

name: Deploy to VPS

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Deploy to Server
      uses: easingthemes/ssh-deploy@main
      env:
        # 使用Github托管的VPS服务器私钥
        SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY_BJ_IPC }}
        # rsync同步参数
        ARGS: "-avzr --delete"
        # 需要同步的源文件目录
        SOURCE: "./site/"
        # 远程服务器IP地址
        REMOTE_HOST: 1.1.1.1
        # 远程服务器用户名
        REMOTE_USER: root
        # 目标同步目录
        TARGET: /www/wwwroot/ipc

在该配置中，Github Action通过SSH私钥连接远程VPS，并使用rsync工具进行文件同步。

为保障安全性，私钥应托管在Github Secrets中，使用变量引用（如secrets.SSH_PRIVATE_KEY_BJ_IPC）。同理，VPS的IP地址、用户名和同步目录等敏感信息也应通过变量配置，避免明文暴露。

VPS私钥的生成与托管

生成SSH密钥对

登录VPS服务器，执行以下命令生成RSA密钥对：

ssh-keygen -m PEM -t rsa -b 4096

执行后，系统会在.ssh目录下生成两个文件：

• id_rsa：私钥文件
• id_rsa.pub：公钥文件

接下来，将公钥导入authorized_keys文件：

cd .ssh
cat id_rsa.pub >> authorized_keys

为确保SSH连接正常，需设置正确的文件权限：

chmod 600 authorized_keys
chmod 700 ~/.ssh

配置SSH服务

编辑SSH配置文件/etc/ssh/sshd_config，确保以下设置生效：

RSAAuthentication yes
PubkeyAuthentication yes
PermitRootLogin yes

配置完成后，重启SSH服务：

systemctl restart sshd

重要提示：将私钥转换为PEM格式：

ssh-keygen -p -f ~/.ssh/id_rsa -m pem

转换后，检查id_rsa文件是否以-----BEGIN RSA PRIVATE KEY-----开头。

在Github中托管私钥

进入项目仓库的Settings页面，依次选择：

• Security → Secrets and variables → Actions → Secrets
• 点击“New repository secret”

在Name字段中命名密钥（如SSH_PRIVATE_KEY_BJ_IPC），在Secret字段中粘贴完整的私钥内容（以-----BEGIN RSA PRIVATE KEY-----开头）。

配置完成后，就可以在Action配置文件中通过${{ secrets.SSH_PRIVATE_KEY_BJ_IPC }}引用该密钥。

Rsync参数详解

easingthemes/ssh-deploy使用Linux rsync工具进行文件同步。rsync支持增量备份，具有高效和可靠的特点。以下是常用的rsync参数说明：

短参数	长参数	功能描述
-a	–archive	归档模式，递归传输文件并保持所有属性
-v	–verbose	显示详细信息，如文件列表和数量
-z	–compress	在传输过程中压缩数据
-r	–recursive	递归处理子目录
-l	–links	保留软链接
-L	–copy-links	将软链接作为普通文件处理
-p	–perms	保持文件权限
-t	–times	保持文件时间信息
-g	–group	保持文件属组信息
-o	–owner	保持文件属主信息
-D	–devices –specials	保持设备文件信息
-u	–update	不覆盖目标端比源端更新的文件
	–delete	删除目标端中源端不存在的文件
	–exclude=	排除指定文件或模式
	–progress	显示同步进度

特别说明：使用--delete选项时，目标端中新增的文件会被删除，确保两端完全一致。

优化部署速度：缓存依赖

在使用Github Action部署Mkdocs站点时，发现大部分时间都消耗在安装依赖库和环境配置上。通过调研发现，Github提供了cache action功能来缓存这些文件，从而显著提升部署效率。

虽然Github cache action有详细文档，但对于新手来说配置较为复杂。在对比Hexo部署流程时，发现使用了c-hive/gha-yarn-cache这一专门用于缓存依赖库的Action。

该工具的宣传语很好地说明了其价值：

一行命令实现yarn install缓存，专为GitHub Actions设计。GitHub Action缓存可以显著提升构建速度并减少网络依赖，但正确的缓存逻辑配置相当复杂。您需要理解缓存操作的密钥和恢复密钥工作原理。您是否知道不应该直接缓存node_modules文件夹？不同操作系统的配置各不相同，而且会在工作流中占用大量空间。现在，这些问题都将不复存在！

对于不熟悉Github cache action配置的用户来说，gha-yarn-cache提供了简单高效的解决方案。