# Coba 部署到 Synology NAS — 完整步驟

> 適用對象:**非工程師看了能跟著做**。
> 預估時間:第一次跑通約 60-90 分鐘(含等套件下載)。

---

## 你需要先準備

| 物品 | 說明 |
|---|---|
| Synology NAS | DSM 7.0+(最近 5 年買的都行) |
| SSH 連線權限 | 在 DSM「控制台 → 終端機 / SNMP」開啟 SSH |
| Anthropic API key | 你已經有 |
| 一個網域 | Cloudflare 託管的真網域(建議 `.com` / `.tw`,免費的不行) |
| Cloudflare 帳號 | 免費版就夠 |

---

## 部署架構(對齊「不裝 Docker」的決定)

```
[網路]
   ↓ HTTPS
[Cloudflare Tunnel]   ← 處理 TLS、防 DDoS
   ↓
[Synology NAS]
   ├─ /usr/local/bin/cloudflared       (systemd)
   ├─ /var/packages/PostgreSQL          (Synology 套件)
   ├─ /volume1/coba/qdrant/qdrant       (systemd)
   └─ /volume1/coba/app                 (FastAPI, systemd)
        └─ .venv/(Python 3.12 + 全部依賴)
        └─ uploads/(會議音訊檔)
        └─ qdrant_data/(向量索引)
        └─ logs/
```

每個元件都跑 systemd service,**砍掉 Docker、跟 NAS 同生命週期**。

---

## 步驟一:本機準備(Windows 端)

```powershell
# 把整個 coba-backend 打包(排除 venv 跟 db)
cd C:\Users\user\Desktop\Coba
tar -czf coba-backend.tar.gz `
    --exclude=coba-backend/.venv `
    --exclude=coba-backend/qdrant_data `
    --exclude=coba-backend/coba.db `
    --exclude=coba-backend/__pycache__ `
    --exclude=coba-backend/uploads `
    --exclude=coba-backend/.pytest_cache `
    --exclude=coba-backend/tools/web_scraper/profile `
    --exclude=coba-backend/tools/web_scraper/out `
    coba-backend
```

或用 git(若有):
```powershell
cd C:\Users\user\Desktop\Coba\coba-backend
git init && git add . && git commit -m "deploy"
# 推到自己的 GitHub private repo 或直接上傳
```

---

## 步驟二:把檔案放上 NAS

```bash
# 從 Windows scp 上去(假設 NAS IP=192.168.1.2,SSH 帳號=admin)
scp coba-backend.tar.gz admin@192.168.1.2:/volume1/coba/
ssh admin@192.168.1.2

# NAS 上
sudo -i
cd /volume1/coba
tar -xzf coba-backend.tar.gz
mv coba-backend app
```

---

## 步驟三:在 Synology 套件中心裝 PostgreSQL + Python 3.12

1. DSM 登入 → 套件中心 → 搜「PostgreSQL」→ 安裝
2. 套件中心 → 搜「Python 3.12」→ 安裝(若沒有就裝最新 Python 3.x)
3. 開啟 PostgreSQL → 進去後建一個資料庫:
   - 資料庫名:`coba`
   - 使用者名:`coba`
   - 密碼:**自己想一個強密碼**,等下要填到 .env

---

## 步驟四:跑三支腳本(都在 NAS,SSH 進去後 sudo -i)

```bash
cd /volume1/coba/app/deploy
chmod +x *.sh

# 1. 裝 Qdrant 並設 systemd
bash 01_install_services.sh

# 2. 編輯 .env(用 vi / nano)
nano /volume1/coba/app/.env
# 至少改:POSTGRES_PASSWORD / DATABASE_URL / JWT_SECRET_KEY / ANTHROPIC_API_KEY
# 範例 DATABASE_URL:
#   postgresql+asyncpg://coba:你的密碼@127.0.0.1:5432/coba

