# GPU worker 接口 IP白名单

仅GPU worker使用项目根目录的`ip_access.json`，不存在时仅允许本机。网关不启用IP限制。配置每次请求重新读取，修改后立即生效。Worker 动态接口以直连来源 IP 为准。

```json
{
  "allowed_ips": ["49.232.51.171"]
}
```

当前已将网关IP `49.232.51.171`加入白名单；本机回环地址和网卡自身地址自动允许，其余来源返回HTTP403、`code=1010`。支持IPv4、IPv6及CIDR，不自动允许整个内网。

worker的所有动态路径统一保护，包括5号、52号、其他业务接口、调试接口、代理接口、健康检查和文档接口。`/static/`下的测试页和图片可正常访问，但页面发出的API请求仍需通过IP限制。

启动GPU worker时使用`uvicorn ... --no-proxy-headers`，保留真实连接来源。`run_worker.sh`与`hair-worker.service`已配置该选项。来源被服务器提前改写、地址格式错误或白名单配置无效时拒绝访问。

判断依据是直接连接worker的IP，忽略`X-Forwarded-For`、`X-Real-IP`和`Forwarded`，这些请求头不能用于绕过限制。由网关转发的请求按网关IP判断，网关后面的最终用户无需加入worker白名单。网关保持原有鉴权和转发流程，无需部署此配置。

`ip_access.json`不入Git；配置格式参考`ip_access.example.json`。本机网卡地址在请求时自动获取。

## 部署与维护

首次部署复制`ip_access.example.json`为`ip_access.json`，示例已包含网关`49.232.51.171`；已有配置不覆盖。该操作仅在GPU worker执行，网关服务和启动参数保持原样。

修改`allowed_ips`后保存为有效JSON即可生效，无需重启；建议写入同目录临时文件再原子替换，避免编辑过程中出现半份JSON。文件不存在时仅允许本机，内容损坏时动态接口一律拒绝。更新程序时保留本机配置文件。

Worker 动态路由通过来源 IP 白名单授权，包括 `/health` 和 `/api/v1/debug/*`。静态文件公开读取，调用 API 时以直连 IP 的检查结果为准。

验证命令：`./venv/bin/pytest tests/test_ip_access.py -q`，覆盖本机、精确白名单、CIDR、IPv6、转发头伪造、热更新、全接口拦截与网关不受限制。