fix: type check

Author: xqvvu

document/content/self-host/upgrading/4-15/4150.mdx

@@ -36,6 +36,13 @@ SYNC_INDEX=true
 5. 增加文件解析/HTML转Markdown/文本切块 worker pool，避免并发太高导致资源耗尽，可通过环境变量调整其 pool 数量。
 6. 模型思考配置。
 
+## 环境变量更新
+
+```dotenv
+TRUSTED_PROXY_ENABLE=false
+TRUSTED_PROXY_IPS=
+```
+
 ## ⚙️ 优化
 
 1. 增加父子节点选中互斥功能，解决：同时选中父子节点时，移动节点会出现抖动。

packages/service/common/security/clientIp.ts

@@ -21,6 +21,7 @@ const MAX_FORWARDED_FOR_LENGTH = 2048;
 const MAX_FORWARDED_FOR_HOPS = 32;
 
 let cachedTrustedProxyIpEnv: string | undefined | null = null;
+let cachedTrustedProxyEnableEnv: boolean | undefined | null = null;
 let cachedNodeEnv: string | undefined | null = null;
 let cachedTrustProxyFn: TrustProxyFn = proxyaddr.compile([]);
 let warnedInvalidTrustedProxyIpEnv: string | undefined;
@@ -107,22 +108,31 @@ const parseTrustedProxyIpEnv = (trustedProxyIpEnv?: string) => {
   return Array.from(validAddresses);
 };
 
