feat(gateway): 接入42和72并为42/52/72启用可刷新令牌
This commit is contained in:
@@ -7,6 +7,7 @@
|
||||
|------|------|
|
||||
| [实现说明.md](实现说明.md) | **实现总览**：架构、五个接口怎么实现、base64→URL 映射、错误码、部署/环境要点。先读这份。 |
|
||||
| [接口文档.md](接口文档.md) | 对外 API 契约（字段 / 错误码）。字段命名的唯一权威。 |
|
||||
| [42／52／72 网关鉴权](接口42-52-72网关鉴权.md) | 登录、过期、刷新、令牌签名配置与测试页。 |
|
||||
| [接口52网关接入.md](接口52网关接入.md) | 52号请求透传、图片URL与空字段约定、公开测试页及网关部署步骤。 |
|
||||
| [旷视具体需求.md](旷视具体需求.md) | 原始需求。 |
|
||||
| [../OFFLINE_ASSETS.md](../OFFLINE_ASSETS.md) | worker 离线模型权重/字体清单（内网部署）。 |
|
||||
|
||||
+1
-1
@@ -99,7 +99,7 @@
|
||||
- **怎么实现**：复用接口2 的 502 点渲染管线，三档分别用 `hairline_texture[/_high|/_low]` 同名贴图渲染叠图；生发同接口2（ComfyUI inpaint），**黑模板固定取 `hairline_texture_black/`（middle）**，每发型 1 张生发图。`best_hairline_center_point`=眉心 x × 首个选中发型 middle 档发际线 y。
|
||||
|
||||
### 接口52 发际线新规则 `/api/v1/hairline/generate-52`（网关透传）
|
||||
- **客户端鉴权**：请求头`X-API-Token`，默认`yonghe1999`，可由`gateway/config.json`的`interface52_token`覆盖；不匹配返回HTTP401/code1009且不进入队列。客户端Token不传给worker，内部Token仍由网关添加。
|
||||
- **客户端鉴权**：登录后发送 `Authorization: Bearer <access_token>`。校验失败返回 HTTP 401、`code=1009`，不进入队列。详见[客户端鉴权](接口42-52-72网关鉴权.md)。
|
||||
- `main`新增网关路由和`static/test_interface52.html`。GPU worker负责中下庭均值定位、扶正裁切及生发；主备worker均需部署52号实现，网关只透传表单并附加内部Token。
|
||||
- 非空图片使用原有`*_base64`→`*_url`落盘改写；空图片保留`*_base64: null`。metadata和坐标原样返回，middle叠加到`input_image_url`。旧接口、5号队列优先级及网关IP策略保持原样。
|
||||
- 参数、空字段与部署步骤见[接口52网关接入](接口52网关接入.md)。worker分支的IP限制与算法不合入本次网关改动。
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# 42、52、72 号接口网关鉴权
|
||||
|
||||
| 接口 | 方法与路径 | 执行位置 |
|
||||
|---|---|---|
|
||||
| 42 | `POST /api/v1/face/features-42` | 网关按接口 52 的规则扶正裁切，再用接口 4 的分析结果和 Ft/Zy 判定生成特征 |
|
||||
| 52 | `POST /api/v1/hairline/generate-52` | 网关转发至 worker |
|
||||
| 72 | `POST /api/v1/face/b-end-points` | 网关转发至 worker，底图与标注层转成 URL |
|
||||
|
||||
客户端调用这三个接口时，在原请求上添加 `Authorization: Bearer <access_token>`。缺少、过期、签名无效或误用刷新令牌时，返回 HTTP 401 和业务码 `1009`。网关验证通过后，52 和 72 继续使用独立的 `X-Internal-Token` 转发至 worker，客户端令牌不会传给 worker。
|
||||
|
||||
## 登录
|
||||
|
||||
`POST /api/v1/auth/login`，请求体为 JSON，包含 `username` 和 `password`。当前用户名为 `yonghe`，密码使用约定的服务端固定值。
|
||||
|
||||
成功时 HTTP 200、`code=0`，`data` 包含：
|
||||
|
||||
| 字段 | 值 |
|
||||
|---|---|
|
||||
| `access_token` | 访问令牌 |
|
||||
| `token_type` | `Bearer` |
|
||||
| `expires_in` | 900 秒 |
|
||||
| `refresh_token` | 刷新令牌 |
|
||||
| `refresh_expires_in` | 604800 秒，即 7 天 |
|
||||
|
||||
## 刷新
|
||||
|
||||
`POST /api/v1/auth/refresh`，请求体为 `{"refresh_token":"登录返回的刷新令牌"}`。成功后返回新的 `access_token`、`token_type` 和 `expires_in`。登录时的刷新令牌可以在原有效期内继续使用。到期后重新登录。登录或刷新失败时，响应包含 `code`、`message`、`request_id` 和 `data: null`。
|
||||
|
||||
## 网关配置
|
||||
|
||||
在 `main` 的网关环境中设置 `HAIR_API_TOKEN_SECRET`，或在未跟踪的 `gateway/config.json` 中设置 `api_token_secret`。使用独立且稳定的至少 32 字节随机值。签名密钥缺失时，签发或刷新返回 HTTP 503 和业务码 `1007`。更换签名密钥会使已签发令牌失效。
|
||||
|
||||
网关保留原有 Ark、MediaPipe 与 BiSeNet 配置，42 的裁切还使用 Pillow。部署 72 前，确认所有可接收该请求的 worker 已部署含 72 号的版本（例如 `ubuntu3090_debug` 的 `c9a47a7` 或后续版本）。52、72 沿用现有 worker 池与图片 URL 改写流程。
|
||||
|
||||
网关测试页为 `/static/test_interface42.html`、`/static/test_interface52.html` 和 `/static/test_interface72.html`，页面先登录再提交，访问令牌到期时自动刷新。
|
||||
+5
-5
@@ -7,16 +7,16 @@
|
||||
客户端 → `POST /api/v1/hairline/generate-52` → 网关现有队列和worker池 → worker同路径 → 网关落盘非空图片并返回公网URL。
|
||||
|
||||
- 请求体原样转发，网关附加配置中的`X-Internal-Token`；客户端和公开测试页不携带内部密码。
|
||||
- 客户端须通过`X-API-Token`传入52号静态Token，默认`yonghe1999`。网关校验后才进入队列；该Token不转发给worker，与内部密码独立。
|
||||
- 客户端须登录取得访问令牌，通过 `Authorization: Bearer <access_token>` 发送。网关鉴权后进入队列。
|
||||
- 沿用现有主备派发、隔离期、重试、日志和全局并发限制。原有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队列。其他接口不增加这项校验。
|
||||
缺少、无效或过期的访问令牌返回 HTTP 401、`code=1009`。登录、刷新与部署配置见[客户端鉴权](接口42-52-72网关鉴权.md)。
|
||||
|
||||
|
||||
可在`gateway/config.json`设置`"interface52_token": "自定义值"`；旧配置省略该项时自动使用`yonghe1999`。显式配置空值或非字符串会导致启动校验失败，不能用来关闭鉴权。配置修改后重启网关生效，测试页输入框改为相同值。
|
||||
|
||||
使用`multipart/form-data`；图片三选一：`image_file`、`image_url`、`image_base64`。必填`gender=male/female`和`hair_style=1..7`（支持逗号分隔多选）。
|
||||
|
||||
@@ -56,7 +56,7 @@ worker始终返回`*_base64`。网关沿用原有公共改写，不添加52号
|
||||
|
||||
```bash
|
||||
curl -X POST https://hair.xiangsilian.com/api/v1/hairline/generate-52 \
|
||||
-H 'X-API-Token: yonghe1999' \
|
||||
-H "Authorization: Bearer $ACCESS_TOKEN" \
|
||||
-F 'image_file=@/path/to/photo.jpg' \
|
||||
-F 'gender=male' -F 'hair_style=1' \
|
||||
-F 'normalize_image=true' -F 'generate_grow_image=false'
|
||||
@@ -64,7 +64,7 @@ curl -X POST https://hair.xiangsilian.com/api/v1/hairline/generate-52 \
|
||||
|
||||
成功时`code=0`，检查`input_image_url`和`hairline_images[].image_middle_url`可打开、尺寸一致；high/low仍为`*_base64: null`。访问测试页时无需输入内部Token。
|
||||
|
||||
测试页新增“客户端Token”输入框，默认`yonghe1999`，只作为`X-API-Token`请求头发送；自定义后端Token时应同步填写该值。
|
||||
测试页先登录再提交图片，访问令牌过期时使用当前刷新令牌自动换取新的访问令牌。
|
||||
|
||||
## 验证
|
||||
|
||||
|
||||
+89
-2
@@ -19,6 +19,8 @@
|
||||
| 2 C 端生发 | POST | `/api/v1/hair/grow` |
|
||||
| 3 B 端生发 | POST | `/api/v1/hair/grow-b` |
|
||||
| 4 用户特征 | POST | `/api/v1/face/features` |
|
||||
| 42 用户特征与两项判定 | POST | `/api/v1/face/features-42` |
|
||||
| 72 B 端五个关键点 | POST | `/api/v1/face/b-end-points` |
|
||||
| 5 发际线 PNG 生成 | POST | `/api/v1/hairline/generate` |
|
||||
| 52 发际线新规则 | POST | `/api/v1/hairline/generate-52` |
|
||||
|
||||
@@ -87,7 +89,7 @@
|
||||
| 1006 | 文件超出大小限制 | 单文件超过 1 MB |
|
||||
| 1007 | 图片参数错误 | file / url / base64 未传，或同时传了多个（三者严格互斥） |
|
||||
| 1008 | 图片格式不支持 | 非 JPG / PNG |
|
||||
| 1009 | 未授权 | worker内部`X-Internal-Token`错误；网关52号缺少或错误的客户端`X-API-Token`。HTTP401 |
|
||||
| 1009 | 未授权 | worker内部`X-Internal-Token`错误；网关42／52／72号客户端 Bearer 令牌缺失、无效或过期。HTTP401 |
|
||||
|
||||
---
|
||||
|
||||
@@ -445,6 +447,91 @@
|
||||
|
||||
---
|
||||
|
||||
## 接口 72：B 端五个关键点
|
||||
|
||||
`POST /api/v1/face/b-end-points` 接受三选一图片参数 `image_file`、`image_url`、`image_base64`。复用接口 52 的扶正裁切与虹膜／眼宽厘米估算，返回坐标以处理后底图为准。使用[客户端 Bearer 鉴权](接口42-52-72网关鉴权.md)。
|
||||
|
||||
| 点号 | 位置 | 标注 |
|
||||
|---|---|---|
|
||||
| 1 | MediaPipe 4 | 白点 |
|
||||
| 2 | HL center | 白点 |
|
||||
| 3 | HL center 向画面右侧水平偏移 2 cm | 白点 |
|
||||
| 4 | HL left | 白点 |
|
||||
| 5 | HL left left | 白点 |
|
||||
| 6 | MediaPipe 446 | 白点，兼作射线锚点 |
|
||||
|
||||
六个白点的直径相同。标注层包含三条从起点向目标方向延伸并逐渐变淡的白色虚线（2→1、4→6、5→6），以及 2→3 白色虚线段。2→1 射线比默认可见长度短 15%，5→6 射线的绘制长度比默认长度多 30%，可见范围以图像边界为限。四个距离文字分别放在 2–1 中点左侧、2–3 中点上方、4–6 中点左侧和 5–6 中点右侧，距离保留一位小数，2–3 固定显示 `2.0 CM`。
|
||||
|
||||
| `data` 字段 | 内容 |
|
||||
|---|---|
|
||||
| `input_image_url` | 扶正裁切后的底图 |
|
||||
| `annotated_image_url` | 与底图同尺寸的透明 PNG 标注层 |
|
||||
| `points` | 按字符串点号 `"1"` 到 `"6"` 索引的像素坐标 `{x, y}` |
|
||||
| `measurements_cm` | 四个距离，以 `2-1`、`2-3`、`4-6`、`5-6` 索引 |
|
||||
| `image_size` | 处理后尺寸 `{width, height}` |
|
||||
| `coordinate_space` | `processed_image` |
|
||||
| `px_per_cm` | 估算的每厘米像素数 |
|
||||
|
||||
Worker 直连时图片字段使用 `_base64` 后缀。检测不到人脸返回 `1001`，非正面或标注所需点位无法取得时返回 `1003`，图片无法解码返回 `1008`。
|
||||
|
||||
---
|
||||
|
||||
## 42号接口-加两个特征点
|
||||
|
||||
**请求** `POST /api/v1/face/features-42`，使用 `multipart/form-data`。
|
||||
|
||||
| 请求字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `image_file` | 文件 | 上传 JPG 或 PNG |
|
||||
| `image_url` | 字符串 | 网关可访问的图片 URL |
|
||||
| `image_base64` | 字符串 | 图片 Base64，支持带 `data:image/…;base64,` 前缀 |
|
||||
|
||||
以上三个字段必须且只能传一个。图片按 EXIF 方向解码后，先检查原图的人脸完整性和俯拍角度。俯拍使用头部姿态估算的正向 pitch，超过服务端环境变量 `FRONTAL_PITCH_THR`（默认 30°）时拦截。通过质检后复用接口 52 的扶正裁切规则，再用处理后的图片做面部特征分析。
|
||||
|
||||
客户端通过 Bearer 令牌鉴权，详见[客户端鉴权](接口42-52-72网关鉴权.md)。
|
||||
|
||||
### 质检失败与异常响应
|
||||
|
||||
以下业务响应的 HTTP 状态均为 `200`。
|
||||
|
||||
| `code` | 情况 | `message` |
|
||||
|---|---|---|
|
||||
| `1001` | 原图未检测到人脸 | 无法识别人像，请上传包含完整人脸的照片 |
|
||||
| `1003` | 人脸关键点触及或超出图片边界 | 人脸不完整，请保留完整的脸部轮廓 |
|
||||
| `1003` | 估算的俯拍角度超过阈值 | 俯拍角度过大，请将相机调整至与脸部平视 |
|
||||
| `1003` | 扶正裁切失败，无法保留所需人脸关键点 | 人脸过于贴近边缘，无法扶正裁切 |
|
||||
| `1008` | URL 图片下载失败 | 图片下载失败（URL 不可达） |
|
||||
| `1008` | Base64 解码失败 | 图片格式不支持（base64 解码失败） |
|
||||
| `1008` | 图片无法读取 | 图片格式不支持（仅 JPG / PNG） |
|
||||
| `1007` | 图片字段未按三选一传入 | 图片参数错误：必须且只能传 image_file / image_url / image_base64 其中一个 |
|
||||
| `1007` | 图片预处理内部异常 | 图片预处理失败 |
|
||||
| `1001` | 质检通过，但视觉模型未识别到人脸 | 无法识别人像 |
|
||||
| `1007` | 视觉模型调用异常 | 分析服务异常：… |
|
||||
|
||||
响应包含 `code`（整数业务码）、`message`（字符串提示）、`request_id`（字符串请求标识）和 `data`（失败时为 `null`）。三个 `1003` 情况可通过 `message` 区分，响应中没有独立的质检原因或角度字段。
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 1003,
|
||||
"message": "俯拍角度过大，请将相机调整至与脸部平视",
|
||||
"request_id": "gw-xxxxxxxx",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### 成功响应
|
||||
|
||||
`data.features` 仍为 JSON 字符串，保留 main 网关接口 4 的七项特征（含 `contour_type`），在其中新增：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `zygoma_expansion` | boolean 或 null | 颧弓外扩 |
|
||||
| `temple_hollowing` | boolean 或 null | 太阳穴凹陷 |
|
||||
|
||||
Ft 两端保持横坐标并取平均高度，Zy 为 234 到 454 的距离。只有 Ft ÷ Zy 严格小于 0.8 时两项同时为 `true`，否则同时为 `false`。所需点位缺失或无法测量时两项均为 `null`。网关测量复用接口 99 的 MediaPipe 与 BiSeNet 依赖，裁切还需要 Pillow。
|
||||
|
||||
---
|
||||
|
||||
## 接口 5：发际线 PNG 生成接口
|
||||
|
||||
**说明**：入参同接口2（先选性别、再多选发型）。对每个选中发型返回 `middle` / `high` / `low` **三档**发际线叠图与**生发图**，并返回「最合适发际线」的面部中间点坐标。
|
||||
@@ -574,7 +661,7 @@
|
||||
|
||||
**请求**：`POST /api/v1/hairline/generate-52`（网关透传至同路径GPU worker）
|
||||
|
||||
**客户端鉴权**：请求头必填`X-API-Token: yonghe1999`，缺少、为空或不匹配返回HTTP401/code1009，不进入worker队列。默认值可通过网关`gateway/config.json`的`interface52_token`覆盖，修改后重启网关；内部`X-Internal-Token`仍由网关注入，客户端无需提供。该校验仅用于网关52号。
|
||||
**客户端鉴权**：使用 `Authorization: Bearer <access_token>`。登录、刷新和错误码见[客户端鉴权](接口42-52-72网关鉴权.md)。
|
||||
|
||||
**职责**：GPU worker返回base64并完成算法处理，网关负责透传参数、附加内部Token、保存非空图片及返回公网URL。网关不增加IP限制；网关出口IP须已在worker白名单内。部署与完整字段约定见[接口52网关接入](接口52网关接入.md)。
|
||||
|
||||
|
||||
+1
-1
@@ -7,7 +7,7 @@
|
||||
|
||||
## 接口52（2026-11-04 已接入main）
|
||||
|
||||
客户端新增请求头`X-API-Token`校验，默认`yonghe1999`，可在网关配置`interface52_token`覆盖；缺少或不匹配返回HTTP401/code1009，不进入队列。其他接口不增加该校验。
|
||||
42、52、72 统一采用[客户端登录与刷新令牌](接口42-52-72网关鉴权.md)。校验失败返回 HTTP 401、`code=1009`。
|
||||
|
||||
新增`POST /api/v1/hairline/generate-52`，由网关转发到GPU worker同路径。5号保持原样，52号的`normalize_image`等参数原样透传；非空图片沿用公共base64→URL改写，空图片仍保留`*_base64: null`。不在网关增加IP限制，不合入worker算法。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user