在数字创作的世界里，最折磨人的往往不是缺乏灵感，而是从“想做一个视频”到“看到第一个画面”之间那道漫长的环境鸿沟。依赖冲突、系统版本不对齐、缺失的底层浏览器内核……报错的红字足以在一瞬间浇灭刚燃起的创作欲。
我们之所以选择容器，并不是为了追赶某种技术时髦，而是为了寻得一份安静。Docker 就像是给这套复杂的 AI 程序打包了一个独立的小宇宙——里面空气清新，气候恒定，不沾染你宿主机上的一丝杂乱。
当你准备好 Docker 与 Docker Compose 后，通往 Pixelle-Video 的路其实只有短短的三步：拉取代码，启动容器，然后在浏览器里配置你的生成逻辑。至于中间那些泥泞的坑洼，这份指南会陪你一一跨过。
1 沙盒筑基：Docker 一键部署
1.1 拉取与构建
一切的开端，始于将代码拉取至本地：
git clone https://github.com/AIDC-AI/Pixelle-Video.git
cd Pixelle-Video
随后，我们将启动构建流程。由于国内网络环境的特殊性，建议在构建时开启镜像加速。
💡 终端语法差异提示： 如果你使用的是 PowerShell，环境变量的声明方式较为优雅，需用
$env:起头，并用分号;衔接后续命令：
$env:USE_CN_MIRROR="true"; docker compose build --no-cache
等构建完成后，再运行启动命令（同样带上环境变量）：
$env:USE_CN_MIRROR="true"; docker compose up -d
若你更偏爱传统的 CMD 命令行，则使用 set 与 && 的组合：
set USE_CN_MIRROR=true && docker compose build --no-cache
set USE_CN_MIRROR=true && docker compose up -d
1.2 破局：Playwright 安装问题排查
在理想的情境下，构建会一气呵成。但现实中，你可能会在 Playwright（用于无头浏览器渲染的底层库）这一步遭遇阻碍。
解决之道在于“化整为零”： 用任意编辑器打开项目根目录下的 Dockerfile，找到那段包含 playwright install --with-deps chromium 的代码块，将其临时删去，只保留 Python 依赖的安装：
RUN export UV_HTTP_TIMEOUT=300 && \
uv venv && \
if [ "$USE_CN_MIRROR" = "true" ]; then \
uv pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple; \
else \
uv pip install -e .; \
fi && \
playwright install --with-deps chromium
改成：
RUN export UV_HTTP_TIMEOUT=300 && \
uv venv && \
if [ "$USE_CN_MIRROR" = "true" ]; then \
uv pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple; \
else \
uv pip install -e .; \
fi
保存后，重新执行上述的 build 与 up 命令。此时容器能顺利跑起来，但我们还需要把缺失的浏览器内核补上。
潜入容器内部：
在终端输入：
docker exec -it pixelle-video-api bash
如何判断是否进入到了容器内容，别着急，继续往下看
如果成功，你会发现最左边的提示符变了。
-
之前是：
PS G:\222\Pixelle-Video> -
现在会变成类似这样：
root@1a2b3c4d5e6f:/app#
只要看到类似 root@xxx:/app#，就说明你已经进入 Docker 容器内部（Linux 环境）了！
然后在当前内部环境下，输入下面的命令进行安装
export UV_HTTP_TIMEOUT=300
uv pip install playwright -i https://pypi.tuna.tsinghua.edu.cn/simple
playwright install --with-deps chromium
🕵️ 为什么不能直接输入
playwright？ 项目使用了uv venv在/app/.venv下创建了隔离的虚拟环境。可执行文件被安放在.venv/bin/的深处，而非系统的公共路径/usr/local/bin/。理解了这个层级关系，就不会感到迷惑。
跑完后直接退出就行
装好之后在容器里执行：
exit
回到 PowerShell，然后重启让环境生效：
docker compose restart
如果你是在 pixelle-video-api 里装的，但 Web 页面打开报浏览器/Chromium 相关错，那就再对 pixelle-video-web 也执行一遍同样的命令：
docker exec -it pixelle-video-web bash
# 进入后再执行：
export UV_HTTP_TIMEOUT=300
uv pip install playwright -i https://pypi.tuna.tsinghua.edu.cn/simple
.venv/bin/playwright install --with-deps chromium
exit
然后 docker compose restart。
1.3 验证服务
当一切尘埃落定，Docker 会在你的本机打通三个窗口：
- 操作台：
http://localhost:8501(Web 界面)
- 调度中枢：
http://localhost:8000(API 接口)
- 说明书：
http://localhost:8000/docs(API 文档)
在浏览器打开 http://localhost:8501，你将看到 Pixelle-Video 的全貌。
2 注入灵魂：核心系统配置
Pixelle-Video 本质上是一个调度中心，它自身并不生产算力，而是优雅地指挥外部的 AI 模型为你效劳。因此，首次进入 Web 界面，展开左侧的「⚙️ 系统配置」是必做的功课。
【局部流程图：系统配置与外部依赖关系】
2.1 赋予文采：配置 LLM
在预设下拉框中，你可以选择各类大模型厂商。若追求极致的稳定或零成本，甚至可以指向本地部署的 Ollama 地址。
获取对应平台的 API Key 并填入，这是赋予视频“思想”的钥匙。
这里我选择Custom自定义厂商。这里我选择的依旧是**蓝耘MaaS平台****。嘎嘎好用**
- 获取密钥：点击「🔑 获取 API Key」前往对应平台申请，填入输入框。
2.2 赋予视觉：配置图像生成服务
这里有两种路径供你选择：
-
**本地造物：**填入本地 ComfyUI 的地址。
⚠️ Docker 网络的破壁法则： 切记，Pixelle 运行在 Docker 的沙盒内，它眼中的
127.0.0.1是容器自己，而非你的电脑。因此，地址必须写为host.docker.internal:8188（Win/Mac 适用）或宿主机的实际内网 IP（Linux 适用），这样才能穿透容器壁垒，握手宿主机上的 ComfyUI。 -
**云端捷径：**填入云端服务（如 RunningHub）的 API Key，开箱即用。
配置妥当后，点击「测试连接」，看到绿灯亮起，即可保存配置。
3 挥棒指挥：视频生成操作指南
配置就绪后，便进入了最令人期待的流水线作业环节。整个界面的布局宛如一张调音台：左输入、中调音、右输出。
【全局流程图：一条视频的诞生始末】
3.1 意念落笔（左侧栏）
你可以输入诸如“为什么养成阅读习惯”的主题，让 LLM 为你铺陈文案；也可以直接抛入精心打磨的脚本。
关于背景音乐（BGM），除了内置音源，Docker 的 Volume 挂载技术允许你将本地 MP3 文件丢进宿主机的 data/bgm/ 文件夹，容器会自动感知并映射。
3.2 勾勒轮廓（中间栏）
- **声音的形状：**选择 TTS 工作流（如 Edge-TTS）。若需定制音色，上传一段几秒钟的参考音频，点击「预览语音」试听，确保叙述者的灵魂附体。
-
**画面的皮囊：**指定图像生成工作流（默认
image_flux.json）。在提示词前缀中填入如“Minimalist black-and-white matchstick figure style illustration”
（极简黑白火柴人风格插画）这样的描述，点击「预览风格」进行微调。
- **承载的容器：**选择对应的 HTML 视频模板。同样，你可以通过替换宿主机
data/templates/目录下的文件，来实现自定义模板的永久挂载。
3.3 见证奇迹（右侧栏）
一切设定停当，点击右上角的「🎬 生成视频」。 此时，你只需静静看着进度条推进。系统会在后台如同精密的钟表般运转：拆分镜头、并发生成图像与语音、混入 BGM、按照模板排版…… 最终的视频将被持久化保存在宿主机的 output/ 目录下。无论你日后如何删除或重建容器，这份作品都不会遗失。
4 运筹帷幄：运维与自动化
4.1 日常运维心法
Docker 赋予了我们随时重来、却又不必担心的底气。掌握几条简单的命令，足以应对日常所需：
-
听诊排错：
docker compose logs -f（实时追踪日志，是排查报错的第一利器） -
休眠服务：
docker compose down（优雅停止并移除容器，但不删数据） -
版本更迭：
docker compose up -d --build（拉取最新代码后，一键重新构建并启动）
4.2 配置的永恒
首次启动时，系统会以 config.example.yaml 为蓝本，在项目根目录生成 config.yaml。你在 Web 界面点下的每一次“保存”，都会被刻录进这个文件。得益于 Docker Volume 的映射机制，这份配置拥有了超越容器生命的永恒性。
4.3 跨越界面的自动化
当你不再满足于点击界面，渴望将 Pixelle-Video 嵌入到自己的内容生产流水线中时，API 便是对你敞开的后门。 访问 http://localhost:8000/docs 这里有基于 Swagger UI 生成的详尽接口说明书。按照其中的参数格式，发送一个简单的 POST 请求，你就可以在另一台服务器、一个定时脚本、甚至是一篇博客的发布钩子中，悄无声息地批量生成视频。
尾声
折腾环境的过程，本质上是在和工具较劲；而创作的过程，应该是人和灵感的共舞。
Pixelle-Video 通过 Docker 这种形式，把那些繁琐的依赖、冲突、环境变量统统锁进了一个黑盒里。它退到了幕布后面，安安静静地做一个不知疲倦的齿轮。
无论你是喜欢坐在屏幕前，在 Web 界面里一点点调整提示词、试听音色，享受亲手打磨一件作品的掌控感；还是倾向于写一段脚本，通过 API 让服务器在深夜里自动渲染出上百条视频，去迎合流量的规则——这套工具都能接得住。
代码库会陈旧，框架会迭代，但把复杂留给自己、把简单交给用户的做事哲学不会变。现在，环境已经跑通了，浏览器里的页面正空空荡荡地等着你。
去填满它吧。去输入你的第一个主题，去生成属于你的第一帧画面。至于剩下的事，交给容器就好。
