Skip to content

About

个人自托管的 AI 短视频生产工作站:LLM 写稿 → MoneyPrinterTurbo 出片 → ffprobe 质检 → 人工审核。FastAPI + Vue 3 + SQLite,Docker Compose 部署。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

热点工厂 HotFactory

License: MIT Python Vue Version Stage

输入一个主题,产出一条可预览、可审核的中文短视频。跑在你自己的电脑或服务器上。

HotFactory 是单人使用、自托管的 AI 短视频生产工作站:把「主题 → 结构化脚本与分镜 → 动态画面与配音 → 成片质检 → 人工审核」串成一条可重复运行的流水线。默认用 Remotion 渲染暗色 SVG 动态信息图,也可切换 MoneyPrinterTurbo 兼容模式,产出带中文配音与字幕的口播片。

不做无人值守发布:AI 负责生产,成片是否发布始终由人确认。

快速开始 · 架构设计 · 运行手册 · 进度台账 · 报告问题

目录

为什么用它

  • 零 API Key 即可跑通:默认 fake 脚本 + remotion 引擎,不依赖模型 Key、素材库、外部数据库或 Docker;准备好本地 Edge TTS 后,装完就能出一条带配音的 MP4 验证整条链路。
  • 能力可替换:LLM(fake / DeepSeek / SenseNova)与视频引擎(remotion / mpt / mock)统一收敛到 providers/,配置切换,业务代码不依赖服务商 SDK。
  • 状态可追溯:SQLite 任务表 + 独立 Worker 原子认领,进度落库,刷新页面不丢状态,失败可重试。
  • 人工把关:脚本落盘可手改复用,成片可预览、审核通过或驳回删除。
  • 批量可复现:一条命令跑主题清单,每条独立成片并生成汇总报告。
  • 单机自托管:SQLite 单文件即整库备份;生产机只需拉两个 Docker 镜像,不需要数据库服务、消息队列或 GPU。

一条视频的链路如下;设置 HF_VIDEO_PROVIDER=mpt 时,画面、配音、字幕与合成改由 MoneyPrinterTurbo 一次完成:

flowchart LR
    A[主题 + 内容] --> B[LLM 结构化脚本 / 分镜]
    B --> C[Remotion 动态画面]
    C --> D[Edge TTS 旁白 + FFmpeg 封装]
    D --> E[ffprobe 基础质检]
    E --> F[人工预览 / 审核]
Loading

快速开始

前置条件

依赖 要求
Python 3.12+(后端与 Worker;推荐用 uv 建虚拟环境)
Node.js 22+(前端构建、Remotion 渲染)
FFmpeg / ffprobe 任意较新版本,需在 PATH 中(音轨封装与质检)
Edge TTS CLI Remotion 模式用它生成旁白:默认读 .mpt-venv/Scripts/edge-tts.exe,可用 HF_MPT_TTS_COMMAND 指向任意可执行文件;Docker 镜像已内置
npm 随 Node 安装

不需要:API Key、外部数据库、Redis / 消息队列、GPU、Docker(本机试跑)、MoneyPrinterTurbo 服务(默认 Remotion 引擎)。只想验证任务链路时,把 HF_VIDEO_PROVIDER 设为 mock 可用测试图出片,连 Edge TTS 也不需要。

方式 A · Windows 一键启动(最快)

双击项目根目录的 start.bat,或在终端执行:

start.bat

脚本依次完成:检查 Python / Node / FFmpeg 与端口 → 缺 config/.env 时从样例生成(默认 fake + remotion,不需要任何 Key)→ 安装依赖(含 video-renderer)→ 构建前端 → 启动后台 Worker → 启动 FastAPI 并打开浏览器。

访问 http://127.0.0.1:8000(前端由 FastAPI 单端口托管),接口文档在 /docs;在启动窗口按 Ctrl+C 停止,Worker 一并退出。常用参数:

参数 作用
-WithEngine HF_VIDEO_PROVIDER=mpt 时顺带启动 8080 引擎
-Dev 前端 vite 热更新,访问 http://127.0.0.1:5173
-Rebuild / -Port 8010 强制重建前端 / 换端口
-SkipWorker / -NoBrowser / -Help 只起 Web / 不自动开浏览器 / 查看全部参数

首次出片前准备旁白 CLI(宿主直跑只需一次;Docker 镜像已内置):

python -m venv .mpt-venv
.mpt-venv\Scripts\python.exe -m pip install edge-tts

Linux / macOS 用 .mpt-venv/bin/edge-tts,并把 config/.env 的 HF_MPT_TTS_COMMAND 指向它。缺少它时 Remotion 模式会报「找不到 Edge TTS」;只想验证任务链路,可临时把 HF_VIDEO_PROVIDER 设为 mock。

改了 config/.env 或后端代码后重跑 start.bat 即可(Worker 的配置与代码在启动时读入内存)。日志都在 logs/。

方式 B · 源码运行(Linux / macOS / Git Bash)

git clone https://github.com/999bug/HotFactory.git
cd HotFactory

# 1. 后端依赖与配置
cd backend
uv venv .venv --python 3.12
uv pip install -r requirements.txt
cd ..
cp config/env.example config/.env

