企业官网建设流程全解析

Pixelle-Video 部署指南：3 条安装路径、2 个服务端口、1 张验收清单

【免费下载链接】Pixelle-Video🚀 AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video

Pixelle-Video 是一个 AI 全自动短视频引擎：输入主题或文案，它调用 LLM、图像/视频生成与 TTS 服务，产出可直接发布的短视频。本文按“自检 → 选型 → 实操 → 验收配置 → 排障”的路线，覆盖 Windows 一键整合包、源码安装、Docker 三种部署路径。读完你可以独立在自己的机器上完成环境搭建、启动 Web 界面到http://localhost:8501，并找到填入 LLM 密钥的配置入口。

启动前核对 5 项环境

先对照下表判断自己“达标/不达标”，再决定走哪条路径：

Docker 路径不依赖本地 Python，用 Docker 和 docker-compose（多容器编排工具）替代即可。确认完达标项，下面来选路径。

对比 3 条路径，选定安装方式

大多数读者的默认选择：Windows 普通用户走一键整合包，macOS / Linux 用户走 uv 源码路径，服务器部署走 Docker。下面逐条给出每步的最少操作和背后的机制。

一键整合包跑起来：4 个步骤

整合包已预装全部运行时依赖，你不需要自行安装 Python、uv 或 FFmpeg。

1. 下载：到项目 Releases 页下载最新的Pixelle-Video-v*-win64.zip（同目录附.sha256校验文件）。
2. 解压：放到不含中文与空格的路径（如D:\tools\），中文路径会导致脚本编码异常。
3. 校验（可选）：PowerShell 执行Get-FileHash Pixelle-Video-v*-win64.zip -Algorithm SHA256，与.sha256文件比对，确认下载未损坏。
4. 启动：双击start.bat，浏览器自动打开http://localhost:8501。

构建产物结构（见 packaging/windows/README.md）：

Pixelle-Video-v*-win64/ ├── python/ # 内嵌 Python 发行版（3.11.9） ├── tools/ # FFmpeg 等便携工具 ├── Pixelle-Video/ # 项目文件 ├── data/ # 用户数据（初始为空） ├── output/ # 视频输出目录（初始为空） ├── start.bat # 主启动器 ├── start_api.bat # API 启动器 ├── start_web.bat # Web 启动器 └── README.txt # 用户说明

start.bat 背后做了三件事（对照模板packaging/windows/templates/start.bat可核对）：把PYTHON_HOME指向内嵌 Python（python\python311）并把tools\ffmpeg\bin加入PATH，让音视频处理工具开箱即用；设置PYTHONPATH与PIXELLE_VIDEO_ROOT为项目目录，保证模块导入与资源路径解析不依赖当前工作目录；最后执行python -m streamlit run web\app.py，失败时窗口暂停显示错误而不是静默关闭。

跑起来后能看到什么：终端打印Launching Pixelle-Video Web UI...，浏览器落地到首页（含「⚙️ 系统配置」入口）——此时安装已完成，只差填密钥。

进阶：自行重建整合包。开发者可在仓库内执行python packaging/windows/build.py --cn-mirror重新构建；--cn-mirror开关让下载阶段切换清华 PyPI 与华为云 Python 镜像加速。构建参数由packaging/windows/config/build_config.yaml控制，关键项包括python.version（默认3.11.9）、ffmpeg.version（默认6.1.1）、playwright.install_browsers（是否预装 HTML 模板渲染用的 Chromium）、mirrors.use_cn_mirror。普通用户可跳过本段，继续看源码路径。

用 uv 或 pip 完成源码安装

步骤一：克隆仓库

git clone https://gitcode.com/GitHub_Trending/pi/Pixelle-Video cd Pixelle-Video

步骤二：安装依赖（二选一）

路径 A：uv（推荐）

curl -LsSf https://astral.sh/uv/install.sh | sh # 未装 uv 时先执行；已有可跳过 uv sync # 按锁文件同步全部依赖

uv sync是唯一的“安装”动作：它依据 pyproject.toml 声明的依赖、并按 uv.lock 锁定的精确版本创建虚拟环境，保证任何机器上装出可复现的环境。依赖清单按功能分五块，读者只需知道对应关系：Web 与 API（streamlit、fastapi + uvicorn）、LLM 与多模态（openai、dashscope、httpx）、图像/视频处理（pillow、moviepy、ffmpeg-python、comfykit）、模板渲染（playwright、beautifulsoup4）、TTS（edge-tts）。

HTML 模板渲染依赖无头浏览器（Playwright 管理的独立 Chromium，不要求系统装 Chrome）。计划生成视频的话先执行一次：

uv run playwright install chromium

路径 B：pip

