Qinglong 面板部署在反向代理后如何配置并诊断客户端真实 IP【免费下载链接】qinglong支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台Timed task management platform supporting Python3, JavaScript, Shell, Typescript项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong当 Qinglong青龙面板部署在 Nginx 等反向代理之后时面板从连接上拿到的地址是代理的地址而不是访问者的真实地址。此时登录日志、安全策略等依赖客户端 IP 的功能就会记录到代理 IP。项目为此提供了两层能力QL_TRUST_PROXY环境变量见 .env.example和「系统设置 → 客户端 IP」页面的可信代理配置与诊断工具实现见 back/shared/trustProxy.ts、back/api/clientIp.ts界面见 src/pages/setting/clientIp.tsx。本文介绍两种配置路径以及如何用页面内置的诊断确认最终客户端 IP 是否解析正确。面板如何从代理链中识别客户端 IP面板的判定逻辑是从离青龙最近的一跳开始由右向左检查代理链把第一个不可信地址作为客户端 IP这是设置页顶部「可信代理配置说明」的原文表述实现位于diagnoseClientIp。未做任何配置时信任值默认为loopback即只信任本地回环地址。判断结果在页面上以三种状态呈现可信代理、最终客户端、未检查分别对应诊断返回的trusted、client、not_checked。配置方式一环境变量 QL_TRUST_PROXY在启动面板的环境例如容器的环境变量或.env文件中设置QL_TRUST_PROXY。.env.example 给出的说明与示例# 可信反向代理。未设置时可在「系统设置 → 客户端 IP」中配置和诊断。 # 环境变量优先级高于系统设置。支持固定层数、IP、CIDR 或逗号分隔列表 # QL_TRUST_PROXY1 # QL_TRUST_PROXYloopback,172.18.0.0/16,10.20.0.8/32 # 仅在面板端口绝对无法绕过代理直接访问时使用 true。 # QL_TRUST_PROXYloopback支持的取值形态见resolveTrustProxy纯数字代理层数例如1IP、CIDR 或逗号分隔列表例如loopback,172.18.0.0/16,10.20.0.8/32true/falsetrue仅在面板端口绝对无法绕过代理直接访问时使用面板提示明确建议不要直接使用true。两个限制需要注意代理层数不能超过 20配置值最长 500 字符且不能包含换行否则会报「trust proxy 配置格式无效」。配置方式二系统设置 → 客户端 IP 页面没有设置QL_TRUST_PROXY环境变量时可以登录面板在「系统设置 → 客户端 IP」页面配置前端请求api/system/client-ip/config在「Trust Proxy 自定义设置」中选择模式直接访问不信任任何代理等价于关闭代理解析一层代理等价于层数1固定多层输入层数页面范围为 220 层指定地址或网段手动输入 IP/CIDR 列表例如loopback,172.18.0.0/16,10.20.0.8/32。点击「保存配置」保存成功后页面提示「更新成功」并自动重新诊断。页面「当前生效值」会显示生效的trustProxy值及来源默认配置 / 系统设置 / 环境变量。页面说明同时给出两条选型建议代理层数只适合所有访问路径长度完全一致的部署生产环境更推荐填写代理的固定 IP 或专用网络 CIDR。如果你的流量会经过长度不一致的代理链应优先使用「指定地址或网段」。诊断客户端 IP配置保存后或随时点击「客户端 IP 诊断」区域的「重新诊断」按钮面板会展示Socket 地址面板与对端 TCP 连接的远端地址remoteAddressX-Forwarded-For请求头中携带的代理链地址列表最终客户端 IP面板按当前 trust proxy 配置解析出的客户端地址代理链表每一跳的地址、跳数距离青龙的跳数和判定结果可信代理 / 最终客户端 / 未检查。对应的后端接口为GET api/system/client-ip/config读取当前配置与来源、PUT api/system/client-ip/config更新请求体{ trustProxy: ... }、GET api/system/client-ip/diagnose诊断见 back/api/clientIp.ts。核对方法从你实际出口 IP 的视角看诊断结果——「最终客户端 IP」应当是你的真实出口地址如果它显示为代理地址说明当前 trust proxy 配置没有覆盖到代理链例如代理 IP 不在你填写的网段中或层数与实际路径长度不符需要按上面的配置调整后再重新诊断。另外如果诊断中 X-Forwarded-For 为空面板就只看到与它直连的 Socket 地址此时应先确认反向代理是否在转发X-Forwarded-For头——诊断数据完全来源于该请求头与连接地址代理没有转发该头时面板无从识别上游客户端。环境变量与系统设置的优先级两者只能生效一个QL_TRUST_PROXY的优先级高于系统设置。一旦检测到该环境变量已生效设置页会显示「当前由环境变量 QL_TRUST_PROXY 管理」的警告所有配置控件被禁用并提示「请修改容器环境变量并重启系统设置不能覆盖环境变量」此时若直接调用更新接口会返回「环境变量 QL_TRUST_PROXY 已生效系统设置不可覆盖」。因此如果你先改了页面配置却发现值没变先检查容器/进程环境里是否已经设置了QL_TRUST_PROXY。小结与限制配置生效值最长 500 字符、不含换行代理层数上限 20true只用于面板端口无法绕过代理直连的极端场景层数模式仅适合各访问路径长度一致的部署路径不一致时填写代理 IP 或 CIDR 列表诊断页展示的「最终客户端 IP」和逐跳判定是核对配置是否正确的直接依据调整后重新诊断即可确认。【免费下载链接】qinglong支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台Timed task management platform supporting Python3, JavaScript, Shell, Typescript项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考