diff --git a/deploy/EDGE_SECURITY.md b/deploy/EDGE_SECURITY.md
index b2c08cf20c..0c0e78768a 100644
--- a/deploy/EDGE_SECURITY.md
+++ b/deploy/EDGE_SECURITY.md
@@ -29,21 +29,23 @@ the application's responsibility.
 
 ## Trusted client IPs
 
-`server.trusted_proxies` controls forwarded-IP trust for security-sensitive
-paths such as API-key ACLs, session binding, and rejection aggregation. Fresh
-installations default to local/container ranges (`127.0.0.0/8`, `::1/128`,
-`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, and `fc00::/7`) so a local
-Nginx/Caddy or Docker bridge works without a migration. For a remote load
-balancer, replace the defaults with only the CIDRs that connect directly to
-Sub2API. An explicit empty list disables forwarded-IP trust for these paths;
-ordinary request/usage metadata keeps its legacy compatibility behavior.
+`security.trust_forwarded_ip_for_api_key_acl` is enabled by default for upgrade
+compatibility. On the first upgrade to this mode, a legacy `false` value is
+changed to `true` only when `server.trusted_proxies` was not explicitly
+configured; explicit proxy policies remain in secure mode. Later administrator
+changes are preserved. While enabled, raw `CF-Connecting-IP`, `X-Real-IP`, and
+`X-Forwarded-For` values take over client-IP resolution for logs and
+security-sensitive paths. Disable the switch to make Gin's
+`server.trusted_proxies` chain authoritative. Configure only the exact CIDR/IP
+addresses that connect directly to Sub2API; an explicit empty list trusts no
+forwarded client IPs while the switch is disabled.
 
-Never use `CF-Connecting-IP`, `X-Real-IP`, or `X-Forwarded-For` for an ACL or
-session decision merely because the header exists. A CDN deployment must
-firewall the origin so only the CDN or load balancer can reach it, and the proxy
-must overwrite forwarded headers.
+Compatibility takeover accepts forwarded headers without validating the direct
+peer. Protect the origin from direct access while it is enabled. A CDN
+deployment must firewall the origin so only the CDN or load balancer can reach
+it, and the proxy must overwrite forwarded headers.
 
-Example for a proxy on the same host (the default already covers this case):
+Example for a proxy on the same host:
 
 ```yaml
 server:
diff --git a/deploy/config.example.yaml b/deploy/config.example.yaml
index 2720c2d298..e84a906d4d 100644
--- a/deploy/config.example.yaml
+++ b/deploy/config.example.yaml
@@ -36,18 +36,15 @@ server:
   # Keep-alive idle timeout in seconds.
   # Keep-Alive 空闲连接超时（秒）。
   idle_timeout: 120
-  # Trusted proxies for security-sensitive X-Forwarded-For parsing (CIDR/IP).
-  # These local/container ranges are the default; replace them with the exact
-  # proxy CIDRs for a remote load balancer. Set [] explicitly to disable trust.
-  # 安全敏感场景解析 X-Forwarded-For 的可信代理（CIDR/IP）。以下为本机/容器
-  # 网段默认值；远程负载均衡请替换为实际 CIDR。显式设置 [] 可禁用代理信任。
+  # Trusted proxies used when security.trust_forwarded_ip_for_api_key_acl is false.
+  # List only the exact proxy addresses that connect directly to Sub2API.
+  # Set [] explicitly to disable forwarded-IP trust in high-security mode.
+  # security.trust_forwarded_ip_for_api_key_acl=false 时使用的可信代理。
+  # 只填写直接连接 Sub2API 的精确代理地址；显式设置 [] 可在高安全模式下
+  # 禁用转发 IP 信任。
   trusted_proxies:
-    - 127.0.0.0/8
+    - 127.0.0.1/32
     - ::1/128
-    - 10.0.0.0/8
-    - 172.16.0.0/12
-    - 192.168.0.0/16
-    - fc00::/7
   # Global max request body size in bytes (default: 256MB)
   # 全局最大请求体大小（字节，默认 256MB）
   # Applies to all requests, especially important for h2c first request memory protection
@@ -104,6 +101,11 @@ cors:
 # 安全配置
 # =============================================================================
 security:
+  # Legacy compatibility switch. When true, raw forwarded headers take over
+  # server.trusted_proxies. Set false to enforce the trusted proxy chain above.
+  # 旧版兼容开关。开启时原始转发头会接管 server.trusted_proxies；关闭后严格
+  # 使用上方配置的可信代理链。示例配置采用高安全模式。
+  trust_forwarded_ip_for_api_key_acl: false
   url_allowlist:
     # Enable URL allowlist validation (disable to skip all URL checks)
     # 启用 URL 白名单验证（禁用则跳过所有 URL 检查）