• ✅ 文生视频自动生成
• ✅ FFmpeg 单镜头合成与字幕处理
• ✅ 整集拼接导出

📦 资源管理

• ✅ 素材库统一管理
• ✅ 本地存储支持
• ✅ 任务进度追踪

🤖 AI Agents

内置 4 个 Mastra Agent，支持数据库配置和 Skill 扩展：

🔌 多厂商适配

🚀 快速开始

📋 环境要求

FFmpeg 无需安装：项目通过 ffmpeg-static / ffprobe-static npm 包内置二进制，本地与 Docker 均开箱即用。

⚙️ 环境变量

无需配置文件，通过环境变量设置（均有默认值，本地开发可零配置启动）：

说明：AI 服务的 API Key、Base URL 和模型参数全部在 Web 界面的「设置」页配置并入库，不在配置文件/环境变量中维护。

📥 安装依赖

# 克隆项目
git clone https://github.com/chatfire-AI/huobao-drama.git
cd huobao-drama

# 安装后端依赖
cd backend && npm install

# 安装前端依赖
cd ../frontend && npm install

🎯 启动项目

方式一：开发模式（推荐）

前后端分离，支持热重载：

# 终端1：启动后端
cd backend
npm run dev

# 终端2：启动前端
cd frontend
npm run dev

• 前端地址: http://localhost:3013
• 后端 API: http://localhost:5679/api/v1
• 前端自动代理 /api 和 /static 到后端

方式二：单服务模式

后端同时提供 API 和前端静态文件：

# 1. 构建前端
cd frontend && npm run generate

# 2. 复制构建产物到后端读取的目录（generate 产物在 .output/public，后端只读取 frontend/dist）
cp -r .output/public dist

# 3. 启动后端
cd ../backend && npm start

访问: http://localhost:5679

🗄️ 数据库

数据库表在首次启动时自动创建（幂等，每次启动自动重放初始化与迁移）。默认连接读取 DATABASE_URL，也可以通过 MYSQL_HOST、MYSQL_PORT、MYSQL_USER、MYSQL_PASSWORD、MYSQL_DATABASE 分项配置：

DATABASE_URL=mysql://huobao:huobao@127.0.0.1:3306/huobao_drama npm start

如需在应用外预建表（如 DBA 审核场景），可使用 docker/init.sql；schema 变更后通过 cd backend && npx tsx scripts/export-init-sql.ts 重新生成。

🔑 首次使用：配置 AI 服务

启动后所有 AI 功能（文本/生图/视频）都需要先配置模型服务，未配置时页面顶部会有横幅引导：

1. 打开「设置」页
2. 在「火宝快捷配置」中粘贴 Huobao API Key（前往 api.chatfire.site 获取），一键写入文本、图片和视频推荐配置（视频包含 Seedance、Wan 3.0 与 MiniMax）
3. 或使用「手动模板」按厂商逐个添加，支持连通性测试

Wan 3.0 可直接通过「火宝快捷配置」接入 ChatFire 网关；若直连阿里云，则选择「阿里云百炼 Wan 3.0」模板，将 Base URL 中的 {WorkspaceId} 替换为真实业务空间 ID。直连时 Base URL、API Key 与模型必须属于同一地域。

POST /api/v1/tasks 的 Wan 3.0 请求可直接使用官方入参结构（另加项目任务类型 type）：

{
  "type": "video",
  "model": "wan3.0-video-prime",
  "input": {
    "prompt": "图1中的人物走进房间",
    "media": [{ "type": "reference_image", "url": "https://example.com/ref.png" }]
  },
  "parameters": {
    "resolution": "1080P",
    "ratio": "16:9",
    "duration": 5,
    "audio": true,
    "seed": -1,
    "prompt_extend": true,
    "watermark": false
  }
}

配置完成横幅自动消失，即可开始创建剧集生产。

📦 部署指南

🐳 Docker 部署（推荐）

方式一：Docker Compose（推荐）

一条命令拉起应用 + MySQL 8.4，含健康检查与启动顺序编排（应用等待 MySQL 就绪后启动，建表自动完成）：

# 构建并启动
docker compose up -d --build

# 查看日志
docker compose logs -f

# 停止服务
docker compose down

访问: http://localhost:5679

持久化数据：

提示：compose 为源码构建方式，构建过程需从外网下载 ffmpeg-static / sharp 预编译二进制，网络受限环境请先配置 npm 镜像或代理；想跳过构建可直接使用方式二的 Docker Hub 预构建镜像。

方式二：Docker 命令（Docker Hub 镜像）

已发布多架构镜像（linux/amd64 + linux/arm64，x86 服务器与 ARM 设备均自动匹配），无需克隆仓库、无需本地构建：

# 拉取镜像
docker pull huobao/huobao-drama:3.1.0

# 运行(MySQL 需另行准备,通过 DATABASE_URL 指向;命名卷自动从镜像初始化 skills 等内容)
docker run -d \
  --name huobao-drama \
  -p 5679:5679 \
  -v huobao-data:/app/data \
  -v huobao-workspace:/app/backend/workspace \
  -e DATABASE_URL=mysql://huobao:huobao@host.docker.internal:3306/huobao_drama \
  --restart unless-stopped \
  huobao/huobao-drama:3.1.0

# 查看日志
docker logs -f huobao-drama

注意：Linux 用户需添加 --add-host=host.docker.internal:host-gateway 以访问宿主机服务

从源码构建（可选，需克隆仓库）：

docker build -t huobao-drama:latest .

Docker 部署优势：

• ✅ Docker Hub 预构建多架构镜像（amd64 / arm64），免构建即拉即用
• ✅ 开箱即用，内置 FFmpeg 二进制，无需系统安装
• ✅ 前后端合并为单镜像、单端口
• ✅ MySQL 健康检查 + 应用启动重试，首次部署零人工干预
• ✅ data/ 与 workspace/ 目录 volume 挂载，数据与技能持久化

🔗 访问宿主机服务（Ollama / 本地模型）

容器内可通过 http://host.docker.internal:端口号 访问宿主机服务。

配置步骤：

1. 宿主机启动服务（监听所有接口）：

   export OLLAMA_HOST=0.0.0.0:11434 && ollama serve
   

2. 在 Web 界面「设置 → AI 服务配置」中填写：

   • Base URL: http://host.docker.internal:11434/v1
   • Provider: openai
   • Model: qwen2.5:latest

🏭 传统部署方式

# 1. 构建前端
cd frontend && npm run generate

# 2. 复制构建产物（generate 产物在 frontend/.output/public，后端只读取 frontend/dist，缺此步 API 正常但页面 404）
cp -r .output/public dist && cd ..

# 3. 启动后端
cd backend && npm start

需要上传到服务器的文件：

backend/                    # 后端源码 + node_modules
backend/workspace/skills/   # Agent 技能文件
frontend/dist/              # 前端构建产物
data/                       # 数据目录（首次运行自动创建）

Nginx 反向代理

server {
    listen 80;
    server_name your-domain.com;

    # 参考视频/音频上传最大 50MB
    client_max_body_size 100m;

    # 生成的图片/视频直连磁盘，不经过 Node：sendfile 零拷贝 + 长缓存
    # （产物按 uuid 命名、内容不变，可安全 immutable 缓存）
    location /static/ {
        alias /path/to/huobao-drama/data/static/;
        sendfile on;
        tcp_nopush on;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    location / {
        proxy_pass http://localhost:5679;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

媒体加载优化：生成图片时后端会自动产出 400px 缩略图（*_thumb.webp）供列表页加载，视频会抽取海报帧（*_poster.jpg）作为封面，前端仅在点开大图/播放时才加载原文件。历史存量文件可在 backend/ 下执行 npm run backfill-artwork 一次性补齐。

🎨 技术栈

后端

• 运行时: Node.js 20+
• Web 框架: Hono
• ORM: Drizzle ORM + mysql2
• AI Agent: Mastra + AI SDK (OpenAI compatible)
• 视频处理: FFmpeg (fluent-ffmpeg)
• 图片处理: Sharp

前端

• 框架: Nuxt 3 (SPA 模式)
• 语言: Vue 3 + TypeScript
• 路由: 文件路由 (Vue Router 4)
• 样式: 纯 CSS + CSS Variables
• 图标: Lucide Vue

📝 常见问题

Q: Docker 容器如何访问宿主机的 Ollama？

A: 使用 http://host.docker.internal:11434/v1 作为 Base URL。注意：

1. 宿主机 Ollama 需监听 0.0.0.0：export OLLAMA_HOST=0.0.0.0:11434 && ollama serve
2. Linux 用户使用 docker run 需添加：--add-host=host.docker.internal:host-gateway

Q: FFmpeg 未安装或找不到？

A: 无需安装。项目内置 ffmpeg-static / ffprobe-static 二进制（本地与 Docker 均是）。如自定义 PATH 中的系统 FFmpeg 也不会冲突，代码优先使用内置二进制。

Q: 页面顶部提示「尚未配置模型」？

A: 这是正常的首次部署引导。前往「设置」页，用「火宝快捷配置」粘贴 API Key 一键写入，或通过「手动模板」按厂商添加。文本、图片、视频三类均有启用中的配置后横幅自动消失。

Q: 前端无法连接后端 API？

A: 检查后端是否启动，端口是否正确。开发模式下前端代理配置在 frontend/nuxt.config.ts。

Q: 数据库表未创建？

A: 后端会在首次启动时自动创建所有表，检查日志确认初始化是否成功。

📋 更新日志

v3.1.0 (2026-09)

• 新增阿里云百炼 Wan 3.0 视频模型（Prime / 标准，支持官方 input.media/parameters 入参）
• 工作台顶栏新增分辨率选择器，按厂商显示原生档位（Seedance 480p/720p、MiniMax 768P/2K、Wan 480P/720P/1080P）
• 默认视频模型调整为 Seedance 2.0 Mini
• 修复切换视频模型时厂商/模型错配导致的生成报错
• 批量视频：选择模式 + 生成前确认（镜头数/总时长/模型/分辨率），失败任务一键重试
• 分镜时长在视频生成参数区直接编辑保存，单次/批量生成统一生效
• 真人/敏感内容审核失败时提示切换模型重试

v3.0.0 (2026-08)

🚀 部署与体验优化

• Docker 部署就绪改造
  • MySQL / 应用健康检查，应用等待数据库就绪后启动
  • 数据库初始化增加重试，容器编排下首次部署零人工干预
  • 移除系统 FFmpeg 依赖，全面使用内置二进制
  • Agent skills 目录 volume 持久化（设置页在线编辑不丢失）
  • 新增 docker/init.sql 及导出脚本（DBA 审核 / 预建表）
• 首次使用引导
  • 未配置 AI 服务时全站顶部横幅提示并引导至设置页
  • 设置页新增「火宝快捷配置」：一个 Key 写入文本/图片/视频推荐配置
  • 未配置模型的报错中文化并指引设置页
• 视频模型默认调整为 Seedance 2.0 Fast
• 厂商支持：OpenAI / Gemini / 火山引擎 / MiniMax / 阿里云百炼
• 工作台：任务列表抽屉、流水线大环节状态、选择性拼接（拼接前校验视频文件存在）
• 素材库改版、@提及优化、剧集列表重构

v2.0.0 (2026-04)

🚀 重大更新

• 项目全面迁移至 TypeScript 技术栈
  • 后端：Hono + Drizzle ORM + mysql2
  • 前端：Nuxt 3 + Vue 3
  • AI Agent：Mastra 框架
• 重做单集工作台 UI 和生产流程
  • 更紧凑的控制台布局
  • 重做分镜编辑区
  • 重做镜头图、视频、合成、导出界面
• 新增 Docker 部署支持，前后端合并为单镜像
• 增加运行时 Skill 加载机制
• 扩展多厂商媒体 Adapter
  • 图片：OpenAI、Gemini、火山引擎、阿里
  • 视频：火山引擎/Seedance、Vidu、阿里
• 优化本地文件处理与参考图按需转码

v1.0.4 (2026-01-27)

• 引入本地存储策略，规避外部资源链接失效
• Base64 参考图嵌入式传输
• 修复镜头切换状态重置问题
• 添加场景迁移至章节

v1.0.3 (2026-01-16)

• 优化数据库并发访问性能
• Docker 跨平台支持 host.docker.internal

v1.0.2 (2026-01-14)

• 修复视频生成 API 响应解析问题
• 添加 OpenAI Sora 视频端点配置
• 优化错误处理和日志输出

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交改动 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

常用检查命令：

cd backend && npm run typecheck
cd ../frontend && npm run build

☕ 捐赠支持

如果这个项目对你有帮助，欢迎扫码请作者喝杯咖啡 ☕，你的支持是持续更新的动力！

"让 AI 帮我们做更有创造力的事"

🔗 友情链接

本项目已获得 LINUX DO 社区链接认可。

• LINUX DO — 真正的开源精神，共建共享的技术社区