feat(gateway): 接入52号发际线接口与公开测试页

新增52号同路径转发，沿用现有主备派发、鉴权、队列和图片URL改写。空图片保留既有base64字段名，不带入worker算法及IP限制。同步52号测试页、图片解析和矩形叠加依赖，公开页面不包含内部Token。补全网关契约与部署文档，Nginx示例读取超时延长至660秒。验证：42项网关测试通过；临时网关连接真实GPU worker，5号三档与52号七型URL、长图裁切和边框均通过浏览器检查。
2026-11-04 11:15:58 +08:00
parent 44a6082938
commit 544c2a83d6
12 changed files with 918 additions and 2 deletions
@@ -0,0 +1,65 @@
+# 接口52：网关接入与部署
+
+`main`用于网关部署，本次只加入网关调用52号所需的路由、公开测试页及契约。GPU worker继续使用已部署的`ubuntu3090_debug`版本（`1c51f3e`及后续兼容版本），负责算法和本机IP限制；本次不把worker的算法、启动参数或IP中间件合并到网关。
+
+## 调用流程
+
+客户端 → `POST /api/v1/hairline/generate-52` → 网关现有队列和worker池 → worker同路径 → 网关落盘非空图片并返回公网URL。
+
+- 请求体原样转发，网关附加配置中的`X-Internal-Token`；客户端和公开测试页不携带内部密码。
+- 沿用现有主备派发、隔离期、重试、日志和全局并发限制。原有5号插队优先级保持原样，52号走默认队列。
+- 5号`/api/v1/hairline/generate`和其他接口保持原样；网关不新增IP限制。
+- worker的中下庭规则、扶正、3:4裁切和生发结果由同一次worker响应提供，网关不重新计算坐标。
+
+## 请求
+
+使用`multipart/form-data`；图片三选一：`image_file`、`image_url`、`image_base64`。必填`gender=male/female`和`hair_style=1..7`（支持逗号分隔多选）。
+
+可选参数全部透传：
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| normalize_image | false | true先扶正9→152并按当前规则裁切；网关测试页主动开启 |
+| generate_grow_image | true | false跳过ComfyUI，快速检查曲线和坐标 |
+| use_mask | true | 是否使用生发遮罩 |
+| prompt | 填充遮罩区域的头发，人物增加一点磨皮 | 生发提示词 |
+
+当前标准裁切高约`(3÷0.9)L`、宽`2.5L`，L为9→152像素距离；标准窗口不足时长图尝试保留人脸裁成3:4，其余仅扶正。具体状态以`framing`为准。
+
+## 响应及空图片
+
+worker始终返回`*_base64`。网关沿用原有公共改写，不添加52号专用的空字段改名规则：
+
+| worker字段 | 网关字段 |
+|---|---|
+| image_middle_base64（非空PNG） | image_middle_url |
+| input_image_base64、original_image_base64（非空JPEG） | input_image_url、original_image_url |
+| grown_image_base64（非空JPEG） | grown_image_url |
+| image_high_base64、image_low_base64（null） | 原字段保留，值为null |
+| grown_image_base64（null） | 原字段保留，值为null；没有grown_image_url |
+
+`height_rule`、每个样式的`height_placement`、`guide_landmarks`、`face_measure`、`framing`、`width/height`和中心点原样返回。开启预处理时`coordinate_space=processed_image`，middle必须叠加到`input_image_url`，原始图`original_image_url`仅供对照。
+
+公开测试页：`/static/test_interface52.html`，按原图、middle、矩形裁切发际线叠加、生发图排列。矩形左/右边过162/389，底边过9，高为9→152的70%。worker的30案例调试接口和对比报告不在本次网关同步范围。
+
+## 部署步骤
+
+1. 网关拉取`main`，保留原有`gateway/config.json`。
+2. 确保池中所有可能被选中的主/备worker都已提供`/api/v1/hairline/generate-52`；仅更新网关无法让旧worker获得52号功能。网关出口IP须在对应worker白名单内，当前GPU worker已允许`49.232.51.171`。无需在网关配置IP白名单。
+3. 重启网关服务（本仓库示例名`hair-gateway`）。若线上使用`nginx/hair-gateway.conf`，同步其中的读取超时并检查、重载Nginx。单张高分辨率生发已观察到超过100秒，本次示例从90秒改为660秒，覆盖默认600秒上游单次请求超时；多样式或重试时按总耗时另行调整。
+4. 先以`generate_grow_image=false`检查请求转发和URL，再在实际需要时验证生发。`/monitor`、worker主备配置和旧接口无需调整。
+
+```bash
+curl -X POST https://hair.xiangsilian.com/api/v1/hairline/generate-52 \
+  -F 'image_file=@/path/to/photo.jpg' \
+  -F 'gender=male' -F 'hair_style=1' \
+  -F 'normalize_image=true' -F 'generate_grow_image=false'
+```
+
+成功时`code=0`，检查`input_image_url`和`hairline_images[].image_middle_url`可打开、尺寸一致；high/low仍为`*_base64: null`。访问测试页时无需输入内部Token。
+
+## 验证
+
+`tests/test_gateway_interface52.py`覆盖5/52路由分离、完整表单透传、由网关注入内部Token、真实公共转发函数的图片落盘与URL可访问、空字段保持原样和队列槽释放。现有pool、serialization、monitor、reqlog测试用于防止回归。
+
+2026-11-04验证结果：上述网关测试共42项通过。另起本机临时网关连接当前真实GPU worker，浏览器验证旧5号仍返回三档，52号女性7型均返回可访问的图片URL，长图输出1062×1416，矩形叠加与空字段正常，页面请求不携带内部Token，无脚本错误。本轮关闭生发以验证网关链路，未重新运行ComfyUI生发；临时网关验证后关闭。