NarratoAI零门槛部署指南：AI视频解说平台容器化实践

准备阶段：构建稳定的部署环境

环境检查的价值：提前验证系统兼容性，避免部署到一半才发现环境问题。

如何验证Docker环境

目标：确保Docker及相关组件满足最低运行要求
方法：执行版本检查命令组合

docker --version | grep -q "20.10.0" && echo "Docker版本达标" || echo "需升级Docker"
docker-compose --version | grep -q "1.29.0" && echo "Compose版本达标" || echo "需升级Compose"

验证：两个命令均输出"达标"字样
⚠️ 常见陷阱：系统预装的Docker版本可能低于要求，建议使用Docker官方安装脚本升级

资源配置评估

目标：确认系统资源满足应用运行需求
方法：使用系统命令检查关键资源

free -h | awk '/Mem:/ {print "内存可用: " $7}'
df -h / | awk '/\// {print "磁盘可用: " $4}'

验证：内存≥4GB且磁盘空间≥10GB

资源类型	最低要求	推荐配置	风险提示
内存	4GB	8GB	低于4GB会导致视频处理时崩溃
磁盘	10GB	20GB	空间不足会导致视频生成失败
CPU	双核	四核	核心数少会延长处理时间

实施阶段：自动化部署流程

部署流程的价值：通过容器化技术实现环境隔离，确保部署一致性和可重复性。

项目代码获取与配置

目标：获取最新代码并完成基础配置
方法：

git clone https://gitcode.com/gh_mirrors/na/NarratoAI
cd NarratoAI
cp config.example.toml config.toml

使用文本编辑器打开config.toml，添加API密钥：

[app]
vision_litellm_api_key = "your_vision_api_key"
text_litellm_api_key = "your_text_api_key"

验证：配置文件存在且包含非空的API密钥字段
⚠️ 常见陷阱：直接修改示例配置文件而不创建副本，可能导致git更新时冲突

容器化部署执行

目标：一键完成镜像构建与服务启动
方法：

chmod +x docker-deploy.sh
./docker-deploy.sh --build --force-recreate

验证：脚本最后输出"部署成功"提示

graph TD
    A[执行部署脚本] --> B{环境检查}
    B -->|通过| C[构建Docker镜像]
    B -->|失败| Z[显示错误信息]
    C --> D[创建存储卷]
    D --> E[启动容器服务]
    E --> F[健康检查]
    F -->|通过| G[部署成功]
    F -->|失败| Z

验证阶段：系统功能确认

验证环节的价值：确保部署后的系统各项功能正常工作，避免在实际使用时发现问题。

服务状态检查

目标：确认所有容器服务正常运行
方法：

docker-compose ps | grep "Up" | wc -l
curl -s http://localhost:8501/_stcore/health | grep "healthy"

验证：第一个命令返回1（表示1个服务正常运行），第二个命令返回包含"healthy"的JSON

NarratoAI Web界面，显示视频脚本配置、字幕设置等功能模块

核心功能测试

目标：验证视频处理核心流程
方法：

1. 访问http://localhost:8501
2. 在"Video Script Configuration"区域上传测试视频
3. 点击"Generate Video Script"按钮
4. 等待处理完成后检查生成结果

验证：系统成功生成视频脚本和预览效果

视频内容检查界面，支持预览、时间戳对比和旁白文本生成

进阶阶段：生产环境优化

优化配置的价值：针对生产环境特点调整系统参数，提升性能和稳定性。

性能优化参数配置

目标：提升视频处理效率和系统响应速度
方法：编辑docker-compose.yml文件，添加资源限制配置：

services:
  narratoai-webui:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8501:8501"
    volumes:
      - ./storage:/NarratoAI/storage
      - ./config.toml:/NarratoAI/config.toml
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G

验证：重启服务后使用docker stats确认资源限制生效

常见问题解决方案

问题：服务启动后无法访问Web界面
→ 原因：端口被占用或防火墙限制
→ 解决方案：

# 检查端口占用
sudo lsof -i :8501
# 如被占用，修改docker-compose.yml中的端口映射
# 或关闭占用进程后重启服务

问题：视频处理过程中API调用超时
→ 原因：网络连接问题或API密钥无效
→ 解决方案：

# 检查网络连接
ping api.openai.com
# 验证API密钥有效性
grep "api_key" config.toml

视频生成完成界面，显示处理结果和预览效果

附录：工具替代方案对比

工具	优势	劣势	适用场景
Docker Compose	配置简单，适合单机部署	不支持集群扩展	开发环境、小型生产环境
Kubernetes	支持自动扩缩容，高可用	配置复杂，学习曲线陡	大型生产环境，多节点部署
Podman	无守护进程，更安全	部分Docker命令不兼容	对安全性要求高的环境

通过以上步骤，您已完成NarratoAI的容器化部署和优化配置。系统现在可以稳定处理视频解说生成任务，支持后续功能扩展和性能调优。建议定期备份config.toml配置文件和storage目录，以防止数据丢失。