Blender 自动化渲染 Docker 学习项目模板

本项目为“学习 Docker + 构建 Blender 自动化建模/渲染流水线”之起始模版。提供 Dev / Test / Prod 分层结构、示例服务（API + Worker）、任务队列（Redis），以及渲染任务流程骨架（未真正集成 GPU / 真实 .blend 资产）。

目录结构

project-root/
  compose/              # 多环境 compose 文件
  infra/docker/         # 各服务 Dockerfile
  services/
    api/                # FastAPI 服务 (提交与查询任务)
    worker/             # 渲染 Worker (消费队列, 调用 Blender CLI)
  config/render_profiles/ # 渲染参数配置
  tests/                # 单元 / 集成 / 基线占位
  assets/               # .blend 及资源(示例为占位)
  scripts/              # 构建、运行、测试脚本
  .env.example

快速开始 (Dev)

1. 复制环境变量

cp .env.example .env

2. 构建并启动（开发版热加载）

docker compose -f compose/dev.yml up --build

3. 访问 API 文档

http://localhost:8000/docs

4. 提交渲染任务

POST /tasks  {"scene": "sample.blend", "profile": "draft"}

5. 查询状态

GET /tasks/{task_id}

任务流概念

API -> Redis (任务入列) -> Worker 取出 -> (调用 Blender CLI/Python 脚本) -> 产出上传(此模板暂写入本地) -> 状态更新

Blender 集成说明

当前 worker 基础镜像会尝试下载 Blender (默认 4.1.0)。如下载失败（网络或版本更新），修改构建参数：

DOCKER_BUILDKIT=1 docker build \
  --build-arg BLENDER_VERSION=4.1.0 \
  -f infra/docker/worker.Dockerfile -t blender-worker:dev .

Mac 本机制作无法使用 NVIDIA GPU；需在 Linux + NVIDIA Driver + nvidia-container-toolkit 环境中运行，并在 compose/prod.yml 中取消注释 GPU 配置片段。

渲染配置 (Profiles)

config/render_profiles/*.json 用于抽象质量档：分辨率、采样、是否开启降噪等。Worker 启动时按 profile 注入场景参数（模板中做示例解析）。

测试策略（模板最小化实现）

• 单元：任务 ID 生成、队列封装
• 集成：通过 test compose 发送一个任务并确认状态流转（后续可拓展）
• 渲染回归：tests/render_baseline/ 放置期望输出帧（此模板未提供真实图像，比对逻辑留空位）

安全 & 最佳实践要点（模板体现部分）

• 非 root 用户运行容器
• 多阶段构建 (Worker 先下载再精简)
• .dockerignore 减少上下文
• requirements 版本锁示例 (可扩展 constraints)

后续扩展建议

• 引入 Postgres 持久化任务状态
• 使用 Celery / RQ 替换手写 Redis list 简化可靠性
• 加入对象存储 (MinIO/S3) 上传帧图
• 引入 Prometheus 指标 & OpenTelemetry trace
• 增加渲染回归图像差异 (SSIM/MSE)
• K8s 部署 (Helm charts / GitOps)

常用脚本

./scripts/build.sh      # 构建所有镜像
./scripts/run_dev.sh    # Dev 模式 compose up
./scripts/test.sh       # 运行测试 (容器内)
./scripts/lint.sh       # 代码质量 (占位)

API 端点 (初稿)

• POST /tasks 提交任务
• GET /tasks/{id} 查询任务状态
• GET /healthz 健康检查

环境文件关键变量 (.env)

参见 .env.example，根据运行阶段进行覆盖或在 CI/CD 中注入。

许可证

此模板自由使用/修改。请自备合法 Blender 资产与插件。