70 lines
4.9 KiB
Markdown
70 lines
4.9 KiB
Markdown
# 心音（Kokorone）
|
||
|
||
以人腦「記憶／情緒／關係」架構為引擎基礎的戀愛陪伴系統。
|
||
|
||
## 開發環境
|
||
|
||
Monorepo 採 pnpm workspace + Turborepo（`pnpm-workspace.yaml` / `turbo.json`）。
|
||
|
||
```bash
|
||
pnpm install # 安裝所有 workspace 套件
|
||
pnpm run build # turbo run build（依相依順序建置 shared/db/api，並建置 web 的 production bundle）
|
||
pnpm run restart # 停止舊的 api／web 行程、重建 TypeScript（tsc -b）、重新啟動並等待健康檢查
|
||
pnpm run smoke A # 執行 A 群組冒煙測試；all 表示依序執行 A~R 全部群組
|
||
```
|
||
|
||
對外指令介面（`restart` / `smoke`）維持與遷移前相同的腳本名稱；唯一差異是
|
||
**pnpm 不會像 npm 一樣吃掉 `--` 分隔符**，`pnpm run smoke -- A` 會把字面上的
|
||
`--` 一起傳給腳本而找不到群組，要執行子指令請直接接在腳本名稱後面
|
||
（`pnpm run smoke A`），不要加 `--`。
|
||
|
||
## 環境變數
|
||
|
||
複製 `.env.example` 為 `.env` 後依需要調整；`apps/web/.env.local` 另外可設定
|
||
`NEXT_PUBLIC_API_URL`（瀏覽器端呼叫 api 用，預設 `http://localhost:3001`）。
|
||
|
||
| 變數 | 預設值 | 說明 |
|
||
| --- | --- | --- |
|
||
| `DATABASE_URL` | `file:./prisma/dev.db` | Prisma 連線字串。R-5 若遷移到 PostgreSQL，改為 `postgresql://user:password@host:5432/db` 並將 `prisma/schema.prisma` 的 `provider` 由 `sqlite` 換成 `postgresql`。 |
|
||
| `PORT` | `3001` | api（NestJS）監聽埠。 |
|
||
| `PORT_API` / `PORT_WEB` | `3001` / `3100` | `pnpm run restart`（`scripts/dev-restart.mjs`）啟動 api／web 時使用的埠號。 |
|
||
| `WEB_ORIGIN` | `http://localhost:3100` | api 的 CORS 允許來源之一；`http://localhost:8081`（Expo web 開發伺服器）已固定加入，不受此變數影響。 |
|
||
| `NEXT_PUBLIC_API_URL` | `http://localhost:3001` | web（Next.js）呼叫 api 的位址，build time 注入，正式環境需在建置時設定。 |
|
||
| `LLM_PROVIDER` | `mock` | `mock`（模板庫，冒煙測試固定用這個）／`claude`（呼叫真實 API，見下）。 |
|
||
| `CLAUDE_BASE_URL` | `http://localhost:3000/api/v1` | OpenAI 相容的 chat completions 端點基底路徑。本專案的部署方式是透過 [CLIProxy](https://gitea.jsc.idv.tw/jiantw83/CLIProxy)（分散式派工代理，本機 3000 埠）轉發到真實 Claude，而非直連 `api.anthropic.com`；若要直連官方 API，把這個值換成 `https://api.anthropic.com/v1` 並確認金鑰／請求格式相容即可，`ClaudeProvider` 的呼叫端程式碼不需要改動。 |
|
||
| `CLAUDE_API_KEY` | （無） | 呼叫 `CLAUDE_BASE_URL` 用的金鑰，`LLM_PROVIDER=claude` 時必填。 |
|
||
| `CLAUDE_MODEL` | `claude-sonnet-4-5` | 要求 Provider 使用的模型名稱；CLIProxy 端需要有對應的 Worker 已註冊、能接這個模型的派工，否則會回報「沒有任何可用的 {模型}-{執行者}-{工具} 組合」。 |
|
||
| `TTS_PROVIDER` | `mock` | `mock`／`real`（P-4 空殼，尚未接上真實供應商，人工確認後才實作）。 |
|
||
| `PUSH_PROVIDER` | `mock` | `mock`／`expo`（Q-3，`expo` 直接可用，不需金鑰）。 |
|
||
|
||
## 部署路徑
|
||
|
||
開發環境：以上服務直接用 `node`／`next dev`／`expo start` 跑在同一台 Linux 主機上
|
||
（`pnpm run restart` 一鍵重啟 api／web），**不使用 Docker**——這是本專案的實際
|
||
部署選擇，取代原先技術選型草案中「Docker Compose（開發）」的規劃。
|
||
|
||
正式環境建議路徑：
|
||
|
||
1. **建置**：`pnpm install --frozen-lockfile && pnpm run build`（turbo 依序建置
|
||
`packages/shared`／`packages/db`／`apps/api`，並產出 `apps/web` 的 production
|
||
bundle）。
|
||
2. **資料庫遷移**：`npx prisma migrate deploy`（依 `DATABASE_URL` 指向的資料庫套用
|
||
遷移；R-5 遷移到 PostgreSQL 後流程相同，只是連線字串換成 postgresql）。
|
||
3. **啟動**：
|
||
- api：`node apps/api/dist/main.js`（讀取上表環境變數）。
|
||
- web：`apps/web` 下 `npx next start -p <PORT_WEB>`（讀取建置時注入的
|
||
`NEXT_PUBLIC_API_URL`）。
|
||
- mobile：`apps/mobile` 透過 `eas build` 產出實際的 App Store／Google Play
|
||
安裝檔，不隨 api／web 一起常駐部署。
|
||
4. **程序常駐與重啟**：用 systemd unit（或 pm2）分別管理 api／web 兩個
|
||
Node 行程，設定 `Restart=on-failure`；健康檢查沿用 `GET /health`
|
||
（api）與首頁 200（web），與 `scripts/dev-restart.mjs` 開發環境用的
|
||
檢查邏輯一致。
|
||
5. **反向代理／TLS**：nginx 或雲端負載平衡器終止 TLS 後轉發到 api／web
|
||
對應埠號，對外只曝露 443。
|
||
|
||
這個路徑刻意不假設 K8s 或容器化，只依賴「Node.js 行程 + systemd + nginx」，
|
||
因為這台開發主機本身就是照這個模式跑（`pnpm run restart` 正是這個模式的
|
||
開發期簡化版），移植到正式主機時只是把「用 node 直接跑」換成「用 systemd
|
||
管理同一組 node 指令」，中間不需要引入額外的容器化工具鏈。
|