2026-05-18-22-23-07 增加Docker安装包与发布配置

工程分析/经验记录.md

@@ -175,3 +175,35 @@ B. 产生问题原因：上一版使用“最近一次分割掩膜持续叠加
 C. 解决问题方案：后端生成右侧完整结果视频时改为每一帧都运行当前方法分割；`max_frames` 只控制下方结果卡片保存数量，不再控制主结果视频是否分割。关键帧卡片与视频对应帧用像素差测试校验一致性。
 
 D. 后续如何避免问题：用于播放的结果视频必须逐帧使用当前帧结果；抽帧限制只能用于结果列表、调参预览或摘要，不应用来偷换主视频的逐帧分割语义。
+
+## 2026-05-18-22-23-07 Docker 安装包与发布
+
+### 1. Docker 构建阶段 OpenCV 安装段错误
+
+A. 具体问题：用完整 `requirements.txt` 构建 Docker 镜像时，`pip install` 在安装 `opencv-python` 相关依赖后发生段错误，镜像无法稳定构建。
+
+B. 产生问题原因：服务端容器只需要无界面 OpenCV 运行时，完整 `opencv-python` 轮子会携带 GUI 相关依赖，构建阶段资源和二进制兼容风险更高。
+
+C. 解决问题方案：新增 `requirements-docker.txt`，将容器依赖收敛为运行时所需库，并使用 `opencv-python-headless==4.13.0.92`；Dockerfile 使用 `--no-cache-dir --no-compile` 安装，最终构建通过。
+
+D. 后续如何避免问题：服务端 Docker 镜像优先使用 headless 图像处理依赖，并将开发依赖与容器运行依赖拆分，避免把本地开发包完整带入生产镜像。
+
+### 2. Compose 模板注释块导致配置解析失败
+
+A. 具体问题：纯净模板最初只注释了 build args 的值，保留了空的 `args:`，`docker compose config` 解析失败。
+
+B. 产生问题原因：YAML 中空配置节点不是注释说明，Compose 会按实际配置校验类型。
+
+C. 解决问题方案：将整个可选 `args:` 块都注释掉，只保留待填写说明；需要代理时再整体取消注释。
+
+D. 后续如何避免问题：带 TODO 的 Compose 模板必须用 `docker compose config` 同时校验默认路径和可选 profile，确保注释示例不会变成无效配置。
+
+### 3. 安装包夹带 Python 缓存
+
+A. 具体问题：首次打包后安装包内包含 `__pycache__` 和 `.pyc`，不符合纯净安装包预期。
+
+B. 产生问题原因：自动化测试和 Docker 构建前已运行 Python 代码，工作目录中生成了缓存文件，打包清单没有排除。
+
+C. 解决问题方案：重新打包时排除 `__pycache__`、`.pyc`、临时目录和发布目录，并新增 `.gitignore` 避免后续误提交。
+
+D. 后续如何避免问题：发布包生成后必须执行包内文件检查，至少确认无缓存、无临时目录、无本地数据和无敏感配置外泄。