Actions/ssh-action
1
Fork 0
mirror of https://github.com/appleboy/ssh-action.git synced 2025-10-31 16:23:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: revamp and unify multi-language readme documentation

Browse Source 
- Remove the Table of Contents section to simplify documentation.
- Add and reorganize introduction sections for a clearer project overview.
- Rename and clarify section titles for improved structure and navigation.
- Consolidate and expand explanatory text around SSH key setup, OpenSSH compatibility, security, and troubleshooting.
- Provide richer descriptions for core concepts and advanced SSH usage scenarios.
- Apply the same documentation improvements and structural changes across English, Simplified Chinese, and Traditional Chinese readme files for consistency.

Signed-off-by: appleboy <appleboy.tw@gmail.com>
This commit is contained in:
appleboy 2025-04-27 11:52:09 +08:00
parent c7fbbc9208
commit 4d84f0522a
No known key found for this signature in database
3 changed files with 87 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
README.md
View File

@ -2,44 +2,22 @@
English | [繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md) English | [繁體中文](./README.zh-tw.md) | [简体中文](./README.zh-cn.md)
## Table of Contents ---
- [🚀 SSH for GitHub Actions](#-ssh-for-github-actions) ## 📖 Introduction
- [Table of Contents](#table-of-contents)
- [📥 Input Parameters](#-input-parameters)
- [🚦 Usage Example](#-usage-example)
- [🔑 Setting Up SSH Keys](#-setting-up-ssh-keys)
- [Generate RSA key](#generate-rsa-key)
- [Generate ED25519 key](#generate-ed25519-key)
- [🛡️ OpenSSH Compatibility](#️-openssh-compatibility)
- [🧑‍💻 More Usage Examples](#-more-usage-examples)
- [Using password authentication](#using-password-authentication)
- [Using private key authentication](#using-private-key-authentication)
- [Multiple commands](#multiple-commands)
- [Run commands from a file](#run-commands-from-a-file)
- [Multiple hosts](#multiple-hosts)
- [Multiple hosts with different ports](#multiple-hosts-with-different-ports)
- [Synchronous execution on multiple hosts](#synchronous-execution-on-multiple-hosts)
- [Pass environment variables to shell script](#pass-environment-variables-to-shell-script)
- [🌐 Using ProxyCommand (Jump Host)](#-using-proxycommand-jump-host)
- [🔒 Protecting Your Private Key](#-protecting-your-private-key)
- [🖐️ Host Fingerprint Verification](#️-host-fingerprint-verification)
- [❓ Q\&A](#-qa)
- [Command not found (npm or other command)](#command-not-found-npm-or-other-command)
- [🤝 Contributing](#-contributing)
- [📝 License](#-license)
A [GitHub Action](https://github.com/features/actions) for executing remote SSH commands easily and securely. **SSH for GitHub Actions** is a powerful [GitHub Action](https://github.com/features/actions) for executing remote SSH commands easily and securely in your CI/CD workflows.
Built with [Golang](https://go.dev) and [drone-ssh](https://github.com/appleboy/drone-ssh), it supports a wide range of SSH scenarios, including multi-host, proxy, and advanced authentication.
![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).
--- ---
## 📥 Input Parameters ## 🧩 Core Concepts & Input Parameters
This action provides flexible SSH command execution with a rich set of configuration options.
For full details, see [action.yml](./action.yml). For full details, see [action.yml](./action.yml).
@ -85,9 +63,9 @@ For full details, see [action.yml](./action.yml).
--- ---
## 🚦 Usage Example ## ⚡ Quick Start
Run remote SSH commands in your workflow: Run remote SSH commands in your workflow with minimal configuration:
```yaml ```yaml
name: Remote SSH Command name: Remote SSH Command
@ -121,17 +99,19 @@ linuxserver.io
--- ---
## 🔑 Setting Up SSH Keys ## 🔑 SSH Key Setup & OpenSSH Compatibility
### Setting Up SSH Keys
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: 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 #### 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"
@ -175,9 +155,7 @@ See more: [SSH login without a password](http://www.linuxproblem.org/art_9.html)
> - Set `.ssh` permissions to 700 > - Set `.ssh` permissions to 700
> - Set `.ssh/authorized_keys2` permissions to 640 > - Set `.ssh/authorized_keys2` permissions to 640
--- ### OpenSSH Compatibility
## 🛡️ OpenSSH Compatibility
If you see this error: If you see this error:
@ -199,7 +177,9 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
--- ---
## 🧑‍💻 More Usage Examples ## 🛠️ Usage Scenarios & Advanced Examples
This section covers common and advanced usage patterns, including multi-host, proxy, and environment variable passing.
### Using password authentication ### Using password authentication
@ -331,7 +311,9 @@ Default `port` is `22`.
--- ---
## 🌐 Using ProxyCommand (Jump Host) ## 🌐 Proxy & Jump Host Usage
You can connect to remote hosts via a proxy (jump host) for advanced network topologies.
```bash ```bash
+--------+ +----------+ +-----------+ +--------+ +----------+ +-----------+
@ -376,7 +358,9 @@ Host FooServer
--- ---
## 🔒 Protecting Your Private Key ## 🛡️ Security Best Practices
### Protecting Your Private Key
A passphrase encrypts your private key, making it useless to attackers if leaked. Always store your private key securely. A passphrase encrypts your private key, making it useless to attackers if leaked. Always store your private key securely.
@ -394,9 +378,7 @@ A passphrase encrypts your private key, making it useless to attackers if leaked
ls -al ls -al
``` ```
--- ### Host Fingerprint Verification
## 🖐️ Host Fingerprint Verification
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): 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):
@ -422,9 +404,11 @@ Update your config:
--- ---
## ❓ Q&A ## 🚨 Error Handling & Troubleshooting
### Command not found (npm or other command) ### Q&A
#### Command not found (npm or other command)
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 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.

74
README.zh-cn.md
View File

@ -2,44 +2,22 @@
[English](./README.md) | [繁體中文](./README.zh-tw.md) | 简体中文 [English](./README.md) | [繁體中文](./README.zh-tw.md) | 简体中文
## 目录 ---
- [🚀 用于 GitHub Actions 的 SSH](#-用于-github-actions-的-ssh) ## 📖 简介
- [目录](#目录)
- [📥 输入参数](#-输入参数)
- [🚦 使用示例](#-使用示例)
- [🔑 配置 SSH 密钥](#-配置-ssh-密钥)
- [生成 RSA 密钥](#生成-rsa-密钥)
- [生成 ED25519 密钥](#生成-ed25519-密钥)
- [🛡️ OpenSSH 兼容性](#️-openssh-兼容性)
- [🧑‍💻 更多用法示例](#-更多用法示例)
- [使用密码认证](#使用密码认证)
- [使用私钥认证](#使用私钥认证)
- [多条命令](#多条命令)
- [从文件执行命令](#从文件执行命令)
- [多主机](#多主机)
- [多主机不同端口](#多主机不同端口)
- [多主机同步执行](#多主机同步执行)
- [传递环境变量到 shell 脚本](#传递环境变量到-shell-脚本)
- [🌐 使用 ProxyCommand（跳板机）](#-使用-proxycommand跳板机)
- [🔒 保护你的私钥](#-保护你的私钥)
- [🖐️ 主机指纹验证](#️-主机指纹验证)
- [❓ 常见问题](#-常见问题)
- [命令未找到（npm 或其他命令）](#命令未找到npm-或其他命令)
- [🤝 贡献](#-贡献)
- [📝 许可证](#-许可证)
一个让你轻松安全地执行远程 SSH 命令的 [GitHub Action](https://github.com/features/actions)。 **SSH for GitHub Actions** 是一个强大的 [GitHub Action](https://github.com/features/actions)，可让你在 CI/CD 工作流中轻松且安全地执行远程 SSH 命令。
本项目基于 [Golang](https://go.dev) 和 [drone-ssh](https://github.com/appleboy/drone-ssh) 构建，支持多主机、代理、高级认证等多种 SSH 场景。
![ssh workflow](./images/ssh-workflow.png) ![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) 构建。
--- ---
## 📥 输入参数 ## 🧩 核心概念与输入参数
本 Action 提供灵活的 SSH 命令执行能力，并具备丰富的配置选项。
详细参数请参阅 [action.yml](./action.yml)。 详细参数请参阅 [action.yml](./action.yml)。
@ -85,9 +63,9 @@
--- ---
## 🚦 使用示例 ## ⚡ 快速开始
在工作流中执行远程 SSH 命令： 只需简单配置，即可在工作流中执行远程 SSH 命令：
```yaml ```yaml
name: Remote SSH Command name: Remote SSH Command
@ -121,17 +99,19 @@ linuxserver.io
--- ---
## 🔑 配置 SSH 密钥 ## 🔑 SSH 密钥配置与 OpenSSH 兼容性
### 配置 SSH 密钥
建议在本地机器（而非远程服务器）上创建 SSH 密钥。请使用 GitHub Secrets 中指定的用户名登录并生成密钥对： 建议在本地机器（而非远程服务器）上创建 SSH 密钥。请使用 GitHub Secrets 中指定的用户名登录并生成密钥对：
### 生成 RSA 密钥 #### 生成 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"
@ -175,9 +155,7 @@ xclip < ~/.ssh/id_ed25519
> - 设置 `.ssh` 权限为 700 > - 设置 `.ssh` 权限为 700
> - 设置 `.ssh/authorized_keys2` 权限为 640 > - 设置 `.ssh/authorized_keys2` 权限为 640
--- ### OpenSSH 兼容性
## 🛡️ OpenSSH 兼容性
如果出现如下错误： 如果出现如下错误：
@ -199,7 +177,9 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
--- ---
## 🧑‍💻 更多用法示例 ## 🛠️ 用法场景与进阶示例
本节涵盖常见与进阶用法，包括多主机、代理、环境变量传递等。
### 使用密码认证 ### 使用密码认证
@ -331,7 +311,9 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
--- ---
## 🌐 使用 ProxyCommand（跳板机） ## 🌐 代理与跳板机用法
你可以通过代理（跳板机）连接到远程主机，适用于进阶网络拓扑。
```bash ```bash
+--------+ +----------+ +-----------+ +--------+ +----------+ +-----------+
@ -376,7 +358,9 @@ Host FooServer
--- ---
## 🔒 保护你的私钥 ## 🛡️ 安全最佳实践
### 保护你的私钥
密码短语会加密你的私钥，即使泄露也无法被攻击者直接利用。请务必妥善保管私钥。 密码短语会加密你的私钥，即使泄露也无法被攻击者直接利用。请务必妥善保管私钥。
@ -394,9 +378,7 @@ Host FooServer
ls -al ls -al
``` ```
--- ### 主机指纹验证
## 🖐️ 主机指纹验证
验证 SSH 主机指纹有助于防止中间人攻击。获取主机指纹（将 `ed25519` 替换为你的密钥类型，`example.com` 替换为你的主机）： 验证 SSH 主机指纹有助于防止中间人攻击。获取主机指纹（将 `ed25519` 替换为你的密钥类型，`example.com` 替换为你的主机）：
@ -422,9 +404,11 @@ ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' '
--- ---
## ❓ 常见问题 ## 🚨 错误处理与疑难解答
### 命令未找到（npm 或其他命令） ### 常见问题
#### 命令未找到（npm 或其他命令）
如果遇到 "command not found" 错误，请参考 [此评论](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) 了解交互式与非交互式 shell 的区别。 如果遇到 "command not found" 错误，请参考 [此评论](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) 了解交互式与非交互式 shell 的区别。

74
README.zh-tw.md
View File

@ -2,44 +2,22 @@
[English](./README.md) | 繁體中文 | [简体中文](./README.zh-cn.md) [English](./README.md) | 繁體中文 | [简体中文](./README.zh-cn.md)
## 目錄 ---
- [🚀 GitHub Actions 的 SSH](#-github-actions-的-ssh) ## 📖 簡介
- [目錄](#目錄)
- [📥 輸入參數](#-輸入參數)
- [🚦 使用範例](#-使用範例)
- [🔑 設定 SSH 金鑰](#-設定-ssh-金鑰)
- [產生 RSA 金鑰](#產生-rsa-金鑰)
- [產生 ED25519 金鑰](#產生-ed25519-金鑰)
- [🛡️ OpenSSH 相容性](#️-openssh-相容性)
- [🧑‍💻 更多用法範例](#-更多用法範例)
- [使用密碼認證](#使用密碼認證)
- [使用私鑰認證](#使用私鑰認證)
- [多條指令](#多條指令)
- [從檔案執行指令](#從檔案執行指令)
- [多主機](#多主機)
- [多主機不同埠號](#多主機不同埠號)
- [多主機同步執行](#多主機同步執行)
- [傳遞環境變數到 shell 腳本](#傳遞環境變數到-shell-腳本)
- [🌐 使用 ProxyCommand（跳板機）](#-使用-proxycommand跳板機)
- [🔒 保護你的私鑰](#-保護你的私鑰)
- [🖐️ 主機指紋驗證](#️-主機指紋驗證)
- [❓ 常見問題](#-常見問題)
- [指令找不到（npm 或其他指令）](#指令找不到npm-或其他指令)
- [🤝 貢獻](#-貢獻)
- [📝 授權](#-授權)
一個讓你輕鬆安全執行遠端 SSH 指令的 [GitHub Action](https://github.com/features/actions)。 **SSH for GitHub Actions** 是一個強大的 [GitHub Action](https://github.com/features/actions)，可讓你在 CI/CD 工作流程中輕鬆且安全地執行遠端 SSH 指令。
本專案以 [Golang](https://go.dev) 和 [drone-ssh](https://github.com/appleboy/drone-ssh) 建立，支援多主機、代理、進階認證等多種 SSH 場景。
![ssh workflow](./images/ssh-workflow.png) ![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) 建立。
--- ---
## 📥 輸入參數 ## 🧩 核心概念與輸入參數
本 Action 提供彈性的 SSH 指令執行能力，並具備豐富的設定選項。
完整參數請參閱 [action.yml](./action.yml)。 完整參數請參閱 [action.yml](./action.yml)。
@ -85,9 +63,9 @@
--- ---
## 🚦 使用範例 ## ⚡ 快速開始
在工作流程中執行遠端 SSH 指令： 只需簡單設定，即可在工作流程中執行遠端 SSH 指令：
```yaml ```yaml
name: Remote SSH Command name: Remote SSH Command
@ -121,17 +99,19 @@ linuxserver.io
--- ---
## 🔑 設定 SSH 金鑰 ## 🔑 SSH 金鑰設定與 OpenSSH 相容性
### 設定 SSH 金鑰
建議於本地端（非遠端伺服器）產生 SSH 金鑰。請以 GitHub Secrets 指定的使用者名稱登入並產生金鑰對： 建議於本地端（非遠端伺服器）產生 SSH 金鑰。請以 GitHub Secrets 指定的使用者名稱登入並產生金鑰對：
### 產生 RSA 金鑰 #### 產生 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"
@ -175,9 +155,7 @@ xclip < ~/.ssh/id_ed25519
> - 設定 `.ssh` 權限為 700 > - 設定 `.ssh` 權限為 700
> - 設定 `.ssh/authorized_keys2` 權限為 640 > - 設定 `.ssh/authorized_keys2` 權限為 640
--- ### OpenSSH 相容性
## 🛡️ OpenSSH 相容性
若出現以下錯誤： 若出現以下錯誤：
@ -199,7 +177,9 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
--- ---
## 🧑‍💻 更多用法範例 ## 🛠️ 用法場景與進階範例
本節涵蓋常見與進階用法，包括多主機、代理、環境變數傳遞等。
### 使用密碼認證 ### 使用密碼認證
@ -331,7 +311,9 @@ ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
--- ---
## 🌐 使用 ProxyCommand（跳板機） ## 🌐 代理與跳板機用法
你可以透過代理（跳板機）連線到遠端主機，適用於進階網路拓撲。
```bash ```bash
+--------+ +----------+ +-----------+ +--------+ +----------+ +-----------+
@ -376,7 +358,9 @@ Host FooServer
--- ---
## 🔒 保護你的私鑰 ## 🛡️ 安全最佳實踐
### 保護你的私鑰
密碼短語會加密你的私鑰，即使外洩也無法被攻擊者直接利用。請務必妥善保管私鑰。 密碼短語會加密你的私鑰，即使外洩也無法被攻擊者直接利用。請務必妥善保管私鑰。
@ -394,9 +378,7 @@ Host FooServer
ls -al ls -al
``` ```
--- ### 主機指紋驗證
## 🖐️ 主機指紋驗證
驗證 SSH 主機指紋有助於防止中間人攻擊。取得主機指紋（將 `ed25519` 換成你的金鑰型別，`example.com` 換成你的主機）： 驗證 SSH 主機指紋有助於防止中間人攻擊。取得主機指紋（將 `ed25519` 換成你的金鑰型別，`example.com` 換成你的主機）：
@ -422,9 +404,11 @@ ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' '
--- ---
## ❓ 常見問題 ## 🚨 錯誤處理與疑難排解
### 指令找不到（npm 或其他指令） ### 常見問題
#### 指令找不到（npm 或其他指令）
若遇到 "command not found" 錯誤，請參考 [此討論](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) 了解互動式與非互動式 shell 差異。 若遇到 "command not found" 錯誤，請參考 [此討論](https://github.com/appleboy/ssh-action/issues/31#issuecomment-1006565847) 了解互動式與非互動式 shell 差異。