Meeting_Assistant/DEPLOYMENT.md

# Meeting Assistant Deployment Guide

## Prerequisites

- Python 3.10+
- Node.js 18+
- MySQL 8.0+ 或 SQLite（本地模式）
- Access to Dify LLM service

## Quick Start

Use the startup script to run all services locally:

```bash
# Check environment
./start.sh check

# Start all services
./start.sh start

# Stop all services
./start.sh stop

# View status
./start.sh status
```

## Backend Deployment

### Quick Start (One-Click Setup)

使用一鍵設置腳本自動安裝依賴並啟動服務：

**Linux/macOS/WSL:**
```bash
./scripts/setup-backend.sh start
```

**Windows:**
```batch
.\scripts\setup-backend.bat start
```

**腳本命令：**
| 命令 | 說明 |
|------|------|
| `setup` | 僅設置環境（安裝依賴） |
| `start` | 設置並啟動後端服務（預設） |
| `stop` | 停止後端服務 |
| `--port PORT` | 指定服務端口（預設: 8000） |
| `--no-sidecar` | 不安裝 Sidecar 依賴 |

### Manual Setup

### 1. Setup Environment

```bash
cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt
```

### 2. Configure Environment Variables

```bash
# Copy example and edit
cp .env.example .env
```

**Required Environment Variables:**

| Variable | Description |
|----------|-------------|
| `BACKEND_HOST` | Server bind address (default: 0.0.0.0) |
| `BACKEND_PORT` | Server port (default: 8000) |
| `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASS`, `DB_NAME` | MySQL connection |
| `AUTH_API_URL` | Company authentication API |
| `DIFY_API_URL`, `DIFY_API_KEY`, `DIFY_STT_API_KEY` | Dify API settings |
| `ADMIN_EMAIL` | Admin user email |
| `JWT_SECRET` | JWT signing secret (generate secure random string) |

**Optional Environment Variables:**

| Variable | Description | Default |
|----------|-------------|---------|
| `DB_POOL_SIZE` | Database connection pool size | 5 |
| `JWT_EXPIRE_HOURS` | JWT token expiration | 24 |
| `UPLOAD_TIMEOUT` | File upload timeout (ms) | 600000 |
| `DIFY_STT_TIMEOUT` | STT processing timeout (ms) | 300000 |
| `LLM_TIMEOUT` | LLM request timeout (ms) | 120000 |
| `MAX_FILE_SIZE` | Max upload size (bytes) | 524288000 |

See `backend/.env.example` for complete documentation.

### 3. Run Server

```bash
# Development
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Production
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
```

### 4. Verify Deployment

```bash
curl http://localhost:8000/api/health
# Should return: {"status":"healthy","service":"meeting-assistant"}
```

### 5. Production Deployment (1Panel)

For detailed server deployment instructions including Nginx, systemd, and SSL configuration, see:

📖 **[docs/1panel-deployment.md](docs/1panel-deployment.md)**

Or use the deployment script:

```bash
sudo ./scripts/deploy-backend.sh install --port 8000
```

## Electron Client Deployment

### 1. Prerequisites

- **Windows**: Node.js 18+, Python 3.10+ (for building Sidecar)
- **Disk Space**: 5GB+ recommended (Whisper model + build artifacts)

### 2. Quick Build (Windows)

使用一鍵打包腳本在 Windows 上建置免安裝執行檔：

```batch
# 完整建置（使用預設 localhost）
.\scripts\build-client.bat build --clean

# 指定後端 API URL
.\scripts\build-client.bat build --api-url "http://192.168.1.100:8000/api" --clean

# 使用公司伺服器
.\scripts\build-client.bat build --api-url "https://api.company.com/api"

# 僅打包 Electron（已打包過 Sidecar）
.\scripts\build-client.bat build --skip-sidecar --api-url "http://your-server:8000/api"
```

或使用 PowerShell：

```powershell
.\scripts\build-all.ps1 -ApiUrl "http://192.168.1.100:8000/api" -Clean
```