# 3. 部署 FastAPI(會跑 alembic + 註冊 systemd)
bash 02_deploy_app.sh

# 4. 設 Cloudflare Tunnel(讓外網能連)
COBA_DOMAIN=coba.yourdomain.com bash 03_cloudflare_tunnel.sh
```

---

## 驗證部署成功

```bash
# 在 NAS 上
systemctl status qdrant      # 綠燈 active (running)
systemctl status coba         # 綠燈 active (running)
systemctl status cloudflared  # 綠燈 active (running)

curl http://127.0.0.1:8000/health
# {"status":"ok","service":"coba-api","environment":"production"}

# 從外部
curl https://coba.yourdomain.com/health
# 同樣 200 OK
```

開瀏覽器:`https://coba.yourdomain.com/` → 看到 Coba 登入頁。

**手機**:Safari 開 → 分享 → 加到主畫面 → 圖示出現在桌面。

---

## 日常維護

### 看 log
```bash
tail -f /volume1/coba/logs/coba.log         # FastAPI
tail -f /volume1/coba/logs/qdrant.log       # Qdrant
journalctl -u cloudflared -f                # Cloudflare Tunnel
```

### 更新程式碼
```bash
ssh admin@192.168.1.2
sudo -i
cd /volume1/coba/app
git pull   # 若用 git;不然就 scp 上去覆蓋
.venv/bin/pip install -r requirements.txt   # 有新套件才需要
.venv/bin/alembic upgrade head              # 有 schema 變更才需要
systemctl restart coba                      # 重啟服務
```

### 重啟某個服務
```bash
systemctl restart coba
systemctl restart qdrant
systemctl restart cloudflared
```

### 完整關機 / 重啟整套
```bash
systemctl stop coba qdrant cloudflared
systemctl start qdrant coba cloudflared
```

---

## 故障排查

### Q: `systemctl status coba` 顯示 failed
看 log:`journalctl -u coba -n 100`

最常見:
- `.env` 裡 `DATABASE_URL` 不對 → PostgreSQL 連不上
- `JWT_SECRET_KEY` 還是預設值 → uvicorn 啟動會擋下

### Q: `https://coba.yourdomain.com/` 連不上
1. NAS 內部能不能連:`curl http://127.0.0.1:8000/health`
2. Cloudflared 跑沒跑:`systemctl status cloudflared`
3. Cloudflare DNS 設定:在 Cloudflare 後台看 DNS 記錄,應該有一筆 `coba` CNAME 指到 `<tunnel-id>.cfargotunnel.com`

### Q: 庫柏會議轉文字超慢 / 失敗
- 看 NAS CPU 規格。低階 NAS(Celeron J4125 等)Whisper small 跑 1 小時音訊要 2-3 小時
- 改用更小模型:編輯 `app/services/meeting_processor.py` 的 `WHISPER_MODEL_SIZE = "tiny"`
- 或:不在 NAS 跑 Whisper,改打 OpenAI Whisper API(每分鐘 $0.006)

### Q: 想完全砍掉重來
```bash
systemctl stop coba qdrant cloudflared
systemctl disable coba qdrant cloudflared
rm /etc/systemd/system/{coba,qdrant,cloudflared}.service
rm -rf /volume1/coba
```

(PostgreSQL 資料庫要在 DSM Web 介面手動刪)

---

## 之後想擴充

| 功能 | 改什麼 |
|---|---|
| 語音轉文字超慢 | Whisper 換 OpenAI API,改 `meeting_processor.py` |
| 多人同時用 WebSocket 卡 | 把 ws_manager 換成 Redis Pub/Sub(改一個檔) |
| 想要 iOS 原生 App | 找一台 Mac + Xcode,SwiftUI 串現有 API |
| 想加 SSL 自簽 | 跳過,Cloudflare 已處理 |
| 想跑多 NAS / HA | 那就要回 Docker + Kubernetes,本架構不適用 |