# 部署紀錄

本頁說明 CLI 在每次操作時送給 API Server 的部署資訊與操作紀錄，以及 `dismiss` 旗標的轉換。

## 回報時機

| 函式 | 呼叫時機 | API | 失敗處理 |
|---|---|---|---|
| `removePod()` | `up` 清掉舊容器後、`clear` 開始時、`down` 結束後 | `POST /api/pod/update/:uid`，body `{"dismiss": 1}` | 忽略 |
| `upsertPod()` | `up` 結束時 | `POST /api/pod/upsert` | 回傳錯誤，`up` 視為失敗 |
| `recordPod()` | 每個指令結束時，以及同步時 | `POST /api/pod/record/insert` | 忽略 |

CLI 固定連往 `http://localhost:8080`，API Server 未啟動時 `up` 會在最後一步回報 `failed to upsert pod`，但遠端容器已經啟動。

## 紀錄內容

`records.content` 的值：

| 值 | 來源 |
|---|---|
| `sync` | 遠端目錄為空，首次同步 |
| `overwrite` | 差異預覽後確認覆寫 |
| `up` | `up` 完成 |
| `clear` | `clear` 完成 |
| `down`／`ps`／`logs`／`restart`／`exec`／`build` | 轉送指令完成，值為指令名稱 |

每筆紀錄另存執行 CLI 的主機名稱與第一個非 loopback IPv4。`records.pod_id` 以 `uid` 查 `pods.id` 寫入，且欄位為 `NOT NULL`；首次部署的 `sync` 紀錄發生在 `pods` 寫入之前，查不到 `pods.id`，寫入會失敗並被忽略。

## dismiss 狀態

```mermaid
stateDiagram-v2
    [*] --> 有效: up（upsert）
    有效 --> 已移除: down／clear／重新 up 前清理
    已移除 --> 有效: up（upsert 重設 dismiss=0）
    已移除 --> [*]
```

`GET /api/pod/list` 只列出 `dismiss = 0` 的部署。`status` 欄位由 CLI 寫入 `starting`，目前不會更新為其他值。

## 資料庫位置

| 條件 | 路徑 |
|---|---|
| 設定 `DB_PATH` | `DB_PATH` 的值 |
| 存在 `/.dockerenv` | `/data/database.db` |
| 其他 | `~/.podrun/database.db`，目錄不存在時自動建立 |

資料表結構見 [HTTP API](/zh/http-api)。