feat: 新增52号发际线接口并限制GPU worker来源IP
保留5号历史三档实现，新增中下庭高度定位、扶正裁切、矩形叠加与30案例对比页。 worker仅允许本机和配置白名单访问；网关不增加IP限制。空图片URL字段改写限定为52号，保持旧接口兼容。同步接口、裁切与部署文档。 验证：113项测试通过；1项历史数值基线失败，在未修改的a3fddbb版本复现。浏览器验证5/52及30案例对比页通过。
This commit is contained in:
+18
-5
@@ -13,21 +13,22 @@
|
||||
```
|
||||
客户端 ──HTTPS──> 外网网关(gateway/) ──HTTP(X-Internal-Token)──> worker(GPU 机, app.py)
|
||||
│ 薄代理 + 落盘改URL │ 跑算法(本地模型/ComfyUI/change_hair)
|
||||
└ 接口4(豆包)/99(特殊点) 本机实现(不转发) └ 接口1/2/3/5/6/7/9/10/11/12 + 工具路由
|
||||
└ 接口4(豆包)/99(特殊点) 本机实现(不转发) └ 接口1/2/3/5/52/6/7/9/10/11/12 + 工具路由
|
||||
```
|
||||
|
||||
- **worker**（`app.py` + `face_analysis/` + `hairline/`）：跑真正的算法，除 ComfyUI/change_hair 走本机
|
||||
回环外无外网依赖。对 `/api/*` 校验 `X-Internal-Token`（密码在 `worker_config.json` 的 `accept_passwords`）；
|
||||
`/health` 模型就绪才返回 200。监听 **8187**（systemd `hair-worker.service`，也可 `./run_worker.sh` 手动起）。
|
||||
另有 worker 本机的工具路由：`/api/swapHair/v1`、`/hairColor/v2`（CORS 代理转发 change_hair:8801）、
|
||||
`/api/v1/redraw`（直接 ComfyUI 重绘）、`/api/v1/debug/*`（免鉴权调试）。
|
||||
`/api/v1/redraw`（直接 ComfyUI 重绘）、`/api/v1/debug/*`（免Token调试，仍受IP限制）。
|
||||
所有动态路径先校验直连来源IP：允许本机与网关`49.232.51.171`，其余返回HTTP403/code1010；`/static/`除外。配置见[`接口IP白名单.md`](接口IP白名单.md)，网关侧不增加IP限制。
|
||||
- **网关**（`gateway/`）：薄反向代理，健康检查/派发/鉴权/把 worker 的 `*_base64` 落盘改成 `*_url`。
|
||||
网关本机实现的接口（不转发 worker）：**接口4**（调外网豆包）与**接口99**（纯 CPU 特殊点检测，
|
||||
直接 import 同仓库 `face_analysis/special_points`，`_if99_lock` 单路排队）。
|
||||
- **图片三选一**：所有接口图片入参 `image_file`/`image_url`/`image_base64` 严格三选一（接口3 是 `marked_image_*`）。
|
||||
- **响应信封**：`{code, message, request_id, data}`；业务错误用 `code`（HTTP 一律 200）。
|
||||
- **响应信封**：`{code, message, request_id, data}`；业务错误用 `code`（HTTP 200）；IP拒绝为HTTP403/code1010，Token错误为HTTP401/code1009，依赖健康异常为HTTP503。
|
||||
|
||||
### base64 → URL 映射（网关落盘改写，递归进数组、可空保留 null）
|
||||
### base64 → URL 映射（网关落盘改写，递归进数组）
|
||||
|
||||
| 接口 | worker 字段（内部） | 对外字段 |
|
||||
|------|--------------------|----------|
|
||||
@@ -36,6 +37,7 @@
|
||||
| 2 | `results[].image_base64` / `results[].grown_image_base64`(可空) | `results[].image_url` / `results[].grown_image_url` |
|
||||
| 3 | `hair_growth_image_base64`(可空) | `hair_growth_image_url` |
|
||||
| 5 | `hairline_images[].image_{middle,high,low}_base64` / `grown_image_base64`(可空) | `hairline_images[].image_{middle,high,low}_url` / `grown_image_url` |
|
||||
| 52 | `hairline_images[].image_{middle,high,low}_base64` / `grown_image_base64`、`input_image_base64` / `original_image_base64` | 同名 `*_url`，空图片也改为`*_url: null` |
|
||||
| 9 | `steps_common.*_base64`、`bisenet|segformer.{hair,closed_region,final_overlay,mask}_mask_base64` 等 | 同名 `*_url` |
|
||||
| 10 | `steps_common.*_base64`、`bisenet|segformer.{base_mask,contour,band_overlay,mask}_base64` 等 | 同名 `*_url` |
|
||||
| 11 | `steps.{input,baseline,hair_mask,mask_overlay,mask,swap_raw,alpha,final}_base64` | `steps.*_url` |
|
||||
@@ -43,13 +45,14 @@
|
||||
| 4 | （网关本机产出，无图片字段，`features` 为 JSON 字符串） | — |
|
||||
|
||||
> 实现建议：递归遍历 data，凡 key 以 `_base64` 结尾就落盘改 `_url`，自动覆盖嵌套/新增字段。
|
||||
> 兼容约定：接口52显式开启空图片字段改名；接口2/3/5等旧接口仍保留空图片的`*_base64: null`字段名。有图片时均落盘为`*_url`。
|
||||
> **图片格式**：接口1 标注图含透明用 **PNG**；接口2/3/5 是不透明照片用 **JPG**(小很多，~9×)。
|
||||
> 网关落盘按内容嗅探扩展名（PNG 头→`.png`，否则 `.jpg`）。
|
||||
|
||||
### 错误码
|
||||
|
||||
`1001` 无法识别人像 ｜ `1002` 分辨率过低 ｜ `1003` 非正面 ｜ `1004` gender 必填/非法（接口2/5/7）｜
|
||||
`1006` >1MB ｜ `1007` 图片参数错误（0或多个）/未预期异常 ｜ `1008` 格式不支持。
|
||||
`1006` >1MB ｜ `1007` 图片参数错误（0或多个）/未预期异常 ｜ `1008` 格式不支持 ｜ `1009` Token鉴权失败 ｜ `1010` worker来源IP不允许或白名单配置无效。
|
||||
|
||||
---
|
||||
|
||||
@@ -99,6 +102,15 @@
|
||||
- **做什么**：入参同接口2（`gender` + 多选 `hair_style` 必填）。对每个选中发型 → `middle`/`high`/`low` 三档发际线叠图 + 生发图 + 首个选中发型的面部中间点坐标。
|
||||
- **怎么实现**：复用接口2 的 502 点渲染管线，三档分别用 `hairline_texture[/_high|/_low]` 同名贴图渲染叠图；生发同接口2（ComfyUI inpaint），**黑模板固定取 `hairline_texture_black/`（middle）**，每发型 1 张生发图。`best_hairline_center_point`=眉心 x × 首个选中发型 middle 档发际线 y。
|
||||
|
||||
### 接口52 发际线PNG生成 `/api/v1/hairline/generate-52`（worker）
|
||||
- **预处理**：`hairline/framing.py`先扶正9→152，再按高(3÷0.9)L、宽2.5L（3:4）做原像素裁切，人物相对原3L规则缩小约10%。L为9→152距离；眉心位置沿用已扶正参考图比例。长图的标准窗口不足时，求原图内最大的3:4窗口，通过可行区域约束保留全部人脸关键点，并尽量贴近目标眉心位置；无法保留人脸时回退仅扶正。其余图片空间不足时仍仅扶正、去除旋转空角。参考图与参数由`scripts/calibrate_hairline_framing.py`生成。公开接口为兼容旧调用默认关闭预处理，`normalize_image=true`开启；规则页显式开启，对比调试页默认开启。返回当前底图、原图及双向坐标矩阵。
|
||||
- **目标高度**：`上庭=(中庭+下庭)/2`，用当前底图测量的未取整像素坐标（眉心9、鼻翼下缘94、下巴152）算目标中心。测量失败时用发际线管线同编号点计算并标注来源。
|
||||
- **模板定位**：原有502点/贴图生成形状，`hairline/height_rule.py` 将每种 middle 曲线沿面部向上方向平移、校准中心 Y，保留曲线形状与倾斜。此规则仅接口52使用，接口2保持原逻辑。
|
||||
- **生发**：移动后的预览曲线直接生成黑线和重绘遮罩，再送ComfyUI，避免预览与黑模板位置不一致。
|
||||
- **裁切叠加预览**：测试页新增“裁切发际线叠加”。`static/hairline_reference_box.js`共享同一个162/389/9/152参考框几何，按原图像素裁切middle透明图层，再叠加到处理后人像；四栏顺序为原图、middle、裁切发际线叠加、生发图。
|
||||
- **兼容**：high/low不再生成，图片与中心点字段保留为null。网关`gateway/forward.py`仅为接口52开启空图片`*_base64`→`*_url: null`，旧接口空字段名保持原样。部署52路由时同步该改写；网关不增加IP限制。`face_measure`为当前底图测量；新增`height_rule`与各项`height_placement`说明设计目标与实际误差。
|
||||
- **测试**：规则页`static/test_interface52.html`，对比页`static/test_interface52_compare.html`；运行`scripts/compare_hairline_height.py`默认保存全部30张×男女各7型，共420组对比。每人一行，顺序为未裁切原图、单张旧规则图、全部新规则样式，支持位置对照、额头特写、同图叠线和上传新图。新图可叠加162/389两侧、底边经过9、高度为9→152距离70%的参考框。原图与叠图按需加载。
|
||||
|
||||
### 接口9 头发遮罩 `/api/v1/head/mask`（worker）
|
||||
- **做什么**：人像照 → 头发遮罩 + 全流程分步可视化。
|
||||
- **怎么实现**（`face_analysis/head_mask.py`）：MediaPipe 底部分割线（21/68/104/69/108/151/337/299/333/298/251 连线，21/251 水平延伸）→ 线以上为上半区 → BiSeNet 与 SegFormer 双路头发分割、逐列向下填充到分割线得闭合区域（头发+额头）→ 外缘朝 151 内缩 `erode_cm`(默认1.2cm，虹膜标定) → 最终遮罩。返回 `steps_common` + `bisenet`/`segformer` 两组各四张图。
|
||||
@@ -126,6 +138,7 @@
|
||||
## 3. 部署 / 环境要点
|
||||
|
||||
**worker（GPU 机，本机 = gpu_worker 角色）**
|
||||
- 启动使用`./run_worker.sh`或`hair-worker.service`，均显式传`--no-proxy-headers`以保留直连来源IP。部署时复制`ip_access.example.json`为`ip_access.json`并核对网关IP；运行配置不入Git，改动即时生效。旧启动方式也应补上此参数，详见[`接口IP白名单.md`](接口IP白名单.md)。
|
||||
- Python **3.10.12**（本机 venv 在 `./venv`）；`numpy<2`(1.26.4)，`scikit-image==0.24.0`
|
||||
（**别升 0.25+，会顶 numpy≥2 顶崩 mediapipe**）。
|
||||
- 本机 **RTX 4090**：venv 实装 `torch 2.7.1+cu128`，CUDA 可用（BiSeNet/SegFormer GPU 推理）。
|
||||
|
||||
Reference in New Issue
Block a user