v0.11.0

架構

最後更新


本頁以一張概覽圖說明 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
  1. graph LR
  2. subgraph 本地主機
  3. CLI["podrun CLI (cmd/cli)"]
  4. API["API Server (cmd/api :8080)"]
  5. DB[(SQLite)]
  6. end
  7. subgraph 遠端主機
  8. Dir[/home/podrun/名稱_雜湊/]
  9. Compose[Podman Compose]
  10. K3s[k3s 未完成]
  11. end
  12. CLI -->|rsync over sshpass| Dir
  13. CLI -->|ssh 指令| Compose
  14. CLI -.->|未完成| K3s
  15. Compose --> Dir
  16. CLI -->|HTTP POST| API
  17. API --> DB

分層


層套件職責
入口cmd/cli載入 .env、檢查依賴與環境變數、測試 SSH、分派指令
入口cmd/api決定 DB_PATH、開啟 SQLite、啟動 HTTP Server
指令internal/command解析參數、推導本地與遠端路徑、執行 up/clear/轉送指令、回報 API
工具internal/utilssshpass 包裝(SSHRun、SSEOutput、SSHTest)、依賴安裝、本機 MAC/IP/Hostname
HTTPinternal/handlerGin 路由與 JSON 綁定
儲存internal/databasepods/records 的 upsert、update、insert、list
模型internal/modelPod、Record、User 結構

跨切原則


  • 遠端不裝 PodRun:遠端只需 SSH、rsync 與可執行 podman compose 的 Podman,所有邏輯在本地 CLI 透過 SSH 指令完成
  • 不動原始檔:本地 compose 檔不修改,改寫只發生在遠端副本 docker-compose.podrun.yml
  • 紀錄失敗不阻斷部署:removePod() 與 recordPod() 的錯誤被忽略;只有 up 結尾的 upsertPod() 失敗會回傳錯誤

相關工具


工具是什麼與 PodRun 的關係
docker contextDocker CLI 的設定,讓指令改連另一台 Docker daemonPodRun 先把專案複製到遠端主機,再在遠端執行 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.ymlPodRun 直接讀既有的 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 CLIPodRun 部署到 PODRUN_SERVER 指定的單一主機,並把每次操作回報給本地 API Server(部署紀錄)

延伸閱讀


模組級圖、up 時序圖與狀態機見 doc/architecture.zh.md。
EN