actions/ssh-action
0
0
Fork 0
mirror of https://github.com/appleboy/ssh-action.git synced 2025-04-28 19:49:22 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

docs: rewrite and unify documentation across all supported languages

Browse Source 
- 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 2025-04-27 09:47:26 +08:00
parent 0e19dd962d
commit b80f638dc4
No known key found for this signature in database
3 changed files with 384 additions and 351 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

265
README.md
View File

@ -2,71 +2,75 @@
English | [繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md) English | [繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md)
A [GitHub Action](https://github.com/features/actions) for executing remote SSH commands. A [GitHub Action](https://github.com/features/actions) for executing remote SSH commands easily and securely.
![ssh workflow](./images/ssh-workflow.png) ![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) [![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)
This project is built with [Golang](https://go.dev) and [drone-ssh](https://github.com/appleboy/drone-ssh). 🚀 This project is built with [Golang](https://go.dev) and [drone-ssh](https://github.com/appleboy/drone-ssh).
## Input variables ---
Refer to [action.yml](./action.yml) for more detailed information. ## 📥 Input Parameters
| Input Parameter | Description | Default Value | For full details, see [action.yml](./action.yml).
| ------------------------- | ---------------------------------------------------------------------------------------- | ------------- |
| host | SSH host address | |
| port | SSH port number | 22 |
| passphrase | SSH key passphrase | |
| username | SSH username | |
| password | SSH password | |
| protocol | SSH protocol version (tcp, tcp4, tcp6) | tcp |
| sync | Enable synchronous execution if multiple hosts are specified | false |
| use_insecure_cipher | Include more ciphers with use_insecure_cipher | false |
| cipher | Allowed cipher algorithms. If unspecified, sensible defaults are used | |
| timeout | Timeout duration for SSH to host | 30s |
| command_timeout | Timeout duration for SSH command | 10m |
| key | Content of SSH private key. e.g., raw content of ~/.ssh/id_rsa | |
| key_path | Path of SSH private key | |
| fingerprint | SHA256 fingerprint of the host public key | |
| proxy_host | SSH proxy host | |
| proxy_port | SSH proxy port | 22 |
| proxy_protocol | SSH proxy protocol version (tcp, tcp4, tcp6) | tcp |
| proxy_username | SSH proxy username | |
| proxy_password | SSH proxy password | |
| proxy_passphrase | SSH proxy key passphrase | |
| proxy_timeout | Timeout for SSH to proxy host | 30s |
| proxy_key | Content of SSH proxy private key | |
| proxy_key_path | Path of SSH proxy private key | |
| proxy_fingerprint | SHA256 fingerprint of the proxy host public key | |
| proxy_cipher | Allowed cipher algorithms for the proxy | |
| proxy_use_insecure_cipher | Include more ciphers with use_insecure_cipher for the proxy | false |
| script | Execute commands | |
| script_path | Execute commands from a file | |
| envs | Pass environment variables to the shell script | |
| envs_format | Flexible configuration of environment value transfer | |
| debug | Enable debug mode | false |
| allenvs | Pass the environment variables with prefix value of `GITHUB_` and `INPUT_` to the script | false |
| request_pty | Request a pseudo-terminal from the server | false |
| curl_insecure | Allow curl to connect to SSL sites without certificates | false |
| version | drone-ssh binary version. If not specified, the latest version will be used. | |
**Note:** Users can add `set -e` in their shell script to achieve similar functionality to the removed `script_stop` option. | Parameter | Description | Default |
| ------------------------- | --------------------------------------------------------------------------------- | ------- |
| host | SSH host address | |
| port | SSH port number | 22 |
| passphrase | Passphrase for the SSH private key | |
| username | SSH username | |
| password | SSH password | |
| protocol | SSH protocol version (`tcp`, `tcp4`, `tcp6`) | tcp |
| sync | Run synchronously if multiple hosts are specified | false |
| use_insecure_cipher | Allow additional (less secure) ciphers | false |
| cipher | Allowed cipher algorithms. Uses sensible defaults if unspecified | |
| timeout | Timeout for SSH connection to host | 30s |
| command_timeout | Timeout for SSH command execution | 10m |
| key | Content of SSH private key (e.g., raw content of `~/.ssh/id_rsa`) | |
| key_path | Path to SSH private key | |
| fingerprint | SHA256 fingerprint of the host public key | |
| proxy_host | SSH proxy host | |
| proxy_port | SSH proxy port | 22 |
| proxy_protocol | SSH proxy protocol version (`tcp`, `tcp4`, `tcp6`) | tcp |
| proxy_username | SSH proxy username | |
| proxy_password | SSH proxy password | |
| proxy_passphrase | SSH proxy key passphrase | |
| proxy_timeout | Timeout for SSH connection to proxy host | 30s |
| proxy_key | Content of SSH proxy private key | |
| proxy_key_path | Path to SSH proxy private key | |
| proxy_fingerprint | SHA256 fingerprint of the proxy host public key | |
| proxy_cipher | Allowed cipher algorithms for the proxy | |
| proxy_use_insecure_cipher | Allow additional (less secure) ciphers for the proxy | false |
| script | Commands to execute remotely | |
| script_path | Path to a file containing commands to execute | |
| envs | Environment variables to pass to the shell script | |
| envs_format | Flexible configuration for environment variable transfer | |
| debug | Enable debug mode | false |
| allenvs | Pass all environment variables with `GITHUB_` and `INPUT_` prefixes to the script | false |
| request_pty | Request a pseudo-terminal from the server | false |
| curl_insecure | Allow curl to connect to SSL sites without certificates | false |
| version | drone-ssh binary version. If not specified, the latest version will be used. | |
## Usage > **Note:** To mimic the removed `script_stop` option, add `set -e` at the top of your shell script.
Executing remote SSH commands. ---
## 🚦 Usage Example
Run remote SSH commands in your workflow:
```yaml ```yaml
name: remote ssh command name: Remote SSH Command
on: [push] on: [push]
jobs: jobs:
build: build:
name: Build name: Build
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- name: executing remote ssh commands using password - name: Execute remote SSH commands using password
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -76,7 +80,7 @@ jobs:
script: whoami script: whoami
``` ```
output: **Output:**
```sh ```sh
======CMD====== ======CMD======
@ -88,50 +92,35 @@ linuxserver.io
=============================================== ===============================================
``` ```
### Setting up a SSH Key ---
Follow the steps below to create and use SSH Keys. ## 🔑 Setting Up SSH Keys
It is best practice to create SSH Keys on your local machine, not on a remote machine.
Log in with the username specified in GitHub Secrets and generate an RSA Key-Pair:
### Generate rsa key It is best practice to create SSH keys on your local machine (not on a remote server). Log in with the username specified in GitHub Secrets and generate a key pair:
### Generate RSA key
```bash ```bash
ssh-keygen -t rsa -b 4096 -C "your_email@example.com" ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
``` ```
### Generate ed25519 key ### Generate ED25519 key
```bash ```bash
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
``` ```
Add the newly generated key to the Authorized keys. Read more about authorized keys [here](https://www.ssh.com/ssh/authorized_keys/). Add the new public key to the authorized keys on your server. [Learn more about authorized keys.](https://www.ssh.com/ssh/authorized_keys/)
### Add rsa key into Authorized keys
```bash ```bash
cat .ssh/id_rsa.pub | ssh b@B 'cat >> .ssh/authorized_keys' # Add RSA key
cat .ssh/id_rsa.pub | ssh user@host 'cat >> .ssh/authorized_keys'
# Add ED25519 key
cat .ssh/id_ed25519.pub | ssh user@host 'cat >> .ssh/authorized_keys'
``` ```
### Add ed25519 key into Authorized keys Copy the private key content and paste it into GitHub Secrets.
```bash
cat .ssh/id_ed25519.pub | ssh b@B 'cat >> .ssh/authorized_keys'
```
Copy the Private Key content and paste it into GitHub Secrets.
### Copy rsa Private key
Before copying the private key, install the `clip` command as shown below:
```bash
# Ubuntu
sudo apt-get install xclip
```
Copy the private key:
```bash ```bash
# macOS # macOS
@ -140,9 +129,9 @@ pbcopy < ~/.ssh/id_rsa
xclip < ~/.ssh/id_rsa xclip < ~/.ssh/id_rsa
``` ```
Starting from and including the comment section `-----BEGIN OPENSSH PRIVATE KEY-----` and ending at and including the comment section `-----END OPENSSH PRIVATE KEY-----`, copy the private key and paste it into GitHub Secrets. > **Tip:** Copy from `-----BEGIN OPENSSH PRIVATE KEY-----` to `-----END OPENSSH PRIVATE KEY-----` (inclusive).
### Copy ed25519 Private key For ED25519:
```bash ```bash
# macOS # macOS
@ -151,40 +140,44 @@ pbcopy < ~/.ssh/id_ed25519
xclip < ~/.ssh/id_ed25519 xclip < ~/.ssh/id_ed25519
``` ```
See detailed information about [SSH login without a password](http://www.linuxproblem.org/art_9.html). See more: [SSH login without a password](http://www.linuxproblem.org/art_9.html).
**Note**: Depending on your version of SSH, you might also need to make the following changes: > **Note:** Depending on your SSH version, you may also need to:
>
> - Place the public key in `.ssh/authorized_keys2`
> - Set `.ssh` permissions to 700
> - Set `.ssh/authorized_keys2` permissions to 640
- Put the public key in `.ssh/authorized_keys2` ---
- Change the permissions of `.ssh` to 700
- Change the permissions of `.ssh/authorized_keys2` to 640
### If you are using OpenSSH ## 🛡️ OpenSSH Compatibility
If you are currently using OpenSSH and are getting the following error: If you see this error:
```bash ```bash
ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey] ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey]
``` ```
Ensure that your chosen key algorithm is supported. On Ubuntu 20.04 or later, you must explicitly allow the use of the ssh-rsa algorithm. Add the following line to your OpenSSH daemon file (either `/etc/ssh/sshd_config` or a drop-in file under `/etc/ssh/sshd_config.d/`): On Ubuntu 20.04+ you may need to explicitly allow the `ssh-rsa` algorithm. Add this to your OpenSSH daemon config (`/etc/ssh/sshd_config` or a drop-in under `/etc/ssh/sshd_config.d/`):
```bash ```bash
CASignatureAlgorithms +ssh-rsa CASignatureAlgorithms +ssh-rsa
``` ```
Alternatively, `ed25519` keys are accepted by default in OpenSSH. You can use this instead of rsa if needed: Alternatively, use ED25519 keys (supported by default):
```bash ```bash
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
``` ```
### Example ---
#### Executing remote ssh commands using password ## 🧑‍💻 More Usage Examples
### Using password authentication
```yaml ```yaml
- name: executing remote ssh commands using password - name: Execute remote SSH commands using password
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -194,10 +187,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script: whoami script: whoami
``` ```
#### Using private key ### Using private key authentication
```yaml ```yaml
- name: executing remote ssh commands using ssh key - name: Execute remote SSH commands using SSH key
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -207,10 +200,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script: whoami script: whoami
``` ```
#### Multiple Commands ### Multiple commands
```yaml ```yaml
- name: multiple command - name: Multiple commands
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -224,10 +217,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
![result](./images/output-result.png) ![result](./images/output-result.png)
#### Commands from a file ### Run commands from a file
```yaml ```yaml
- name: file commands - name: File commands
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -237,10 +230,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script_path: scripts/script.sh script_path: scripts/script.sh
``` ```
#### Multiple Hosts ### Multiple hosts
```diff ```diff
- name: multiple host - name: Multiple hosts
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
- host: "foo.com" - host: "foo.com"
@ -253,12 +246,12 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
ls -al ls -al
``` ```
The default value of `port` is `22`. Default `port` is `22`.
#### Multiple hosts with different port ### Multiple hosts with different ports
```diff ```diff
- name: multiple host - name: Multiple hosts
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
- host: "foo.com" - host: "foo.com"
@ -270,10 +263,10 @@ The default value of `port` is `22`.
ls -al ls -al
``` ```
#### Synchronous execution on multiple hosts ### Synchronous execution on multiple hosts
```diff ```diff
- name: multiple host - name: Multiple hosts
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: "foo.com,bar.com" host: "foo.com,bar.com"
@ -286,10 +279,10 @@ The default value of `port` is `22`.
ls -al ls -al
``` ```
#### Pass environment variable to shell script ### Pass environment variables to shell script
```diff ```diff
- name: pass environment - name: Pass environment
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
+ env: + env:
+ FOO: "BAR" + FOO: "BAR"
@ -307,9 +300,11 @@ The default value of `port` is `22`.
echo "sha: $SHA" echo "sha: $SHA"
``` ```
_Inside `env` object, you need to pass every environment variable as a string, passing `Integer` data type or any other may output unexpected results._ > _All environment variables in the `env` object must be strings. Using integers or other types may cause unexpected results._
#### How to connect remote server using `ProxyCommand`? ---
## 🌐 Using ProxyCommand (Jump Host)
```bash ```bash
+--------+ +----------+ +-----------+ +--------+ +----------+ +-----------+
@ -317,7 +312,7 @@ _Inside `env` object, you need to pass every environment variable as a string, p
+--------+ +----------+ +-----------+ +--------+ +----------+ +-----------+
``` ```
in your `~/.ssh/config`, you will see the following. Example `~/.ssh/config`:
```bash ```bash
Host Jumphost Host Jumphost
@ -333,10 +328,10 @@ Host FooServer
ProxyCommand ssh -q -W %h:%p Jumphost ProxyCommand ssh -q -W %h:%p Jumphost
``` ```
#### How to convert to YAML format of GitHubActions **GitHub Actions YAML:**
```diff ```diff
- name: ssh proxy command - name: SSH proxy command
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -352,14 +347,14 @@ Host FooServer
ls -al ls -al
``` ```
#### Protecting a Private Key ---
The purpose of the passphrase is usually to encrypt the private key. ## 🔒 Protecting Your Private Key
This makes the key file by itself useless to an attacker.
It is not uncommon for files to leak from backups or decommissioned hardware, and hackers commonly exfiltrate files from compromised systems. A passphrase encrypts your private key, making it useless to attackers if leaked. Always store your private key securely.
```diff ```diff
- name: ssh key passphrase - name: SSH key passphrase
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -372,20 +367,20 @@ It is not uncommon for files to leak from backups or decommissioned hardware, an
ls -al ls -al
``` ```
#### Using host fingerprint verification ---
Setting up SSH host fingerprint verification can help to prevent Person-in-the-Middle attacks. Before setting this up, run the command below to get your SSH host fingerprint. Remember to replace `ed25519` with your appropriate key type (`rsa`, `dsa`, etc.) that your server is using and `example.com` with your host. ## 🖐️ Host Fingerprint Verification
In modern OpenSSH releases, the _default_ key types to be fetched are `rsa` (since version 5.1), `ecdsa` (since version 6.0), and `ed25519` (since version 6.7). Verifying the SSH host fingerprint helps prevent man-in-the-middle attacks. To get your host's fingerprint (replace `ed25519` with your key type and `example.com` with your host):
```sh ```sh
ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2 ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2
``` ```
Now you can adjust you config: Update your config:
```diff ```diff
- name: ssh key passphrase - name: SSH key passphrase
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -398,33 +393,31 @@ Now you can adjust you config:
ls -al ls -al
``` ```
## Q&A ---
## ❓ Q&A
### Command not found (npm or other command) ### Command not found (npm or other command)
See the [issue comment](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) about interactive vs non interactive shell. Thanks @kocyigityunus for the solution. If you encounter "command not found" errors, see [this issue comment](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) about interactive vs non-interactive shells.
If you are running a command in a non-interactive shell, like ssh-action, on many Linux distros, On many Linux distros, `/etc/bash.bashrc` contains:
`/etc/bash.bashrc` file has a specific command that returns only, so some of the files didn't run and some specific commands doesn't add to path,
```sh ```sh
# /etc/bash.bashrc
# System-wide .bashrc file for interactive bash(1) shells.
# To enable the settings / commands in this file for login shells as well,
# this file has to be sourced in /etc/profile.
# If not running interactively, don't do anything # If not running interactively, don't do anything
[ -z "$PS1" ] && return` [ -z "$PS1" ] && return
``` ```
comment out the line that returns early, and everything should work fine. Alternatively, you can use the real paths of the commands you want to use. Comment out this line or use absolute paths for your commands.
## Contributing ---
We would love for you to contribute to `appleboy/ssh-action`, pull requests are welcome! ## 🤝 Contributing
## License Contributions are welcome! Please submit a pull request to help improve `appleboy/ssh-action`.
The scripts and documentation in this project are released under the [MIT License](LICENSE) ---
## 📝 License
This project is licensed under the [MIT License](LICENSE).

232
README.zh-cn.md
View File

@ -2,71 +2,75 @@
[English](./README.md) | [繁體中文](./README.zh-tw.md) | 简体中文 [English](./README.md) | [繁體中文](./README.zh-tw.md) | 简体中文
一个用于执行远程 SSH 命令的 [GitHub Action](https://github.com/features/actions)。 一个让你轻松安全地执行远程 SSH 命令的 [GitHub Action](https://github.com/features/actions)。
![ssh workflow](./images/ssh-workflow.png) ![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) [![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) 构建。🚀 本项目基于 [Golang](https://go.dev) 和 [drone-ssh](https://github.com/appleboy/drone-ssh) 构建。
## 输入变量 ---
有关更详细的信息，请参阅 [action.yml](./action.yml)。 ## 📥 输入参数
| 输入参数 | 描述 | 默认值 | 详细参数请参阅 [action.yml](./action.yml)。
| 参数 | 描述 | 默认值 |
| ------------------------- | ----------------------------------------------------- | ------ | | ------------------------- | ----------------------------------------------------- | ------ |
| host | SSH 主机地址 | | | host | SSH 主机地址 | |
| port | SSH 端口号 | 22 | | port | SSH 端口号 | 22 |
| passphrase | SSH 密钥密码短语 | | | passphrase | SSH 私钥密码短语 | |
| username | SSH 用户名 | | | username | SSH 用户名 | |
| password | SSH 密码 | | | password | SSH 密码 | |
| protocol | SSH 协议版本（tcp, tcp4, tcp6） | tcp | | protocol | SSH 协议版本（`tcp`、`tcp4`、`tcp6`） | tcp |
| sync | 如果指定了多个主机，则启用同步执行 | false | | sync | 指定多个主机时同步执行 | false |
| use_insecure_cipher | 使用不安全的密码算法 | false | | use_insecure_cipher | 允许额外（不安全）的加密算法 | false |
| cipher | 允许的密码算法。如果未指定，则使用适当的默认值 | | | cipher | 允许的加密算法，未指定时使用默认值 | |
| timeout | SSH 连接到主机的超时时间 | 30s | | timeout | SSH 连接主机的超时时间 | 30s |
| command_timeout | SSH 命令的超时时间 | 10m | | command_timeout | SSH 命令执行超时时间 | 10m |
| key | SSH 私钥的内容，例如 ~/.ssh/id_rsa 的原始内容 | | | key | SSH 私钥内容（如 `~/.ssh/id_rsa` 的原始内容） | |
| key_path | SSH 私钥的路径 | | | key_path | SSH 私钥路径 | |
| fingerprint | 主机公钥的 SHA256 指纹 | | | fingerprint | 主机公钥的 SHA256 指纹 | |
| proxy_host | SSH 代理主机 | | | proxy_host | SSH 代理主机 | |
| proxy_port | SSH 代理端口 | 22 | | proxy_port | SSH 代理端口 | 22 |
| proxy_protocol | SSH 代理协议版本（tcp, tcp4, tcp6） | tcp | | proxy_protocol | SSH 代理协议版本（`tcp`、`tcp4`、`tcp6`） | tcp |
| proxy_username | SSH 代理用户名 | | | proxy_username | SSH 代理用户名 | |
| proxy_password | SSH 代理密码 | | | proxy_password | SSH 代理密码 | |
| proxy_passphrase | SSH 代理密钥密码短语 | | | proxy_passphrase | SSH 代理私钥密码短语 | |
| proxy_timeout | SSH 连接到代理主机的超时时间 | 30s | | proxy_timeout | SSH 连接代理主机的超时时间 | 30s |
| proxy_key | SSH 代理私钥的内容 | | | proxy_key | SSH 代理私钥内容 | |
| proxy_key_path | SSH 代理私钥的路径 | | | proxy_key_path | SSH 代理私钥路径 | |
| proxy_fingerprint | 代理主机公钥的 SHA256 指纹 | | | proxy_fingerprint | 代理主机公钥的 SHA256 指纹 | |
| proxy_cipher | 代理允许的密码算法 | | | proxy_cipher | 代理允许的加密算法 | |
| proxy_use_insecure_cipher | 使用不安全的密码算法 | false | | proxy_use_insecure_cipher | 代理允许额外（不安全）的加密算法 | false |
| script | 执行命令 | | | script | 远程执行的命令 | |
| script_path | 从文件执行命令 | | | script_path | 包含要执行命令的文件路径 | |
| envs | 传递环境变量到 shell 脚本 | | | envs | 传递给 shell 脚本的环境变量 | |
| envs_format | 环境变量传递的灵活配置 | | | envs_format | 环境变量传递的灵活配置 | |
| debug | 启用调试模式 | false | | debug | 启用调试模式 | false |
| allenvs | 将带有 `GITHUB_` 和 `INPUT_` 前缀的环境变量传递给脚本 | false | | allenvs | 传递所有带 `GITHUB_` 和 `INPUT_` 前缀的环境变量到脚本 | false |
| request_pty | 请求伪终端 | false | | request_pty | 向服务器请求伪终端 | false |
| curl_insecure | 在 curl 中使用不安全的证书验证 | false | | curl_insecure | 允许 curl 连接无证书的 SSL 站点 | false |
| version | drone-ssh 版本号。若未指定，将使用最新版本。 | | | version | drone-ssh 二进制版本，未指定时使用最新版本 | |
**注意：** 用户可以在他们的 shell 脚本中添加 `set -e` 以实现类似于已删除的 `script_stop` 选项的功能。 > **注意：** 如需实现已移除的 `script_stop` 功能，请在 shell 脚本顶部添加 `set -e`。
## 使用方法 ---
执行远程 SSH 命令。 ## 🚦 使用示例
在工作流中执行远程 SSH 命令：
```yaml ```yaml
name: remote ssh command name: Remote SSH Command
on: [push] on: [push]
jobs: jobs:
build: build:
name: Build name: Build
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- name: executing remote ssh commands using password - name: 执行远程 SSH 命令（密码认证）
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -76,7 +80,7 @@ jobs:
script: whoami script: whoami
``` ```
输出： **输出：**
```sh ```sh
======CMD====== ======CMD======
@ -88,11 +92,11 @@ linuxserver.io
=============================================== ===============================================
``` ```
### 设置 SSH 密钥 ---
请按照以下步骤创建和使用 SSH 密钥。 ## 🔑 配置 SSH 密钥
最佳做法是在本地机器上创建 SSH 密钥，而不是在远程机器上。
使用 GitHub Secrets 中指定的用户名登录并生成 RSA 密钥对： 建议在本地机器（而非远程服务器）上创建 SSH 密钥。请使用 GitHub Secrets 中指定的用户名登录并生成密钥对：
### 生成 RSA 密钥 ### 生成 RSA 密钥
@ -100,38 +104,23 @@ linuxserver.io
ssh-keygen -t rsa -b 4096 -C "your_email@example.com" ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
``` ```
### 生成 ed25519 密钥 ### 生成 ED25519 密钥
```bash ```bash
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
``` ```
将新生成的密钥添加到已授权的密钥中。详细了解已授权的密钥请点[此处](https://www.ssh.com/ssh/authorized_keys/)。 将新生成的公钥添加到服务器的 authorized_keys。 [了解更多 authorized_keys](https://www.ssh.com/ssh/authorized_keys/)
### 将 RSA 密钥添加到已授权密钥中
```bash ```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 密钥添加到已授权密钥中 复制私钥内容并粘贴到 GitHub Secrets。
```bash
cat .ssh/id_ed25519.pub | ssh b@B 'cat >> .ssh/authorized_keys'
```
复制私钥内容，然后将其粘贴到 GitHub Secrets 中。
### 复制 RSA 私钥内容
在复制私钥之前，按照以下步骤安装 `clip` 命令：
```bash
# Ubuntu
sudo apt-get install xclip
```
复制私钥：
```bash ```bash
# macOS # macOS
@ -140,9 +129,9 @@ pbcopy < ~/.ssh/id_rsa
xclip < ~/.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 ```bash
# macOS # macOS
@ -151,40 +140,44 @@ pbcopy < ~/.ssh/id_ed25519
xclip < ~/.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 ```bash
ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey] 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 ```bash
CASignatureAlgorithms +ssh-rsa CASignatureAlgorithms +ssh-rsa
``` ```
或者，`ed25519` 密钥在 OpenSSH 中默认被接受。如果需要，您可以使用它来替代 RSA： 或者，直接使用默认支持的 ED25519 密钥：
```bash ```bash
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
``` ```
### 示例 ---
#### 使用密码执行远程 SSH 命令 ## 🧑‍💻 更多用法示例
### 使用密码认证
```yaml ```yaml
- name: executing remote ssh commands using password - name: 执行远程 SSH 命令（密码认证）
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -194,10 +187,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script: whoami script: whoami
``` ```
#### 使用私钥 ### 使用私钥认证
```yaml ```yaml
- name: executing remote ssh commands using ssh key - name: 执行远程 SSH 命令（密钥认证）
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -207,10 +200,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script: whoami script: whoami
``` ```
#### 多个命令 ### 多条命令
```yaml ```yaml
- name: multiple command - name: 多条命令
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -224,10 +217,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
![result](./images/output-result.png) ![result](./images/output-result.png)
#### 从文件执行命令 ### 从文件执行命令
```yaml ```yaml
- name: file commands - name: 文件命令
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -237,10 +230,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script_path: scripts/script.sh script_path: scripts/script.sh
``` ```
#### 多台主机 ### 多主机
```diff ```diff
- name: multiple host - name: 多主机
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
- host: "foo.com" - host: "foo.com"
@ -253,12 +246,12 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
ls -al ls -al
``` ```
默认的 `port` 值是 `22`。 默认 `port` 为 `22`。
#### 多个不同端口的主机 ### 多主机不同端口
```diff ```diff
- name: multiple host - name: 多主机
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
- host: "foo.com" - host: "foo.com"
@ -270,10 +263,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
ls -al ls -al
``` ```
#### 在多台主机上同步执行 ### 多主机同步执行
```diff ```diff
- name: multiple host - name: 多主机
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: "foo.com,bar.com" host: "foo.com,bar.com"
@ -286,10 +279,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
ls -al ls -al
``` ```
#### 将环境变量传递到 shell 脚本 ### 传递环境变量到 shell 脚本
```diff ```diff
- name: pass environment - name: 传递环境变量
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
+ env: + env:
+ FOO: "BAR" + FOO: "BAR"
@ -307,9 +300,11 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
echo "sha: $SHA" echo "sha: $SHA"
``` ```
_在 `env` 对象中，您需要将每个环境变量作为字符串传递，传递 `Integer` 数据类型或任何其他类型可能会产生意外结果。_ > _`env` 对象中的所有环境变量必须为字符串。传递整数或其他类型可能导致意外结果。_
#### 如何使用 `ProxyCommand` 连接远程服务器？ ---
## 🌐 使用 ProxyCommand（跳板机）
```bash ```bash
+--------+ +----------+ +-----------+ +--------+ +----------+ +-----------+
@ -317,7 +312,7 @@ _在 `env` 对象中，您需要将每个环境变量作为字符串传递，传
+--------+ +----------+ +-----------+ +--------+ +----------+ +-----------+
``` ```
在您的 `~/.ssh/config` 文件中，您会看到以下内容。 示例 `~/.ssh/config`：
```bash ```bash
Host Jumphost Host Jumphost
@ -333,10 +328,10 @@ Host FooServer
ProxyCommand ssh -q -W %h:%p Jumphost ProxyCommand ssh -q -W %h:%p Jumphost
``` ```
#### 如何将其转换为 GitHubActions 的 YAML 格式？ **GitHub Actions YAML:**
```diff ```diff
- name: ssh proxy command - name: SSH 代理命令
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -352,12 +347,14 @@ Host FooServer
ls -al ls -al
``` ```
#### 保护私钥 ---
密码短语通常用于加密私钥。这使得密钥文件本身对攻击者无用。文件泄露可能来自备份或停用的硬件，黑客通常可以从受攻击系统中泄露文件。 ## 🔒 保护你的私钥
密码短语会加密你的私钥，即使泄露也无法被攻击者直接利用。请务必妥善保管私钥。
```diff ```diff
- name: ssh key passphrase - name: SSH 密钥密码短语
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -370,20 +367,20 @@ Host FooServer
ls -al ls -al
``` ```
#### 使用主机指纹验证 ---
设置 SSH 主机指纹验证可以帮助防止中间人攻击。在设置之前，运行以下命令以获取 SSH 主机指纹。请记得将 `ed25519` 替换为您适当的密钥类型（`rsa`、 `dsa`等），而 `example.com` 则替换为您的主机。 ## 🖐️ 主机指纹验证
在现代 OpenSSH 版本中，默认提取的密钥类型是 `rsa`（从版本 5.1 开始）、`ecdsa`（从版本 6.0 开始）和 `ed25519`（从版本 6.7 开始）。 验证 SSH 主机指纹有助于防止中间人攻击。获取主机指纹（将 `ed25519` 替换为你的密钥类型，`example.com` 替换为你的主机）：
```sh ```sh
ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2 ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2
``` ```
现在您可以调整您的配置： 更新配置：
```diff ```diff
- name: ssh key passphrase - name: SSH 密钥密码短语
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} 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 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) 授权。

238
README.zh-tw.md
View File

@ -2,71 +2,75 @@
[English](./README.md) | 繁體中文 | [简体中文](./README.zh-cn.md) [English](./README.md) | 繁體中文 | [简体中文](./README.zh-cn.md)
[GitHub Action](https://github.com/features/actions) 用於執行遠端 SSH 命令。 一個讓你輕鬆安全執行遠端 SSH 指令的 [GitHub Action](https://github.com/features/actions)。
![ssh workflow](./images/ssh-workflow.png) ![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) [![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) 建立。🚀 本專案以 [Golang](https://go.dev) 和 [drone-ssh](https://github.com/appleboy/drone-ssh) 建立。
## 輸入變數 ---
請參閱 [action.yml](./action.yml) 以獲取更詳細的信息。 ## 📥 輸入參數
| 輸入參數 | 描述 | 預設值 | 完整參數請參閱 [action.yml](./action.yml)。
| 參數 | 說明 | 預設值 |
| ------------------------- | ----------------------------------------------------- | ------ | | ------------------------- | ----------------------------------------------------- | ------ |
| host | SSH 主機地址 | | | host | SSH 主機位址 | |
| port | SSH 埠號 | 22 | | port | SSH 埠號 | 22 |
| passphrase | SSH 金鑰密碼 | | | passphrase | SSH 私鑰密碼 | |
| username | SSH 使用者名稱 | | | username | SSH 使用者名稱 | |
| password | SSH 密碼 | | | password | SSH 密碼 | |
| protocol | SSH 協議版本 (tcp, tcp4, tcp6) | tcp | | protocol | SSH 協議版本（`tcp`、`tcp4`、`tcp6`） | tcp |
| sync | 如果有多個主機，啟用同步執行 | false | | sync | 指定多個主機時同步執行 | false |
| use_insecure_cipher | 包含更多不安全的加密算法 | false | | use_insecure_cipher | 允許額外（不安全）的加密演算法 | false |
| cipher | 允許的加密算法。如果未指定，則使用合理的預設值 | | | cipher | 允許的加密演算法，未指定時使用預設值 | |
| timeout | SSH 連接主機的超時時間 | 30s | | timeout | SSH 連線主機的逾時時間 | 30s |
| command_timeout | SSH 命令的超時時間 | 10m | | command_timeout | SSH 指令執行逾時時間 | 10m |
| key | SSH 私鑰的內容。例如，~/.ssh/id_rsa 的原始內容 | | | key | SSH 私鑰內容（如 `~/.ssh/id_rsa` 的原始內容） | |
| key_path | SSH 私鑰的路徑 | | | key_path | SSH 私鑰路徑 | |
| fingerprint | 主機公鑰的 SHA256 指紋 | | | fingerprint | 主機公鑰的 SHA256 指紋 | |
| proxy_host | SSH 代理主機 | | | proxy_host | SSH 代理主機 | |
| proxy_port | SSH 代理埠號 | 22 | | proxy_port | SSH 代理埠號 | 22 |
| proxy_protocol | SSH 代理協議版本 (tcp, tcp4, tcp6) | tcp | | proxy_protocol | SSH 代理協議版本（`tcp`、`tcp4`、`tcp6`） | tcp |
| proxy_username | SSH 代理使用者名稱 | | | proxy_username | SSH 代理使用者名稱 | |
| proxy_password | SSH 代理密碼 | | | proxy_password | SSH 代理密碼 | |
| proxy_passphrase | SSH 代理金鑰密碼 | | | proxy_passphrase | SSH 代理私鑰密碼 | |
| proxy_timeout | SSH 連接代理主機的超時時間 | 30s | | proxy_timeout | SSH 連線代理主機的逾時時間 | 30s |
| proxy_key | SSH 代理私鑰的內容 | | | proxy_key | SSH 代理私鑰內容 | |
| proxy_key_path | SSH 代理私鑰的路徑 | | | proxy_key_path | SSH 代理私鑰路徑 | |
| proxy_fingerprint | 代理主機公鑰的 SHA256 指紋 | | | proxy_fingerprint | 代理主機公鑰的 SHA256 指紋 | |
| proxy_cipher | 代理允許的加密算法 | | | proxy_cipher | 代理允許的加密演算法 | |
| proxy_use_insecure_cipher | 包含更多不安全的加密算法 | false | | proxy_use_insecure_cipher | 代理允許額外（不安全）的加密演算法 | false |
| script | 執行命令 | | | script | 遠端執行的指令 | |
| script_path | 從文件中執行命令 | | | script_path | 包含要執行指令的檔案路徑 | |
| envs | 將環境變數傳遞給 shell 腳本 | | | envs | 傳遞給 shell 腳本的環境變數 | |
| envs_format | 環境值傳遞的靈活配置 | | | envs_format | 環境變數傳遞的彈性設定 | |
| debug | 啟用調試模式 | false | | debug | 啟用除錯模式 | false |
| allenvs | 將帶有 `GITHUB_` 和 `INPUT_` 前綴的環境變數傳遞給腳本 | false | | allenvs | 傳遞所有帶 `GITHUB_` 和 `INPUT_` 前綴的環境變數到腳本 | false |
| request_pty | 從伺服器請求偽終端 | false | | request_pty | 向伺服器請求偽終端 | false |
| curl_insecure | 在 curl 命令中使用不安全的 SSL 證書驗證 | false | | curl_insecure | 允許 curl 連線無憑證的 SSL 網站 | false |
| version | drone-ssh 版本號。若未指定，將使用最新版本。 | | | version | drone-ssh 執行檔版本，未指定時使用最新版本 | |
**注意：** 用戶可以在他們的 shell 腳本中添加 `set -e` 以實現類似於已刪除的 `script_stop` 選項的功能。 > **注意：** 如需實現已移除的 `script_stop` 功能，請在 shell 腳本最上方加上 `set -e`。
## 用法 ---
執行遠端 SSH 命令 ## 🚦 使用範例
在工作流程中執行遠端 SSH 指令：
```yaml ```yaml
name: remote ssh command name: Remote SSH Command
on: [push] on: [push]
jobs: jobs:
build: build:
name: Build name: Build
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- name: executing remote ssh commands using password - name: 執行遠端 SSH 指令（密碼認證）
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -76,7 +80,7 @@ jobs:
script: whoami script: whoami
``` ```
畫面輸出 **輸出：**
```sh ```sh
======CMD====== ======CMD======
@ -88,48 +92,35 @@ linuxserver.io
=============================================== ===============================================
``` ```
### 設置 SSH 金鑰 ---
請在創建 SSH 金鑰並使用 SSH 金鑰時遵循以下步驟。最佳做法是在本地機器上創建 SSH 金鑰而不是遠端機器上。請使用 Github Secrets 中指定的用戶名登錄。生成 RSA 金鑰： ## 🔑 設定 SSH 金鑰
### 生成 RSA 金鑰 建議於本地端（非遠端伺服器）產生 SSH 金鑰。請以 GitHub Secrets 指定的使用者名稱登入並產生金鑰對：
### 產生 RSA 金鑰
```bash ```bash
ssh-keygen -t rsa -b 4096 -C "your_email@example.com" ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
``` ```
### 生成 ed25519 金鑰 ### 產生 ED25519 金鑰
```bash ```bash
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
``` ```
將新生成的金鑰添加到已授權的金鑰中。詳細了解已授權的金鑰請點擊[此處](https://www.ssh.com/ssh/authorized_keys/). 將新產生的公鑰加入伺服器的 authorized_keys。 [了解更多 authorized_keys](https://www.ssh.com/ssh/authorized_keys/)
### 將 RSA 金鑰添加到已授權金鑰中
```bash ```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 金鑰添加到已授權金鑰中 複製私鑰內容並貼到 GitHub Secrets。
```bash
cat .ssh/id_ed25519.pub | ssh b@B 'cat >> .ssh/authorized_keys'
```
複製私鑰內容，然後將其粘貼到 Github Secrets 中。
### 複製 rsa 私鑰內容
在複製私鑰之前，請按照以下說明安裝 `clip` 命令：
```bash
# Ubuntu
sudo apt-get install xclip
```
複製私鑰：
```bash ```bash
# macOS # macOS
@ -138,9 +129,9 @@ pbcopy < ~/.ssh/id_rsa
xclip < ~/.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 ```bash
# macOS # macOS
@ -149,40 +140,44 @@ pbcopy < ~/.ssh/id_ed25519
xclip < ~/.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 ```bash
ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey] 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 ```bash
CASignatureAlgorithms +ssh-rsa CASignatureAlgorithms +ssh-rsa
``` ```
或者，`Ed25519` 密鑰在 OpenSSH 中默認被接受。如果需要，您可以使用它來替代 RSA。 或直接使用預設支援的 ED25519 金鑰：
```bash ```bash
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
``` ```
### Example ---
#### 使用密碼執行遠端 SSH 命令 ## 🧑‍💻 更多用法範例
### 使用密碼認證
```yaml ```yaml
- name: executing remote ssh commands using password - name: 執行遠端 SSH 指令（密碼認證）
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -192,10 +187,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script: whoami script: whoami
``` ```
#### 使用私鑰 ### 使用私鑰認證
```yaml ```yaml
- name: executing remote ssh commands using ssh key - name: 執行遠端 SSH 指令（私鑰認證）
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -205,10 +200,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script: whoami script: whoami
``` ```
#### 多個命令 ### 多條指令
```yaml ```yaml
- name: multiple command - name: 多條指令
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -222,10 +217,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
![result](./images/output-result.png) ![result](./images/output-result.png)
#### 從文件中執行命令 ### 從檔案執行指令
```yaml ```yaml
- name: file commands - name: 檔案指令
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -235,10 +230,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
script_path: scripts/script.sh script_path: scripts/script.sh
``` ```
#### 多台主機 ### 多主機
```diff ```diff
- name: multiple host - name: 多主機
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
- host: "foo.com" - host: "foo.com"
@ -251,10 +246,12 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
ls -al ls -al
``` ```
#### 多個不同端口的主機 預設 `port` 為 `22`。
### 多主機不同埠號
```diff ```diff
- name: multiple host - name: 多主機
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
- host: "foo.com" - host: "foo.com"
@ -266,10 +263,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
ls -al ls -al
``` ```
#### 在多個主機上同步執行 ### 多主機同步執行
```diff ```diff
- name: multiple host - name: 多主機
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: "foo.com,bar.com" host: "foo.com,bar.com"
@ -282,10 +279,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
ls -al ls -al
``` ```
#### 將環境變量傳遞到 Shell 腳本 ### 傳遞環境變數到 shell 腳本
```diff ```diff
- name: pass environment - name: 傳遞環境變數
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
+ env: + env:
+ FOO: "BAR" + FOO: "BAR"
@ -303,9 +300,11 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
echo "sha: $SHA" echo "sha: $SHA"
``` ```
_在 `env` 對象中，您需要將每個環境變量作為字符串傳遞，傳遞 `Integer` 數據類型或任何其他類型可能會產生意外結果。_ > _`env` 物件中的所有環境變數必須為字串。傳遞整數或其他型別可能導致非預期結果。_
#### 如何使用 `ProxyCommand` 連接遠程服務器？ ---
## 🌐 使用 ProxyCommand（跳板機）
```bash ```bash
+--------+ +----------+ +-----------+ +--------+ +----------+ +-----------+
@ -313,7 +312,7 @@ _在 `env` 對象中，您需要將每個環境變量作為字符串傳遞，傳
+--------+ +----------+ +-----------+ +--------+ +----------+ +-----------+
``` ```
在您的 `~/.ssh/config` 文件中，您會看到以下內容。 範例 `~/.ssh/config`：
```bash ```bash
Host Jumphost Host Jumphost
@ -329,10 +328,10 @@ Host FooServer
ProxyCommand ssh -q -W %h:%p Jumphost ProxyCommand ssh -q -W %h:%p Jumphost
``` ```
#### 如何將其轉換為 GitHubActions 的 YAML 格式？ **GitHub Actions YAML:**
```diff ```diff
- name: ssh proxy command - name: SSH 代理指令
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -348,12 +347,14 @@ Host FooServer
ls -al ls -al
``` ```
#### 如何保護私鑰？ ---
密碼短語通常用於加密私鑰。這使得攻擊者無法單獨使用密鑰文件。文件泄露可能來自備份或停用的硬件，黑客通常可以從受攻擊系統中洩露文件。因此，保護私鑰非常重要。 ## 🔒 保護你的私鑰
密碼短語會加密你的私鑰，即使外洩也無法被攻擊者直接利用。請務必妥善保管私鑰。
```diff ```diff
- name: ssh key passphrase - name: SSH 私鑰密碼
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -366,20 +367,20 @@ Host FooServer
ls -al ls -al
``` ```
#### 使用主機指紋驗證 ---
設置 SSH 主機指紋驗證可以幫助防止中間人攻擊。在設置之前，運行以下命令以獲取 SSH 主機指紋。請記得將 `ed25519` 替換為您的適當金鑰類型（`rsa`、 `dsa`等），而 `example.com` 則替換為您的主機。 ## 🖐️ 主機指紋驗證
現代 OpenSSH 版本中，需要提取的**默認金鑰**類型是 `rsa`（從版本 5.1 開始）、`ecdsa`（從版本 6.0 開始）和 `ed25519`（從版本 6.7 開始）。 驗證 SSH 主機指紋有助於防止中間人攻擊。取得主機指紋（將 `ed25519` 換成你的金鑰型別，`example.com` 換成你的主機）：
```sh ```sh
ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2 ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2
``` ```
現在您可以調整您的配置： 更新設定：
```diff ```diff
- name: ssh key passphrase - name: SSH 私鑰密碼
uses: appleboy/ssh-action@v1 uses: appleboy/ssh-action@v1
with: with:
host: ${{ secrets.HOST }} host: ${{ secrets.HOST }}
@ -392,10 +393,31 @@ ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' '
ls -al 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) 授權。