# 接口52：网关接入与部署

`main`用于网关部署，本次只加入网关调用52号所需的路由、公开测试页及契约。GPU worker继续使用已部署的`ubuntu3090_debug`版本（`1c51f3e`及后续兼容版本），负责算法和本机IP限制；本次不把worker的算法、启动参数或IP中间件合并到网关。

## 调用流程

客户端 → `POST /api/v1/hairline/generate-52` → 网关现有队列和worker池 → worker同路径 → 网关落盘非空图片并返回公网URL。

- 请求体原样转发，网关附加配置中的`X-Internal-Token`；客户端和公开测试页不携带内部密码。
- 客户端须通过`X-API-Token`传入52号静态Token，默认`yonghe1999`。网关校验后才进入队列；该Token不转发给worker，与内部密码独立。
- 沿用现有主备派发、隔离期、重试、日志和全局并发限制。原有5号插队优先级保持原样，52号走默认队列。
- 5号`/api/v1/hairline/generate`和其他接口保持原样；网关不新增IP限制。
- worker的中下庭规则、扶正、3:4裁切和生发结果由同一次worker响应提供，网关不重新计算坐标。

## 请求

请求头必填：`X-API-Token: yonghe1999`。缺少、为空或不匹配时返回HTTP401，响应为`{"code":1009,"message":"未授权：缺少或错误的 X-API-Token","request_id":"gw-…","data":null}`，不读取转发表单、不占用GPU队列。其他接口不增加这项校验。

可在`gateway/config.json`设置`"interface52_token": "自定义值"`；旧配置省略该项时自动使用`yonghe1999`。显式配置空值或非字符串会导致启动校验失败，不能用来关闭鉴权。配置修改后重启网关生效，测试页输入框改为相同值。

使用`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 \
  -H 'X-API-Token: yonghe1999' \
  -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。

测试页新增“客户端Token”输入框，默认`yonghe1999`，只作为`X-API-Token`请求头发送；自定义后端Token时应同步填写该值。

## 验证

`tests/test_gateway_interface52.py`覆盖5/52路由分离、完整表单透传、由网关注入内部Token、真实公共转发函数的图片落盘与URL可访问、空字段保持原样和队列槽释放。现有pool、serialization、monitor、reqlog测试用于防止回归。

静态Token测试覆盖默认值、自定义覆盖、缺失/错误/空Token、内部Token不能代替客户端Token、未通过时不派发、无效配置启动失败以及客户端Token不透传至worker。

加入客户端Token后的验证：57项网关测试通过；临时网关实测缺失/错误Token返回401，测试页携带默认Token成功调用真实worker并显示7型图片，旧5号页面正常。测试关闭生发，未改动正在运行的GPU worker。

2026-11-04验证结果：上述网关测试共42项通过。另起本机临时网关连接当前真实GPU worker，浏览器验证旧5号仍返回三档，52号女性7型均返回可访问的图片URL，长图输出1062×1416，矩形叠加与空字段正常，页面请求不携带内部Token，无脚本错误。本轮关闭生发以验证网关链路，未重新运行ComfyUI生发；临时网关验证后关闭。