mirror of
https://github.com/appleboy/ssh-action.git
synced 2025-06-20 16:42:10 +10:00
docs: rewrite and unify documentation across all supported languages
- Rewrite and reorganize documentation for clarity and readability, including reworded introductions and consistent headings. - Improve input parameter tables: clarify descriptions, unify formatting, and better explain parameter purposes across all three languages. - Expand and update step-by-step SSH key setup guides, streamline copy instructions, and add practical notes and tips. - Enhance usage examples with clearer titles, better labels, and updated YAML examples for different authentication methods and scenarios. - Add new sections and tips on OpenSSH compatibility and troubleshooting "command not found" issues, with improved cross-platform guidance. - Refine explanations for host fingerprint verification, proxy setup, and command environment management. - Update and polish contributing and license sections for greater encouragement and style consistency. - Apply the above documentation improvements to both Simplified and Traditional Chinese versions for parity. Signed-off-by: appleboy <appleboy.tw@gmail.com>
This commit is contained in:
appleboy
parent
0e19dd962d
commit
b80f638dc4
3 changed files with 384 additions and 351 deletions
232
README.zh-cn.md
232
README.zh-cn.md
|
|
@ -2,71 +2,75 @@
|
|||
|
||||
[English](./README.md) | [繁體中文](./README.zh-tw.md) | 简体中文
|
||||
|
||||
一个用于执行远程 SSH 命令的 [GitHub Action](https://github.com/features/actions)。
|
||||
一个让你轻松安全地执行远程 SSH 命令的 [GitHub Action](https://github.com/features/actions)。
|
||||
|
||||
|
||||
|
||||
[](https://github.com/appleboy/ssh-action/actions/workflows/main.yml)
|
||||
|
||||
该项目使用 [Golang](https://go.dev) 和 [drone-ssh](https://github.com/appleboy/drone-ssh) 构建。🚀
|
||||
本项目基于 [Golang](https://go.dev) 和 [drone-ssh](https://github.com/appleboy/drone-ssh) 构建。
|
||||
|
||||
## 输入变量
|
||||
---
|
||||
|
||||
有关更详细的信息，请参阅 [action.yml](./action.yml)。
|
||||
## 📥 输入参数
|
||||
|
||||
| 输入参数 | 描述 | 默认值 |
|
||||
详细参数请参阅 [action.yml](./action.yml)。
|
||||
|
||||
| 参数 | 描述 | 默认值 |
|
||||
| ------------------------- | ----------------------------------------------------- | ------ |
|
||||
| host | SSH 主机地址 | |
|
||||
| port | SSH 端口号 | 22 |
|
||||
| passphrase | SSH 密钥密码短语 | |
|
||||
| passphrase | SSH 私钥密码短语 | |
|
||||
| username | SSH 用户名 | |
|
||||
| password | SSH 密码 | |
|
||||
| protocol | SSH 协议版本（tcp, tcp4, tcp6） | tcp |
|
||||
| sync | 如果指定了多个主机，则启用同步执行 | false |
|
||||
| use_insecure_cipher | 使用不安全的密码算法 | false |
|
||||
| cipher | 允许的密码算法。如果未指定，则使用适当的默认值 | |
|
||||
| timeout | SSH 连接到主机的超时时间 | 30s |
|
||||
| command_timeout | SSH 命令的超时时间 | 10m |
|
||||
| key | SSH 私钥的内容，例如 ~/.ssh/id_rsa 的原始内容 | |
|
||||
| key_path | SSH 私钥的路径 | |
|
||||
| protocol | SSH 协议版本（`tcp`、`tcp4`、`tcp6`） | tcp |
|
||||
| sync | 指定多个主机时同步执行 | false |
|
||||
| use_insecure_cipher | 允许额外（不安全）的加密算法 | false |
|
||||
| cipher | 允许的加密算法，未指定时使用默认值 | |
|
||||
| timeout | SSH 连接主机的超时时间 | 30s |
|
||||
| command_timeout | SSH 命令执行超时时间 | 10m |
|
||||
| key | SSH 私钥内容（如 `~/.ssh/id_rsa` 的原始内容） | |
|
||||
| key_path | SSH 私钥路径 | |
|
||||
| fingerprint | 主机公钥的 SHA256 指纹 | |
|
||||
| proxy_host | SSH 代理主机 | |
|
||||
| proxy_port | SSH 代理端口 | 22 |
|
||||
| proxy_protocol | SSH 代理协议版本（tcp, tcp4, tcp6） | tcp |
|
||||
| proxy_protocol | SSH 代理协议版本（`tcp`、`tcp4`、`tcp6`） | tcp |
|
||||
| proxy_username | SSH 代理用户名 | |
|
||||
| proxy_password | SSH 代理密码 | |
|
||||
| proxy_passphrase | SSH 代理密钥密码短语 | |
|
||||
| proxy_timeout | SSH 连接到代理主机的超时时间 | 30s |
|
||||
| proxy_key | SSH 代理私钥的内容 | |
|
||||
| proxy_key_path | SSH 代理私钥的路径 | |
|
||||
| proxy_passphrase | SSH 代理私钥密码短语 | |
|
||||
| proxy_timeout | SSH 连接代理主机的超时时间 | 30s |
|
||||
| proxy_key | SSH 代理私钥内容 | |
|
||||
| proxy_key_path | SSH 代理私钥路径 | |
|
||||
| proxy_fingerprint | 代理主机公钥的 SHA256 指纹 | |
|
||||
| proxy_cipher | 代理允许的密码算法 | |
|
||||
| proxy_use_insecure_cipher | 使用不安全的密码算法 | false |
|
||||
| script | 执行命令 | |
|
||||
| script_path | 从文件执行命令 | |
|
||||
| envs | 传递环境变量到 shell 脚本 | |
|
||||
| proxy_cipher | 代理允许的加密算法 | |
|
||||
| proxy_use_insecure_cipher | 代理允许额外（不安全）的加密算法 | false |
|
||||
| script | 远程执行的命令 | |
|
||||
| script_path | 包含要执行命令的文件路径 | |
|
||||
| envs | 传递给 shell 脚本的环境变量 | |
|
||||
| envs_format | 环境变量传递的灵活配置 | |
|
||||
| debug | 启用调试模式 | false |
|
||||
| allenvs | 将带有 `GITHUB_` 和 `INPUT_` 前缀的环境变量传递给脚本 | false |
|
||||
| request_pty | 请求伪终端 | false |
|
||||
| curl_insecure | 在 curl 中使用不安全的证书验证 | false |
|
||||
| version | drone-ssh 版本号。若未指定，将使用最新版本。 | |
|
||||
| allenvs | 传递所有带 `GITHUB_` 和 `INPUT_` 前缀的环境变量到脚本 | false |
|
||||
| request_pty | 向服务器请求伪终端 | false |
|
||||
| curl_insecure | 允许 curl 连接无证书的 SSL 站点 | false |
|
||||
| version | drone-ssh 二进制版本，未指定时使用最新版本 | |
|
||||
|
||||
**注意：** 用户可以在他们的 shell 脚本中添加 `set -e` 以实现类似于已删除的 `script_stop` 选项的功能。
|
||||
> **注意：** 如需实现已移除的 `script_stop` 功能，请在 shell 脚本顶部添加 `set -e`。
|
||||
|
||||
## 使用方法
|
||||
---
|
||||
|
||||
执行远程 SSH 命令。
|
||||
## 🚦 使用示例
|
||||
|
||||
在工作流中执行远程 SSH 命令：
|
||||
|
||||
```yaml
|
||||
name: remote ssh command
|
||||
name: Remote SSH Command
|
||||
on: [push]
|
||||
jobs:
|
||||
build:
|
||||
name: Build
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: executing remote ssh commands using password
|
||||
- name: 执行远程 SSH 命令（密码认证）
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
|
|
@ -76,7 +80,7 @@ jobs:
|
|||
script: whoami
|
||||
```
|
||||
|
||||
输出：
|
||||
**输出：**
|
||||
|
||||
```sh
|
||||
======CMD======
|
||||
|
|
@ -88,11 +92,11 @@ linuxserver.io
|
|||
===============================================
|
||||
```
|
||||
|
||||
### 设置 SSH 密钥
|
||||
---
|
||||
|
||||
请按照以下步骤创建和使用 SSH 密钥。
|
||||
最佳做法是在本地机器上创建 SSH 密钥，而不是在远程机器上。
|
||||
使用 GitHub Secrets 中指定的用户名登录并生成 RSA 密钥对：
|
||||
## 🔑 配置 SSH 密钥
|
||||
|
||||
建议在本地机器（而非远程服务器）上创建 SSH 密钥。请使用 GitHub Secrets 中指定的用户名登录并生成密钥对：
|
||||
|
||||
### 生成 RSA 密钥
|
||||
|
||||
|
|
@ -100,38 +104,23 @@ linuxserver.io
|
|||
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
|
||||
```
|
||||
|
||||
### 生成 ed25519 密钥
|
||||
### 生成 ED25519 密钥
|
||||
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
||||
```
|
||||
|
||||
将新生成的密钥添加到已授权的密钥中。详细了解已授权的密钥请点[此处](https://www.ssh.com/ssh/authorized_keys/)。
|
||||
|
||||
### 将 RSA 密钥添加到已授权密钥中
|
||||
将新生成的公钥添加到服务器的 authorized_keys。 [了解更多 authorized_keys](https://www.ssh.com/ssh/authorized_keys/)
|
||||
|
||||
```bash
|
||||
cat .ssh/id_rsa.pub | ssh b@B 'cat >> .ssh/authorized_keys'
|
||||
# 添加 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'
|
||||
```
|
||||
|
||||
### 将 ed25519 密钥添加到已授权密钥中
|
||||
|
||||
```bash
|
||||
cat .ssh/id_ed25519.pub | ssh b@B 'cat >> .ssh/authorized_keys'
|
||||
```
|
||||
|
||||
复制私钥内容，然后将其粘贴到 GitHub Secrets 中。
|
||||
|
||||
### 复制 RSA 私钥内容
|
||||
|
||||
在复制私钥之前，按照以下步骤安装 `clip` 命令：
|
||||
|
||||
```bash
|
||||
# Ubuntu
|
||||
sudo apt-get install xclip
|
||||
```
|
||||
|
||||
复制私钥：
|
||||
复制私钥内容并粘贴到 GitHub Secrets。
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
|
|
@ -140,9 +129,9 @@ pbcopy < ~/.ssh/id_rsa
|
|||
xclip < ~/.ssh/id_rsa
|
||||
```
|
||||
|
||||
从包含注释部分 `-----BEGIN OPENSSH PRIVATE KEY-----` 开始，到包含注释部分 `-----END OPENSSH PRIVATE KEY-----` 结束，复制私钥并将其粘贴到 GitHub Secrets 中。
|
||||
> **提示：** 复制内容需包含 `-----BEGIN OPENSSH PRIVATE KEY-----` 到 `-----END OPENSSH PRIVATE KEY-----`（含）。
|
||||
|
||||
### 复制 ed25519 私钥内容
|
||||
ED25519 同理：
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
|
|
@ -151,40 +140,44 @@ pbcopy < ~/.ssh/id_ed25519
|
|||
xclip < ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
有关无需密码登录 SSH 的详细信息，请[见该网站](http://www.linuxproblem.org/art_9.html)。
|
||||
更多信息：[SSH 无密码登录](http://www.linuxproblem.org/art_9.html)。
|
||||
|
||||
**注意**：根据您的 SSH 版本，您可能还需要进行以下更改：
|
||||
> **注意：** 根据 SSH 版本，可能还需：
|
||||
>
|
||||
> - 将公钥放入 `.ssh/authorized_keys2`
|
||||
> - 设置 `.ssh` 权限为 700
|
||||
> - 设置 `.ssh/authorized_keys2` 权限为 640
|
||||
|
||||
- 将公钥放在 `.ssh/authorized_keys2` 中
|
||||
- 将 `.ssh` 的权限更改为 700
|
||||
- 将 `.ssh/authorized_keys2` 的权限更改为 640
|
||||
---
|
||||
|
||||
### 如果你使用的是 OpenSSH
|
||||
## 🛡️ OpenSSH 兼容性
|
||||
|
||||
如果您正在使用 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/` 中的一个附加文件）：
|
||||
在 Ubuntu 20.04+，你可能需要显式允许 `ssh-rsa` 算法。请在 OpenSSH 配置文件（`/etc/ssh/sshd_config` 或 `/etc/ssh/sshd_config.d/` 下的 drop-in 文件）中添加：
|
||||
|
||||
```bash
|
||||
CASignatureAlgorithms +ssh-rsa
|
||||
```
|
||||
|
||||
或者，`ed25519` 密钥在 OpenSSH 中默认被接受。如果需要，您可以使用它来替代 RSA：
|
||||
或者，直接使用默认支持的 ED25519 密钥：
|
||||
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
||||
```
|
||||
|
||||
### 示例
|
||||
---
|
||||
|
||||
#### 使用密码执行远程 SSH 命令
|
||||
## 🧑💻 更多用法示例
|
||||
|
||||
### 使用密码认证
|
||||
|
||||
```yaml
|
||||
- name: executing remote ssh commands using password
|
||||
- name: 执行远程 SSH 命令（密码认证）
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
|
|
@ -194,10 +187,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
|||
script: whoami
|
||||
```
|
||||
|
||||
#### 使用私钥
|
||||
### 使用私钥认证
|
||||
|
||||
```yaml
|
||||
- name: executing remote ssh commands using ssh key
|
||||
- name: 执行远程 SSH 命令（密钥认证）
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
|
|
@ -207,10 +200,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
|||
script: whoami
|
||||
```
|
||||
|
||||
#### 多个命令
|
||||
### 多条命令
|
||||
|
||||
```yaml
|
||||
- name: multiple command
|
||||
- name: 多条命令
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
|
|
@ -224,10 +217,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
|||
|
||||
|
||||
|
||||
#### 从文件执行命令
|
||||
### 从文件执行命令
|
||||
|
||||
```yaml
|
||||
- name: file commands
|
||||
- name: 文件命令
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
|
|
@ -237,10 +230,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
|||
script_path: scripts/script.sh
|
||||
```
|
||||
|
||||
#### 多台主机
|
||||
### 多主机
|
||||
|
||||
```diff
|
||||
- name: multiple host
|
||||
- name: 多主机
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
- host: "foo.com"
|
||||
|
|
@ -253,12 +246,12 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
|||
ls -al
|
||||
```
|
||||
|
||||
默认的 `port` 值是 `22`。
|
||||
默认 `port` 为 `22`。
|
||||
|
||||
#### 多个不同端口的主机
|
||||
### 多主机不同端口
|
||||
|
||||
```diff
|
||||
- name: multiple host
|
||||
- name: 多主机
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
- host: "foo.com"
|
||||
|
|
@ -270,10 +263,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
|||
ls -al
|
||||
```
|
||||
|
||||
#### 在多台主机上同步执行
|
||||
### 多主机同步执行
|
||||
|
||||
```diff
|
||||
- name: multiple host
|
||||
- name: 多主机
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: "foo.com,bar.com"
|
||||
|
|
@ -286,10 +279,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
|||
ls -al
|
||||
```
|
||||
|
||||
#### 将环境变量传递到 shell 脚本
|
||||
### 传递环境变量到 shell 脚本
|
||||
|
||||
```diff
|
||||
- name: pass environment
|
||||
- name: 传递环境变量
|
||||
uses: appleboy/ssh-action@v1
|
||||
+ env:
|
||||
+ FOO: "BAR"
|
||||
|
|
@ -307,9 +300,11 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
|||
echo "sha: $SHA"
|
||||
```
|
||||
|
||||
_在 `env` 对象中，您需要将每个环境变量作为字符串传递，传递 `Integer` 数据类型或任何其他类型可能会产生意外结果。_
|
||||
> _`env` 对象中的所有环境变量必须为字符串。传递整数或其他类型可能导致意外结果。_
|
||||
|
||||
#### 如何使用 `ProxyCommand` 连接远程服务器？
|
||||
---
|
||||
|
||||
## 🌐 使用 ProxyCommand（跳板机）
|
||||
|
||||
```bash
|
||||
+--------+ +----------+ +-----------+
|
||||
|
|
@ -317,7 +312,7 @@ _在 `env` 对象中，您需要将每个环境变量作为字符串传递，传
|
|||
+--------+ +----------+ +-----------+
|
||||
```
|
||||
|
||||
在您的 `~/.ssh/config` 文件中，您会看到以下内容。
|
||||
示例 `~/.ssh/config`：
|
||||
|
||||
```bash
|
||||
Host Jumphost
|
||||
|
|
@ -333,10 +328,10 @@ Host FooServer
|
|||
ProxyCommand ssh -q -W %h:%p Jumphost
|
||||
```
|
||||
|
||||
#### 如何将其转换为 GitHubActions 的 YAML 格式？
|
||||
**GitHub Actions YAML:**
|
||||
|
||||
```diff
|
||||
- name: ssh proxy command
|
||||
- name: SSH 代理命令
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
|
|
@ -352,12 +347,14 @@ Host FooServer
|
|||
ls -al
|
||||
```
|
||||
|
||||
#### 保护私钥
|
||||
---
|
||||
|
||||
密码短语通常用于加密私钥。这使得密钥文件本身对攻击者无用。文件泄露可能来自备份或停用的硬件，黑客通常可以从受攻击系统中泄露文件。
|
||||
## 🔒 保护你的私钥
|
||||
|
||||
密码短语会加密你的私钥，即使泄露也无法被攻击者直接利用。请务必妥善保管私钥。
|
||||
|
||||
```diff
|
||||
- name: ssh key passphrase
|
||||
- name: SSH 密钥密码短语
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
|
|
@ -370,20 +367,20 @@ Host FooServer
|
|||
ls -al
|
||||
```
|
||||
|
||||
#### 使用主机指纹验证
|
||||
---
|
||||
|
||||
设置 SSH 主机指纹验证可以帮助防止中间人攻击。在设置之前，运行以下命令以获取 SSH 主机指纹。请记得将 `ed25519` 替换为您适当的密钥类型（`rsa`、 `dsa`等），而 `example.com` 则替换为您的主机。
|
||||
## 🖐️ 主机指纹验证
|
||||
|
||||
在现代 OpenSSH 版本中，默认提取的密钥类型是 `rsa`（从版本 5.1 开始）、`ecdsa`（从版本 6.0 开始）和 `ed25519`（从版本 6.7 开始）。
|
||||
验证 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 key passphrase
|
||||
- name: SSH 密钥密码短语
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
|
|
@ -396,10 +393,31 @@ ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' '
|
|||
ls -al
|
||||
```
|
||||
|
||||
## 贡献
|
||||
---
|
||||
|
||||
我们非常希望您为 `appleboy/ssh-action` 做出贡献，欢迎提交请求！
|
||||
## ❓ 常见问题
|
||||
|
||||
## 授权方式
|
||||
### 命令未找到（npm 或其他命令）
|
||||
|
||||
本项目中的脚本和文档采用 [MIT 许可证](LICENSE) 发布。
|
||||
如果遇到 "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) 授权。
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue