# 檔案同步

本頁說明 `podrun up` 如何以 rsync 把本地專案同步到遠端，以及覆寫前的差異預覽。

## 流程

```mermaid
graph TB
    Start[RsyncToRemote] --> Check{遠端目錄是否為空}
    Check -->|空| Sync[rsync -avz --delete]
    Check -->|非空| Preview[rsync -avni --delete<br/>dry-run]
    Preview --> Changed{有變更}
    Changed -->|否| Sync
    Changed -->|是| Ask[詢問 confirm sync? y/N]
    Ask -->|y／Y| Sync
    Ask -->|其他| Cancel[回傳 cancelled]
```

## 差異預覽

遠端目錄已有內容時，先以 `rsync -avni --delete` 試跑並印出結果。下列行會被視為「沒有變更」而略過：

| 行 | 說明 |
|---|---|
| 空行 | — |
| `sending ...`／`sent ...`／`total size ...` | rsync 摘要 |
| `.d..t.......` 開頭 | 只有目錄時間戳改變 |

其他任何一行都代表有變更，需輸入 `y` 或 `Y` 才會繼續；輸入其他值則回傳 `cancelled` 並中止 `up`。確認後寫入一筆 `overwrite` 紀錄；遠端目錄為空時則寫入 `sync` 紀錄。

## 同步

實際同步使用 `rsync -avz --delete`，遠端多出的檔案會被刪除，讓遠端目錄與本地一致。

## 排除清單

| 類別 | 排除項目 |
|---|---|
| 相依套件 | `node_modules/`、`vendor/`、`__pycache__/`、`*.pyc`、`.venv/`、`venv/`、`env/` |
| 版本控制 | `.git/`、`.gitignore` |
| 本機檔案 | `.env.local`、`*.log`、`.DS_Store`、`Thumbs.db` |
| 建置產物 | `.next/`、`app/package-lock.json` |

差異預覽另外排除 `docker-compose.podrun.yml`，避免遠端副本被列為變更；實際同步則未排除它，因此 `--delete` 會先刪除遠端副本，之後由 [Compose 改寫](/zh/compose-rewrite) 重新產生。

`.env` 不在排除清單內，會一併同步到遠端。

## SSH 行為

| 項目 | 設定 |
|---|---|
| 認證 | `sshpass -p $PODRUN_PASSWORD` |
| 主機金鑰 | `StrictHostKeyChecking=no` |
| 遠端位址 | `$PODRUN_USERNAME@$PODRUN_SERVER` |