fix: 兼容反代和 Docker 客户端 IP 解析

deploy/EDGE_SECURITY.md

@@ -29,15 +29,21 @@ the application's responsibility.
 
 ## Trusted client IPs
 
-`server.trusted_proxies` must contain only the CIDR/IP addresses that connect
-directly to Sub2API, normally the local Nginx/Caddy address or the private load
-balancer subnet. An empty list disables forwarded-IP trust.
+`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.
 
-Never trust `CF-Connecting-IP`, `X-Real-IP`, or `X-Forwarded-For` 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.
+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.
 
-Example for a proxy on the same host:
+Example for a proxy on the same host (the default already covers this case):
 
 ```yaml
 server:

deploy/config.example.yaml

@@ -36,9 +36,18 @@ server:
   # Keep-alive idle timeout in seconds.
   # Keep-Alive 空闲连接超时（秒）。
   idle_timeout: 120
-  # Trusted proxies for X-Forwarded-For parsing (CIDR/IP). Empty disables trusted proxies.
-  # 信任的代理地址（CIDR/IP 格式），用于解析 X-Forwarded-For 头。留空则禁用代理信任。
-  trusted_proxies: []
+  # 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:
+    - 127.0.0.0/8
+    - ::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