**打包腳本參數：**

| 參數 | 說明 |
|------|------|
| `--api-url URL` | 後端 API URL（會寫入 config.json） |
| `--skip-sidecar` | 跳過 Sidecar 打包（已打包過時使用） |
| `--clean` | 建置前清理所有暫存檔案 |

### 3. Runtime Configuration

打包後的 exe 會讀取 `config.json` 中的設定：

```json
{
  "apiBaseUrl": "http://localhost:8000/api",
  "uploadTimeout": 600000,
  "appTitle": "Meeting Assistant",
  "whisper": {
    "model": "medium",
    "device": "cpu",
    "compute": "int8"
  }
}
```

**方式一**：打包時指定（推薦）
```batch
.\scripts\build-client.bat build --api-url "http://your-server:8000/api"
```

**方式二**：打包前手動編輯 `client/config.json`

**方式三**：打包後修改（適合測試）
- 執行檔旁邊的 `resources/config.json` 可在打包後修改

### 4. Manual Setup (Development)

```bash
cd client

# Install dependencies
npm install

# Start in development mode
npm start
```

### 5. Build Output

建置完成後，輸出檔案位於：
- `client/dist/` - Electron 打包輸出
- `build/` - 最終整合輸出（含 exe）

**輸出檔案：**
- `Meeting Assistant-1.0.0-portable.exe` - 免安裝執行檔

### 6. GitHub Actions (CI/CD)

也可以使用 GitHub Actions 自動建置：

1. 前往 GitHub Repository → Actions
2. 選擇 "Build Windows Client"
3. 點擊 "Run workflow"
4. 輸入 `api_url` 參數（例如 `http://192.168.1.100:8000/api`）
5. 等待建置完成後下載 artifact

## All-in-One Deployment (全包部署模式)

此模式將前端、後端、Whisper 全部打包成單一執行檔，用戶雙擊即可使用，無需額外設置後端服務。

### 適用場景

- 企業內部部署，簡化用戶操作
- 無法獨立架設後端的環境
- 快速測試和演示
- **離線環境**：使用 SQLite 本地資料庫，無需網路連接資料庫

### 打包方式

```batch
# Windows 全包打包（NSIS 安裝檔，推薦）
.\scripts\build-client.bat build --embedded-backend --clean

# Windows 全包打包（SQLite 本地資料庫，適合離線/防火牆環境）
.\scripts\build-client.bat build --embedded-backend --database-type sqlite --clean

# Windows 全包打包（Portable 免安裝，注意臨時資料夾限制）
.\scripts\build-client.bat build --embedded-backend --target portable --clean
```

**打包參數說明：**

| 參數 | 說明 |
|------|------|
| `--embedded-backend` | 啟用內嵌後端模式 |
| `--database-type TYPE` | 資料庫類型：`mysql`（雲端）或 `sqlite`（本地） |
| `--target TARGET` | 打包目標：`nsis`（安裝檔，預設）或 `portable`（免安裝） |
| `--clean` | 建置前清理所有暫存檔案 |

### 打包目標比較

| 特性 | NSIS 安裝檔（推薦） | Portable 免安裝 |
|------|---------------------|-----------------|
| 安裝方式 | 執行安裝精靈 | 直接執行 |
| 資料持久性 | ✅ 安裝目錄內持久保存 | ⚠️ 臨時資料夾關閉後清空 |
| SQLite 位置 | 安裝目錄/data/ | %APPDATA%\Meeting-Assistant |
| 適用場景 | 正式部署 | 快速測試、展示 |

### config.json 配置

全包模式需要在 `config.json` 中配置資料庫和 API 金鑰：

#### MySQL 模式（雲端資料庫）

