架構

最後更新 2026-10-06

本頁以一張概覽圖說明 PodRun 的 CLI、遠端主機與 API Server 之間的層級關係。

系統概覽

graph LR
    subgraph 本地主機
        CLI[podrun CLI<br/>cmd/cli]
        API[API Server<br/>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` 結構

跨切原則

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

延伸閱讀

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