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

## 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