Fun-ASR容器化部署：Docker Compose配置示例

1. 引言

如果你正在寻找一个开箱即用的语音识别解决方案，Fun-ASR WebUI绝对值得一试。这个由科哥构建的语音识别系统，基于钉钉与通义联合推出的语音识别大模型，提供了一个直观的Web界面，让语音转文字变得像点外卖一样简单。

但直接部署一个完整的Web应用，涉及到环境配置、依赖安装、端口映射等一系列繁琐操作，对于不熟悉Python环境或系统配置的用户来说，门槛不低。有没有一种方法，能让整个过程变得像安装手机App一样简单？

这就是Docker Compose的价值所在。今天，我就来分享一个完整的Fun-ASR Docker Compose配置方案，让你在10分钟内完成部署，无需关心底层环境，直接享受语音识别的便利。

2. 为什么选择Docker Compose部署？

2.1 传统部署的痛点

在介绍具体配置之前，我们先看看传统部署方式会遇到哪些问题：

1. 环境依赖复杂：需要安装Python、PyTorch、CUDA等一系列依赖，版本兼容性问题频发
2. 配置繁琐：端口设置、模型下载、路径配置，每一步都可能出错
3. 隔离性差：多个应用可能产生依赖冲突，影响系统稳定性
4. 迁移困难：换台机器就要重新配置一遍，费时费力

2.2 Docker Compose的优势

相比之下，Docker Compose方案的优势很明显：

• 一键部署：一个命令启动所有服务
• 环境隔离：每个应用在独立的容器中运行，互不干扰
• 配置即代码：所有配置写在YAML文件中，版本可控，易于分享
• 快速迁移：在任何支持Docker的机器上都能快速部署
• 资源可控：可以精确控制CPU、内存、GPU资源的使用

3. 完整的Docker Compose配置

下面是我在实际项目中使用的完整配置，经过多次测试和优化，可以直接复制使用。

3.1 项目结构

首先，创建一个项目目录，结构如下：

fun-asr-docker/
├── docker-compose.yml    # Docker Compose配置文件
├── .env                  # 环境变量配置文件
├── models/               # 模型文件目录（挂载用）
├── data/                 # 数据目录（挂载用）
└── logs/                 # 日志目录（挂载用）

3.2 docker-compose.yml 配置文件

这是核心配置文件，定义了Fun-ASR WebUI服务的所有设置：

version: '3.8'

services:
  fun-asr-webui:
    image: registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:funasr-v1.0.0
    container_name: fun-asr-webui
    restart: unless-stopped
    
    # 端口映射：将容器内的7860端口映射到主机的7860端口
    ports:
      - "7860:7860"
    
    # 环境变量配置
    environment:
      - GRADIO_SERVER_NAME=0.0.0.0
      - GRADIO_SERVER_PORT=7860
      - MODEL_CACHE_DIR=/app/models
      - DATA_DIR=/app/data
      - LOG_DIR=/app/logs
      - CUDA_VISIBLE_DEVICES=${CUDA_DEVICE:-0}
    
    # 卷挂载：将本地目录挂载到容器内
    volumes:
      - ./models:/app/models
      - ./data:/app/data
      - ./logs:/app/logs
    
    # 资源限制
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    
    # 健康检查
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7860"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    
    # 网络配置
    networks:
      - funasr-network

# 自定义网络
networks:
  funasr-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

3.3 .env 环境变量文件

创建.env文件，用于配置环境变量：

# Docker Compose环境变量配置

# 项目名称（用于容器命名前缀）
COMPOSE_PROJECT_NAME=funasr

# GPU设备设置（0表示第一个GPU，空表示不使用GPU）
CUDA_DEVICE=0

# 时区设置
TZ=Asia/Shanghai

# 内存限制（单位：MB）
MEMORY_LIMIT=4096

# CPU限制（0.5表示半个CPU核心）
CPU_LIMIT=2.0

# 模型下载设置
MODEL_REPO=damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch
MODEL_REVISION=v2.0.4

3.4 启动脚本

为了方便使用，可以创建一个启动脚本start.sh：

#!/bin/bash

# Fun-ASR Docker Compose 启动脚本

set -e

echo "========================================"
echo "Fun-ASR WebUI Docker Compose 部署脚本"
echo "========================================"

# 检查Docker是否安装
if ! command -v docker &> /dev/null; then
    echo "❌ Docker未安装，请先安装Docker"
    exit 1
fi

# 检查Docker Compose是否安装
if ! command -v docker-compose &> /dev/null; then
    echo "❌ Docker Compose未安装，请先安装Docker Compose"
    exit 1
fi

# 检查NVIDIA Docker运行时（如果使用GPU）
if [ "$1" = "--gpu" ]; then
    if ! docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi &> /dev/null; then
        echo "⚠️  NVIDIA Docker运行时未正确配置，将使用CPU模式"
        export CUDA_DEVICE=""
    else
        echo "✅ NVIDIA Docker运行时已就绪"
    fi
fi

# 创建必要的目录
echo "📁 创建目录结构..."
mkdir -p models data logs

