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

工程分析/实现方案-2026-05-18-22-23-07.md

@@ -0,0 +1,55 @@
+# 实现方案
+
+开始时间：2026-05-18-22-23-07
+
+## 容器化
+
+1. 新增 `Dockerfile`
+   - 基于 `python:3.12-slim`。
+   - 安装 `ffmpeg`、`libgl1`、`libglib2.0-0`、`libgomp1`。
+   - 安装 Docker 专用 `requirements-docker.txt`，OpenCV 使用 headless 版本。
+   - 复制 `backend`、`frontend`、`storage/samples`、`scripts`。
+   - 默认监听 `8001`。
+
+2. 新增 `requirements-docker.txt`
+   - 保留 FastAPI、Uvicorn、NumPy、scikit-image、Pillow 等运行依赖。
+   - 使用 `opencv-python-headless==4.13.0.92`，避免容器中额外 GUI 依赖和构建不稳定。
+
+3. 新增 `.dockerignore` 和扩展 `.gitignore`
+   - 排除 `.git`、缓存、测试产物、`storage/jobs`、`storage/uploads`、打包目录。
+
+## Compose 文件
+
+1. `docker_compose.yaml`
+   - 纯净模板。
+   - app 服务可直接构建启动。
+   - frpc 服务放在 `frpc` profile 中。
+   - 域名、FRP 地址、token、远端端口等以注释和环境变量形式标记为待填写。
+
+2. `docker_compose_huijutec.yaml`
+   - 直接运行版。
+   - app 端口映射 `10004:8001`。
+   - frpc 连接用户参考配置中的服务器和 token，`remotePort = 10004`。
+   - 预置 `PUBLIC_URL=https://isiseg.huijutec.cn`。
+
+3. `docker_compose_Nas.yaml`
+   - QNAP 版。
+   - build context 使用 `/share/Container/ISISeg`。
+   - 数据目录使用 `/share/Container/ISISeg/data/...`。
+   - 代理使用 `192.168.31.7:7893`。
+   - frpc 远端端口 `10004`。
+
+## 安装包
+
+- `isiseg-clean-install-2026-05-18-22-23-07.tar.gz`
+- `isiseg-huijutec-direct-2026-05-18-22-23-07.tar.gz`
+- `isiseg-qnap-nas-2026-05-18-22-23-07.tar.gz`
+
+每个包包含运行所需源码、Dockerfile、compose 文件和安装说明。
+
+## Gitea 发布
+
+- 提交代码到 main。
+- 创建 tag：`v2026-05-18-22-23-07-docker-packages`。
+- 调用 Gitea API 创建 release。
+- 上传三个 tar.gz 作为 release 附件。

工程分析/测试方案-2026-05-18-22-23-07.md

@@ -0,0 +1,50 @@
+# 测试方案
+
+开始时间：2026-05-18-22-23-07
+
+## 自动化测试
+
+- `python3 -m compileall backend tests`
+- `node --check frontend/app.js`
+- `pytest -q`
+
+执行结果：全部通过，`pytest -q` 为 `5 passed`。
+
+## Docker/Compose 校验
+
+- `docker compose -f docker_compose.yaml config`
+- `docker compose -f docker_compose.yaml --profile frpc config`
+- `docker compose -f docker_compose_huijutec.yaml config`
+- `docker compose -f docker_compose_Nas.yaml config`
+- `docker build -t isiseg:docker-package-test .`
+- 运行容器并请求 `/api/health`。
+
+执行结果：
+
+- 三个 compose 文件及纯净模板 frpc profile 均可解析。
+- Docker 镜像构建通过。
+- 测试容器 `/api/health` 返回 `{"status":"ok","service":"ISISeg","version":"0.1.0"}`。
+- 首次使用完整 `requirements.txt` 构建时，`opencv-python` 安装阶段触发段错误；已改为 Docker 专用 `requirements-docker.txt`，使用 `opencv-python-headless` 并保留运行时所需依赖。
+
+## 安装包校验
+
+- 检查三个 tar.gz 都存在。
+- 分别列出包内文件，确认包含 compose、Dockerfile、backend、frontend、样例视频和 README。
+- 解包后分别执行 compose config 校验。
+- 确认安装包内不包含 `__pycache__` 或 `.pyc`。
+
+执行结果：
+
+| 安装包 | SHA256 |
+| --- | --- |
+| `isiseg-clean-install-2026-05-18-22-23-07.tar.gz` | `dc62b411877271375b91833a48c933ff1201f87f9710626f4ba637c04eb039d1` |
+| `isiseg-huijutec-direct-2026-05-18-22-23-07.tar.gz` | `84df7476152dd98a44b5b6479bd713f639bd12485ee4385559c5571dfba8850e` |
+| `isiseg-qnap-nas-2026-05-18-22-23-07.tar.gz` | `f31bb0bc290b0d3e8f68721c16c638964dc80f6ac1a0b4d11063e4dcf80a71dd` |
+
+## Gitea 发布校验
+
+- push main。
+- push tag。
+- 创建 release。
+- 上传三个附件。
+- 查询 release 附件列表确认三个包均存在。

工程分析/经验记录.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. 后续如何避免问题：发布包生成后必须执行包内文件检查，至少确认无缓存、无临时目录、无本地数据和无敏感配置外泄。

工程分析/需求分析-2026-05-18-22-23-07.md

@@ -0,0 +1,25 @@
+# 需求分析
+
+开始时间：2026-05-18-22-23-07
+
+## 用户需求
+
+1. 系统可以通过 `docker_compose.yaml` 安装。
+2. 打包一个纯净安装包：
+   - 网络相关信息保留注释，作为待填写项。
+   - 适合迁移到任意环境后再配置域名、端口、FRP。
+3. 打包一个可直接运行安装包：
+   - 预置 `isiseg.huijutec.cn`。
+   - 参考用户提供的 frpc 配置。
+   - frpc 远端映射端口使用 `10004`。
+4. 打包一个威联通 NAS 版安装包：
+   - 提供 `docker_compose_Nas.yaml`。
+   - 参考 QNAP QTS / Container Station 的绝对路径和代理写法。
+   - 端口和 frpc 映射与直接运行版保持一致。
+5. 三个安装包都需要在 Gitea 发布。
+
+## 约束
+
+- 当前项目是 FastAPI 后端直接挂载静态前端，不需要单独 nginx。
+- OpenCV 和视频转码依赖 `ffmpeg`、系统图形/运行库，需要 Docker 镜像补齐。
+- 应保留内置样例视频，但不要把运行产生的 jobs/uploads 打进安装包。