python -m venv venv source venv/bin/activate # Windows 为 venv\Scripts\activate pip install -e . # 可编辑安装

pip install -e .以可编辑模式注册pixelle_video包，改代码后无需重装即生效；该路径没有锁文件，依赖版本按pyproject.toml声明的最低要求解析。

步骤三：启动

仓库根目录的 start_web.sh 内部执行的就是uv run streamlit run web/app.py，直接跑它即可：

bash start_web.sh

若在没装 uv 的源码包里直接执行start_web.bat，脚本会明确提示“改用一键包，或先装 uv 再执行uv sync”，按提示处理即可。

跑起来后能看到什么：与 Windows 路径一致，终端输出Starting Pixelle-Video Web UI...，浏览器落到http://localhost:8501。服务器场景请看下一条 Docker 路径。

用 Docker 部署 3 个服务

Docker-compose.yml 编排三个服务，各司其职：

• init（alpine 镜像）：启动前确保config.yaml存在，缺失时从config.example.yaml复制生成，规避“挂载不存在的文件会被 Docker 创建成目录”的坑；
• api：FastAPI 后端（Python 异步 Web 框架），监听0.0.0.0:8000，挂载./config.yaml、./data、./output实现配置与数据持久化，健康检查每30秒命中一次/health，日志按10MB × 3滚动；
• web：Streamlit 前端（Python Web 界面框架），监听0.0.0.0:8501，同样挂载配置与数据目录，并关闭使用统计上报。

镜像基于python:3.11-slim，构建阶段装好curl、ffmpeg、fonts-noto-cjk（中日韩字体渲染），并预装 Playwright Chromium；构建参数USE_CN_MIRROR（默认false）置为true时切换阿里云 apt 源与清华 PyPI 镜像，适合国内网络。

docker-compose up -d # 国际环境 USE_CN_MIRROR=true docker-compose up -d # 国内环境，镜像加速构建

跑起来后能看到什么：docker compose ps中api、web两个容器均为健康状态；浏览器打开http://localhost:8501出界面，8000端口可被程序化调用。接下来确认成功信号、填好配置文件。

验收启动，定位配置文件

config.yaml含敏感密钥，切勿提交到 Git（config.example.yaml文件头部同样有此警示）。

先看三个成功信号：

完成一次生成后，可对照一张模板样例输出检查版式：

再改配置。配置文件是仓库根目录的config.yaml，不存在时从 config.example.yaml 复制一份；或直接在 Web 界面「⚙️ 系统配置」页填写并保存——程序会以 UTF-8 写回config.yaml（保留中文、保持键顺序）。关键配置项：

自托管 ComfyUI 的用户：按 ComfyUI 官方文档安装并启动（默认监听http://127.0.0.1:8188），把同一地址填入comfyui_url即可；容器内访问宿主机 ComfyUI 时改用host.docker.internal:8188（Mac/Windows）或宿主机 IP（Linux）。没有本地显卡则直接填runninghub_api_key、选runninghub/前缀工作流，全程无需本地 ComfyUI。

启动与配置入口都已就位，最后把高频报错整理成急救清单。

🩹 处理 5 类常见故障

1. 现象：双击start.bat报错即退出 →根因：在源码包（非整合包）里运行，缺少内嵌 Python 与依赖 →修复：改用 Releases 页的一键包，或安装 uv 后先执行uv sync再重跑。
2. 现象：uv sync/pip install极慢或超时 →根因：直连 PyPI 不稳定 →修复：源码安装配置国内 PyPI 镜像；Docker 构建加USE_CN_MIRROR=true；整合包重建用--cn-mirror。
3. 现象：Web 界面正常，但生成视频必失败 →根因：LLM 密钥未填或 ComfyUI 地址不可达 →修复：进「⚙️ 系统配置」补全llm.api_key并测试连接；核对comfyui_url（默认http://127.0.0.1:8188），或切换到runninghub/云端工作流。
4. 现象：生成的模板中文显示为方块 →根因：系统缺中日韩字体 →修复：Docker 路径已预装fonts-noto-cjk，出此问题说明走的是源码路径，给系统安装 CJK 字体（如 Linux 的 Noto Sans CJK）后重跑。
5. 现象：Docker 里config.yaml是目录而非文件 →根因：挂载不存在的文件被 Docker 创建成了目录 →修复：compose 的 init 服务会自动清理重建，看到日志config.yaml is a directory, removing it后重新docker-compose up -d。

若以上都不对症，回头核对「三个成功信号」是否仍成立，问题通常仍在密钥或地址这一层。

下一步

• 打开配置说明：填入 LLM 与图像生成服务密钥，完成首次连通测试；
• 跟着快速开始生成你的第一条 AI 短视频。

【免费下载链接】Pixelle-Video🚀 AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video