📦 白板声画工坊 (cs-board) 详细部署教程

白板声画工坊是一个本地运行的 AI 视频制作工具，能将参考音频和中文文案自动生成为白板动画视频 (MP4)。它支持音色克隆、内容拆解、插画生成、手绘笔迹动画和字幕合成。所有素材、密钥和成片默认保存在本机，支持局域网协作。

⚙️ 部署前准备

硬件与系统要求

操作系统：Windows 10/11 或 macOS 15+ (Intel/Apple Silicon)。
处理器与内存：推荐至少 8GB 内存，CPU 性能影响渲染速度。
显卡：无硬性要求，CPU 可完成所有任务，但渲染视频时 GPU 能显著加速。

必须安装的依赖环境

依赖	版本要求	验证命令	备注
Python	3.11+	`python --version`	推荐 3.11 或 3.13
Node.js	22.13+	`node --version`	用于前端和视频渲染引擎
FFmpeg	最新版	`ffmpeg -version`	必须，并确保在系统 `PATH` 中
FFprobe	同 FFmpeg	`ffprobe -version`	必须，并确保在系统 `PATH` 中

需要提前准备的外部服务 (API 与密钥)

OpenLux API Key：需要具备文本模型 (如 gpt-5) 和图片模型 (如 gpt-image-2) 的调用权限。密钥仅保存在本机配置中。
IndexTTS 服务：一个可访问的 IndexTTS 2.5 服务端点 (Gradio 或 FastAPI 接口)，用于本地音色克隆。你需要自行部署或使用已有的服务。

🚀 安装与启动

步骤 1: 克隆仓库

1 2	git clone https://github.com/ChenShuo2004/cs-board.git cd cs-board

步骤 2: 安装依赖

根据你的操作系统，在项目根目录下执行对应的安装命令。

Windows (PowerShell)

# 1. 准备 Python 虚拟环境
python scripts/prepare_env.py

# 2. 安装后端 Python 依赖
.\.venv\Scripts\python.exe -m pip install -r webapp\requirements.txt

# 3. 安装前端 Node.js 依赖
Push-Location web
npm ci
Pop-Location

macOS / Linux

# 1. 准备 Python 虚拟环境 (请使用你的 Python 3.11+ 命令, 如 python3.13)
python3.13 scripts/prepare_env.py

# 2. 安装后端 Python 依赖
.venv/bin/python -m pip install -r webapp/requirements.txt

# 3. 安装前端 Node.js 依赖
(cd web && npm ci)

国内网络加速：如果 Python 依赖下载缓慢，可在上述 pip install 命令前添加 PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple。

步骤 3: 启动应用

执行对应平台的启动脚本，它会同时启动后端 API 和前端界面。

Windows: 双击 start-webapp.ps1 或在 PowerShell 中运行 .\start-webapp.ps1
macOS/Linux: 在终端中运行 ./start-webapp.sh

脚本运行后，会自动在浏览器中打开 http://127.0.0.1:13000/。如果未自动打开，请手动访问该地址。同一局域网内的其他设备也可通过脚本输出的局域网 IP 地址访问。

⚙️ 首次配置 (API 设置)

打开浏览器访问工作台后，点击右上角的 API 设置，填写并测试以下关键信息：

OpenLux API Key：填入你的密钥，它将保存在本机 .webapp/config.json 中。
文本模型：默认 gpt-5，用于拆解文案和生成分镜。
图片模型：默认 gpt-image-2，用于生成插画。
IndexTTS 地址与接口类型：填写你部署的 IndexTTS 服务地址 (Gradio 通常为 http://127.0.0.1:7860，FastAPI 通常为 http://127.0.0.1:8000) 并选择对应类型。
（可选）图片接口地址 / 图片 API Key：如果你的图片生成服务与文本服务分离，可在此单独配置。留空则自动沿用上方配置。

完成填写后，点击“测试连接”确保所有服务均可正常访问。

🎬 生成你的第一个白板视频

上传参考音频：录制或准备一段 10-30 秒的、单人且背景噪音少的音频文件。
输入中文文案：至少 10 个汉字，作为视频的口播内容。
选择制作模式：
- 标准制作：快速验证，系统自动完成分镜和插画。
- 自定义参考：上传风格参考图和最多 5 个角色的参考图，用于固定 IP 或品牌化内容。
- 动态信息图：适合知识讲解，内容会随语音时间轴逐步呈现。
选择视觉模板：从 12 种风格中选择，如“极简粗线简笔白板风”、“黑金科技发布会风”等，这会影响插画的配色、线条和材质。
点击“开始制作”：系统将按顺序执行音色克隆 → 内容拆解 → 插画生成 → 动画渲染 → 音画合成。整个流程可能需要几分钟到几十分钟，取决于文案长度和机器性能。你可以在任务队列中查看进度。

🔧 数据存储、运维与故障排查

项目数据与状态

所有本地配置、任务文件和成片都保存在项目根目录下的 .webapp/ 文件夹中。
重要：.webapp/、.env*、虚拟环境等目录已被 .gitignore 忽略，请勿将包含 API Key 或个人素材的目录提交到版本控制系统。

常见问题与解决

ffmpeg 或 ffprobe 命令找不到：
请确保这两个程序已正确安装，并且其所在目录已添加到系统环境变量 PATH 中。安装后请重启终端。
npm ci 或 pip install 失败：
通常是网络问题。对于 Python 依赖，可尝试使用国内镜像源。对于 Node.js 依赖，可尝试设置 npm 代理或使用 npm install --registry=https://registry.npmmirror.com。
IndexTTS 连接失败：
确认 IndexTTS 服务已启动，且 API 设置中的地址（包含端口号）和接口类型（Gradio/FastAPI）填写正确。
视频生成卡住或报错：
检查任务日志（可在界面中查看）。常见原因包括：OpenLux API 调用超时、参考音频过长、文案过于复杂导致分镜过多。可尝试缩短音频或文案、降低分辨率或重启任务。
macOS 14 及更低版本渲染问题：
当前 Remotion 版本在旧版 macOS 上视频渲染不保证成功，建议升级系统或使用 Windows 环境。