141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
# 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** 為主。
|