```json
{
  "apiBaseUrl": "http://localhost:8000/api",
  "uploadTimeout": 600000,
  "appTitle": "Meeting Assistant",
  "whisper": {
    "model": "medium",
    "device": "cpu",
    "compute": "int8"
  },
  "backend": {
    "embedded": true,
    "host": "127.0.0.1",
    "port": 8000,
    "database": {
      "type": "mysql",
      "sqlitePath": "data/meeting.db",
      "host": "mysql.theaken.com",
      "port": 33306,
      "user": "your_username",
      "password": "your_password",
      "database": "your_database"
    },
    "externalApis": {
      "authApiUrl": "https://pj-auth-api.vercel.app/api/auth/login",
      "difyApiUrl": "https://dify.theaken.com/v1",
      "difyApiKey": "app-xxxxxxxxxx",
      "difySttApiKey": "app-xxxxxxxxxx"
    },
    "auth": {
      "adminEmail": "admin@example.com",
      "jwtSecret": "your_secure_jwt_secret",
      "jwtExpireHours": 24
    }
  }
}
```

#### SQLite 模式（本地資料庫）

適合離線環境或網路防火牆阻擋資料庫連線的情況：

```json
{
  "apiBaseUrl": "http://localhost:8000/api",
  "uploadTimeout": 600000,
  "appTitle": "Meeting Assistant",
  "whisper": {
    "model": "medium",
    "device": "cpu",
    "compute": "int8"
  },
  "backend": {
    "embedded": true,
    "host": "127.0.0.1",
    "port": 8000,
    "database": {
      "type": "sqlite",
      "sqlitePath": "data/meeting.db"
    },
    "externalApis": {
      "authApiUrl": "https://pj-auth-api.vercel.app/api/auth/login",
      "difyApiUrl": "https://dify.theaken.com/v1",
      "difyApiKey": "app-xxxxxxxxxx",
      "difySttApiKey": "app-xxxxxxxxxx"
    },
    "auth": {
      "adminEmail": "admin@example.com",
      "jwtSecret": "your_secure_jwt_secret",
      "jwtExpireHours": 24
    }
  }
}
```

> **注意**：SQLite 資料庫位置會根據打包目標不同：
> - **NSIS 安裝檔**：安裝目錄內的 `data/meeting.db`
> - **Portable**：`%APPDATA%\Meeting-Assistant\data\meeting.db`（持久保存，不會因關閉程式而清空）

### 配置說明

| 區段 | 欄位 | 說明 |
|------|------|------|
| `backend.embedded` | `true`/`false` | 啟用/停用內嵌後端模式 |
| `backend.host` | IP | 後端監聽地址（通常為 127.0.0.1） |
| `backend.port` | 數字 | 後端監聽端口（預設 8000） |
| `backend.database.type` | `mysql`/`sqlite` | 資料庫類型（預設 mysql） |
| `backend.database.sqlitePath` | 路徑 | SQLite 資料庫檔案路徑（相對或絕對） |
| `backend.database.*` | 各欄位 | MySQL 資料庫連線資訊（僅 MySQL 模式需要） |
| `backend.externalApis.*` | 各欄位 | 外部 API 設定（認證、Dify） |
| `backend.auth.*` | 各欄位 | 認證設定（管理員信箱、JWT 金鑰） |

### 資料庫模式比較

| 特性 | MySQL 模式 | SQLite 模式 |
|------|------------|-------------|
| 網路需求 | 需連接遠端資料庫 | 完全離線運作 |
| 資料位置 | 雲端資料庫伺服器 | 本機檔案 |
| 多用戶共享 | ✅ 支援 | ❌ 僅單機使用 |
| 適用場景 | 企業部署、多人共用 | 離線環境、防火牆限制 |
| 資料備份 | 使用資料庫工具 | 複製 `.db` 檔案即可 |

### Portable 執行檔說明

Portable exe 執行時會解壓縮到 `%TEMP%\Meeting-Assistant` 資料夾（固定路徑，非隨機資料夾）。

- **優點**：Windows Defender 不會每次都提示警告
- **注意**：關閉程式後，臨時資料夾會被清空
- **SQLite 資料庫位置**：自動儲存到 `%APPDATA%\Meeting-Assistant\data\meeting.db`（不會被清空）
- **建議**：正式部署請使用 NSIS 安裝檔（`--target nsis`，預設）

