Pixelle-Video 如何用 Docker Compose 部署并检查服务健康状态？
【免费下载链接】Pixelle-Video🚀 AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video
Pixelle-Video 的 Docker 部署由三个容器组成：init负责确保配置文件的初始化，api运行 FastAPI 后端（端口 8000），web运行 Streamlit 前端（端口 8501）。本文的任务是：在装有 Docker Compose 的机器上把 Pixelle-Video 构建并启动起来，然后确认两个服务确实处于健康状态。部署定义在 docker-compose.yml 中，镜像基于 Dockerfile（Python 3.11-slim，内置 curl、ffmpeg、Playwright Chromium），启动前需要确认宿主机已安装 Docker Compose——项目自带的 docker-start.sh 脚本会同时检查docker-compose和docker compose两种命令是否存在，不存在会直接报错退出。
部署前先准备 config.yaml
容器启动时会把宿主机当前目录的./config.yaml挂载到/app/config.yaml（docker-compose.yml 中 api 与 web 两个服务都挂载了它）。如果config.yaml不存在，compose 里的init服务会在 api/web 启动前自动从 config.example.yaml 复制一份；如果config.yaml意外是一个目录（Docker 挂载不存在的文件会创建目录的问题），init 服务会将其删除并重新创建。
如果希望启动前就配好参数，手动执行一次即可：
cp config.example.yaml config.yaml需要按自己的环境修改的关键配置是 ComfyUI 地址。config.example.yaml 中默认值为：
comfyui_url: http://127.0.0.1:8188 # ComfyUI server URL (required for selfhost workflows)文件中的注释明确说明：Docker 用户应使用host.docker.internal:8188（Mac/Windows）或宿主机 IP 地址（Linux）替换127.0.0.1，因为容器内的127.0.0.1指向容器自身。自托管工作流（selfhost workflows）依赖这个地址能真正连到宿主机的 ComfyUI；此外脚本启动提示中还要求填写 LLM API key，RunningHub API key 为可选项（用于云端工作流）。启动后也可以在 Web UI 里继续配置这些设置。
构建并启动服务
在项目根目录（与 docker-compose.yml 同级）执行：
docker-compose build docker-compose up -d如果环境使用docker compose（带空格的新版插件），把命令中的docker-compose换成docker compose即可，两种形式 docker-start.sh 都支持。
构建阶段受USE_CN_MIRROR构建参数控制（默认false）。国内环境按 docker-compose.yml 头部注释的示例使用清华/阿里云镜像源加速构建：
USE_CN_MIRROR=true docker-compose up -d也可以直接运行项目自带的启动脚本：
./docker-start.sh该脚本会依次执行：若config.yaml是目录则rm -rf删除（这是它对当前目录文件的唯一破坏性操作，仅针对挂载事故产生的空目录）；若config.yaml不存在则从config.example.yaml复制；然后自动选择可用的docker-compose或docker compose执行build和up -d。副作用范围仅限当前目录的config.yaml，且仅在上述两种情况下才动它，其余时间与手动执行完全等价。
检查服务健康状态
docker-compose up -d之后，用以下三种方式核对两个服务。
1.docker-compose ps查看容器与健康标志
两个服务都配置了健康检查（docker-compose.yml 的healthcheck段），容器会周期性自检，状态异常时ps输出中会标记unhealthy：
- api：
curl -f http://localhost:8000/health，间隔 30s、超时 10s、重试 3 次、start_period10s； - web：
curl -f http://localhost:8501/_stcore/health，间隔 30s、超时 10s、重试 3 次、start_period15s。
因此服务刚启动后的头十几秒内状态可能还未就绪，属于健康检查的start_period覆盖范围，等待后重新执行docker-compose ps再判断。
2. 直接请求健康接口
curl http://localhost:8000/health这是 API 服务的健康端点，实现在 api/routers/health.py，返回的字段包括status（值为healthy）、version和service（Pixelle-Video API）。同文件里还有一个等价的GET /version端点返回相同信息。
Web 服务对应 Streamlit 自带的健康路径，compose 文件中使用的检查命令即为：
curl http://localhost:8501/_stcore/health3.docker-compose logs -f跟踪日志
确认某个服务是否反复重启、依赖安装或配置加载有无报错时，直接看日志。日志驱动配置为 json-file，单文件上限 10m、最多保留 3 个文件（logging段），不会无限膨胀。
docker-start.sh 启动完成后给出的常用命令可作参考：
docker-compose logs -f # 查看日志 docker-compose down # 停止并移除容器 docker-compose restart # 重启 docker-compose up -d --build # 重新构建并启动访问入口与持久化边界
服务就绪后，docker-start.sh 提示的三个入口是：
- Web UI：
http://localhost:8501 - API：
http://localhost:8000 - API 文档：
http://localhost:8000/docs
两个服务都把./data和./output挂载到容器内/app/data、/app/output，生成的视频产物和自定义资源（data/bgm/、data/templates/、data/workflows/会覆盖镜像内置的默认资源）落在宿主机目录中，容器删除不丢数据。镜像本身（ffmpeg、CJK 字体、Chromium 等）由 Dockerfile 在构建期一次性装好，运行时不再下载这些系统依赖。
需要注意的限制：
config.yaml不能是目录。正常情况下 init 服务会自动修复，手动排查时如果发现挂载点变成了目录，先删掉再重启。- 自托管 ComfyUI 工作流要求
comfyui_url指向容器可达的地址，127.0.0.1在容器内不通，这一点是容器化部署与直接运行最大的环境差异。 - 健康检查只覆盖 api（
/health）和 web（/_stcore/health）两个端点，上游依赖（LLM 接口、ComfyUI）是否可用不在健康检查范围内，需在 Web UI 发起实际任务时验证。
【免费下载链接】Pixelle-Video🚀 AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
