From 6a1b59d972b8284bc1127691af3cb964ae4c841b Mon Sep 17 00:00:00 2001 From: Bo-Yi Wu Date: Fri, 3 Mar 2023 10:45:48 +0800 Subject: [PATCH] docs: add chinese --- README.md | 2 + README.zh-tw.md | 348 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 350 insertions(+) diff --git a/README.md b/README.md index 87f303d..460866f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # 🚀 SSH for GitHub Actions +[繁體中文](./README.zh-tw.md) + [GitHub Action](https://github.com/features/actions) for executing remote ssh commands. ![ssh workflow](./images/ssh-workflow.png) diff --git a/README.zh-tw.md b/README.zh-tw.md index f08a5f7..eeeca6d 100644 --- a/README.zh-tw.md +++ b/README.zh-tw.md @@ -43,3 +43,351 @@ SSH 代理設置: * `proxy_fingerprint` - 代理主機公鑰的 SHA256 指紋，預設為跳過驗證 * `proxy_use_insecure_cipher` - 使用不安全的加密方式，請參閱 [#56](https://github.com/appleboy/ssh-action/issues/56) * `proxy_cipher` - 允許的加密算法。如果未指定，則使用合理的算法 + +## 使用方式 + +執行遠端 SSH 命令 + +```yaml +name: remote ssh command +on: [push] +jobs: + + build: + name: Build + runs-on: ubuntu-latest + steps: + - name: executing remote ssh commands using password + uses: appleboy/ssh-action@v0.1.8 + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USERNAME }} + password: ${{ secrets.PASSWORD }} + port: ${{ secrets.PORT }} + script: whoami +``` + +畫面輸出 + +```sh +======CMD====== +whoami +======END====== +out: *** +============================================== +✅ Successfully executed commands to all host. +============================================== +``` + +### 設置 SSH 金鑰 + +請在創建 SSH 金鑰並使用 SSH 金鑰時遵循以下步驟。最佳做法是在本地機器上創建 SSH 金鑰而不是遠端機器上。請使用 Github Secrets 中指定的用戶名登錄。生成 RSA 金鑰： + +### 生成 RSA 金鑰 + +```bash +ssh-keygen -t rsa -b 4096 -C "your_email@example.com" +``` + +### 生成 ed25519 金鑰 + +```bash +ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" +``` + +將新生成的金鑰添加到已授權的金鑰中。詳細了解已授權的金鑰請點擊[此處](https://www.ssh.com/ssh/authorized_keys/). + +### 將 RSA 金鑰添加到已授權金鑰中 + +```bash +cat .ssh/id_rsa.pub | ssh b@B 'cat >> .ssh/authorized_keys' +``` + +### 將 ed25519 金鑰添加到已授權金鑰中 + +```bash +cat .ssh/id_ed25519.pub | ssh b@B 'cat >> .ssh/authorized_keys' +``` + +複製私鑰內容，然後將其粘貼到 Github Secrets 中。 + +### 複製 rsa 私鑰內容 + +```bash +clip < ~/.ssh/id_rsa +``` + +### 複製 ed25519 私鑰內容 + +```bash +clip < ~/.ssh/id_ed25519 +``` + +有關無需密碼登錄 SSH 的詳細信息，請[參見該網站](http://www.linuxproblem.org/art_9.html)。 + +**來自讀者的注意事項**： 根據您的 SSH 版本，您可能還需要進行以下更改： + +* 將公鑰放在 `.ssh/authorized_keys2` 中 +* 將 `.ssh` 的權限更改為700 +* 將 `.ssh/authorized_keys2` 的權限更改為640 + +### 如果你使用的是 OpenSSH + +如果您正在使用 OpenSSH，並出現以下錯誤： + +```bash +ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey] +``` + +請確保您所選擇的密鑰演算法得到支援。在 Ubuntu 20.04 或更高版本上，您必須明確允許使用 SSH-RSA 演算法。請在 OpenSSH 守護進程文件中添加以下行（它可以是 `/etc/ssh/sshd_config` 或 `/etc/ssh/sshd_config.d/` 中的一個附著文件）： + +```bash +CASignatureAlgorithms +ssh-rsa +``` + +或者，`Ed25519` 密鑰在 OpenSSH 中默認被接受。如果需要，您可以使用它來替代 RSA。 + +```bash +ssh-keygen -t ed25519 -a 200 -C "your_email@example.com" +``` + +### Example + +#### 使用密碼執行遠端 SSH 命令 + +```yaml +- name: executing remote ssh commands using password + uses: appleboy/ssh-action@v0.1.8 + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USERNAME }} + password: ${{ secrets.PASSWORD }} + port: ${{ secrets.PORT }} + script: whoami +``` + +#### 使用私鑰 + +```yaml +- name: executing remote ssh commands using ssh key + uses: appleboy/ssh-action@v0.1.8 + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USERNAME }} + key: ${{ secrets.KEY }} + port: ${{ secrets.PORT }} + script: whoami +``` + +#### 多個命令 + +```yaml +- name: multiple command + uses: appleboy/ssh-action@v0.1.8 + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USERNAME }} + key: ${{ secrets.KEY }} + port: ${{ secrets.PORT }} + script: | + whoami + ls -al +``` + +![result](./images/output-result.png) + +#### 多台主機 + +```diff + - name: multiple host + uses: appleboy/ssh-action@v0.1.8 + with: +- host: "foo.com" ++ host: "foo.com,bar.com" + username: ${{ secrets.USERNAME }} + key: ${{ secrets.KEY }} + port: ${{ secrets.PORT }} + script: | + whoami + ls -al +``` + +#### 多個不同端口的主機 + +```diff + - name: multiple host + uses: appleboy/ssh-action@v0.1.8 + with: +- host: "foo.com" ++ host: "foo.com:1234,bar.com:5678" + username: ${{ secrets.USERNAME }} + key: ${{ secrets.KEY }} + script: | + whoami + ls -al +``` + +#### 在多個主機上同步執行 + +```diff + - name: multiple host + uses: appleboy/ssh-action@v0.1.8 + with: + host: "foo.com,bar.com" ++ sync: true + username: ${{ secrets.USERNAME }} + key: ${{ secrets.KEY }} + port: ${{ secrets.PORT }} + script: | + whoami + ls -al +``` + +#### 將環境變量傳遞到 Shell 腳本 + +```diff + - name: pass environment + uses: appleboy/ssh-action@v0.1.8 ++ env: ++ FOO: "BAR" ++ BAR: "FOO" ++ SHA: ${{ github.sha }} + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USERNAME }} + key: ${{ secrets.KEY }} + port: ${{ secrets.PORT }} ++ envs: FOO,BAR,SHA + script: | + echo "I am $FOO" + echo "I am $BAR" + echo "sha: $SHA" +``` + +_在 `env` 對象中，您需要將每個環境變量作為字符串傳遞，傳遞 `Integer` 數據類型或任何其他類型可能會產生意外結果。_ + +#### 在第一次失敗後停止腳本 + +> ex: missing `abc` folder + +```diff + - name: stop script if command error + uses: appleboy/ssh-action@v0.1.8 + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USERNAME }} + key: ${{ secrets.KEY }} + port: ${{ secrets.PORT }} ++ script_stop: true + script: | + mkdir abc/def + ls -al +``` + +畫面輸出: + +```sh +======CMD====== +mkdir abc/def +ls -al + +======END====== +2019/11/21 01:16:21 Process exited with status 1 +err: mkdir: cannot create directory ‘abc/def’: No such file or directory +##[error]Docker run failed with exit code 1 +``` + +#### 如何使用 `ProxyCommand` 連接遠程服務器？ + +```bash ++--------+ +----------+ +-----------+ +| Laptop | <--> | Jumphost | <--> | FooServer | ++--------+ +----------+ +-----------+ +``` + +在您的 `~/.ssh/config` 文件中，您會看到以下內容。 + +```bash +Host Jumphost + HostName Jumphost + User ubuntu + Port 22 + IdentityFile ~/.ssh/keys/jump_host.pem + +Host FooServer + HostName FooServer + User ubuntu + Port 22 + ProxyCommand ssh -q -W %h:%p Jumphost +``` + +#### 如何將其轉換為 GitHubActions 的 YAML 格式？ + +```diff + - name: ssh proxy command + uses: appleboy/ssh-action@v0.1.8 + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USERNAME }} + key: ${{ secrets.KEY }} + port: ${{ secrets.PORT }} ++ proxy_host: ${{ secrets.PROXY_HOST }} ++ proxy_username: ${{ secrets.PROXY_USERNAME }} ++ proxy_key: ${{ secrets.PROXY_KEY }} ++ proxy_port: ${{ secrets.PROXY_PORT }} + script: | + mkdir abc/def + ls -al +``` + +#### 如何保護私鑰？ + +密碼短語通常用於加密私鑰。這使得攻擊者無法單獨使用密鑰文件。文件泄露可能來自備份或停用的硬件，黑客通常可以從受攻擊系統中洩露文件。因此，保護私鑰非常重要。 + +```diff + - name: ssh key passphrase + uses: appleboy/ssh-action@v0.1.8 + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USERNAME }} + key: ${{ secrets.KEY }} + port: ${{ secrets.PORT }} ++ passphrase: ${{ secrets.PASSPHRASE }} + script: | + whoami + ls -al +``` + +#### 使用主機指紋驗證 + +設置 SSH 主機指紋驗證可以幫助防止中間人攻擊。在設置之前，運行以下命令以獲取 SSH 主機指紋。請記得將 `ed25519` 替換為您的適當金鑰類型（`rsa`、 `dsa`等），而 `example.com` 則替換為您的主機。 + +現代 OpenSSH 版本中，需要提取的_默認金鑰_類型是 `rsa`（從版本 5.1 開始）、`ecdsa`（從版本 6.0 開始）和 `ed25519`（從版本 6.7 開始）。 + +```sh +ssh example.com ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d ' ' -f2 +``` + +現在您可以調整您的配置： + +```diff + - name: ssh key passphrase + uses: appleboy/ssh-action@v0.1.8 + with: + host: ${{ secrets.HOST }} + username: ${{ secrets.USERNAME }} + key: ${{ secrets.KEY }} + port: ${{ secrets.PORT }} ++ fingerprint: ${{ secrets.FINGERPRINT }} + script: | + whoami + ls -al +``` + +## 貢獻 + +我們非常希望您為 `appleboy/ssh-action` 做出貢獻，歡迎提交請求！ + +## 授權方式 + +本項目中的腳本和文檔采用 [MIT](LICENSE) 許可證 發布。