Printfilm AI 短剧创作平台详细部署教程

Printfilm 是一款一站式的 AI 短剧创作 SaaS 平台，它集成了项目管理、短剧生产流水线（DramaForge）和无限画布工作流，并支持通过 TokenFree 和火山方舟 Seedance 调用文生图、文生视频等模型。本文将根据官方文档，详细介绍在本地开发环境和生产服务器上的部署流程。

一、部署前准备

在开始安装之前，请确保你的服务器或开发机满足以下最低要求：

组件 版本要求
Node.js ≥ 20.x
npm ≥ 10.x（随 Node 安装）
Java 21 (JDK)
Maven 3.9+
Docker 24+（部署用）
Docker Compose v2
操作系统 Linux / macOS / Windows（推荐 Linux 或 macOS）

获取代码

1
2
3
# 克隆主代码仓库（注意：代码实际托管在 gitcc.com）
git clone -b main https://www.gitcc.com/yi-ee/ai-manju.git
cd ai-manju

端口规划

服务 端口 说明
Web 前端 7050 Next.js 开发/生产
API 后端 7051 REST + SSE
PostgreSQL 7052 仅 docker-compose.yml 映射
Redis 7053 仅 docker-compose.yml 映射

二、本地开发启动（分步指南）

第一步：启动中间件（PostgreSQL + Redis）

使用 Docker Compose 快速启动数据库和缓存：

1
docker compose up -d

这将在后台运行 PostgreSQL（端口 7052）和 Redis（端口 7053）。

第二步：配置前端环境变量

1
2
# 复制示例环境变量文件
cp apps/web/.env.local.example apps/web/.env.local

编辑 apps/web/.env.local 文件，设置 API 基址（通常为开发默认值）：

1
NEXT_PUBLIC_API_URL=http://localhost:7051

第三步：配置后端（可选，推荐）

1
2
# 复制示例配置文件
cp services/api/application-local.yml.example services/api/application-local.yml

在 services/api/application-local.yml 中，你可以填写 TokenFree 和火山方舟的 API Key。注意：这些 Key 也可以在 Web 界面中配置，因此此步骤不是必需的。

第四步：安装依赖并启动 API 服务

1
2
3
4
5
# 在项目根目录安装所有 Node.js 依赖
npm install

# 启动后端 API 服务（Spring Boot）
npm run api:dev

或者，你也可以切换到 API 目录并使用 Maven 启动：

1
2
cd services/api
mvn spring-boot:run -Dspring-boot.run.profiles=local

第五步：启动前端服务

打开一个新的终端窗口，在项目根目录下运行：

1
npm run dev

第六步：验证安装

检查项 地址 / 命令 期望结果
API 健康检查 http://localhost:7051/api/v1/health 返回 {"status":"UP"}
前端首页 http://localhost:7050 显示创作中心页面
命令行验证 curl http://localhost:7051/api/v1/health 返回 JSON 健康信息

三、Docker 全栈部署（推荐生产环境）

项目提供了 docker-compose.full.yml 文件，用于一键部署包含所有服务的全栈应用，并使用预构建的阿里云 ACR 镜像。

第一步：准备环境变量

在项目根目录下，为生产环境设置必要的环境变量（务必修改默认密码和密钥）：

1
2
3
4
5
export JWT_SECRET=your-production-jwt-secret-at-least-32-chars
export TOKENFREE_API_KEY=sk-your-tokenfree-key
export ARK_API_KEY=your-ark-seedance-key
export API_BASE_URL=           # 生产留空，由 Nginx 处理同源请求
export IMAGE_TAG=latest

第二步：拉取镜像并启动服务

1
2
3
4
5
# 拉取最新的 ACR 镜像（API 和 Web）
docker compose -f docker-compose.full.yml pull

# 在后台启动所有容器
docker compose -f docker-compose.full.yml up -d

第三步：访问与验证

  • 前端：http://<你的服务器IP>:7050
  • API 健康检查：http://<你的服务器IP>:7051/api/v1/health

第四步：查看日志与停止服务

1
2
3
4
5
# 查看 API 日志
docker compose -f docker-compose.full.yml logs -f api

# 停止所有容器
docker compose -f docker-compose.full.yml down

数据持久化

Docker Compose 会自动创建以下卷来持久化数据，即使容器删除，数据也不会丢失：

  • postgres_data：数据库
  • redis_data：缓存
  • api_media：生成的媒体文件
  • api_uploads：用户上传文件

四、生产部署（带 HTTPS）

对于正式上线，推荐使用 docker-compose.prod.yml 配合宿主机的 Nginx 提供 HTTPS 支持。

第一步：配置生产环境变量

1
2
cp .env.prod.example .env.prod
# 编辑 .env.prod，填写所有必需的密钥、密码和域名

第二步：启动生产容器

1
2
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

此配置中，Web 和 API 服务只会绑定到容器的内部端口，由宿主机 Nginx 反向代理并处理 TLS 证书。

第三步：配置宿主机 Nginx

项目提供了 Nginx 配置示例 deploy/nginx/printfilm.conf，你需要将其复制到你的 Nginx 配置目录，并根据实际域名修改 server_name 和 SSL 证书路径。

1
2
3
4
5
6
# 关键配置：将 /api/v1/ 请求转发到后端 API 服务
location /api/v1/ {
    proxy_pass http://127.0.0.1:7051;
    proxy_set_header Host $host;
    # ... 其他代理设置
}

五、常见问题与排查

问题 可能原因 处理建议
前端无法调用 API API_BASE_URL 未配置或 Nginx 反代错误 生产环境留空 API_BASE_URL，确保 Nginx 正确转发 /api/v1/ 路径。
登录报 403 错误 CORS 配置未包含你的前端域名 设置环境变量 CORS_ALLOWED_ORIGINS=https://你的域名.com。
提示“请配置 TokenFree Key” 未设置 AI 服务 Key 在 Web 界面「API Key 设置」中填写，或配置 TOKENFREE_API_KEY 环境变量。
视频任务一直排队 火山方舟 Key 未配置或模型未开通 检查 ARK_API_KEY 是否正确，并在火山方舟控制台确认 Seedance 服务已开通。
Docker 部署后无法登录 数据库为全新实例，默认管理员账号可能未创建 确保 ADMIN_AUTO_CREATE=true（默认），使用默认管理员邮箱 admin@printfilm.local 和密码 admin123456 登录，生产环境务必修改。
SSE 连接断开 浏览器关闭页面或网络超时 正常现象，不影响服务器端任务执行。

请注意：本项目当前版本为 v0.1.0，处于快速迭代中。部署生产环境前，请务必修改所有默认密码（JWT、数据库、管理员账号）并配置 HTTPS。如果你在使用中遇到问题，可以查阅项目内的 docs/部署指南.md 获取更详细的排障信息。