From 4b4ec070ff7755e90fadaf5093e2ee0179d84207 Mon Sep 17 00:00:00 2001 From: Fantarzero Date: Tue, 16 Sep 2025 12:57:51 +0700 Subject: [PATCH] Delete README.zh-cn.md --- README.zh-cn.md | 490 ------------------------------------------------ 1 file changed, 490 deletions(-) delete mode 100644 README.zh-cn.md diff --git a/README.zh-cn.md b/README.zh-cn.md deleted file mode 100644 index 40d6400..0000000 --- a/README.zh-cn.md +++ /dev/null @@ -1,490 +0,0 @@ -# 🚀 用于 GitHub Actions 的 SSH - -[English](./README.md) | [繁體中文](./README.zh-tw.md) | 简体中文 - -## 目录 - -- [🚀 用于 GitHub Actions 的 SSH](#-用于-github-actions-的-ssh) - - [目录](#目录) - - [📖 简介](#-简介) - - [🧩 核心概念与输入参数](#-核心概念与输入参数) - - [🔌 连接设置](#-连接设置) - - [🛠️ 指令设置](#️-指令设置) - - [🌐 代理设置](#-代理设置) - - [⚡ 快速开始](#-快速开始) - - [🔑 SSH 密钥配置与 OpenSSH 兼容性](#-ssh-密钥配置与-openssh-兼容性) - - [配置 SSH 密钥](#配置-ssh-密钥) - - [生成 RSA 密钥](#生成-rsa-密钥) - - [生成 ED25519 密钥](#生成-ed25519-密钥) - - [OpenSSH 兼容性](#openssh-兼容性) - - [🛠️ 用法场景与进阶示例](#️-用法场景与进阶示例) - - [使用密码认证](#使用密码认证) - - [使用私钥认证](#使用私钥认证) - - [多条命令](#多条命令) - - [从文件执行命令](#从文件执行命令) - - [多主机](#多主机) - - [多主机不同端口](#多主机不同端口) - - [多主机同步执行](#多主机同步执行) - - [传递环境变量到 shell 脚本](#传递环境变量到-shell-脚本) - - [🌐 代理与跳板机用法](#-代理与跳板机用法) - - [🛡️ 安全最佳实践](#️-安全最佳实践) - - [保护你的私钥](#保护你的私钥) - - [主机指纹验证](#主机指纹验证) - - [🚨 错误处理与疑难解答](#-错误处理与疑难解答) - - [常见问题](#常见问题) - - [命令未找到（npm 或其他命令）](#命令未找到npm-或其他命令) - - [🤝 贡献](#-贡献) - - [📝 许可证](#-许可证) - ---- - -## 📖 简介 - -**SSH for GitHub Actions** 是一个强大的 [GitHub Action](https://github.com/features/actions)，可让你在 CI/CD 工作流中轻松且安全地执行远程 SSH 命令。 -本项目基于 [Golang](https://go.dev) 和 [drone-ssh](https://github.com/appleboy/drone-ssh) 构建，支持多主机、代理、高级认证等多种 SSH 场景。 - -![ssh workflow](./images/ssh-workflow.png) - -[![testing main branch](https://github.com/appleboy/ssh-action/actions/workflows/main.yml/badge.svg)](https://github.com/appleboy/ssh-action/actions/workflows/main.yml) - ---- - -## 🧩 核心概念与输入参数 - -本 Action 提供灵活的 SSH 命令执行能力，并具备丰富的配置选项。 - -详细参数请参阅 [action.yml](./action.yml)。 - -### 🔌 连接设置 - -这些参数用于控制如何连接到远程主机。 - -| 参数 | 描述 | 默认值 | -| ------------------- | --------------------------------------------- | ------ | -| host | SSH 主机地址 | | -| port | SSH 端口号 | 22 | -| username | SSH 用户名 | | -| password | SSH 密码 | | -| protocol | SSH 协议版本（`tcp`、`tcp4`、`tcp6`） | tcp | -| sync | 指定多个主机时同步执行 | false | -| timeout | SSH 连接主机的超时时间 | 30s | -| key | SSH 私钥内容（如 `~/.ssh/id_rsa` 的原始内容） | | -| key_path | SSH 私钥路径 | | -| passphrase | SSH 私钥密码短语 | | -| fingerprint | 主机公钥的 SHA256 指纹 | | -| use_insecure_cipher | 允许额外（不安全）的加密算法 | false | -| cipher | 允许的加密算法，未指定时使用默认值 | | - ---- - -### 🛠️ 指令设置 - -这些参数用于控制在远程主机上执行的命令及相关行为。 - -| 参数 | 描述 | 默认值 | -| --------------- | ----------------------------------------------------- | ------ | -| script | 远程执行的命令 | | -| script_path | 仓库中包含要远程执行命令的文件路径 | | -| envs | 传递给 shell 脚本的环境变量 | | -| envs_format | 环境变量传递的灵活配置 | | -| allenvs | 传递所有带 `GITHUB_` 和 `INPUT_` 前缀的环境变量到脚本 | false | -| command_timeout | SSH 命令执行超时时间 | 10m | -| debug | 启用调试模式 | false | -| request_pty | 向服务器请求伪终端 | false | -| curl_insecure | 允许 curl 连接无证书的 SSL 站点 | false | -| version | drone-ssh 二进制版本，未指定时使用最新版本 | | - ---- - -### 🌐 代理设置 - -这些参数用于通过代理（跳板机）连接到目标主机。 - -| 参数 | 描述 | 默认值 | -| ------------------------- | ----------------------------------------- | ------ | -| proxy_host | SSH 代理主机 | | -| proxy_port | SSH 代理端口 | 22 | -| proxy_username | SSH 代理用户名 | | -| proxy_password | SSH 代理密码 | | -| proxy_passphrase | SSH 代理私钥密码短语 | | -| proxy_protocol | SSH 代理协议版本（`tcp`、`tcp4`、`tcp6`） | tcp | -| proxy_timeout | SSH 连接代理主机的超时时间 | 30s | -| proxy_key | SSH 代理私钥内容 | | -| proxy_key_path | SSH 代理私钥路径 | | -| proxy_fingerprint | 代理主机公钥的 SHA256 指纹 | | -| proxy_cipher | 代理允许的加密算法 | | -| proxy_use_insecure_cipher | 代理允许额外（不安全）的加密算法 | false | - -> **注意：** 如需实现已移除的 `script_stop` 功能，请在 shell 脚本顶部添加 `set -e`。 - ---- - -## ⚡ 快速开始 - -只需简单配置，即可在工作流中执行远程 SSH 命令： - -```yaml -name: Remote SSH Command -on: [push] -jobs: - build: - name: Build - runs-on: ubuntu-latest - steps: - - name: 执行远程 SSH 命令（密码认证） - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: linuxserver.io - password: ${{ secrets.PASSWORD }} - port: ${{ secrets.PORT }} - script: whoami -``` - -**输出：** - -```sh -======CMD====== -whoami -======END====== -linuxserver.io -=============================================== -✅ Successfully executed commands to all hosts. -=============================================== -``` - ---- - -## 🔑 SSH 密钥配置与 OpenSSH 兼容性 - -### 配置 SSH 密钥 - -建议在本地机器（而非远程服务器）上创建 SSH 密钥。请使用 GitHub Secrets 中指定的用户名登录并生成密钥对： - -#### 生成 RSA 密钥 - -```bash -ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -``` - -#### 生成 ED25519 密钥 - -```bash -ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" -``` - -将新生成的公钥添加到服务器的 authorized_keys。 [了解更多 authorized_keys](https://www.ssh.com/ssh/authorized_keys/) - -```bash -# 添加 RSA 公钥 -cat .ssh/id_rsa.pub | ssh user@host 'cat >> .ssh/authorized_keys' - -# 添加 ED25519 公钥 -cat .ssh/id_ed25519.pub | ssh user@host 'cat >> .ssh/authorized_keys' -``` - -复制私钥内容并粘贴到 GitHub Secrets。 - -```bash -# macOS -pbcopy < ~/.ssh/id_rsa -# Ubuntu -xclip < ~/.ssh/id_rsa -``` - -> **提示：** 复制内容需包含 `-----BEGIN OPENSSH PRIVATE KEY-----` 到 `-----END OPENSSH PRIVATE KEY-----`（含）。 - -ED25519 同理： - -```bash -# macOS -pbcopy < ~/.ssh/id_ed25519 -# Ubuntu -xclip < ~/.ssh/id_ed25519 -``` - -更多信息：[SSH 无密码登录](http://www.linuxproblem.org/art_9.html)。 - -> **注意：** 根据 SSH 版本，可能还需： -> -> - 将公钥放入 `.ssh/authorized_keys2` -> - 设置 `.ssh` 权限为 700 -> - 设置 `.ssh/authorized_keys2` 权限为 640 - -### OpenSSH 兼容性 - -如果出现如下错误： - -```bash -ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey] -``` - -在 Ubuntu 20.04+，你可能需要显式允许 `ssh-rsa` 算法。请在 OpenSSH 配置文件（`/etc/ssh/sshd_config` 或 `/etc/ssh/sshd_config.d/` 下的 drop-in 文件）中添加： - -```bash -CASignatureAlgorithms +ssh-rsa -``` - -或者，直接使用默认支持的 ED25519 密钥： - -```bash -ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" -``` - ---- - -## 🛠️ 用法场景与进阶示例 - -本节涵盖常见与进阶用法，包括多主机、代理、环境变量传递等。 - -### 使用密码认证 - -```yaml -- name: 执行远程 SSH 命令（密码认证） - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - password: ${{ secrets.PASSWORD }} - port: ${{ secrets.PORT }} - script: whoami -``` - -### 使用私钥认证 - -```yaml -- name: 执行远程 SSH 命令（密钥认证） - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} - script: whoami -``` - -### 多条命令 - -```yaml -- name: 多条命令 - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} - script: | - whoami - ls -al -``` - -![result](./images/output-result.png) - -### 从文件执行命令 - -```yaml -- name: 文件命令 - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} - script_path: scripts/script.sh -``` - -### 多主机 - -```diff - - name: 多主机 - uses: appleboy/ssh-action@v1 - with: -- host: "foo.com" -+ host: "foo.com,bar.com" - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} - script: | - whoami - ls -al -``` - -默认 `port` 为 `22`。 - -### 多主机不同端口 - -```diff - - name: 多主机 - uses: appleboy/ssh-action@v1 - with: -- host: "foo.com" -+ host: "foo.com:1234,bar.com:5678" - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - script: | - whoami - ls -al -``` - -### 多主机同步执行 - -```diff - - name: 多主机 - uses: appleboy/ssh-action@v1 - with: - host: "foo.com,bar.com" -+ sync: true - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} - script: | - whoami - ls -al -``` - -### 传递环境变量到 shell 脚本 - -```diff - - name: 传递环境变量 - uses: appleboy/ssh-action@v1 -+ env: -+ FOO: "BAR" -+ BAR: "FOO" -+ SHA: ${{ github.sha }} - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} -+ envs: FOO,BAR,SHA - script: | - echo "I am $FOO" - echo "I am $BAR" - echo "sha: $SHA" -``` - -> _`env` 对象中的所有环境变量必须为字符串。传递整数或其他类型可能导致意外结果。_ - ---- - -## 🌐 代理与跳板机用法 - -你可以通过代理（跳板机）连接到远程主机，适用于进阶网络拓扑。 - -```bash -+--------+ +----------+ +-----------+ -| Laptop | <--> | Jumphost | <--> | FooServer | -+--------+ +----------+ +-----------+ -``` - -示例 `~/.ssh/config`： - -```bash -Host Jumphost - HostName Jumphost - User ubuntu - Port 22 - IdentityFile ~/.ssh/keys/jump_host.pem - -Host FooServer - HostName FooServer - User ubuntu - Port 22 - ProxyCommand ssh -q -W %h:%p Jumphost -``` - -**GitHub Actions YAML:** - -```diff - - name: SSH 代理命令 - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} -+ proxy_host: ${{ secrets.PROXY_HOST }} -+ proxy_username: ${{ secrets.PROXY_USERNAME }} -+ proxy_key: ${{ secrets.PROXY_KEY }} -+ proxy_port: ${{ secrets.PROXY_PORT }} - script: | - mkdir abc/def - ls -al -``` - ---- - -## 🛡️ 安全最佳实践 - -### 保护你的私钥 - -密码短语会加密你的私钥，即使泄露也无法被攻击者直接利用。请务必妥善保管私钥。 - -```diff - - name: SSH 密钥密码短语 - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} -+ passphrase: ${{ secrets.PASSPHRASE }} - script: | - whoami - ls -al -``` - -### 主机指纹验证 - -验证 SSH 主机指纹有助于防止中间人攻击。获取主机指纹（将 `ed25519` 替换为你的密钥类型，`example.com` 替换为你的主机）： - -```sh -ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2 -``` - -更新配置： - -```diff - - name: SSH 密钥密码短语 - uses: appleboy/ssh-action@v1 - with: - host: ${{ secrets.HOST }} - username: ${{ secrets.USERNAME }} - key: ${{ secrets.KEY }} - port: ${{ secrets.PORT }} -+ fingerprint: ${{ secrets.FINGERPRINT }} - script: | - whoami - ls -al -``` - ---- - -## 🚨 错误处理与疑难解答 - -### 常见问题 - -#### 命令未找到（npm 或其他命令） - -如果遇到 "command not found" 错误，请参考 [此评论](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) 了解交互式与非交互式 shell 的区别。 - -许多 Linux 发行版的 `/etc/bash.bashrc` 包含如下内容： - -```sh -# If not running interactively, don't do anything -[ -z "$PS1" ] && return -``` - -注释掉该行或使用命令的绝对路径。 - ---- - -## 🤝 贡献 - -欢迎贡献！请提交 Pull Request 改进 `appleboy/ssh-action`。 - ---- - -## 📝 许可证 - -本项目采用 [MIT License](LICENSE) 授权。