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:

# 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

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

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

適用場景

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

打包方式

# 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 模式（雲端資料庫）

{
  "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 模式（本地資料庫）

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

{
  "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

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

MySQL 模式

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

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

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