架構
最後更新
本頁以一張概覽圖說明 PodRun 的 CLI、遠端主機與 API Server 之間的層級關係。
系統概覽
graph LR
subgraph 本地主機
CLI["podrun CLI (cmd/cli)"]
API["API Server (cmd/api :8080)"]
DB[(SQLite)]
end
subgraph 遠端主機
Dir[/home/podrun/名稱_雜湊/]
Compose[Podman Compose]
K3s[k3s 未完成]
end
CLI -->|rsync over sshpass| Dir
CLI -->|ssh 指令| Compose
CLI -.->|未完成| K3s
Compose --> Dir
CLI -->|HTTP POST| API
API --> DB- graph LR
- subgraph 本地主機
- CLI["podrun CLI (cmd/cli)"]
- API["API Server (cmd/api :8080)"]
- DB[(SQLite)]
- end
- subgraph 遠端主機
- Dir[/home/podrun/名稱_雜湊/]
- Compose[Podman Compose]
- K3s[k3s 未完成]
- end
- CLI -->|rsync over sshpass| Dir
- CLI -->|ssh 指令| Compose
- CLI -.->|未完成| K3s
- Compose --> Dir
- CLI -->|HTTP POST| API
- API --> DB
分層
| 層 | 套件 | 職責 |
|---|---|---|
| 入口 | cmd/cli | 載入 .env、檢查依賴與環境變數、測試 SSH、分派指令 |
| 入口 | cmd/api | 決定 DB_PATH、開啟 SQLite、啟動 HTTP Server |
| 指令 | internal/command | 解析參數、推導本地與遠端路徑、執行 up/clear/轉送指令、回報 API |
| 工具 | internal/utils | sshpass 包裝(SSHRun、SSEOutput、SSHTest)、依賴安裝、本機 MAC/IP/Hostname |
| HTTP | internal/handler | Gin 路由與 JSON 綁定 |
| 儲存 | internal/database | pods/records 的 upsert、update、insert、list |
| 模型 | internal/model | Pod、Record、User 結構 |
跨切原則
- 遠端不裝 PodRun:遠端只需 SSH、
rsync與可執行podman compose的 Podman,所有邏輯在本地 CLI 透過 SSH 指令完成 - 不動原始檔:本地 compose 檔不修改,改寫只發生在遠端副本
docker-compose.podrun.yml - 紀錄失敗不阻斷部署:
removePod()與recordPod()的錯誤被忽略;只有up結尾的upsertPod()失敗會回傳錯誤
相關工具
| 工具 | 是什麼 | 與 PodRun 的關係 |
|---|---|---|
docker context | Docker CLI 的設定,讓指令改連另一台 Docker daemon | PodRun 先把專案複製到遠端主機,再在遠端執行 Podman;見檔案同步 |
| containers/podman-compose | 以 Podman 執行 docker-compose.yml 的 Python 腳本 | PodRun 透過 SSH 在遠端執行 podman compose;podman compose 會把檔案交給已安裝的 compose provider(例如 podman-compose) |
| basecamp/kamal | 經 SSH 部署 Docker 容器的 Ruby CLI,設定寫在 config/deploy.yml | PodRun 直接讀既有的 docker-compose.yml,部署目標是 Podman;up 會先 down -v 再啟動,部署期間不保留舊容器 |
| g1ibby/dcd | 經 SSH 同步檔案並管理 Docker Compose 服務的 Rust CLI | 同樣是 SSH 加檔案同步;PodRun 在改寫過的副本上執行 podman compose,移除主機 Port 並為相對路徑 volume 補 :z |
| davidfowl/aspire-ssh-deploy | .NET Aspire docker compose 整合的擴充,經 SSH 部署到 Docker 主機 | PodRun 是獨立的 Go CLI,任何 compose 專案都能用,不綁應用程式框架 |
| sprisa/composure | 經 SSH 把 docker-compose 服務送到多台伺服器的 Go CLI | PodRun 部署到 PODRUN_SERVER 指定的單一主機,並把每次操作回報給本地 API Server(部署紀錄) |
延伸閱讀
模組級圖、
up 時序圖與狀態機見 doc/architecture.zh.md。