3x-ui v3.6.0 更新汇总：xray-core 升至 v26.7.28、订阅正确性和面板加固
3x-ui 在 2026 年 7 月 30 日发布了 v3.6.0，距离上一个引发大量兼容性问题的 v3.5.0（详见《3x-ui v3.5.0 节点连接失败？七个已知 Bug 及临时解决方案汇总》）不到两周。本次更新体量很大：内置 xray-core 升级到 v26.7.28，面板经历了两轮总计 70 处的代码审计修复，另外还有 Overview 页面重做、订阅系统一整批修正、几项面板安全加固。本文按"要不要升级""升级后要注意什么""v3.5.0 的坑修好了没"三个角度整理，方便大家决策。
一、这次更新解决了什么核心问题
1. xray-core 升级到 v26.7.28，REALITY Final Mask 变更被面板兜底
内核升级到 v26.7.28 后，REALITY 的 Final Mask 配置结构发生了破坏性变更：原来的 usernames 列表被替换为必须填写用户名、UUID 和两个 Mojang 材质字段的 profiles 数组，并且不再有"默认回落到 Dream"的容错行为。
针对这个破坏性变更，面板做了两层兜底：
- 保存时校验：如果 Final Mask 配置不完整，面板会在保存配置时直接拒绝，并明确指出缺失的字段，而不是让问题流入生产配置；
- 生成配置时隔离故障：即使某一条 Final Mask 配置有问题，面板生成配置时只会剔除这一条有问题的记录，不会导致整个入站全部离线。
升级前提醒：如果你之前给某个入站启用了 Final Mask 混淆，升级后需要重新补全 profiles 信息，否则该条配置会在保存或生成配置时被拒绝/剔除。
2. 数据库层面：老版本迁移遗留的 tgId 类型问题得到修复
这一条直接对应此前 v3.5.0 的第七个已知问题——从 2.9.4 等老版本升级上来的客户端，tgId 字段以空字符串形式存在数据库里，一编辑保存就报 json: cannot unmarshal string into Go struct field 的错误。v3.6.0 增加了数据库迁移修复逻辑，在升级时自动修复历史遗留的字符串型 tgId，此前受影响、"不能编辑保存"的老客户端理论上不再需要手动进数据库改字段。
3. 两轮大规模审计：70 处修复
- 一轮仓库级自我审计，涉及 54 处经过验证的 bug 修复；
- 一轮基于 bug 标签的 issue 排查，另外修复了 16 处问题。
覆盖范围包括邮件发送、节点同步、订阅生成、xray 配置生成和数据库读写等多个模块，属于面板质量的一次系统性补强，而不是针对单一功能的小修小补。
二、面板安全加固（升级后请注意行为变化）
这部分变化不会导致"连不上"，但会改变现有工具链的对接方式，升级前建议留意：
| 变更内容 | 影响 |
|---|---|
GET /panel/api/openapi.json 现在需要登录会话才能访问 |
此前该接口未经认证即可访问，等于把整个后台 API 接口文档暴露在公网上；如果有脚本依赖免登录访问此接口，升级后需要带上会话 |
| 节点 API Token 改为只写（write-only） | 创建后 API 不再回传 Token 内容，如果你的运维脚本依赖"创建后读取 Token"，需要改为在创建时就保存好 Token |
| 生产环境不再内置 sourcemap | 减小体积、避免源码信息随二进制泄露，纯正向变化，无需额外操作 |
默认出站规则新增 geoip:private 私有网段拦截 |
面板默认的 freedom 出站规则会阻断对私有 IP 段的访问；如果你的出站本来就依赖访问内网私有地址（级联、内网穿透等场景），升级后可能需要手动调整该规则 |
三、订阅系统：一整批"细节但影响面广"的修复
订阅相关问题在 v3.5.0 时期比较集中（对应此前第三条 REALITY 订阅认证失败问题 #5957），v3.6.0 又做了一整批修正，包括：
- 转发 URL 的信任处理修正，配合
trustedProxyCIDRs生效顺序修复； - 外部订阅刷新请求合并，避免重复触发；
- 修正 Clash 订阅里会被 YAML 解析器误判为数字的字符串字段（需要加引号但之前没加）；
- VLESS
flow流控在 JSON 订阅里的启用逻辑与原始链接、Clash 链接保持一致； - 外部代理链接的备注名称保留问题修复；
- WireGuard 的
Allowed IPs在分享链接、.conf文件、订阅三处都能完整保留（此前会丢失部分条目）； - 新增可选的订阅身份令牌、原始订阅下载操作、按 User-Agent 自动识别订阅格式、以及新增
?format=info端点用于查看客户端在线状态。
如果你此前在 Clash/Mihomo 订阅使用上遇到过参数与实际入站不一致的问题，这批修复大概率会有帮助，建议升级后重新拉取一次订阅验证。
四、其他值得关注的修复
- 客户端流量统计：不再误删"已从入站解绑但仍存活"客户端的流量记录；入站被删除后邮箱被复用时，旧的流量记录会正确刷新而不是遗留脏数据。
- 数据库备份：SQLite 备份改为在线快照方式生成，减少备份对运行中面板的影响。
- 端口设置：清空端口输入框不会再意外把端口写成
0，而是保留原有配置。 - REALITY 客户端版本范围：保存时会做校验，避免出现此前 v3.5.0 时期"
minClientVersion设置得比maxClientVersion还高"导致链接直接失效的逻辑冲突（对应此前已知问题第二条 #6069）。 - 出站校验：新增对生成的出站目标做校验，这与此前"无 TLS 的 VLESS 出站被面板误拒"的问题（issue #5916）是相关领域的修复，实际使用中如遇到内网穿透场景仍报错的，建议升级后重新测试。
- WireGuard 客户端地址池：突破了此前限制在
/24以内的容量限制，节点规模较大时更实用。 - 前端体验：Overview 概览页整体重做为"趋势优先"的仪表盘风格，四个核心指标卡片带 72 个采样点的迷你走势图，新增吞吐量双序列图表和 TCP/UDP 连接数图表；组件库修复了所有无障碍访问（a11y）问题；前端依赖升级到 react-router 8、Node 24 LTS；删除了 230 个失效的多语言翻译键。
五、对照表：v3.5.0 已知问题在 v3.6.0 中的修复情况
| v3.5.0 已知问题 | v3.6.0 修复情况 |
|---|---|
| ① REALITY dest 用 microsoft.com 握手失败（Xray-core #6356） | 未在本次修复范围内，这是 REALITY 库本身的硬编码限制，与面板版本无关，仍建议换用其他 dest |
| ② minClientVersion / maxClientVersion 默认值逻辑冲突（#6069） | 已修复，v3.6.0 增加了保存时的版本范围校验 |
| ③ REALITY 订阅在 Clash/Mihomo 认证失败（#5957） | 此前已在 v3.5.0 内修复，v3.6.0 又追加了一批订阅正确性修复，进一步降低类似问题概率 |
| ④ 无 TLS 的 VLESS 出站被面板误拒（#5916） | 相关方向已有改进（新增出站目标校验），具体场景建议自行验证 |
| ⑤ XHTTP + REALITY 在 v26.7.11 下失联（Xray-core #6482） | 内核已升级到 v26.7.28，大概率随上游修复而解决，建议升级后实测确认 |
| ⑥ v26.7.11 与多种 REALITY 客户端不兼容（#6477 / #6048） | 同上，内核版本已更新，理论上不再受影响 |
| ⑦ 老版本升级后 tgId 类型冲突导致客户端无法编辑（#5934） | 已修复，新增数据库迁移逻辑自动修复历史字符串型 tgId |
可以看到，七条已知问题里，除了第①条（REALITY 库本身的硬编码限制，非面板可控）之外，其余基本都已修复或大概率随内核升级而解决。整体来看，v3.6.0 更像是一次针对 v3.5.0 遗留问题的"补课式"发布。
六、升级建议
- 升级前务必备份数据库：
cp /etc/x-ui/x-ui.db /etc/x-ui/x-ui.db.bak.$(date +%F)，虽然本次没有大的 schema 变更，但涉及数据库迁移逻辑，稳妥起见还是建议备份。 - 如果用了 REALITY Final Mask 混淆，升级后第一时间检查对应入站的
profiles信息是否完整，避免保存配置时被拒绝。 - 如果有外部脚本依赖
openapi.json或读取节点 API Token，升级前调整好对接方式（带会话访问 / 创建时保存 Token）。 - 如果之前因为 XHTTP+REALITY 或 mihomo 兼容性问题手动把内核锁定在 v26.6.27，可以尝试升级面板并同步内核到 v26.7.28 后重新测试，理论上问题已经解决。
- 升级后重新拉取一次订阅，确认 Clash/Mihomo 等客户端订阅可以正常连接。