mirror of
https://github.com/appleboy/ssh-action.git
synced 2025-06-20 16:42:10 +10:00
docs: rewrite and unify documentation across all supported languages
- Rewrite and reorganize documentation for clarity and readability, including reworded introductions and consistent headings. - Improve input parameter tables: clarify descriptions, unify formatting, and better explain parameter purposes across all three languages. - Expand and update step-by-step SSH key setup guides, streamline copy instructions, and add practical notes and tips. - Enhance usage examples with clearer titles, better labels, and updated YAML examples for different authentication methods and scenarios. - Add new sections and tips on OpenSSH compatibility and troubleshooting "command not found" issues, with improved cross-platform guidance. - Refine explanations for host fingerprint verification, proxy setup, and command environment management. - Update and polish contributing and license sections for greater encouragement and style consistency. - Apply the above documentation improvements to both Simplified and Traditional Chinese versions for parity. Signed-off-by: appleboy <appleboy.tw@gmail.com>
This commit is contained in:
appleboy
parent
0e19dd962d
commit
b80f638dc4
3 changed files with 384 additions and 351 deletions
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…
Add table
Add a link
Reference in a new issue