### 啟動流程

1. 用戶雙擊 exe
2. 解壓縮到 `%TEMP%\Meeting-Assistant`
3. Electron 主程序啟動
4. 讀取 `config.json`
5. 啟動內嵌後端 (FastAPI)
6. 健康檢查等待後端就緒（最多 30 秒）
7. 後端就緒後，載入前端頁面
8. 啟動 Whisper Sidecar
9. 應用就緒

### 向後相容性

此功能完全向後相容，不影響既有部署方式：

| 部署方式 | config.json 設定 | 說明 |
|---------|------------------|------|
| 分離部署（預設） | `backend.embedded: false` | 前端連接遠端後端，使用 `apiBaseUrl` |
| 全包部署（新增） | `backend.embedded: true` | 前端內嵌後端，雙擊即可使用 |

### 安全注意事項

⚠️ **重要**：全包模式的 `config.json` 包含敏感資訊（資料庫密碼、API 金鑰），請確保：

1. 不要將含有真實憑證的 config.json 提交到版本控制
2. 部署時由 IT 管理員配置敏感資訊
3. 考慮使用環境變數覆蓋敏感設定（環境變數優先級較高）

### Whisper 模型下載進度

首次運行時，Whisper 模型（約 1.5GB）會自動下載。新版本會顯示下載進度：

- `⬇️ Downloading medium: 45% (675/1530 MB)` - 下載中
- `⏳ Loading medium...` - 載入模型中
- `✅ Ready` - 就緒

## Transcription Sidecar

### 1. Setup

```bash
cd sidecar

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install pyinstaller
```

### 2. Download Whisper Model

The model will be downloaded automatically on first run. For faster startup, pre-download:

```python
from faster_whisper import WhisperModel
model = WhisperModel("medium", device="cpu", compute_type="int8")
```

### 3. Build Executable

```bash
python build.py
```

The executable will be in `sidecar/dist/transcriber`.

### 4. Package with Electron

Copy `sidecar/dist/` to `client/sidecar/` before building Electron app.

## Database Setup

### MySQL 模式

The backend will automatically create tables on first startup. To manually verify:

```sql
USE your_database;
SHOW TABLES LIKE 'meeting_%';
```

### SQLite 模式

SQLite 資料庫檔案會在首次啟動時自動建立：

- **開發環境**：`backend/data/meeting.db`
- **NSIS 安裝檔**：安裝目錄內的 `data/meeting.db`
- **Portable**：`%APPDATA%\Meeting-Assistant\data\meeting.db`

**備份方式**：直接複製 `.db` 檔案即可。

> **注意**：Portable 模式下，SQLite 資料庫自動儲存到 `%APPDATA%` 以確保持久性（不會因關閉程式而清空）。

### Expected tables

- `meeting_users`
- `meeting_records`
- `meeting_conclusions`
- `meeting_action_items`

## Testing

### Backend Tests

```bash
cd backend
pytest tests/ -v
```

### Performance Verification

On target hardware (i5/8GB):
1. Start the Electron app
2. Record 1 minute of audio
3. Verify transcription completes within acceptable time
4. Test AI summarization with the transcript

## Troubleshooting

### Database Connection Issues

1. Verify MySQL is accessible from server
2. Check firewall rules for database port
3. Verify credentials in .env

### Dify API Issues

1. Verify API key is valid
2. Check Dify service status
3. Review timeout settings for long transcripts (adjust `DIFY_STT_TIMEOUT`, `LLM_TIMEOUT`)

### Transcription Issues

1. Verify microphone permissions
2. Check sidecar executable runs standalone
3. Review audio format (16kHz, 16-bit, mono)
4. Try different `WHISPER_MODEL` sizes (tiny, base, small, medium)

## Security Notes

- Never commit `.env` files to version control
- Keep JWT_SECRET secure and unique per deployment
- Ensure HTTPS in production (see [1panel-deployment.md](docs/1panel-deployment.md))
- Regular security updates for dependencies