e7a06e2b8f
Force archive the following proposals: - add-audio-device-selector (complete) - add-embedded-backend-packaging (19/26 tasks) - add-flexible-deployment-options (20/21 tasks) New specs created: - audio-device-management (7 requirements) - embedded-backend (8 requirements) Updated specs: - transcription (+2 requirements for model download progress) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
130 lines
4.0 KiB
Markdown
130 lines
4.0 KiB
Markdown
# Design: Extract Environment Variables
|
||
|
||
## Context
|
||
|
||
專案需要支援以下部署場景：
|
||
1. 開發環境：前後端在本地同時運行
|
||
2. 生產環境：後端部署於 1Panel 伺服器，前端（Electron 應用）獨立打包部署
|
||
|
||
**架構說明**：
|
||
- **後端**：FastAPI 服務，使用兩個 Dify 服務（LLM 摘要 + STT 轉錄）
|
||
- **前端**：Electron 應用，包含 Sidecar（本地 Whisper 即時轉錄服務）
|
||
|
||
目前的硬編碼配置使得部署困難，且敏感資訊（如 API 密鑰、資料庫密碼）散落在代碼中。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
### Goals
|
||
- 將所有硬編碼配置提取到環境變數
|
||
- 提供完整的 `.env.example` 範例檔案
|
||
- 支援前端獨立打包時指定後端 API URL
|
||
- 提供 1Panel 部署完整指南和腳本
|
||
- 確保向後相容（預設值與現有行為一致）
|
||
|
||
### Non-Goals
|
||
- 不實現配置熱重載
|
||
- 不實現密鑰輪換機制
|
||
- 不實現多環境配置管理（如 .env.production, .env.staging）
|
||
|
||
## Decisions
|
||
|
||
### 1. 環境變數命名規範
|
||
|
||
**決定**：使用大寫蛇形命名法，前端變數加 `VITE_` 前綴
|
||
|
||
**原因**：
|
||
- Vite 要求客戶端環境變數必須以 `VITE_` 開頭
|
||
- 大寫蛇形是環境變數的標準慣例
|
||
|
||
### 2. 前端 API URL 配置
|
||
|
||
**決定**：使用 `VITE_API_BASE_URL` 環境變數，在 `api.js` 中讀取
|
||
|
||
```javascript
|
||
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || "http://localhost:8000/api";
|
||
```
|
||
|
||
**替代方案**：
|
||
- 使用 runtime 配置檔案（如 `/config.js`）- 更靈活但增加部署複雜度
|
||
- 使用相對路徑 `/api` - 需要 nginx 反向代理，不適合獨立部署
|
||
|
||
### 3. 超時配置單位
|
||
|
||
**決定**：統一使用毫秒（ms），與 JavaScript 一致
|
||
|
||
**後端配置項**：
|
||
| 變數名 | 預設值 | 用途 |
|
||
|--------|--------|------|
|
||
| UPLOAD_TIMEOUT | 600000 | 大檔案上傳（10分鐘） |
|
||
| DIFY_STT_TIMEOUT | 300000 | Dify STT 轉錄每個分塊（5分鐘） |
|
||
| LLM_TIMEOUT | 120000 | Dify LLM 摘要處理（2分鐘） |
|
||
| AUTH_TIMEOUT | 30000 | 認證 API 調用（30秒） |
|
||
|
||
**前端/Sidecar 配置項**：
|
||
| 變數名 | 預設值 | 用途 |
|
||
|--------|--------|------|
|
||
| WHISPER_MODEL | medium | 本地 Whisper 模型大小 |
|
||
| WHISPER_DEVICE | cpu | 執行裝置（cpu/cuda） |
|
||
| WHISPER_COMPUTE | int8 | 運算精度 |
|
||
|
||
### 4. 1Panel 部署架構
|
||
|
||
**決定**：使用 systemd 管理後端服務，nginx 反向代理
|
||
|
||
```
|
||
[Client] → [Nginx:443] → [Uvicorn:8000]
|
||
↓
|
||
[Static Files]
|
||
```
|
||
|
||
**原因**：
|
||
- systemd 提供進程管理、日誌、自動重啟
|
||
- nginx 處理 HTTPS、靜態檔案、反向代理
|
||
- 這是 1Panel 的標準部署模式
|
||
|
||
### 5. CORS 配置
|
||
|
||
**決定**：保持 `allow_origins=["*"]`，不額外配置
|
||
|
||
**原因**：
|
||
- 前端是 Electron 桌面應用，分發到多台電腦
|
||
- Electron 主進程的 HTTP 請求不受 CORS 限制
|
||
- 簡化部署配置，IT 只需關心 HOST 和 PORT
|
||
|
||
## Risks / Trade-offs
|
||
|
||
### 風險 1：環境變數遺漏
|
||
- **風險**：部署時遺漏必要的環境變數導致服務異常
|
||
- **緩解**：提供完整的 `.env.example`，啟動時檢查必要變數
|
||
|
||
### 風險 2：前端打包後無法修改 API URL
|
||
- **風險**：Vite 環境變數在打包時固定
|
||
- **緩解**：文件中說明需要為不同環境分別打包，或考慮未來實現 runtime 配置
|
||
|
||
### 風險 3：敏感資訊外洩
|
||
- **風險**：`.env` 檔案被提交到版本控制
|
||
- **緩解**：確保 `.gitignore` 包含 `.env`，只提交 `.env.example`
|
||
|
||
## Migration Plan
|
||
|
||
1. **Phase 1 - 後端配置**
|
||
- 更新 `config.py` 添加新配置項
|
||
- 更新各 router 使用配置
|
||
- 更新 `.env` 和 `.env.example`
|
||
|
||
2. **Phase 2 - 前端配置**
|
||
- 創建 `.env` 和 `.env.example`
|
||
- 更新 `api.js` 使用環境變數
|
||
|
||
3. **Phase 3 - 部署文件**
|
||
- 創建 1Panel 部署指南
|
||
- 創建部署腳本
|
||
|
||
4. **Rollback**
|
||
- 所有配置都有預設值，回滾只需刪除環境變數
|
||
|
||
## Open Questions
|
||
|
||
- Q: 是否需要支援 Docker 部署？
|
||
- A: 暫不包含，但環境變數配置天然支援 Docker
|