PRINTFILM

开源项目：PRINTFILM
版本：0.2.0 | 更新：2026-09-17

模板驱动的 AI 短视频与漫剧创作平台：主题 / 剧本 → 分镜 → 生图 → 生视频 → 成片。口播由 Seedance 在出片时一并生成，无需单独配音。同一条生成能力，多套视觉风格；支持注册登录、按量计费、管理后台与开放 API。

• 快速开始
• Docker 部署
• AI 服务配置
• 操作手册
  • 1. 系统概述
  • 2. 环境要求
  • 3. 安装与启动
  • 4. 登录与账号
  • 5. 界面与模块导航
  • 6. 业务模块操作指南
  • 7. 典型业务流程
  • 8. 系统管理
  • 9. 日常运维
  • 10. 常见问题与排查
  • 11. 附录
• 贡献
• 开源许可

推荐用预构建镜像，本机只需 Docker。gcc 命名空间公开，拉取无需登录。

git clone https://github.com/yi1108/printfilm.git
cd printfilm

cp deploy/.env.docker.example deploy/.env.docker
# 请把 POSTGRES_PASSWORD、SECRET_KEY 改成自己的值
# 填入 TokenFree API Key（OPENAI_API_KEY 与 ARK_API_KEY 可用同一把）

docker compose --env-file deploy/.env.docker up -d

仓库没有内置演示账号。生产环境请立即改掉 SECRET_KEY、数据库密码与所有 API Key。无 Key 想先看界面时设 ARK_MOCK=true。

预构建镜像

gcc-registry.cn-hangzhou.cr.aliyuncs.com/gcc/printfilm-api:latest
gcc-registry.cn-hangzhou.cr.aliyuncs.com/gcc/printfilm-web:latest
gcc-registry.cn-hangzhou.cr.aliyuncs.com/gcc/printfilm-admin-web:latest
postgres:16-alpine
redis:7-alpine

项目结构

backend/         FastAPI、流水线、计费、任务运行时
frontend/        用户端（工作台 / 漫剧 / 科普 / 工具）
admin/           运营后台
deploy/          环境变量示例、仅中间件 compose、发布说明
docs/            规范、计费、发布记录
docker-compose.yml        拉取公开镜像一键启动
docker-compose.full.yml   从源码构建（开发 / 自建镜像）

源码地址：https://github.com/yi1108/printfilm

适用于 GitHub 克隆后的自托管。业务镜像已推到阿里云 ACR 公开仓库；Postgres / Redis 用 Docker Hub 官方镜像。

浏览器 :8080 / :8081
        │  /api  ·  /static
        ▼
   nginx（web / admin-web 镜像）
        │
        ▼
   FastAPI :8000（api 镜像，内含 FFmpeg 与中文字体）
        ├── PostgreSQL :15432
        └── Redis :16379

1. 安装 Docker Desktop 或 Docker Engine 20.10+（含 Compose v2）。
2. 复制环境文件并修改密码与 Key：

cp deploy/.env.docker.example deploy/.env.docker

3. 启动：

docker compose --env-file deploy/.env.docker pull
docker compose --env-file deploy/.env.docker up -d
docker compose --env-file deploy/.env.docker ps

4. 打开 http://localhost:8080 注册；健康检查：

curl http://localhost:8000/api/health

ok 为 true 表示任务运行时与数据库可用。首次 up 会 create_all 并写入缺失模板，约需数十秒。

改过前端或后端、或无法拉取 ACR 时：

cp deploy/.env.docker.example deploy/.env.docker
docker compose --env-file deploy/.env.docker -f docker-compose.full.yml up -d --build

用户端镜像构建时强制 VITE_API_BASE=（空字符串），由 nginx 同源反代 /api 与 /static，不要把本机 http://127.0.0.1:8000 打进 dist。

若端口冲突，改 docker-compose.yml 左侧宿主机端口，并同步 CORS_ORIGINS、PUBLIC_BASE_URL。

编辑 deploy/.env.docker：

密钥也可以启动后再到管理后台 系统设置 → 模型 填写，不必写进环境文件。

# 日志
docker compose --env-file deploy/.env.docker logs -f api

# 只重启 API（改环境变量后）
docker compose --env-file deploy/.env.docker up -d --force-recreate api

