SSH 操作器

SSH Operator

透過 SSH/SFTP 操作遠端 Linux 伺服器，進行應用程式部署、Docker 容器管理及運行狀態檢查。支援多檔案/多資料夾專案，並針對寶塔面板環境進行了調適。

何時呼叫

• 使用者要求將程式碼部署、發布或更新到伺服器。
• 使用者要求重新啟動、重建或更新遠端服務。
• 使用者要求上傳檔案或整個資料夾到遠端主機。
• 使用者要求查看遠端日誌或檢查服務狀態。
• 使用者要求執行命令或診斷遠端伺服器問題。
• 使用者要求編輯遠端網站/部落格原始碼檔案。
• 使用者要求發布部落格文章或偵測部落格平台的發布 API。
• 使用者提及寶塔面板、/www/wwwroot/ 或中國雲端 VPS 主機。

功能

• 透過 SSH 連線到遠端主機（密碼或金鑰認證）。
• 透過 SFTP 上傳/下載檔案，並遞迴上傳資料夾。
• 執行 Shell 命令並串流輸出。
• 管理 Docker 及 docker-compose 工作負載。
• 檢查服務健康狀態、日誌、磁碟使用量及行程狀態。
• 驗證部署的變更是否生效（校驗碼、行程重啟、HTTP 健康檢查）。
• 針對寶塔面板的目錄佈局及 Nginx 反向代理設定調整命令。
• 直接透過 SSH 編輯遠端網站/部落格原始碼檔案。
• 偵測部落格發布 API（WordPress、Ghost、Halo）並透過 Python 腳本發布 Markdown 文章。

必要輸入

請在操作前向使用者或環境收集以下資訊：

1. HOST — 伺服器 IP 或主機名稱。
2. PORT — SSH 通訊埠（預設 22）。
3. USER — SSH 使用者名稱。
4. AUTH — 密碼或私鑰路徑。建議使用金鑰；切勿將機密寫死在提交的檔案中。
5. REMOTE_ROOT — 伺服器上的專案基礎路徑（例如 /www/wwwroot/ai-interviewer）。
6. FILES_TO_UPLOAD — local_path -> remote_relative_path 配對列表，可包含整個資料夾。
7. COMMANDS — 要執行的部署或診斷命令。

多檔案/多資料夾部署

大多數真實專案都不是單一檔案。請使用以下方法之一：

選項 1：使用提供的腳本範本

將 scripts/deploy-folder.py 複製到專案儲存庫中，設定 FILES_TO_UPLOAD 列表，然後執行。它會處理遞迴資料夾上傳並保留相對路徑。

對於類 Unix 本地環境，scripts/deploy-rsync.sh 提供了一個基於 rsync 的增量替代方案，並含有合理的排除規則。

選項 2：代理驅動的 SFTP

當代理具備 SFTP/SSH 工具時：

1. 建立 SSH 工作階段。
2. 對於每個變更的資料夾，遍歷其內容並逐個上傳檔案，同時在遠端重建目錄樹。
3. 對於每個變更的檔案，上傳到對應的遠端相對路徑。
4. 執行部署命令並進行驗證。

選項 3：一次性打包傳輸

對於大型專案，建議在本地打包然後在遠端解壓縮：

# 本地端
 tar czf deploy.tar.gz backend/app frontend/.next docker-compose.yml .env.production
 scp deploy.tar.gz user@host:/tmp/

# 遠端
 ssh user@host "cd /www/wwwroot/project && tar xzf /tmp/deploy.tar.gz && docker-compose up -d --build"

腳本庫

現成的自動化腳本。Python 腳本共用 scripts/_ssh.py 進行連線/設定載入，並從 .env 檔案中讀取憑證（請參考 .env.example）。請將腳本與 _ssh.py 一起複製到您的專案中。

腳本	用途
scripts/_ssh.py	共用輔助程式：載入 .env 設定並開啟 SSH/SFTP 連線。
scripts/deploy-folder.py	遞迴 SFTP 上傳檔案與資料夾，然後執行部署後命令。
scripts/deploy-rsync.sh	增量 rsync 部署，包含常用排除規則。
scripts/blog_api_probe.py	偵測常見的部落格發布 API（WordPress、Ghost、Halo）。
scripts/publish_post.py	透過 REST API 將 Markdown 檔案發布到 WordPress 或 Ghost。
scripts/backup_before_deploy.py	在部署前備份程式碼、Nginx 設定、Docker 磁碟區及 SQLite。
scripts/server_health.py	收集 CPU、記憶體、磁碟、Docker、Nginx 及 HTTP 健康狀態。
scripts/log_collector.py	將 Docker、Nginx 及寶塔日誌拉取到本地檔案以供分析。
scripts/nginx_manager.py	讀取/備份/編輯寶塔 Nginx 站點設定並安全重新載入。
scripts/bt_panel.py	安裝寶塔、檢視面板資訊、重新載入 Nginx 並透過 SSH 檢查 Docker 狀態。

