huobao-drama README

The project's README from github.com/chatfire-AI/huobao-drama. As one markdown file: README.md.

🎬 Huobao Drama - AI 短剧生成平台

基于 TypeScript 全栈的 AI 短剧自动化生产平台

Node Version Vue Version License

功能特性 • 快速开始 • 部署指南

🔑 获取 Huobao API Key 👉 立即查看

文本 · 图片 · 视频全部 AI 能力，一个 Key 即可开通

部署完成后在「设置 → 火宝快捷配置」粘贴 Key，一键写入推荐配置，开箱即用

📖 项目简介

Huobao Drama 是一个基于 AI 的短剧自动化生产平台，实现从剧本生成、角色设计、分镜制作到视频合成的全流程自动化。

🎯 核心价值

🛠️ 技术架构

frontend/   — Nuxt 3 + Vue 3 + TypeScript (纯 CSS，无 UI 框架)
backend/    — Hono + Drizzle ORM + Mastra AI Agents + mysql2
backend/workspace/skills/ — Agent 技能定义 (SKILL.md，支持界面在线编辑)
data/       — 生成资源文件
docker/     — init.sql 数据库初始化脚本(可选，启动时自动建表)

🔥 AI创作省钱攻略｜快乐马 & Seedance 合作专属折扣，优惠到底 👉 立即查看

✨ 功能特性

🎭 角色管理

🎬 视频任务

🎥 视频生成

📦 资源管理

🤖 AI Agents

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

Agent 职责
script_rewriter 小说 → 格式化剧本改写
extractor 角色 / 场景 / 道具智能提取与去重
storyboard_breaker 剧本 → 分镜序列拆解
prompt_generator 角色/场景/道具图片提示词 + 分镜视频提示词生成

🔌 多厂商适配

类型 支持厂商
文本 OpenAI(兼容接口)、Gemini
图片 OpenAI、Gemini、火山引擎
视频 火山引擎 Seedance 2.0、MiniMax H3、阿里云百炼 Wan 3.0 (Prime / 标准)

🚀 快速开始

📋 环境要求

软件 版本要求 说明
Node.js 20+ 前后端运行环境
npm 9+ 包管理工具
MySQL 8.0+ 数据库（Docker 部署已内置，无需单独安装）

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

⚙️ 环境变量

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

变量 默认值 说明
DATABASE_URL — 完整 MySQL 连接串（优先）
MYSQL_HOST / MYSQL_PORT 127.0.0.1 / 3306 未设 DATABASE_URL 时分项配置
MYSQL_USER / MYSQL_PASSWORD huobao / huobao 同上
MYSQL_DATABASE huobao_drama 同上
PORT 5679 后端服务端口
STORAGE_PATH ./data/static 生成文件存储目录
PUBLIC_BASE_URL — 使用本地参考视频、音频或文件时，供上游模型访问 static/ 素材的公网地址

说明：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

方式二：单服务模式

后端同时提供 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:[email protected]: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

持久化数据：

挂载 内容
./data 生成的图片/视频等文件
./backend/workspace Agent 技能文件（设置页可在线编辑）
mysql-data(命名卷) MySQL 数据

提示：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:[email protected]: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 部署优势：

🔗 访问宿主机服务（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 一次性补齐。

🎨 技术栈

后端

前端

📝 常见问题

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)

v3.0.0 (2026-08)

🚀 部署与体验优化

v2.0.0 (2026-04)

🚀 重大更新

v1.0.4 (2026-01-27)

v1.0.3 (2026-01-16)

v1.0.2 (2026-01-14)

🤝 贡献指南

欢迎提交 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 社区链接认可。

huobao-drama (chatfire-AI/huobao-drama)

Searching Database…

16.3K ·GitHub
Huobao-drama
这是什么？Huobao Drama 是一个由 AI 驱动的平台，几乎无需人工操作，就能自动完成短剧的全部制作流程：将剧本或小说转化为角色设定、分镜，并生成剪辑完成的成片视频。
这是托管服务，还是需要我自己运行的软件？这是一个自托管的全 TypeScript 技术栈网页应用（后端为 Hono，前端为 Nuxt 3 / Vue 3），需要你自己部署；此外还提供可选的桌面客户端版本（desktop/ 文件夹，内含各自的开发和打包脚本）。
我该怎么把它跑起来？推荐使用 Docker Compose，一条命令即可启动应用以及带健康检查的 MySQL 8.4；也可以安装 Node.js 20+，运行 npm install，然后手动启动后端和前端的开发服务器。
我需要自己的 AI API 密钥吗？需要。你必须为文本、图像和视频模型配置密钥（支持 OpenAI 兼容接口、Gemini、火山引擎、MiniMax、阿里巴巴 Wan 3.0）。只需填入一个 Huobao API Key，就能通过设置页面为这三类模型自动填入推荐配置。
安装时有哪些需要注意的坑吗？从源码构建 Docker Compose 镜像时，会从互联网下载 ffmpeg-static 和 sharp 的预编译二进制文件，在网络受限的环境下会失败，除非设置 npm 镜像源或代理；使用预构建的 Docker Hub 多架构镜像则可以完全避免这个问题。
它开箱即用自带哪些 AI 智能体？内置四个 Mastra 智能体：scriptrewriter（将小说改写为格式化剧本）、extractor（提取角色、场景、道具）、storyboardbreaker（将剧本拆解为镜头序列）、promptgenerator（为每个镜头生成图像或视频提示词）。
我可以接入哪些视频生成服务商？目前支持的视频服务商有火山引擎 Seedance 2.0、MiniMax H3 和阿里云 Wan 3.0（Prime/Standard）；图像生成支持 OpenAI、Gemini 和火山引擎。
我能用本地模型代替付费 API 吗？可以。容器可以通过 host.docker.internal 访问宿主机上运行的 Ollama 服务，然后将其注册为 OpenAI 兼容的服务商，例如指向 qwen2.5:latest 模型。
我需要自己安装 FFmpeg 吗？不需要。FFmpeg 和 ffprobe 二进制文件已通过 ffmpeg-static / ffprobe-static npm 包打包，因此本地部署和 Docker 部署都无需单独安装系统级 FFmpeg。
What are similar projects?waoowaoo, youtube-automation-agent, banana-slides, printfilm, MoneyPrinterTurbo, ArcReel, OpenReels, JeecgBoot
Which topics is it in?hono, short-drama, nuxt, drizzle-orm, vue3, text-to-video, orm, content-creation, video-processing, ffmpeg, mysql, video-generation
Creator
chatfire-AI
Size
46.8 MB
Stars
16.3K
Updated
CommitOct 05Releasev4.0.8Oct 05
Age
9mo
Commits · 90 Days