Meeting_Assistant/openspec/changes/archive/2025-12-14-extract-environment-variables/design.md

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 中讀取

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