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:

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

./scripts/setup-backend.sh start

Windows:

.\scripts\setup-backend.bat start

腳本命令：

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

Manual Setup

1. Setup Environment

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

# 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

# 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

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

Or use the deployment script:

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 上建置免安裝執行檔：

# 完整建置（使用預設 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：

.\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 中的設定：

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

方式一：打包時指定（推薦）

.\scripts\build-client.bat build --api-url "http://your-server:8000/api"

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

方式三：打包後修改（適合測試）

• 執行檔旁邊的 resources/config.json 可在打包後修改

4. Manual Setup (Development)

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

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:

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

3. Build Executable

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:

USE your_database;
SHOW TABLES LIKE 'meeting_%';

Expected tables:

• meeting_users
• meeting_records
• meeting_conclusions
• meeting_action_items

Testing

Backend Tests

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)
• Regular security updates for dependencies