# 更新到最新镜像
docker compose --env-file deploy/.env.docker pull
docker compose --env-file deploy/.env.docker up -d

# 停止（保留数据库与成片卷）
docker compose --env-file deploy/.env.docker down

# 停止并删除数据卷（清库）
docker compose --env-file deploy/.env.docker down -v

数据卷：printfilm_pgdata、printfilm_redisdata、printfilm_media（成片与分镜落盘，FFmpeg 只读本地）。

• 反向代理到 8080 / 8081 时，把 PUBLIC_BASE_URL 和 CORS_ORIGINS 改成真实域名。
• 易支付回调 URL 不要包含 /api/（部分网关 WAF 会拦截）。用户端 nginx 已将 /epay/notify 转到 /api/billing/epay/notify。
• API 容器建议保持 --workers 1（镜像默认），避免多进程抢任务租约。
• 本仓库开源路径以 Docker 全栈为准；现网机器部署手册不在公开仓库。

开源版图 / 视频 / 文字统一走 TokenFree New API（https://www.tokenfree.com/v1）。视频口播交给 Seedance 自行发挥，不必再配 TTS / 音色。

可在管理后台 系统设置 → 模型 填写渠道 Key 并拉取模型；deploy/.env.docker 或 backend/.env 仅作首次导入。

OPENAI_API_KEY=sk-你的密钥
OPENAI_BASE_URL=https://www.tokenfree.com/v1
MODEL_LLM=kimi-k2.6

ARK_MOCK=false
ARK_API_KEY=sk-你的密钥
MODEL_IMAGE=doubao-seedream-5-0-260128
MODEL_VIDEO=doubao-seedance-2-5-260628

curl http://localhost:8000/api/health

返回 JSON 中 ok 表示任务运行时健康；models 为当前 LLM / 图像 / 视频模型；ark_mock 为是否 mock。

PRINTFILM 面向创作者与运营：输入主题或剧本，按模板生成分镜、画面与成片。两条主产品线：

• AI 漫剧：大纲 → 资产 → 分集分镜 → 画布，强调角色与场景一致性。
• AI 短视频（科普）：选模板 → 输入文案 → 风格 → 分镜流水线 → FFmpeg 合成。

另有独立 工具中心（文生图、图生图、文生视频等）和可选 按量钱包（易支付）。

浏览器 (8080 用户端 / 8081 管理端；开发时 5173 / 5174)
        │  /api  ·  /static
        ▼
   FastAPI :8000
        │
        ├── 任务运行时（scheduler / executor / poller）
        ├── PostgreSQL
        ├── Redis（找回密码、缓存等）
        ├── TokenFree（图 / 视频 / 文本；Seedance 出片自带口播）
        └── 本地 static/generated + 可选阿里云 OSS
                    │
                    ▼
                 FFmpeg 合成成片

工程约定见 docs/STANDARDS.md。

见上文 Docker 部署。

只把 Postgres / Redis 跑在容器里，API 与两个前端在宿主机：

cp deploy/.env.prod.example deploy/.env.prod
# 修改 POSTGRES_PASSWORD
docker compose -f deploy/docker-compose.yml --env-file deploy/.env.prod up -d

cd backend
python -m venv .venv
# Windows: .\.venv\Scripts\activate
# Linux / macOS: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# DATABASE_URL 密码与 deploy/.env.prod 一致；填入模型 Key
uvicorn app.main:app --reload --port 8000

另开两个终端：

cd frontend
npm install
npm run dev

cd admin
npm install
npm run dev

注意：

1. deploy/.env.prod 的数据库密码必须与 backend/.env 的 DATABASE_URL / DATABASE_URL_SYNC 一致。
2. 用户端开发时 不要 设置 VITE_API_BASE（未设置则访问当前主机 :8000）。生产 / Docker 构建必须 VITE_API_BASE= 空字符串。
3. CORS 默认允许 localhost:5173 与 localhost:5174，以及局域网私有 IP。
4. 本机需安装 FFmpeg；Linux 成片字幕需中文字体。

线上站点也可由 nginx + 进程管理器托管前后端静态资源与 API。OSS 只用于成片 / 分镜等媒体，不要把 SPA 丢到 OSS 当唯一发布方式。中间件与本机进程说明见 deploy/README.md。

路径：/auth（管理端为 /login）