# 2. 前端与渲染器依赖
(cd frontend && npm install && npm run build)
(cd video-renderer && npm install)

# 3. 起两个进程(各占一个终端)
cd backend
. .venv/bin/activate        # Windows 用 .venv/Scripts/activate
python -m uvicorn app.main:app --port 8000
python -m app.workers       # 另一个终端

浏览器打开 http://127.0.0.1:8000;开发前端时改为 cd frontend && npm run dev(5173,/api 代理到 8000)。宿主直跑同样要按上一节准备 Edge TTS CLI,Linux / macOS 把 HF_MPT_TTS_COMMAND 指向 .mpt-venv/bin/edge-tts。

方式 C · Docker 镜像部署(生产机)

生产机只拉 GHCR 上的 hot-factory-web / hot-factory-worker 两个镜像,不需要装 Node / Python / FFmpeg,镜像内也已备好 Edge TTS 与中文字体:

sudo mkdir -p /opt/hotfactory && sudo chown "$USER" /opt/hotfactory
git clone https://github.com/999bug/HotFactory.git /opt/hotfactory
cd /opt/hotfactory
cp deploy.env.example deploy.env
cp config/env.example config/.env
bash scripts/docker-deploy.sh          # pull → up -d → 等 healthy → 校验 build_version

升级用 bash scripts/docker-update.sh(可加版本号或 --dry-run),回滚只需把 deploy.env 的 HF_IMAGE_TAG 改回上一版再跑一次部署脚本。校验:curl http://127.0.0.1:8000/api/health 返回的 build_version 应等于配置的镜像 tag。

镜像发布由推 v* tag 触发 GitHub Actions,只推 GHCR、无需配置任何 secret。镜像与部署的完整手册见 docs/runbook/docker-deploy-upgrade.md。

验证第一步

打开页面填一个主题 → 点「生成视频」→ 等待状态变为 WAITING_REVIEW → 预览成片;成片落在 output/videos/{task_id}/。也可以直接用 API:

curl -X POST http://127.0.0.1:8000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"topic":"一杯手冲咖啡的冲泡过程"}'
curl http://127.0.0.1:8000/api/tasks/<上一步返回的 id>

⚠️ 安全提示:系统没有登录认证,容器默认监听 0.0.0.0。任何能访问该端口的人都能提交任务、消耗你的模型额度并写满磁盘。公网部署前至少做一件事:安全组只放行自己的 IP、改回 127.0.0.1 走 ssh -L,或前置反代做 TLS + Basic Auth。MoneyPrinterTurbo 的 8080 端口一律只监听本机。

配置

两个 env 文件分工固定,不要混用:

文件 管什么 典型键
config/.env(样例 config/env.example) 应用配置:LLM provider / Key / model、视频引擎、Worker 参数 HF_LLM_PROVIDER、HF_VIDEO_PROVIDER、HF_DEEPSEEK_API_KEY
deploy.env(样例 deploy.env.example) compose 插值与部署参数:镜像 tag、端口、UID/GID、容器内引擎地址 HF_IMAGE_TAG、HF_WEB_PORT、HF_MPT_API_BASE