# 设置目录权限
echo "🔧 设置目录权限..."
chmod -R 755 models data logs

# 启动服务
echo "🚀 启动Fun-ASR WebUI服务..."
docker-compose up -d

# 等待服务启动
echo "⏳ 等待服务启动（约30秒）..."
sleep 30

# 检查服务状态
if docker-compose ps | grep -q "Up"; then
    echo "✅ Fun-ASR WebUI 启动成功！"
    echo ""
    echo "📋 访问信息："
    echo "  本地访问：http://localhost:7860"
    echo "  远程访问：http://$(hostname -I | awk '{print $1}'):7860"
    echo ""
    echo "🔧 管理命令："
    echo "  查看日志：docker-compose logs -f"
    echo "  停止服务：docker-compose down"
    echo "  重启服务：docker-compose restart"
    echo "  更新镜像：docker-compose pull && docker-compose up -d"
else
    echo "❌ 服务启动失败，请检查日志："
    docker-compose logs
    exit 1
fi

给脚本添加执行权限：

chmod +x start.sh

4. 部署步骤详解

4.1 准备工作

在开始部署前，确保你的系统满足以下要求：

1. 操作系统：Linux（Ubuntu/CentOS）、macOS、Windows（WSL2）
2. Docker：版本20.10.0或更高
3. Docker Compose：版本2.0.0或更高
4. GPU支持（可选）：NVIDIA GPU + NVIDIA Docker运行时
5. 磁盘空间：至少10GB可用空间
6. 内存：建议8GB或更多

4.2 安装Docker和Docker Compose

如果你还没有安装Docker，可以按照以下步骤安装：

Ubuntu/Debian系统：

# 卸载旧版本
sudo apt-get remove docker docker-engine docker.io containerd runc

# 安装依赖
sudo apt-get update
sudo apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加Docker仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 验证安装
docker --version
docker-compose --version

CentOS/RHEL系统：

# 卸载旧版本
sudo yum remove docker \
    docker-client \
    docker-client-latest \
    docker-common \
    docker-latest \
    docker-latest-logrotate \
    docker-logrotate \
    docker-engine

# 安装依赖
sudo yum install -y yum-utils

# 添加Docker仓库
sudo yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo

# 安装Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io

# 启动Docker
sudo systemctl start docker
sudo systemctl enable docker

# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

4.3 配置NVIDIA Docker运行时（GPU用户）

如果你有NVIDIA GPU并希望使用GPU加速，需要安装NVIDIA Docker运行时：

# 添加NVIDIA容器工具包仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# 安装NVIDIA Docker运行时
sudo apt-get update
sudo apt-get install -y nvidia-docker2

# 重启Docker
sudo systemctl restart docker

# 验证安装
docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

4.4 部署Fun-ASR WebUI

一切准备就绪后，开始部署：

# 1. 克隆或创建项目目录
mkdir fun-asr-docker && cd fun-asr-docker

# 2. 创建配置文件（将前面的docker-compose.yml和.env内容复制过来）
# 创建docker-compose.yml
cat > docker-compose.yml << 'EOF'
# 这里粘贴前面的docker-compose.yml内容
EOF

# 创建.env文件
cat > .env << 'EOF'
# 这里粘贴前面的.env内容
EOF

# 3. 创建启动脚本
cat > start.sh << 'EOF'
#!/bin/bash
# 这里粘贴前面的start.sh内容
EOF

chmod +x start.sh

# 4. 启动服务（使用GPU）
./start.sh --gpu

# 或者使用CPU模式
# ./start.sh

4.5 验证部署

服务启动后，可以通过以下方式验证：

1. 检查容器状态：

docker-compose ps

应该看到fun-asr-webui容器的状态为Up。

2. 查看日志：

docker-compose logs -f

观察日志中是否有错误信息。

3. 访问Web界面： 打开浏览器，访问http://localhost:7860，应该能看到Fun-ASR WebUI的界面。

4. 健康检查：

curl http://localhost:7860

应该返回正常的HTML响应。

5. 高级配置与优化

5.1 自定义模型配置

如果你想使用其他模型，可以修改环境变量：

# 在docker-compose.yml的environment部分添加
environment:
  - MODEL_REPO=damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch
  - MODEL_REVISION=v2.0.4
  - VAD_MODEL=fsmn-vad
  - PUNC_MODEL=ct-punc

5.2 资源限制配置

根据你的服务器配置，调整资源限制：

# 在docker-compose.yml中添加
deploy:
  resources:
    limits:
      cpus: '2.0'      # 限制使用2个CPU核心
      memory: 4G       # 限制使用4GB内存
    reservations:
      devices:
        - driver: nvidia
          count: 1      # 使用1个GPU
          capabilities: [gpu]
          device_ids: ['0']  # 指定使用第一个GPU

5.3 网络配置优化

如果你的服务器有多个网络接口，可以指定绑定的IP：

ports:
  - "192.168.1.100:7860:7860"  # 绑定到特定IP

或者使用自定义网络配置：

networks:
  funasr-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/24
          gateway: 172.20.0.1

5.4 数据持久化配置

确保数据不会丢失，配置数据卷：

volumes:
  # 使用命名卷（推荐用于生产环境）
  funasr-models:
    driver: local
  funasr-data:
    driver: local
  funasr-logs:
    driver: local

services:
  fun-asr-webui:
    volumes:
      - funasr-models:/app/models
      - funasr-data:/app/data
      - funasr-logs:/app/logs

5.5 备份与恢复脚本

创建备份脚本backup.sh：

#!/bin/bash

# 备份Fun-ASR数据
BACKUP_DIR="./backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/funasr_backup_${TIMESTAMP}.tar.gz"

echo "开始备份Fun-ASR数据..."

# 创建备份目录
mkdir -p ${BACKUP_DIR}

# 备份数据
docker-compose exec -T fun-asr-webui tar czf - /app/data /app/models /app/logs > ${BACKUP_FILE}

# 检查备份是否成功
if [ $? -eq 0 ]; then
    echo "✅ 备份成功：${BACKUP_FILE}"
    echo "备份大小：$(du -h ${BACKUP_FILE} | cut -f1)"
else
    echo "❌ 备份失败"
    exit 1
fi

创建恢复脚本restore.sh：

#!/bin/bash

# 恢复Fun-ASR数据
if [ -z "$1" ]; then
    echo "使用方法：$0 <备份文件>"
    exit 1
fi

BACKUP_FILE=$1

if [ ! -f "${BACKUP_FILE}" ]; then
    echo "错误：备份文件不存在"
    exit 1
fi

echo "开始恢复Fun-ASR数据..."
echo "使用备份文件：${BACKUP_FILE}"

# 停止服务
docker-compose down

# 恢复数据
cat ${BACKUP_FILE} | docker-compose run --rm -T fun-asr-webui tar xzf - -C /

# 启动服务
docker-compose up -d

echo "✅ 恢复完成"

6. 常见问题与解决方案

6.1 端口冲突问题

如果7860端口已被占用，可以修改端口映射：

ports:
  - "8888:7860"  # 将主机的8888端口映射到容器的7860端口

6.2 GPU无法使用

检查步骤：

# 1. 检查NVIDIA驱动
nvidia-smi

# 2. 检查NVIDIA Docker运行时
docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

# 3. 检查容器内的GPU
docker-compose exec fun-asr-webui nvidia-smi

6.3 内存不足问题

如果遇到内存不足，可以：

1. 增加交换空间：

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

2. 调整Docker内存限制： 编辑/etc/docker/daemon.json：

{
  "default-ulimits": {
    "memlock": {
      "Hard": -1,
      "Soft": -1
    }
  }
}

6.4 模型下载失败

如果模型下载失败，可以手动下载：

# 进入容器
docker-compose exec fun-asr-webui bash

# 手动下载模型
python -c "
from modelscope import snapshot_download
model_dir = snapshot_download('damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch')
print(f'模型下载到：{model_dir}')
"

6.5 服务无法启动

查看详细日志：

# 查看完整日志
docker-compose logs --tail=100

# 实时查看日志
docker-compose logs -f

# 进入容器调试
docker-compose exec fun-asr-webui bash

7. 生产环境部署建议

7.1 安全性配置

1. 使用HTTPS：

# 添加反向代理配置（使用Nginx）
version: '3.8'

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - fun-asr-webui

  fun-asr-webui:
    # ... 原有配置
    expose:
      - "7860"

2. 设置访问控制： 在Fun-ASR WebUI前添加身份验证层。

7.2 监控与日志

1. 配置日志轮转：

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

2. 添加监控： 使用Prometheus + Grafana监控容器资源使用情况。

7.3 高可用配置

1. 多副本部署：

deploy:
  replicas: 2
  restart_policy:
    condition: on-failure
    delay: 5s
    max_attempts: 3
    window: 120s

2. 负载均衡： 使用Nginx或Traefik作为负载均衡器。

7.4 自动化部署

创建CI/CD流水线，实现自动化部署：

# .gitlab-ci.yml 示例
stages:
  - build
  - deploy

deploy:
  stage: deploy
  script:
    - docker-compose pull
    - docker-compose down
    - docker-compose up -d
    - docker system prune -f
  only:
    - main

8. 总结

通过Docker Compose部署Fun-ASR WebUI，我们实现了：

1. 快速部署：10分钟内完成从零到可用的部署
2. 环境隔离：避免依赖冲突，保持系统干净
3. 配置即代码：所有配置可版本控制，易于复制和迁移
4. 资源可控：精确控制CPU、内存、GPU资源的使用
5. 易于维护：一键启动、停止、更新、备份

这个方案特别适合：

• 快速搭建测试环境
• 团队内部使用
• 中小型生产部署
• 需要频繁迁移的场景

相比传统部署方式，Docker Compose方案大大降低了部署门槛，让更多用户能够轻松体验Fun-ASR的强大功能。无论你是开发者、研究人员，还是普通用户，都可以通过这个方案快速搭建自己的语音识别服务。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。