-// 构建并缓存 proxy-addr 的信任判定函数;非生产环境默认信任 loopback,叠加 TRUSTED_PROXY_IPS 配置。
+// 构建并缓存 proxy-addr 的信任判定函数;用于 TRUSTED_PROXY_ENABLE=true 的可信代理校验模式。
+// 可信代理校验模式下,非生产环境默认信任 loopback,并叠加 TRUSTED_PROXY_IPS 配置。
 // 仅当环境变量或 NODE_ENV 变化时才重新编译,避免每次请求都重复解析。
 const getTrustProxyFn = () => {
+  const trustedProxyEnable = env.TRUSTED_PROXY_ENABLE;
   const trustedProxyIpEnv = env.TRUSTED_PROXY_IPS;
   const nodeEnv = process.env.NODE_ENV;
-  if (trustedProxyIpEnv === cachedTrustedProxyIpEnv && nodeEnv === cachedNodeEnv) {
+  if (
+    trustedProxyEnable === cachedTrustedProxyEnableEnv &&
+    trustedProxyIpEnv === cachedTrustedProxyIpEnv &&
+    nodeEnv === cachedNodeEnv
+  ) {
     return cachedTrustProxyFn;
   }
 
+  cachedTrustedProxyEnableEnv = trustedProxyEnable;
   cachedTrustedProxyIpEnv = trustedProxyIpEnv;
   cachedNodeEnv = nodeEnv;
 
-  const trustedProxyAddresses = [
-    ...(nodeEnv === 'production' ? [] : (['loopback'] satisfies proxyaddr.Address[])),
-    ...parseTrustedProxyIpEnv(trustedProxyIpEnv)
-  ];
+  const trustedProxyAddresses = trustedProxyEnable
+    ? [
+        ...(nodeEnv === 'production' ? [] : (['loopback'] satisfies proxyaddr.Address[])),
+        ...parseTrustedProxyIpEnv(trustedProxyIpEnv)
+      ]
+    : [];
   cachedTrustProxyFn = proxyaddr.compile(trustedProxyAddresses);
 
   return cachedTrustProxyFn;
@@ -149,11 +159,6 @@ export const isTrustedProxyIp = (rawIp?: string | null) => {
 
 // 取 TCP 连接对端地址(socket / 旧版 connection 兜底),作为最可信的回退来源。
 const getRemoteIp = (req: RequestWithClientIp) => {
-  console.log({
-    remoteAddress: req.socket?.remoteAddress,
-    xForwardedFor: req.headers?.['x-forwarded-for'],
-    xRealIp: req.headers?.['x-real-ip']
-  });
   return normalizeClientIp(req.socket?.remoteAddress ?? req.connection?.remoteAddress);
 };
 
@@ -168,6 +173,19 @@ const getForwardedFor = (req: RequestWithClientIp) => {
   return getHeaderValue(req.headers, 'x-forwarded-for');
 };
 
+// 关闭可信代理校验时的兼容模式:直接相信转发头。
+// X-Forwarded-For 按行业约定取最左侧 IP;如果不存在或非法,再尝试 X-Real-IP。
+const getClientIpFromForwardingHeaders = (req: RequestWithClientIp) => {
+  const forwardedFor = getForwardedFor(req);
+  if (forwardedFor && forwardedFor.length <= MAX_FORWARDED_FOR_LENGTH) {
+    const firstForwardedIp = forwardedFor.split(',')[0]?.trim();
+    const ip = normalizeClientIp(firstForwardedIp);
+    if (ip) return ip;
+  }
+
+  return getClientIpFromRealIp(req);
+};
+
 // 在调用 proxy-addr 前对 XFF 做尺寸/跳数/格式预检,防止超长或畸形头造成解析放大攻击。
 const isForwardedForSafeToParse = (forwardedFor: string) => {
   if (forwardedFor.length > MAX_FORWARDED_FOR_LENGTH) return false;
@@ -195,11 +213,16 @@ const createProxyAddrRequest = (remoteAddress: string, forwardedFor: string) =>
 
 // 对外:从请求中解析出最终客户端 IP。
 // 策略:
-//   1. 取 socket 远端 IP 作为底线;若不可解析直接返回 undefined。
-//   2. 远端不在受信代理列表 -> 直接返回远端 IP,忽略一切转发头(防伪造)。
-//   3. 远端可信 -> 优先用 X-Forwarded-For(经安全校验后交给 proxy-addr 沿信任链回溯),
+//   1. TRUSTED_PROXY_ENABLE=false -> 兼容模式,直接相信 X-Forwarded-For / X-Real-IP,再回退远端 IP。
+//   2. TRUSTED_PROXY_ENABLE=true -> 可信代理校验模式,先取 socket 远端 IP 作为底线;若不可解析直接返回 undefined。
+//   3. 远端不在受信代理列表 -> 直接返回远端 IP,忽略一切转发头(防伪造)。
+//   4. 远端可信 -> 优先用 X-Forwarded-For(经安全校验后交给 proxy-addr 沿信任链回溯),
 //      否则回退 X-Real-IP;校验失败或转发头本身仍是受信代理时退回远端 IP。
 export const getClientIpFromRequest = (req: RequestWithClientIp) => {
+  if (!env.TRUSTED_PROXY_ENABLE) {
+    return getClientIpFromForwardingHeaders(req) ?? getRemoteIp(req);
+  }
+
   const remoteIp = getRemoteIp(req);
   if (!remoteIp) return;
 

packages/service/env.ts

@@ -175,6 +175,14 @@ export const serviceEnv = createEnv({
     //==================== 安全配置 ====================
     USE_IP_LIMIT: BoolSchema.default(false).meta({ description: '是否启用 IP 限流' }),
     CHECK_INTERNAL_IP: BoolSchema.default(false).meta({ description: '是否启用内网 IP 检查' }),
+    TRUSTED_PROXY_ENABLE: BoolSchema.default(false).meta({
+      description:
+        '是否启用可信反向代理客户端 IP 校验；关闭时兼容旧逻辑，直接信任 X-Forwarded-For/X-Real-IP'
+    }),
+    TRUSTED_PROXY_IPS: z.string().optional().meta({
+      description:
+        '可信反向代理 IP/CIDR 列表，逗号或空白分隔。仅 TRUSTED_PROXY_ENABLE=true 时生效；仅显式可信代理传入的 X-Forwarded-For/X-Real-IP 会用于客户端 IP 解析'
+    }),
     PASSWORD_LOGIN_LOCK_SECONDS: defaultableIntSchema(120).meta({
       description: '密码错误锁定时长（秒）'
     }),

packages/service/type.ts packages/service/global.d.tspackages/service/type.ts renamed to packages/service/global.d.ts

@@ -3,18 +3,11 @@ import type {
   LicenseDataType,
   SystemEnvType
 } from '@fastgpt/global/common/system/types';
-import {
-  TTSModelType,
-  RerankModelItemType,
-  STTModelType,
-  EmbeddingModelItemType,
-  LLMModelItemType
-} from '@fastgpt/global/core/ai/model.schema';
 import type { SubPlanType } from '@fastgpt/global/support/wallet/sub/type';
 import type { WorkerNameEnum, WorkerPool } from './worker/utils';
-import { Worker } from 'worker_threads';
 
 declare global {
+  var countTrackQueue: Map<string, { event: string; count: number; data: Record<string, any> }>;
   var systemInitBufferId: string | undefined;
 
   var systemVersion: string;
@@ -25,3 +18,5 @@ declare global {
 
   var workerPoll: Record<WorkerNameEnum, WorkerPool>;
 }
+
+export {};

packages/service/test/common/geo/index.test.ts

@@ -8,6 +8,17 @@ import {
   type NextApiRequest
 } from '@fastgpt/service/common/geo';
 import { cleanupIntervalMs } from '@fastgpt/service/common/geo/constants';
+import { env } from '@fastgpt/service/env';
+
+const originalTrustedProxyEnable = env.TRUSTED_PROXY_ENABLE;
+
+const setTrustedProxyEnable = (value: boolean) => {
+  (env as { TRUSTED_PROXY_ENABLE: boolean }).TRUSTED_PROXY_ENABLE = value;
+};
+
+afterEach(() => {
+  setTrustedProxyEnable(originalTrustedProxyEnable);
+});
 
 describe('getGeoReader', () => {
   it('should return a reader instance', () => {
@@ -174,6 +185,8 @@ describe('getIpFromRequest', () => {
   });
 
   it('should return the IP from x-forwarded-for header', () => {
+    setTrustedProxyEnable(true);
+
     const req = {
       headers: { 'x-forwarded-for': '203.0.113.50' },
       connection: {},
@@ -185,6 +198,8 @@ describe('getIpFromRequest', () => {
   });
 
   it('should return the IP from x-real-ip header', () => {
+    setTrustedProxyEnable(true);
+
     const req = {
       headers: { 'x-real-ip': '198.51.100.10' },
       connection: {},
@@ -196,6 +211,8 @@ describe('getIpFromRequest', () => {
   });
 
   it('should ignore spoofed IP headers from untrusted direct clients', () => {
+    setTrustedProxyEnable(true);
+
     const req = {
       headers: { 'x-forwarded-for': '203.0.113.50', 'x-real-ip': '198.51.100.10' },
       connection: {},

packages/service/test/common/middle/reqFrequencyLimit.test.ts

@@ -5,11 +5,16 @@ import { jsonRes } from '@fastgpt/service/common/response';
 import { env } from '@fastgpt/service/env';
 
 const originalUseIpLimit = env.USE_IP_LIMIT;
+const originalTrustedProxyEnable = env.TRUSTED_PROXY_ENABLE;
 
 const setUseIpLimit = (value: boolean) => {
   (env as { USE_IP_LIMIT: boolean }).USE_IP_LIMIT = value;
 };
 
+const setTrustedProxyEnable = (value: boolean) => {
+  (env as { TRUSTED_PROXY_ENABLE: boolean }).TRUSTED_PROXY_ENABLE = value;
+};
+
 const createRes = () =>
   ({
     setHeader: vi.fn(),
@@ -42,6 +47,7 @@ describe('useIPFrequencyLimit', () => {
 
   afterEach(() => {
     setUseIpLimit(originalUseIpLimit);
+    setTrustedProxyEnable(originalTrustedProxyEnable);
   });
 
   it('should enforce IP limit when USE_IP_LIMIT is enabled without force', async () => {
@@ -112,6 +118,8 @@ describe('useIPFrequencyLimit', () => {
   });
 
   it('should ignore spoofed forwarding headers from untrusted direct clients', async () => {
+    setTrustedProxyEnable(true);
+
     const middleware = useIPFrequencyLimit({
       id: 'ip-spoof-test-direct',
       seconds: 60,
@@ -141,7 +149,41 @@ describe('useIPFrequencyLimit', () => {
     expect(spoofedIpRecord).toBeNull();
   });
 
+  it('should use X-Forwarded-For as the limit key when trusted proxy parsing is disabled', async () => {
+    setTrustedProxyEnable(false);
+
+    const middleware = useIPFrequencyLimit({
+      id: 'ip-spoof-test-compat',
+      seconds: 60,
+      limit: 10,
+      force: true
+    });
+
+    await middleware(
+      createReq({
+        remoteAddress: '172.16.0.119',
+        headers: {
+          'x-forwarded-for': '60.186.209.23',
+          'x-real-ip': '60.186.209.23'
+        }
+      }),
+      createRes()
+    );
+
+    const forwardedIpRecord = await MongoFrequencyLimit.findOne({
+      eventId: 'ip-qps-limit-ip-spoof-test-compat-60.186.209.23'
+    }).lean();
+    const remoteIpRecord = await MongoFrequencyLimit.findOne({
+      eventId: 'ip-qps-limit-ip-spoof-test-compat-172.16.0.119'
+    }).lean();
+
+    expect(forwardedIpRecord?.amount).toBe(1);
+    expect(remoteIpRecord).toBeNull();
+  });
+
   it('should use proxy-addr result for trusted proxy forwarding chains', async () => {
+    setTrustedProxyEnable(true);
+
     const middleware = useIPFrequencyLimit({
       id: 'ip-spoof-test-proxy',
       seconds: 60,
@@ -171,6 +213,8 @@ describe('useIPFrequencyLimit', () => {
   });
 
   it('should use a shared fail-closed key when client IP cannot be resolved', async () => {
+    setTrustedProxyEnable(true);
+
     const middleware = useIPFrequencyLimit({
       id: 'ip-spoof-test-unknown',
       seconds: 60,

packages/service/test/common/security/clientIp.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import ipaddr from 'ipaddr.js';
 import {
   getClientIpFromRequest,
@@ -8,8 +8,13 @@ import {
 import { env } from '@fastgpt/service/env';
 
 const originalTrustedProxyIps = env.TRUSTED_PROXY_IPS;
+const originalTrustedProxyEnable = env.TRUSTED_PROXY_ENABLE;
 const originalNodeEnv = process.env.NODE_ENV;
 
+const setTrustedProxyEnable = (value: boolean) => {
+  (env as { TRUSTED_PROXY_ENABLE: boolean }).TRUSTED_PROXY_ENABLE = value;
+};
+
 const setTrustedProxyIps = (value?: string) => {
   (env as { TRUSTED_PROXY_IPS?: string }).TRUSTED_PROXY_IPS = value;
 };
@@ -39,6 +44,7 @@ const createReq = ({
 
 describe('clientIp', () => {
   afterEach(() => {
+    setTrustedProxyEnable(originalTrustedProxyEnable);
     setTrustedProxyIps(originalTrustedProxyIps);
     setNodeEnv(originalNodeEnv);
   });
@@ -68,6 +74,18 @@ describe('clientIp', () => {
   });
 
   describe('isTrustedProxyIp', () => {
+    beforeEach(() => {
+      setTrustedProxyEnable(true);
+    });
+
+    it('should not trust proxies when trusted proxy parsing is disabled', () => {
+      setTrustedProxyEnable(false);
+      setTrustedProxyIps('127.0.0.1/8, 10.0.0.0/8');
+
+      expect(isTrustedProxyIp('127.0.0.1')).toBe(false);
+      expect(isTrustedProxyIp('10.0.0.10')).toBe(false);
+    });
+
     it('should trust loopback proxies by default', () => {
       setTrustedProxyIps(undefined);
 
@@ -131,6 +149,58 @@ describe('clientIp', () => {
   });
 
   describe('getClientIpFromRequest', () => {
+    beforeEach(() => {
+      setTrustedProxyEnable(true);
+    });
+
+    it('should trust forwarding headers when trusted proxy parsing is disabled', () => {
+      setTrustedProxyEnable(false);
+      setTrustedProxyIps('127.0.0.1/8, 10.0.0.0/8');
+
+      const ip = getClientIpFromRequest(
+        createReq({
+          remoteAddress: '127.0.0.1',
+          headers: {
+            'x-forwarded-for': '203.0.113.50',
+            'x-real-ip': '203.0.113.51'
+          }
+        })
+      );
+
+      expect(ip).toBe('203.0.113.50');
+    });
+
+    it('should fall back to X-Real-IP in compatibility mode when X-Forwarded-For is invalid', () => {
+      setTrustedProxyEnable(false);
+
+      const ip = getClientIpFromRequest(
+        createReq({
+          remoteAddress: '127.0.0.1',
+          headers: {
+            'x-forwarded-for': 'not-an-ip',
+            'x-real-ip': '203.0.113.51'
+          }
+        })
+      );
+
+      expect(ip).toBe('203.0.113.51');
+    });
+
+    it('should use the left-most X-Forwarded-For IP in compatibility mode', () => {
+      setTrustedProxyEnable(false);
+
+      const ip = getClientIpFromRequest(
+        createReq({
+          remoteAddress: '127.0.0.1',
+          headers: {
+            'x-forwarded-for': '203.0.113.50, 10.0.0.20'
+          }
+        })
+      );
+
+      expect(ip).toBe('203.0.113.50');
+    });
+
     it('should ignore spoofed forwarding headers for direct requests', () => {
       setTrustedProxyIps(undefined);