compose 注入的进程环境变量优先级高于 config/.env 的同名键(容器里四个路径键固定为 /hotfactory/*,HF_MPT_API_BASE 取 deploy.env);手写 compose 命令必须带 --env-file deploy.env。改 config/.env 后需重启 Web 与 Worker。

最小可跑配置(默认即此,无需修改):

HF_LLM_PROVIDER=fake        # 改 deepseek / sensenova 并填 Key 才会调模型
HF_VIDEO_PROVIDER=remotion  # mpt = MoneyPrinterTurbo 兼容模式;mock = 测试图

HF_LLM_PROVIDER=fake 会用主题套进通用口播稿;在页面填写自己的内容或口播稿即可完全跳过模型调用。所有键位、降级组合与引擎侧配置见 docs/runbook/operations.md。

使用

网页

填主题与内容(可选)→ 选画幅、成片时长、配音语速 → 生成视频 → 看进度、预览成片、审核通过或驳回。可上传图片 / 视频作为本条任务的素材(只使用选中的文件)。成片按主题命名,任务列表可直接看到主题与成片。

命令行批量出片

cd backend && . .venv/bin/activate      # Windows 用 .venv/Scripts/activate

python -m app.workers.cli --subject "一杯手冲咖啡的冲泡过程"
python -m app.workers.cli --topics ../config/topics.example.json \
  --report ../output/reports/batch-report.json

主题清单支持 ["主题A", "主题B"] 或带 topic / script / voice_name 的对象;填 script 会跳过 LLM,--from-script 可复用已落盘脚本,--limit N 只跑前 N 条,有任务失败时退出码为 1。批量 CLI 只是「批量入队 + 汇总报告」的薄封装,复用同一张任务表与同一条流水线,不是第二套实现。

API

Method Path 说明
POST /api/tasks 创建任务,立即返回 id
GET /api/tasks/{id} 轮询状态、进度、阶段、错误与结果
POST /api/tasks/{id}/retry · /cancel · /approve · /reject 重试 / 取消 / 审核通过 / 驳回删除
GET /api/videos · /api/videos/{id}/stream 成片列表 / 预览
POST /api/materials 上传素材
GET /api/health · /docs 健康检查 / OpenAPI 文档

任务状态机:PENDING → SCRIPTING → GENERATING → QC → WAITING_REVIEW → APPROVED,异常态 FAILED / CANCELLED。完整契约以 docs/design/hot-factory-overview-design.md 为准。

工作原理

HotFactory 只负责业务流程与数据管理,外部能力统一收在 backend/app/providers/;新增能力前先确认上游是否已提供,不重复造第二套任务进度体系或字幕 / TTS 实现。

环节 由谁提供
结构化脚本与分镜 providers/llm(fake / deepseek / sensenova),脚本落盘可手改
动态画面 video-renderer/(Remotion + React + SVG),由 Storyboard JSON 驱动
旁白配音 Edge TTS CLI(默认 .mpt-venv,可用 HF_MPT_TTS_COMMAND 指定)/ MPT 兼容模式
字幕、素材、整片合成 MoneyPrinterTurbo(HF_VIDEO_PROVIDER=mpt)
音轨封装与质检 FFmpeg / ffprobe(本项目 providers/qc.py)
任务持久化、进度、预览、审核 本项目:SQLite + 独立 Worker + FastAPI + Vue
backend/app/        api / core / models / schemas / services / providers / storyboard / workers
backend/tests/      pytest
frontend/           Vue 3 + TypeScript + Vite + Element Plus
video-renderer/     Remotion 渲染工程
config/             配置样例(config/.env 不入库)
data/               SQLite 与上传素材 —— 唯一需要备份的目录
output/             成片、分镜、批量报告
logs/               运行日志
docs/               design / runbook / progress

文档

README 只保留「上手所需」,更长的说明都在这里:

想找什么 去哪
架构、接口契约、任务状态、能力边界(唯一真源) docs/design/hot-factory-overview-design.md
运行模式、出片命令、MPT 引擎与素材配置、降级组合 docs/runbook/operations.md
GHCR 镜像、首次部署、升级、回滚、排错 docs/runbook/docker-deploy-upgrade.md
进度、验证记录与待办 docs/progress/PROCESS.md
第三方组件版本与许可证 THIRD-PARTY-NOTICES.md
AI 协作规范(规范本体在全局目录,不随仓库分发) AGENTS.md

路线图与已知限制

按三阶段推进,不提前实现后续阶段:

  1. 第一阶段(当前,alpha):跑通视频生产 —— 主题输入、AI 脚本与分镜、视频生成、质检、预览与人工审核。发布只保留接口与数据结构占位。
  2. 第二阶段:多模板、多音色、字幕增强、封面、自动质量评分、每日热点推荐。
  3. 第三阶段:抖音 / 快手 / 小红书 / 视频号 / B 站发布,官方 API 优先并保留人工确认。

已知限制:

  • 无用户认证;Web 端口默认公网监听,必须靠安全组或反代收口。
  • 热点靠手工主题 / topics.json 输入,没有官方热点 API,也没有自动选题评分。
  • 质检只覆盖元数据(音视频流、时长、分辨率、大小);黑屏 / 静音语义检测与自动评分未实现。
  • 容器启动与容器内 Chrome 渲染链路尚未在本机实跑(本机未装 Docker);镜像构建与 GHCR 推送已通过 CI 验证。镜像仅 linux/amd64。
  • 前端全量引入 Element Plus,构建产物约 1 MB;Windows Docker Desktop 下用 bind mount 跑 SQLite(WAL)有已知风险,仅建议本地试跑。
  • MoneyPrinterTurbo 是独立外部程序,Compose 只编排 Web + Worker,经 HF_MPT_API_BASE 接入;上游没有官方镜像,不编造镜像名。

开发与测试

# 先激活 backend/.venv
cd backend && python -m pytest                       # 当前 110 个用例
cd frontend && npm run typecheck && npm run build    # vue-tsc + vite build

开发约定:先冻结架构与接口,再按模块实现,每完成一个模块跑测试;接口与任务状态字段变更先改架构文档再改代码。

贡献

欢迎提 Issue 或 PR。开始之前请先读 AGENTS.md 与架构文档:外部能力走 providers/ 适配层、复用优先、不引入 Redis / 消息队列等中间件、不建第二套进度体系。提交信息用中文并带 conventional 前缀(如 feat: / fix:),只提交本次改动涉及的具体文件。

许可与致谢

本项目代码以 MIT License 发布。第三方组件的版本、许可证与来源记录在 THIRD-PARTY-NOTICES.md,接入或升级依赖前请复核上游 LICENSE 与服务条款。

能力上站在这些项目的肩膀上:MoneyPrinterTurbo、Remotion、FastAPI、Vue 3、FFmpeg、edge-tts 与 DeepSeek。

About

个人自托管的 AI 短视频生产工作站:LLM 写稿 → MoneyPrinterTurbo 出片 → ffprobe 质检 → 人工审核。FastAPI + Vue 3 + SQLite,Docker Compose 部署。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages