ssh/README.zh-cn.md

# 🚀 用于 GitHub Actions 的 SSH

[GitHub Action](https://github.com/features/actions) 用于执行远程 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)

该项目使用 [Golang](https://go.dev) 和 [drone-ssh](https://github.com/appleboy/drone-ssh) 构建。🚀

## 输入变量

更详细的信息，请参考 [action.yml](./action.yml)。

| 输入参数                  | 描述                                                  | 默认值 |
| ------------------------- | ----------------------------------------------------- | ------ |
| host                      | SSH 主机地址                                          |        |
| port                      | SSH 端口号                                            | 22     |
| 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 私钥的路径                                        |        |
| fingerprint               | 主机公钥的 SHA256 指纹                                |        |
| proxy_host                | SSH 代理主机                                          |        |
| proxy_port                | SSH 代理端口                                          | 22     |
| 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_fingerprint         | 代理主机公钥的 SHA256 指纹                            |        |
| proxy_cipher              | 代理允许的密码算法                                    |        |
| proxy_use_insecure_cipher | 使用不安全的密码算法                                  | false  |
| script                    | 执行命令                                              |        |
| script_file               | 从文件执行命令                                        |        |
| script_stop               | 在第一次失败后停止脚本                                | false  |
| envs                      | 传递环境变量到 shell 脚本                             |        |
| envs_format               | 环境变量传递的灵活配置                                |        |
| debug                     | 启用调试模式                                          | false  |
| allenvs                   | 将带有 `GITHUB_` 和 `INPUT_` 前缀的环境变量传递给脚本 | false  |
| request_pty               | 请求伪终端                                            | false  |

## 使用方法

执行远程 SSH 命令

```yaml
name: remote ssh command
on: [push]
jobs:

  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
    - name: executing remote ssh commands using password
      uses: appleboy/ssh-action@v1.2.0
      with:
        host: ${{ secrets.HOST }}
        username: ${{ secrets.USERNAME }}
        password: ${{ secrets.PASSWORD }}
        port: ${{ secrets.PORT }}
        script: whoami
```

画面输出

```sh
======CMD======
whoami
======END======
out: ***
===============================================
✅ Successfully executed commands to all hosts.
===============================================
```

### 设置 SSH 密钥

请在创建 SSH 密钥并使用 SSH 密钥时遵循以下步骤。最佳做法是在本地机器上创建 SSH 密钥而不是远程机器上。请使用 Github Secrets 中指定的用户名登录。生成 RSA 密钥：

### 生成 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“
```

将新生成的密钥添加到已授权的密钥中。详细了解已授权的密钥请点[此处](https://www.ssh.com/ssh/authorized_keys/)。

### 将 RSA 密钥添加到已授权密钥中

```bash
cat .ssh/id_rsa.pub | ssh b@B ’cat >> .ssh/authorized_keys‘
```

### 将 ed25519 密钥添加到已授权密钥中

```bash
cat .ssh/id_ed25519.pub | ssh b@B ’cat >> .ssh/authorized_keys‘
```

复制私钥内容，然后将其粘贴到 Github Secrets 中。

### 复制 rsa 私钥内容

```bash
clip < ~/.ssh/id_rsa
```

### 复制 ed25519 私钥内容

```bash
clip < ~/.ssh/id_ed25519
```

有关无需密码登录 SSH 的详细信息，请[见该网站](http://www.linuxproblem.org/art_9.html)。

**来自读者的注意事项**： 根据您的 SSH 版本，您可能还需要进行以下更改：

* 将公钥放在 `.ssh/authorized_keys2` 中
* 将 `.ssh` 的权限更改为700
* 将 `.ssh/authorized_keys2` 的权限更改为640

### 如果你使用的是 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/` 中的一个附加文件）：

```bash
CASignatureAlgorithms +ssh-rsa
```

或者，`Ed25519` 密钥在 OpenSSH 中默认被接受。如果需要，您可以使用它来替代 RSA。

```bash
ssh-keygen -t ed25519 -a 200 -C ”your_email@example.com“
```

### Example

#### 使用密码执行远程 SSH 命令

```yaml
- name: executing remote ssh commands using password
  uses: appleboy/ssh-action@v1.2.0
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USERNAME }}
    password: ${{ secrets.PASSWORD }}
    port: ${{ secrets.PORT }}
    script: whoami
```

#### 使用私钥

```yaml
- name: executing remote ssh commands using ssh key
  uses: appleboy/ssh-action@v1.2.0
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USERNAME }}
    key: ${{ secrets.KEY }}
    port: ${{ secrets.PORT }}
    script: whoami
```

#### 多个命令

```yaml
- name: multiple command
  uses: appleboy/ssh-action@v1.2.0
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USERNAME }}
    key: ${{ secrets.KEY }}
    port: ${{ secrets.PORT }}
    script: |
      whoami
      ls -al
```

![result](./images/output-result.png)

#### 多台主机

```diff
  - name: multiple host
    uses: appleboy/ssh-action@v1.2.0
    with:
-     host: ”foo.com“
+     host: ”foo.com,bar.com“
      username: ${{ secrets.USERNAME }}
      key: ${{ secrets.KEY }}
      port: ${{ secrets.PORT }}
      script: |
        whoami
        ls -al
```

#### Commands from a file

```yaml
- name: file commands
  uses: appleboy/ssh-action@v1.2.0
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USERNAME }}
    key: ${{ secrets.KEY }}
    port: ${{ secrets.PORT }}
    script_path: scripts/script.sh 
```

#### 多个不同端口的主机

```diff
  - name: multiple host
    uses: appleboy/ssh-action@v1.2.0
    with:
-     host: ”foo.com“
+     host: ”foo.com:1234,bar.com:5678“
      username: ${{ secrets.USERNAME }}
      key: ${{ secrets.KEY }}
      script: |
        whoami
        ls -al
```

#### 在多台主机上同步执行

```diff
  - name: multiple host
    uses: appleboy/ssh-action@v1.2.0
    with:
      host: ”foo.com,bar.com“
+     sync: true
      username: ${{ secrets.USERNAME }}
      key: ${{ secrets.KEY }}
      port: ${{ secrets.PORT }}
      script: |
        whoami
        ls -al
```

#### 将环境变量传递到 Shell 脚本

```diff
  - name: pass environment
    uses: appleboy/ssh-action@v1.2.0
+   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` 对象中，您需要将每个环境变量作为字符串传递，传递 `Integer` 数据类型或任何其他类型可能会产生意外结果。_

#### 在第一次失败后停止脚本

> ex: missing `abc` folder

```diff
  - name: stop script if command error
    uses: appleboy/ssh-action@v1.2.0
    with:
      host: ${{ secrets.HOST }}
      username: ${{ secrets.USERNAME }}
      key: ${{ secrets.KEY }}
      port: ${{ secrets.PORT }}
+     script_stop: true
      script: |
        mkdir abc/def
        ls -al
```

画面输出：

```sh
======CMD======
mkdir abc/def
ls -al

======END======
2019/11/21 01:16:21 Process exited with status 1
err: mkdir: cannot create directory ‘abc/def’: No such file or directory
##[error]Docker run failed with exit code 1
```

#### 如何使用 `ProxyCommand` 连接远程服务器？

```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
```

#### 如何将其转换为 GitHubActions 的 YAML 格式？

```diff
  - name: ssh proxy command
    uses: appleboy/ssh-action@v1.2.0
    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 key passphrase
    uses: appleboy/ssh-action@v1.2.0
    with:
      host: ${{ secrets.HOST }}
      username: ${{ secrets.USERNAME }}
      key: ${{ secrets.KEY }}
      port: ${{ secrets.PORT }}
+     passphrase: ${{ secrets.PASSPHRASE }}
      script: |
        whoami
        ls -al
```

#### 使用主机指纹验证

设置 SSH 主机指纹验证可以帮助防止中间人攻击。在设置之前，运行以下命令以获取 SSH 主机指纹。请记得将 `ed25519` 替换为您适当的密钥类型（`rsa`、 `dsa`等），而 `example.com` 则替换为您的主机。

现代 OpenSSH 版本中，需要提取的_默认密钥_类型是 `rsa`（从版本 5.1 开始）、`ecdsa`（从版本 6.0 开始）和 `ed25519`（从版本 6.7 开始）。

```sh
ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ’ ‘ -f2
```

现在您可以调整您的配置：

```diff
  - name: ssh key passphrase
    uses: appleboy/ssh-action@v1.2.0
    with:
      host: ${{ secrets.HOST }}
      username: ${{ secrets.USERNAME }}
      key: ${{ secrets.KEY }}
      port: ${{ secrets.PORT }}
+     fingerprint: ${{ secrets.FINGERPRINT }}
      script: |
        whoami
        ls -al
```

## 贡献

我们非常希望您为 `appleboy/ssh-action` 做出贡献，欢迎提交请求！

## 授权方式

本项目中的脚本和文档采用 [MIT](LICENSE) 许可证 发布。