Skip to content

PRODUCTION.md

Latest commit

 

History

History
344 lines (255 loc) · 6.17 KB

PRODUCTION.md

File metadata and controls

344 lines (255 loc) · 6.17 KB
Raw

FunSpeech 生产环境部署指南

本文档介绍如何在生产环境中部署 FunSpeech API 服务。

📋 目录

🚀 部署方式

方式 1: 直接运行（推荐用于单机部署）

适用场景：

  • 单机部署
  • 需要快速启动
  • 使用 systemd 管理进程

步骤：

  1. 准备环境
# 创建项目目录
sudo mkdir -p /opt/funspeech
sudo chown $USER:$USER /opt/funspeech

# 复制项目文件
cp -r /path/to/FunSpeech/* /opt/funspeech/
cd /opt/funspeech

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖
uv sync  # 或 pip install -r dependencies/requirements.txt
  1. 配置环境变量
# 复制配置模板
cp env.production.example .env.production

# 编辑配置文件
vim .env.production
  1. 启动服务
# 方式 A: 使用启动脚本
./start_production.sh

# 方式 B: 直接使用 start.py
source .venv/bin/activate
python start.py

方式 2: Docker Compose（推荐用于容器化部署）

适用场景：

  • 容器化部署
  • 需要快速扩展
  • 多环境管理

步骤：

  1. 准备 docker-compose.yml
version: "3.8"
services:
  funspeech:
    image: docker.cnb.cool/nexa/funspeech:gpu-latest
    container_name: funspeech
    ports:
      - "8000:8000"
    volumes:
      - ~/.cache/modelscope:/root/.cache/modelscope
      - ./temp:/app/temp
      - ./data:/app/data
      - ./logs:/app/logs
      - ./voices:/app/voices
    environment:
      - DEBUG=false
      - LOG_LEVEL=INFO
      - WORKERS=2
      - INFERENCE_THREAD_POOL_SIZE=4
      - TTS_GPUS=0
      - ASR_GPUS=0
      - APPTOKEN=your_production_token
      - APPKEY=your_production_appkey
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped
  1. 启动服务
docker-compose up -d

方式 3: Systemd 服务（推荐用于 Linux 服务器）

适用场景：

  • Linux 服务器
  • 需要开机自启
  • 需要自动重启

步骤：

  1. 安装服务文件
# 复制服务文件
sudo cp systemd/funspeech.service /etc/systemd/system/

# 编辑服务文件（修改路径和用户）
sudo vim /etc/systemd/system/funspeech.service
  1. 配置环境变量
# 创建环境变量文件
sudo vim /opt/funspeech/.env.production
  1. 启动服务
# 重载 systemd
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start funspeech

# 设置开机自启
sudo systemctl enable funspeech

# 查看状态
sudo systemctl status funspeech

⚙️ 环境配置

必需配置

配置项 说明 示例
DEBUG 生产环境必须设为 false DEBUG=false
LOG_LEVEL 日志级别，建议 INFO 或 WARNING LOG_LEVEL=INFO
WORKERS Worker 进程数，根据资源调整 WORKERS=2

推荐配置

配置项 说明 推荐值
APPTOKEN API 访问令牌，生产环境建议启用 设置强密码
APPKEY 应用密钥，生产环境建议启用 设置强密码
TTS_GPUS TTS GPU 配置 0 或 0,1
ASR_GPUS ASR GPU 配置 0 或 0,1
INFERENCE_THREAD_POOL_SIZE 推理线程池大小 4 或 8

资源配置建议

单 GPU (24GB 显存):

WORKERS=2
INFERENCE_THREAD_POOL_SIZE=4
TTS_GPUS=0
ASR_GPUS=0

双 GPU (24GB × 2):

WORKERS=2
INFERENCE_THREAD_POOL_SIZE=4
TTS_GPUS=0,1
ASR_GPUS=0,1

CPU 模式 (64GB 内存):

WORKERS=4
INFERENCE_THREAD_POOL_SIZE=2
TTS_GPUS=cpu
ASR_GPUS=cpu

🚀 启动方式

使用启动脚本

# 设置环境变量
export WORKERS=2
export INFERENCE_THREAD_POOL_SIZE=4
export TTS_GPUS=0
export ASR_GPUS=0

# 启动服务
./start_production.sh

使用 start.py

source .venv/bin/activate
python start.py

使用 systemd

# 启动
sudo systemctl start funspeech

# 停止
sudo systemctl stop funspeech

# 重启
sudo systemctl restart funspeech

# 查看日志
sudo journalctl -u funspeech -f

📊 进程管理

查看进程状态

# 查看进程
ps aux | grep funspeech

# 查看端口占用
lsof -i :8000

# 查看 GPU 使用
nvidia-smi

优雅停止

# 发送 SIGTERM 信号
pkill -TERM -f "python.*start.py"

# 或使用 systemd
sudo systemctl stop funspeech

🔍 监控和维护

健康检查

# ASR 健康检查
curl http://localhost:8000/stream/v1/asr/health

# TTS 健康检查
curl http://localhost:8000/stream/v1/tts/health

日志查看

# 查看应用日志
tail -f logs/funspeech.log

# 查看 systemd 日志
sudo journalctl -u funspeech -f

# 查看 Docker 日志
docker-compose logs -f

性能监控

# 监控资源使用
htop

# 监控 GPU
watch -n 1 nvidia-smi

# 监控网络
iftop

备份

# 备份数据
tar -czf backup_$(date +%Y%m%d).tar.gz data/ voices/ logs/

# 备份模型缓存
tar -czf modelscope_backup_$(date +%Y%m%d).tar.gz ~/.cache/modelscope

🔒 安全建议

  1. 启用鉴权: 设置 APPTOKEN 和 APPKEY
  2. 使用 HTTPS: 通过 Nginx 反向代理配置 SSL
  3. 防火墙: 限制端口访问
  4. 日志审计: 定期检查日志文件
  5. 定期更新: 保持依赖包和系统更新

📝 常见问题

Q: 如何查看服务是否正常运行？

# 检查健康状态
curl http://localhost:8000/stream/v1/asr/health

# 检查进程
ps aux | grep funspeech

Q: 如何调整 Worker 数量？

修改环境变量 WORKERS，然后重启服务。

Q: 如何查看详细的错误日志？

设置 LOG_LEVEL=DEBUG，但生产环境建议使用 INFO 或 WARNING。

Q: 服务启动失败怎么办？

  1. 检查日志: tail -f logs/funspeech.log
  2. 检查端口占用: lsof -i :8000
  3. 检查 GPU 可用性: nvidia-smi
  4. 检查环境变量: env | grep -E "(WORKERS|GPU|DEBUG)"

更多详细信息请参考 部署文档