Python 依賴項列在 requirements.txt 中。

標準部署工作流程

1. 建立 SSH 工作階段，使用提供的憑證並設定合理的逾時時間（≥20 秒）。
2. 在變更任何內容前進行備份 — 執行 scripts/backup_before_deploy.py 或同等操作。
3. 確保 REMOTE_ROOT 存在（mkdir -p）。
4. 上傳檔案/資料夾，保留相對於 REMOTE_ROOT 的路徑。
5. 依序執行命令；建議使用 && 串聯相依命令。
6. 等待服務啟動（使用 sleep + docker-compose ps 或健康端點）。
7. 驗證新程式碼已生效（在容器內 grep、存取 /health、檢查日誌）。
8. 簡潔回報結果：變更了哪些內容、服務是否健康以及任何錯誤。

常用命令模式

# 停止、重建並重新啟動服務
cd ${REMOTE_ROOT} && docker-compose stop backend \
  && docker-compose rm -f backend \
  && docker-compose build backend \
  && docker-compose up -d backend

# 檢查服務狀態
cd ${REMOTE_ROOT} && docker-compose ps

# 查看近期日誌
cd ${REMOTE_ROOT} && docker-compose logs --tail=50 backend

# 驗證執行中容器內的程式碼
docker exec ${CONTAINER_NAME} grep -n "await db.flush()" app/api/v1/interview.py

# 磁碟清理
docker system prune -a -f

寶塔面板調適

完整操作指南請參閱 references/baota.md，bt CLI 速查表請參閱 references/bt-commands.md。重點提示：

• 官方網站：https://www.bt.cn；安裝腳本：https://www.bt.cn/new/download.html。
• 預設專案根目錄：/www/wwwroot/<site-name>。
• 使用 scripts/bt_panel.py 透過 SSH 安裝寶塔、檢視面板資訊或重新載入 Nginx。
• 在專案目錄內使用 Docker Compose；透過 CLI 或寶塔 Docker 外掛管理容器。
• 對於 Node/Python 前端，新增一個寶塔站點，並使用 scripts/nginx_manager.py 新增 Nginx 反向代理位置指向 127.0.0.1:3000。
• 在 Nginx 中將 /api/ 路由到後端容器（例如 127.0.0.1:8000）。
• 在寶塔防火牆和雲端供應商的安全群組中同時開放通訊埠。
• 請勿將高位通訊埠直接暴露到網際網路；應透過 Nginx 使用 80/443 埠。

如果出現問題，請參閱 references/troubleshooting.md。

安全規則

• 切勿提交機密資訊。將 PASS 或金鑰路徑儲存在環境變數、排除在 git 之外的 .env 檔案或機密管理器中。
• 優先使用明確的檔案列表，而非大範圍上傳，以避免覆寫非預期的檔案。
• 診斷時先執行非破壞性檢查（日誌、ps、df），再重新啟動服務。
• 避免 git push --force 或破壞性的 rm -rf，除非使用者明確要求。
• 確認危險操作（資料庫遷移、全服務重新啟動、破壞性刪除）時，如果可以，請先徵求使用者同意。
• 部署後清理暫存檔案（例如 /tmp/deploy.tar.gz）。

跨平台注意事項

• 此技能假設遠端主機為 Linux，本地環境具備 SSH 用戶端或 Python 函式庫（如 paramiko）。
• 在 Windows 本地主機上，路徑可能需要正規化；命令中的遠端路徑請務必加上引號。
• 對於沒有直接 SSH 工具的代理，退而求其次：(1) 生成部署腳本供使用者執行，或 (2) 使用平台提供的終端機/遠端執行工具。
• 為確保在 Claude Code、Codex、TRAE 和 Cursor 之間的最大可移植性，請將主 SKILL.md 保持在 500 行以內，並將詳細參考文件移至 references/ 目錄。

範例

使用者：「將最新的後端修復部署到我的寶塔伺服器。」

代理：

1. 詢問或載入 HOST、PORT、USER、驗證資訊及 REMOTE_ROOT。
2. 詢問哪些檔案變更了，或從最近的編輯中推斷。
3. 將變更的檔案/資料夾上傳到 REMOTE_ROOT 下的遠端路徑。
4. 重建並重新啟動受影響的 Docker 服務。
5. 檢查 docker-compose ps 並查看日誌尾部以確認健康狀態。
6. 回覆一份關於上傳及服務狀態的簡短摘要。