# 2026-06-07 — 登录白名单客户端 IP 识别（反代/Docker）

## 摘要

修复登录 IP 白名单将 Docker 网关 `172.18.0.1` 误判为客户端 IP 的问题；在可信反代跳（内网/回环）上读取 `X-Real-IP` / `X-Forwarded-For`。

## 动机

用户启用登录白名单后提示「当前 IP (172.18.0.1) 不在登录白名单中」。1Panel/OpenResty → Docker 容器时 TCP 对端为桥接网关，非真实公网 IP；`auth.py` 仍用 `request.client.host`。

## 变更

| 文件 | 说明 |
|------|------|
| `server/utils/client_ip.py` | `get_client_ip()`：反代为内网/回环时信任转发头 |
| `server/api/auth.py` | login / refresh / change_password 使用 `get_client_ip` |
| `tests/test_client_ip.py` | 172.18.0.1 + X-Real-IP、公网直连防伪造 |

## 迁移 / 重启

需重启 API。反代须配置 `proxy_set_header X-Real-IP $remote_addr`（见 `deploy/1panel/openresty-nexus.conf.example`）。

## 验证

```bash
pytest tests/test_client_ip.py -q
```

生产登录：错误提示应显示真实公网 IP，而非 `172.18.0.1`。
