Meeting_Assistant/DEPLOYMENT.md

# Meeting Assistant Deployment Guide

## Prerequisites

- Python 3.10+
- Node.js 18+
- MySQL 8.0+
- 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 全部打包成單一執行檔，用戶雙擊即可使用，無需額外設置後端服務。

### 適用場景

- 企業內部部署，簡化用戶操作
- 無法獨立架設後端的環境
- 快速測試和演示

### 打包方式

```batch
# Windows 全包打包
.\scripts\build-client.bat build --embedded-backend --clean
```

### config.json 配置

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

```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": {
      "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
    }
  }
}
```

### 配置說明

| 區段 | 欄位 | 說明 |
|------|------|------|
| `backend.embedded` | `true`/`false` | 啟用/停用內嵌後端模式 |
| `backend.host` | IP | 後端監聽地址（通常為 127.0.0.1） |
| `backend.port` | 數字 | 後端監聽端口（預設 8000） |
| `backend.database.*` | 各欄位 | MySQL 資料庫連線資訊 |
| `backend.externalApis.*` | 各欄位 | 外部 API 設定（認證、Dify） |
| `backend.auth.*` | 各欄位 | 認證設定（管理員信箱、JWT 金鑰） |

### 啟動流程

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

### 向後相容性

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

| 部署方式 | 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

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

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

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