在数字创作的世界里，最折磨人的往往不是缺乏灵感，而是从“想做一个视频”到“看到第一个画面”之间那道漫长的环境鸿沟。依赖冲突、系统版本不对齐、缺失的底层浏览器内核……报错的红字足以在一瞬间浇灭刚燃起的创作欲。
选择容器，并非为了追赶某种技术时髦，而是为了寻得一份安静。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:\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装好之后在容器里执行 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 restart1.3 验证服务
当一切尘埃落定，Docker 会在你的本机打通三个窗口：
- 操作台：
https://localhost:8501（Web 界面）
- 调度中枢：
https://localhost:8000（API 接口）
- 说明书：
https://localhost:8000/docs（API 文档）
在浏览器打开 https://localhost:8501，你将看到 Pixelle-Video 的全貌。
2 注入灵魂：核心系统配置
Pixelle-Video 本质上是一个调度中心，它自身并不生产算力，而是优雅地指挥外部的 AI 模型为你效劳。因此，首次进入 Web 界面，展开左侧的「⚙️ 系统配置」是必做的功课。
【局部流程图：系统配置与外部依赖关系】
2.1 赋予文采：配置 LLM
在预设下拉框中，你可以选择各类大模型厂商。若追求极致的稳定或零成本，甚至可以指向本地部署的 Ollama 地址。
获取对应平台的 API Key 并填入，这是赋予视频“思想”的钥匙。
这里选择 Custom 自定义厂商。蓝耘 MaaS 平台依然是一个值得推荐的选择。
- 获取密钥： 点击「