计费开启时，新用户可获赠 BILLING_SIGNUP_GRANT_FEN（示例默认 500 分 = ¥5.00）。Docker 与本机默认 BILLING_ENABLED=false。

用户端顶栏（中 / 英可切换）：

管理端侧栏：仪表盘、用户管理、订单流水、财务列表、科普项目、作品审核、漫剧（项目 / 资产 / 分集 / 分镜）、模板管理、任务中心、系统设置。

路径：/

功能概述：选择「AI 漫剧」或「AI 短视频」，或进入工具。

路径：/studio/new → /studio/:id/style → /studio/:id → /studio/:id/editor；列表在 /history

功能概述：主题 / 口播文案经模板拆镜后，生成分镜图与视频（可选），再 FFmpeg 合成。口播由 Seedance 出片时生成，不再单独配音。

路径：/drama、/drama/projects/:projectId、/drama/projects/:projectId/episodes/:episodeId、/drama/projects/:projectId/canvas

功能概述：从大纲到分集成片，资产可复用到各集。

细则见 docs/EPISODE_RULES.md、docs/SHOT_SPLITTING.md。

路径：/tools、/tools/:toolId

功能概述：不走完整短视频流水线的单点生成。

生图走统一任务平台；生视频返回任务 ID 供前端轮询。记录在个人中心「工具创作」。

路径：/pricing

功能概述：按上游真实用量（或估价）计费；开源默认按 TokenFree 官方成本、不再加价。充值走易支付。

本地与 Docker 默认关闭。开启后详见 docs/BILLING.md。

BILLING_ENABLED=true
BILLING_MARKUP=1.0
EPAY_API_URL=https://pay.gitcc.com
EPAY_PID=
EPAY_KEY=
# 生产 notify 不要带 /api/
# EPAY_NOTIFY_URL=https://your-site.example.com/epay/notify

路径：/settings

鉴权：Authorization: Bearer <token> 或 X-Api-Key。

注册登录 → 工作台选 AI 短视频 → 选模板与管线
  → 填写主题 / 文案 → 风格配置 → 开始生成
  → 分镜页审阅（可单镜重绘 / 重生）
  → 合成完成后在历史页下载

/drama 新建项目 → 分集工作台（创意 / 摘要 / 剧本）
  → 资产库（角色 / 场景 / 道具）
  → 解析成镜 → 分镜编辑出片

/tools 选能力 → 填提示词或上传参考 → 生成
  → 个人中心回看与下载

独立前端。Docker 端口 8081，本机开发 5174。管理员与用户共用登录接口，需 role=admin。

密钥在后台保存时加密入库；留空再保存表示不修改原值。

curl http://localhost:8000/api/health

关注 ok、task_runtime、db_pool、models。

• Docker：docker compose --env-file deploy/.env.docker logs -f api
• 开发：看 uvicorn / Vite 终端
• 仅中间件：docker compose -f deploy/docker-compose.yml --env-file deploy/.env.prod logs -f
• 重启 API 即可重载大部分环境变量；管理员提权必须重建 / 重启一次 API 容器或进程

• Postgres 卷：printfilm_pgdata（本机开发中间件为 ai_movie_pgdata）
• Redis 卷：printfilm_redisdata
• 成片：printfilm_media 或 backend/static/generated/
• down 不删数据；清库才加 -v

• Docker：docker compose --env-file deploy/.env.docker pull && docker compose --env-file deploy/.env.docker up -d
• 源码：拉代码 → pip install / npm install → 重启 API。启动时会跑 schema 补丁、模板 seed 与管理员 bootstrap。

完整列表以 deploy/.env.docker.example、backend/.env.example 为准。不要把真实 Key 写入文档或 Git。

欢迎 Issue 与 Pull Request。提交前请对照 docs/STANDARDS.md：

• 用户可见文案用简体中文；函数 / 组件顶部加功能注释
• 列表筛选与分页走服务端
• 不要提交 .env、密钥、deploy/scripts/deploy_kepu.py、.tmp/、生成媒体
• 单文件尽量不超过 500 行，公共逻辑放到 lib/ / services/ / components/

cd frontend && npm run lint
cd ../admin && npm run lint
cd ../backend && pytest

本项目采用 MIT License。

PRINTFILM
文档版本：0.2.0 | 2026-09-17