mirror of
https://github.com/appleboy/ssh-action.git
synced 2025-10-31 16:23:52 +00: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
265
README.md
265
README.md
@ -2,71 +2,75 @@
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
[](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 |
|
||||
| ------------------------- | ---------------------------------------------------------------------------------------- | ------------- |
|
||||
| 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. | |
|
||||
For full details, see [action.yml](./action.yml).
|
||||
|
||||
**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
|
||||
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: Execute remote SSH commands using password
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
@ -76,7 +80,7 @@ jobs:
|
||||
script: whoami
|
||||
```
|
||||
|
||||
output:
|
||||
**Output:**
|
||||
|
||||
```sh
|
||||
======CMD======
|
||||
@ -88,50 +92,35 @@ linuxserver.io
|
||||
===============================================
|
||||
```
|
||||
|
||||
### Setting up a SSH Key
|
||||
---
|
||||
|
||||
Follow the steps below to create and use 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:
|
||||
## 🔑 Setting Up SSH Keys
|
||||
|
||||
### 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
|
||||
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
|
||||
```
|
||||
|
||||
### Generate ed25519 key
|
||||
### Generate ED25519 key
|
||||
|
||||
```bash
|
||||
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 rsa key into 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/)
|
||||
|
||||
```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
|
||||
|
||||
```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:
|
||||
Copy the private key content and paste it into GitHub Secrets.
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
@ -140,9 +129,9 @@ pbcopy < ~/.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
|
||||
# macOS
|
||||
@ -151,40 +140,44 @@ pbcopy < ~/.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
|
||||
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
|
||||
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
|
||||
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
|
||||
- name: executing remote ssh commands using password
|
||||
- name: Execute remote SSH commands using password
|
||||
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
|
||||
```
|
||||
|
||||
#### Using private key
|
||||
### Using private key authentication
|
||||
|
||||
```yaml
|
||||
- name: executing remote ssh commands using ssh key
|
||||
- name: Execute remote SSH commands using SSH key
|
||||
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
|
||||
```
|
||||
|
||||
#### Multiple Commands
|
||||
### Multiple commands
|
||||
|
||||
```yaml
|
||||
- name: multiple command
|
||||
- name: Multiple commands
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
@ -224,10 +217,10 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
||||
|
||||
|
||||
|
||||
#### Commands from a file
|
||||
### Run commands from a file
|
||||
|
||||
```yaml
|
||||
- name: file commands
|
||||
- name: File commands
|
||||
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
|
||||
```
|
||||
|
||||
#### Multiple Hosts
|
||||
### Multiple hosts
|
||||
|
||||
```diff
|
||||
- name: multiple host
|
||||
- name: Multiple hosts
|
||||
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
|
||||
```
|
||||
|
||||
The default value of `port` is `22`.
|
||||
Default `port` is `22`.
|
||||
|
||||
#### Multiple hosts with different port
|
||||
### Multiple hosts with different ports
|
||||
|
||||
```diff
|
||||
- name: multiple host
|
||||
- name: Multiple hosts
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
- host: "foo.com"
|
||||
@ -270,10 +263,10 @@ The default value of `port` is `22`.
|
||||
ls -al
|
||||
```
|
||||
|
||||
#### Synchronous execution on multiple hosts
|
||||
### Synchronous execution on multiple hosts
|
||||
|
||||
```diff
|
||||
- name: multiple host
|
||||
- name: Multiple hosts
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: "foo.com,bar.com"
|
||||
@ -286,10 +279,10 @@ The default value of `port` is `22`.
|
||||
ls -al
|
||||
```
|
||||
|
||||
#### Pass environment variable to shell script
|
||||
### Pass environment variables to shell script
|
||||
|
||||
```diff
|
||||
- name: pass environment
|
||||
- name: Pass environment
|
||||
uses: appleboy/ssh-action@v1
|
||||
+ env:
|
||||
+ FOO: "BAR"
|
||||
@ -307,9 +300,11 @@ The default value of `port` is `22`.
|
||||
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
|
||||
+--------+ +----------+ +-----------+
|
||||
@ -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
|
||||
Host Jumphost
|
||||
@ -333,10 +328,10 @@ Host FooServer
|
||||
ProxyCommand ssh -q -W %h:%p Jumphost
|
||||
```
|
||||
|
||||
#### How to convert to YAML format of GitHubActions
|
||||
**GitHub Actions YAML:**
|
||||
|
||||
```diff
|
||||
- name: ssh proxy command
|
||||
- name: SSH proxy command
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
@ -352,14 +347,14 @@ Host FooServer
|
||||
ls -al
|
||||
```
|
||||
|
||||
#### Protecting a Private Key
|
||||
---
|
||||
|
||||
The purpose of the passphrase is usually to encrypt the 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.
|
||||
## 🔒 Protecting Your Private Key
|
||||
|
||||
A passphrase encrypts your private key, making it useless to attackers if leaked. Always store your private key securely.
|
||||
|
||||
```diff
|
||||
- name: ssh key passphrase
|
||||
- name: SSH key passphrase
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
@ -372,20 +367,20 @@ It is not uncommon for files to leak from backups or decommissioned hardware, an
|
||||
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
|
||||
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
|
||||
- name: ssh key passphrase
|
||||
- name: SSH key passphrase
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
@ -398,33 +393,31 @@ Now you can adjust you config:
|
||||
ls -al
|
||||
```
|
||||
|
||||
## Q&A
|
||||
---
|
||||
|
||||
## ❓ Q&A
|
||||
|
||||
### 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,
|
||||
|
||||
`/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,
|
||||
On many Linux distros, `/etc/bash.bashrc` contains:
|
||||
|
||||
```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
|
||||
[ -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
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) 授权。
|
||||
|
||||
238
README.zh-tw.md
238
README.zh-tw.md
@ -2,71 +2,75 @@
|
||||
|
||||
[English](./README.md) | 繁體中文 | [简体中文](./README.zh-cn.md)
|
||||
|
||||
[GitHub Action](https://github.com/features/actions) 用於執行遠端 SSH 命令。
|
||||
一個讓你輕鬆安全執行遠端 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 主機地址 | |
|
||||
| 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 腳本 | |
|
||||
| envs_format | 環境值傳遞的靈活配置 | |
|
||||
| debug | 啟用調試模式 | false |
|
||||
| allenvs | 將帶有 `GITHUB_` 和 `INPUT_` 前綴的環境變數傳遞給腳本 | false |
|
||||
| request_pty | 從伺服器請求偽終端 | false |
|
||||
| curl_insecure | 在 curl 命令中使用不安全的 SSL 證書驗證 | false |
|
||||
| version | drone-ssh 版本號。若未指定，將使用最新版本。 | |
|
||||
| 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 連線無憑證的 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,48 +92,35 @@ linuxserver.io
|
||||
===============================================
|
||||
```
|
||||
|
||||
### 設置 SSH 金鑰
|
||||
---
|
||||
|
||||
請在創建 SSH 金鑰並使用 SSH 金鑰時遵循以下步驟。最佳做法是在本地機器上創建 SSH 金鑰而不是遠端機器上。請使用 Github Secrets 中指定的用戶名登錄。生成 RSA 金鑰：
|
||||
## 🔑 設定 SSH 金鑰
|
||||
|
||||
### 生成 RSA 金鑰
|
||||
建議於本地端（非遠端伺服器）產生 SSH 金鑰。請以 GitHub Secrets 指定的使用者名稱登入並產生金鑰對：
|
||||
|
||||
### 產生 RSA 金鑰
|
||||
|
||||
```bash
|
||||
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
|
||||
@ -138,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
|
||||
@ -149,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"
|
||||
```
|
||||
|
||||
### Example
|
||||
---
|
||||
|
||||
#### 使用密碼執行遠端 SSH 命令
|
||||
## 🧑💻 更多用法範例
|
||||
|
||||
### 使用密碼認證
|
||||
|
||||
```yaml
|
||||
- name: executing remote ssh commands using password
|
||||
- name: 執行遠端 SSH 指令（密碼認證）
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
@ -192,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 }}
|
||||
@ -205,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 }}
|
||||
@ -222,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 }}
|
||||
@ -235,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"
|
||||
@ -251,10 +246,12 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
||||
ls -al
|
||||
```
|
||||
|
||||
#### 多個不同端口的主機
|
||||
預設 `port` 為 `22`。
|
||||
|
||||
### 多主機不同埠號
|
||||
|
||||
```diff
|
||||
- name: multiple host
|
||||
- name: 多主機
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
- host: "foo.com"
|
||||
@ -266,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"
|
||||
@ -282,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"
|
||||
@ -303,9 +300,11 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
|
||||
echo "sha: $SHA"
|
||||
```
|
||||
|
||||
_在 `env` 對象中，您需要將每個環境變量作為字符串傳遞，傳遞 `Integer` 數據類型或任何其他類型可能會產生意外結果。_
|
||||
> _`env` 物件中的所有環境變數必須為字串。傳遞整數或其他型別可能導致非預期結果。_
|
||||
|
||||
#### 如何使用 `ProxyCommand` 連接遠程服務器？
|
||||
---
|
||||
|
||||
## 🌐 使用 ProxyCommand（跳板機）
|
||||
|
||||
```bash
|
||||
+--------+ +----------+ +-----------+
|
||||
@ -313,7 +312,7 @@ _在 `env` 對象中，您需要將每個環境變量作為字符串傳遞，傳
|
||||
+--------+ +----------+ +-----------+
|
||||
```
|
||||
|
||||
在您的 `~/.ssh/config` 文件中，您會看到以下內容。
|
||||
範例 `~/.ssh/config`：
|
||||
|
||||
```bash
|
||||
Host Jumphost
|
||||
@ -329,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 }}
|
||||
@ -348,12 +347,14 @@ Host FooServer
|
||||
ls -al
|
||||
```
|
||||
|
||||
#### 如何保護私鑰？
|
||||
---
|
||||
|
||||
密碼短語通常用於加密私鑰。這使得攻擊者無法單獨使用密鑰文件。文件泄露可能來自備份或停用的硬件，黑客通常可以從受攻擊系統中洩露文件。因此，保護私鑰非常重要。
|
||||
## 🔒 保護你的私鑰
|
||||
|
||||
密碼短語會加密你的私鑰，即使外洩也無法被攻擊者直接利用。請務必妥善保管私鑰。
|
||||
|
||||
```diff
|
||||
- name: ssh key passphrase
|
||||
- name: SSH 私鑰密碼
|
||||
uses: appleboy/ssh-action@v1
|
||||
with:
|
||||
host: ${{ secrets.HOST }}
|
||||
@ -366,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 }}
|
||||
@ -392,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…
x
Reference in New Issue
Block a user