# 核心概念

本頁說明 PodRun 如何識別一個部署：UID、遠端目錄與本地專案目錄的推導規則。

## 本地專案目錄

依下列優先序決定，結果轉成絕對路徑：

| 優先 | 來源 |
|---|---|
| 1 | `--folder=<path>` 或 `--folder <path>` |
| 2 | `-f <file>` 所在目錄（`dir != "."` 時） |
| 3 | 以 `./` 或 `/` 開頭且存在的目錄位置參數 |
| 4 | 當前工作目錄 |

目錄必須存在，且含 `docker-compose.yml` 或 `docker-compose.yaml`，否則 `command.New()` 回傳錯誤。

## 部署 UID

```
uid = md5("<MAC>@<本地絕對路徑>")
```

- MAC 取第一個非 loopback 且有硬體位址的網卡；取不到時改用 Hostname
- 同一台機器、同一個專案路徑永遠得到同一個 UID
- `-u <uid>` 可覆寫；覆寫只影響紀錄用的 UID，不影響遠端目錄

## 遠端目錄

```
/home/podrun/<本地目錄名>_<雜湊前 8 碼>
```

雜湊與 UID 相同來源，因此不同機器、或同機器不同路徑的同名專案不會互相覆蓋。根目錄 `/home/podrun` 為固定值，與 `PODRUN_USERNAME` 無關。

## 指令分派

| 指令 | 路徑 | 行為 |
|---|---|---|
| `up` | `up()` | 同步、改寫 compose、重建容器、回報 API |
| `clear` | `clear()` | 移除容器、Volume、映像與遠端目錄 |
| `down`／`ps`／`logs`／`restart`／`exec`／`build` | `runCMD()` | 在遠端目錄執行 `podman compose <args>` |
| `domain`／`deploy` | `main` | 無動作（未完成） |
| 其他 | — | `unsupported command` |

`RemoteArgs` 的第一個元素即指令名稱；`-d`、`-f <檔名>` 與其餘參數原樣轉送給 `podman compose`。

## 前景與背景

- `-d`：容器在背景啟動，完成後印出 Port 對應與 Pod 資訊
- 未加 `-d`：`up` 在前景跟著 compose 輸出；遠端以 `trap cleanup INT TERM` 包裝，Ctrl+C 會執行 `podman compose down`