Client IP

getClientIPFromRequest 从请求头中解析客户端 IP 地址。出于安全考虑，默认不信任代理头，需显式启用。

基本用法

import { getClientIPFromRequest } from "@ventostack/core";

// 默认不信任代理头，返回 null
const ip = getClientIPFromRequest(request);

信任代理头

在反向代理（Nginx、Cloudflare 等）后部署时，显式启用：

const ip = getClientIPFromRequest(request, { trustProxyHeaders: true });
// 读取 X-Forwarded-For（取第一个 IP）或 X-Real-IP

在中间件中使用

import { getClientIPFromRequest } from "@ventostack/core";

const ipMiddleware: Middleware = async (ctx, next) => {
  ctx.state.clientIP = getClientIPFromRequest(ctx.request, {
    trustProxyHeaders: true,
  });
  return next();
};

IP 解析优先级

当 trustProxyHeaders: true 时，按以下顺序解析：

1. X-Forwarded-For — 取逗号分隔后的第一个 IP
2. X-Real-IP — 直接读取

两者均不存在时返回 null。

配置选项

ClientIPOptions

属性	类型	默认值	说明
trustProxyHeaders	boolean	false	是否信任 X-Forwarded-For / X-Real-IP

⚠️ 仅在确认上游代理可信时启用 trustProxyHeaders，否则客户端可伪造 IP。

平台模块的可信代理配置

Admin 应用的认证路由和审计日志中间件使用 trustedProxies: string[] 参数（IP/CIDR 列表），而非简单的 boolean 开关：

// 在 createAuthRoutes 中传入可信代理列表
createAuthRoutes(authService, authMiddleware, perm, [
  "10.0.0.0/8",
  "172.16.0.0/12",
  "192.168.0.0/16",
]);

// 在 createOperationLogMiddleware 中配置
createOperationLogMiddleware(auditLog, {
  trustedProxies: ["10.0.0.0/8"],
});

安全注意事项：

• 空 trustedProxies 列表时，直接使用连接 IP，不读取任何代理头
• 仅当直接连接 IP 在可信代理列表中时，才读取 X-Forwarded-For / X-Real-IP
• 支持 CIDR 格式（如 10.0.0.0/8）
• 当前 CIDR 匹配仅支持 IPv4，IPv6 地址直接使用连接 IP