# Harbor Desk 部署（apps/ 主線）

本目錄給 **新後端 `apps/backend` + 前端 `apps/web`** 的本機／dev 一鍵部署。  
（`old/deploy` 為舊系統封存，不要混用。）

## 架構

```text
瀏覽器 → nginx:80（可選）
           ├─ /              → Vite :5173
           ├─ /api/          → gateway :8888
           └─ /haixun-assets/→ MinIO :9000

宿主：gateway + vite
Docker：mongo / redis / minio / mailpit（只綁 127.0.0.1）
```

## 快速開始（全部清乾淨重裝）

```bash
cd /path/to/thread-master

# 1) env（首次）
cp deploy/.env.example deploy/.env.dev
# 編輯密鑰：MONGO_ROOT_PASSWORD、REDIS_PASSWORD、MINIO_ROOT_PASSWORD、JWT…
# 並同步 MONGO_URI / MONGO_URL / HAIXUN_STORAGE_S3_SECRET_KEY 內的密碼

# 2) 一鍵：清資料 + infra + migrate + build + start
./deploy/scripts/redeploy.sh --yes --kill-orphan

# 3)（建議）nginx 轉發 — 需要 sudo
./deploy/scripts/install-nginx.sh
```

只重裝 app、**保留**資料庫：

```bash
./deploy/scripts/redeploy.sh --yes --keep-data
```

## 日常開發：只重啟 app（推薦）

不動 Mongo/Redis/MinIO、不 wipe、不 migrate——只重編並重開 **gateway + worker + web**：

```bash
make -C deploy restart
# 等同
./deploy/scripts/restart.sh
```

看現在跑了什麼：

```bash
make -C deploy status
```

## 指令一覽

| 腳本 | 說明 |
|------|------|
| `scripts/restart.sh` | **日常**：build + 重開 gateway/worker/web（保留資料） |
| `scripts/redeploy.sh --yes` | 完整重部署（預設刪 volume） |
| `scripts/wipe.sh --yes` | 停 app + 刪 infra volumes |
| `scripts/up-infra.sh` | 起 Mongo/Redis/MinIO/Mailpit |
| `scripts/migrate.sh` | `golang-migrate` up + seed |
| `scripts/build.sh` | 編譯 gateway/worker、確保 web 依賴 |
| `scripts/start.sh` | 背景啟動 gateway + worker + vite |
| `scripts/stop.sh` | 停 gateway + worker + vite |
| `scripts/status.sh` | 埠／pid／健康檢查 |
| `scripts/install-nginx.sh` | 安裝 `deploy/nginx/haixun-dev.conf` |

或用 Makefile：

```bash
make -C deploy restart      # ★ 開發時重開 backend/web/worker
make -C deploy status
make -C deploy stop
make -C deploy env          # 從 example 複製 .env.dev（若不存在）
make -C deploy redeploy     # = redeploy.sh --yes --kill-orphan（清資料）
```

## 環境變數

- 範本：`deploy/.env.example`
- 實檔：`deploy/.env.dev`（**勿 commit**，已在 `.gitignore`）
- 亦可 `ENV_FILE=/path/to/env ./deploy/scripts/start.sh`

重要鍵：

| 鍵 | 用途 |
|----|------|
| `MONGO_URI` / `MONGO_URL` | gateway / migrate（URL 需含 DB 名） |
| `REDIS_PASSWORD` | monc 快取 |
| `HAIXUN_STORAGE_S3_*` | MinIO 上傳與 `PublicBaseURL` |
| `AUTH_*` / `HAIXUN_JWT_*` | JWT |
| `REDIS_NAMESPACE` | Redis 環境隔離前綴 |
| `AI_MODEL_CACHE_FINGERPRINT_SECRET` | AI model cache credential HMAC |
| `MEMBER_SETTINGS_ENCRYPTION_KEY_ID` / `MEMBER_SETTINGS_ENCRYPTION_KEY` | BYOK AES-256-GCM |
| `STRIPE_ENABLED` / `STRIPE_SECRET_KEY` / `STRIPE_WEBHOOK_SECRET` | Stripe subscription billing; disabled is startup-safe |
| `STRIPE_STARTER_PRICE_ID` / `STRIPE_PRO_PRICE_ID` | Trusted recurring Price IDs mapped by the server |
| `STRIPE_SUCCESS_URL` / `STRIPE_CANCEL_URL` / `STRIPE_PORTAL_RETURN_URL` | Trusted Checkout and portal redirects |
| `PUBLIC_WEB_BASE` | 重設信連結、郵件 logo |

## 首次管理員

Migration 不建立預設管理員，也不包含固定帳密。首次部署請設定 runtime secret 後執行：

```bash
make -C apps/backend seeder
```

## 埠與 URL

| 服務 | 位址 |
|------|------|
| Web | http://127.0.0.1:5173 |
| API | http://127.0.0.1:8888/api/v1/ping |
| Mailpit | http://127.0.0.1:8025 |
| MinIO Console | http://127.0.0.1:9001（ROOT user/pass） |
| 公開（CF/nginx） | https://threads-tool-dev.30cm.net |

頭像公開路徑：`{HAIXUN_STORAGE_S3_PUBLIC_BASE_URL}/avatar/{uid}/{uuid}.jpg`  
未裝 nginx 時，Vite 已 proxy `/haixun-assets` → MinIO。

## 日誌與 PID

```text
deploy/run/gateway.log
deploy/run/web.log
deploy/run/gateway.pid
deploy/run/web.pid
```

## 注意

1. **wipe / redeploy 預設刪 Mongo・Redis・MinIO 全部資料**，務必 `--yes`。  
2. docker 權限：使用者需在 `docker` 群組，或用 root。  
3. `migrate` 首次會 `go install -tags mongodb …`。  
4. 舊系統 worker（`old/`）不會自動起；`--kill-orphan` 可清殘留 process。  
5. 正式 prod 映像部署仍可參考 `old/deploy/`；本目錄以 **原生 binary + compose infra** 為主。