这份详细的部署教程将指引您安装和运行 火宝短剧 (Huobao Drama)——一个基于 AI 的一站式短剧生成平台。它能够将您的一句话创意，自动化地转化为完整的短剧视频。

火宝短剧是一个全栈 TypeScript 应用，通过编排多个 AI Agent（代理），实现了从剧本创作、角色设计、分镜拆解到视频合成的全流程自动化。

整个部署流程根据您的技术背景，可以选择全自动的 Docker 方式或可控的本地开发方式。无论哪种方式，首次启动后都需要在 Web 界面配置 AI 服务的 API 密钥。

🐳 方式一：Docker 部署（强烈推荐新手）

Docker 方式能自动处理所有依赖和环境配置，是最快捷、最推荐的部署方式。

  1. 前提条件：确保系统已安装 Docker 和 Docker Compose。

  2. 克隆并启动：

    1
    2
    3
    git clone https://github.com/chatfire-AI/huobao-drama.git
    cd huobao-drama
    docker compose up -d --build

    此命令会自动构建镜像，并启动应用和 MySQL 数据库。首次启动会自动创建数据表，无需人工干预。

  3. 访问服务：启动完成后，在浏览器中打开 http://localhost:5679 即可开始使用。

    提示：Docker 部署使用源码构建，首次构建可能需要下载依赖。你也可以使用 Docker Hub 上的预构建镜像 huobao/huobao-drama:3.0.0 来跳过构建步骤。

💻 方式二：本地开发部署

如果您是开发者，希望直接运行源码进行开发或定制，可以选择本地部署。

  1. 环境要求：

    • Node.js 20+ 和 npm 9+
    • MySQL 8.0+ (需要有一个运行中的数据库实例)
    • FFmpeg 无需安装：项目已通过 ffmpeg-static 包内置了二进制文件。

  2. 克隆与安装依赖：

    1
    2
    3
    4
    git clone https://github.com/chatfire-AI/huobao-drama.git
    cd huobao-drama
    cd backend && npm install
    cd ../frontend && npm install

  3. 配置数据库：

    • 项目默认使用 MySQL。您需要创建一个数据库（如 huobao_drama）。
    • 通过环境变量设置数据库连接。你可以在启动命令前设置，或者创建一个 .env 文件。
    1
    2
    # 示例环境变量（请替换为你的实际信息）
    export DATABASE_URL="mysql://用户名:密码@127.0.0.1:3306/数据库名"

    首次启动会自动创建所有数据表，无需手动导入 SQL。

  4. 启动项目：

    • 方式一：开发模式（前后端分离，支持热重载）

      1
      2
      3
      4
      5
      # 终端 1：启动后端 (监听 5679 端口)
      cd backend && npm run dev

      # 终端 2：启动前端 (监听 3013 端口)
      cd frontend && npm run dev

      前端地址: http://localhost:3013，后端 API 地址: http://localhost:5679/api/v1。

    • 方式二：单服务模式（后端提供 API 和前端静态文件）

      1
      2
      3
      4
      5
      6
      # 1. 构建前端
      cd frontend && npm run generate
      # 2. 复制构建产物到后端能读取的目录
      cp -r .output/public dist
      # 3. 启动后端
      cd ../backend && npm start

      访问: http://localhost:5679

🔑 首次使用：必须配置 AI 服务

启动后，所有 AI 功能（文本生成、图片生成、视频生成）都需要先配置模型服务。这是使用平台的关键一步。

  1. 获取 API Key：你需要从受支持的 AI 服务商（如 OpenAI、Gemini、火山引擎）获取 API Key。为了方便，项目也提供了“火宝 API Key”的获取途径（见项目文档）。
  2. 在界面中配置：
    • 打开 Web 界面，点击顶部的“设置”页。
    • 在 “火宝快捷配置” 区域，粘贴你的 API Key，点击“一键写入”，即可快速配置好文本、图片、视频三条推荐配置。
    • 或者，你也可以使用 “手动模板” ，按厂商（如 OpenAI、Gemini）逐个添加，并支持连通性测试。
  3. 配置完成：页面顶部的“尚未配置模型”横幅会自动消失，你就可以开始创建剧集了。

🎬 核心使用流程

配置好 AI 服务后，你可以体验完整的短剧生成工作流：

  1. 创建剧集：输入一个故事创意（一句话）。
  2. AI 生成剧本：平台内置的 script_rewriter Agent 会将创意扩写为结构化的剧本。
  3. 提取角色与场景：extractor Agent 会自动从剧本中提取角色、场景和道具信息。
  4. 生成分镜：storyboard_breaker Agent 将剧本拆解为一个个分镜。
  5. AI 绘图与视频生成：为每个分镜生成场景图和对应的视频片段。
  6. 视频合成与导出：所有片段会自动合成，并添加字幕，最终导出一集完整的短剧。

⚙️ 关键配置与提示

  • 数据库：Docker 部署内置 MySQL，本地部署需自行准备。所有表会在首次启动时自动创建。
  • 存储：生成的图片、视频等文件默认保存在 ./data/static/ 目录。建议将此目录挂载到外部卷，以便持久化和备份。
  • Agent 技能：内置的 AI Agent 行为可以通过编辑 backend/workspace/skills/ 目录下的 SKILL.md 文件来定制。
  • 反向代理：如果你使用 Nginx，可以参考项目 README 中的配置示例，以优化静态文件的缓存和传输。

📚 了解更多

  • 完整文档：项目 README 包含了详细的 部署指南、技术架构 和 常见问题。
  • 贡献：欢迎提交 Issue 和 Pull Request。请先运行 npm run typecheck (后端) 和 npm run build (前端) 确保代码质量。