{"topic":{"id":15608,"title":"xray配置入站，个人遇到的一点小问题","slug":"topic","categoryId":60,"createdAt":"2026-06-28 08:43:39.66688","bumpedAt":"2026-06-29 06:01:27.955104","views":765,"postsCount":6,"highestPostNumber":6,"likeCount":4,"closed":false,"pinned":false,"excerpt":"Xray VLESS 入站配置：users 还是 clients？问题按照 Xray 官方文档配置 VLESS 入站时，文档要求使用 users 字段： { \"inbounds\": [{ \"protocol\": \"vless\", \"settings\": { \"users\": [ { \"id\": \"5783a3e7-e373-51cd-8642-c83782b807c5\" } ], \"decryption\": \"none\" } }]…","deletedAt":null,"isAnonymous":false,"category":{"id":60,"name":"日志 / 部落格","slug":"journal","color":"F7941D"},"author":{"id":8156,"username":"setsuna","name":"做回自己世莉架","avatarUrl":"/uploads/image/cc/3a/cc3acf27f130c3875e247a5a040c3e822cf414ecbc78a12f2c11798096606cc2.avif"},"tags":[]},"posts":[{"id":72434,"postNumber":1,"raw":"# Xray VLESS 入站配置：`users` 还是 `clients`？\n\n## 问题\n\n按照 [Xray 官方文档](https://xtls.github.io/en/config/inbounds/vless.html) 配置 VLESS 入站时，文档要求使用 `users` 字段：\n\n```json\n{\n \"inbounds\": [{\n \"protocol\": \"vless\",\n \"settings\": {\n \"users\": [\n { \"id\": \"5783a3e7-e373-51cd-8642-c83782b807c5\" }\n ],\n \"decryption\": \"none\"\n }\n }]\n}\n```\n\n但实际运行时，客户端连接被拒绝，服务器日志报错：\n\n```\nrejected proxy/vless/encoding: invalid request user id\n```\n\n改为 `clients` 后一切正常。**为什么文档和实际行为不一致？**\n\n---\n\n## 本机环境\n\n| 项目 | 值 |\n|------|-----|\n| Xray 版本 | v26.3.27 |\n| 协议 | VLESS |\n| 操作系统 | Linux (WSL2) |\n| 安装日期 | 2026-06-27 |\n| 安装方式 | 官方安装脚本 |\n\n---\n\n## 实验：对照测试\n\n### 实验设计\n\n构建两个仅字段名不同的 VLESS 入站配置，用同一客户端分别连接，观察服务器日志。\n\n### 步骤 1 — 准备配置文件\n\n**配置 A：使用 `users` 字段**（官方文档写法）\n\n```json\n{\n \"log\": {\"loglevel\": \"debug\"},\n \"inbounds\": [{\n \"listen\": \"127.0.0.1\",\n \"port\": 19997,\n \"protocol\": \"vless\",\n \"settings\": {\n \"users\": [\n { \"id\": \"test-user-uuid-00000000000000\" }\n ],\n \"decryption\": \"none\"\n },\n \"tag\": \"vless-in-users\"\n }],\n \"outbounds\": [{\"protocol\": \"freedom\", \"tag\": \"direct\"}]\n}\n```\n\n**配置 B：使用 `clients` 字段**（网络教程常见写法）\n\n```json\n{\n \"log\": {\"loglevel\": \"debug\"},\n \"inbounds\": [{\n \"listen\": \"127.0.0.1\",\n \"port\": 19996,\n \"protocol\": \"vless\",\n \"settings\": {\n \"clients\": [\n { \"id\": \"test-user-uuid-00000000000000\" }\n ],\n \"decryption\": \"none\"\n },\n \"tag\": \"vless-in-clients\"\n }],\n \"outbounds\": [{\"protocol\": \"freedom\", \"tag\": \"direct\"}]\n}\n```\n\n**客户端配置**（出站始终使用 `users`——VLESS 出站未受影响）\n\n```json\n{\n \"log\": {\"loglevel\": \"debug\"},\n \"inbounds\": [{\n \"listen\": \"127.0.0.1\",\n \"port\": 29998,\n \"protocol\": \"dokodemo-door\",\n \"settings\": {\"address\": \"httpbin.org\", \"port\": 80, \"network\": \"tcp\"},\n \"tag\": \"dokodemo-in\"\n }],\n \"outbounds\": [{\n \"protocol\": \"vless\",\n \"settings\": {\n \"vnext\": [{\n \"address\": \"127.0.0.1\",\n \"port\": 19997,\n \"users\": [{\n \"id\": \"test-user-uuid-00000000000000\",\n \"encryption\": \"none\"\n }]\n }]\n },\n \"streamSettings\": {\"network\": \"tcp\"},\n \"tag\": \"vless-out\"\n }]\n}\n```\n\n### 步骤 2 — 运行测试\n\n**测试 A：`users` 配置**\n\n```bash\n# 启动服务器\n/tmp/xray run -c server_users.json &\nSERVER_PID=$!\n\n# 等待服务器就绪\nsleep 2\n\n# 启动客户端并发起请求\n/tmp/xray run -c client.json &\nCLIENT_PID=$!\n\n# 通过 dokodemo-door 代理访问 httpbin.org\ncurl -x http://127.0.0.1:29998 http://httpbin.org/ip\n```\n\n**测试 B：`clients` 配置**\n\n```bash\n# 同上，仅将服务器配置和端口替换为 server_clients.json / 19996\n```\n\n### 步骤 3 — 对比日志\n\n**测试 A 的服务器日志**（`users`）：\n\n```\nfrom 127.0.0.1:46619 rejected\n proxy/vless/encoding: invalid request user id: 14268965-70cd-5490-ac03-e71afae4f108\n\n[Info] proxy/vless/inbound: firstLen = 159\n[Info] app/proxyman/inbound: connection ends > proxy/vless/inbound:\n invalid request from 127.0.0.1:46619 >\n proxy/vless/encoding: invalid request user id: ...\n```\n\n**测试 B 的服务器日志**（`clients`）：\n\n```\n[Info] proxy/vless/inbound: firstLen = 159\n[Info] proxy/vless/inbound: received request for tcp:httpbin.org:80\n[Info] app/dispatcher: default route for tcp:httpbin.org:80\n[Info] transport/internet/tcp: dialing TCP to tcp:httpbin.org:80\nfrom 127.0.0.1:43385 accepted tcp:httpbin.org:80 [vless-in-clients >> direct]\n[Info] proxy/freedom: connection opened to tcp:httpbin.org:80,\n local endpoint 192.168.1.249:44725, remote endpoint 198.18.56.109:80\n```\n\n### 结论\n\n| 字段名 | 连接结果 | 服务器行为 |\n|--------|---------|-----------|\n| `users` | ❌ 拒绝 | 用户列表为空，不认识任何客户端 |\n| `clients` | ✅ 接受 | 正确识别用户，成功转发到目标 |\n\n---\n\n## 根因分析\n\n### 追溯源码\n\nVLESS 入站配置由 Protobuf 定义。检查 Xray-core 源码：\n\n**文件**：[`proxy/vless/inbound/config.proto`](https://github.com/XTLS/Xray-core/blob/main/proxy/vless/inbound/config.proto)\n\n```protobuf\nmessage Config {\n repeated xray.common.protocol.User users = 1;\n repeated Fallback fallbacks = 2;\n string decryption = 3;\n // ...\n}\n```\n\n对应生成的 Go 结构体（[`config.pb.go`](https://github.com/XTLS/Xray-core/blob/main/proxy/vless/inbound/config.pb.go)）：\n\n```go\ntype Config struct {\n Users []*protocol.User `protobuf:\"bytes,1,rep,name=users,proto3\" json:\"users,omitempty\"`\n Fallbacks []*Fallback `protobuf:\"bytes,2,rep,name=fallbacks,proto3\" json:\"fallbacks,omitempty\"`\n Decryption string `protobuf:\"bytes,3,opt,name=decryption,proto3\" json:\"decryption,omitempty\"`\n // ...\n}\n```\n\nJSON tag 是 `json:\"users,omitempty\"`——这和官方文档一致。**但本机版本为什么不是这样？**\n\n### 字段名在 2026 年 5 月被重命名\n\n通过 Git 历史追踪，找到了决定性 commit：\n\n```\nc42deab55c 2026-05-07 Config: Rename inbounds' `clients`/`accounts` to `users` (#6083)\n```\n\n[PR #6083](https://github.com/XTLS/Xray-core/pull/6083) 的作者（Meo597）将以下入站协议的字段统一重命名：\n\n| 协议 | 旧字段名 | 新字段名 | 向后兼容 |\n|------|---------|---------|----------|\n| VLESS | `clients` | `users` | **无别名，直接破坏** |\n| VMess | `clients` | `users` | 同上 |\n| Trojan | `clients` | `users` | 同上 |\n| Shadowsocks | `clients` | `users` | 同上 |\n| Socks | `accounts` | `users` | 保留别名 |\n| HTTP | `accounts` | `users` | 保留别名 |\n\nPR 讨论中明确了 **VLESS/VMess/Trojan/Shadowsocks 不保留别名**，这意味着旧配置必须手动修改字段名。\n\n### 版本发布情况\n\nPR 于 2026-05-07 合并。之后的发布记录：\n\n| 版本 | 日期 | 类型 | `users` 支持 |\n|------|------|------|-------------|\n| v26.3.27 | 2026-03-27 | **稳定版** | ❌ 只有 `clients` |\n| v26.3.23 | 2026-03-23 | pre-release | ❌ |\n| v26.4.x | 2026-04 | pre-release | ❌ |\n| v26.5.3 | 2026-05-03 | pre-release | ❌ |\n| **v26.5.9** | **2026-05-09** | pre-release | ✅ |\n| v26.6.x | 2026-06 | pre-release | ✅ |\n| v26.6.27 | 2026-06-27 | pre-release | ✅ |\n\n**v26.3.27 是最新的稳定版。** 所有带 `users` 字段的版本（v26.5.9+）至今都是 pre-release。\n\n### 为什么下载到的是 \"旧版\"\n\nGitHub 的 `/releases/latest` API 返回 **最新的非 pre-release 版本**：\n\n```\n$ curl -s \"https://api.github.com/repos/XTLS/Xray-core/releases/latest\"\n→ \"tag_name\": \"v26.3.27\" (2026-03-27)\n```\n\n官方安装脚本默认调用此 API，因此任何用户通过标准方式安装都会得到 v26.3.27——即使有更新的 pre-release。\n\n文件时间戳证实了这一点：\n\n```\n$ stat /tmp/xray\n Birth: 2026-06-27 00:01:29 ← 确实是昨天下载的\n Version: 26.3.27 ← 但版本是 3 月的\n```\n\n**没有做错任何事**——官方文档已经更新为 `users`，但官方稳定版还在用 `clients`，而安装脚本默认装稳定版。这是一个文档与稳定发布之间的同步滞后问题。\n\n---\n\n## Protobuf 的静默忽略机制\n\n一个关键问题：为什么用 `users` 字段时 Xray 不报错，而是静默失败？\n\nProtobuf 的 JSON 解析器默认行为是**忽略未知字段**。在 v26.3.27 的代码中：\n\n1. JSON 中出现 `\"users\"` → Protobuf 在 `Config` 消息中查找字段名 `users`\n2. v26.3.27 的 `Config` 定义中，字段名叫 `clients`，没有 `users`\n3. Protobuf 将 `\"users\"` 视为未知字段，**静默丢弃**\n4. 结果：`Config.Users`（Go 字段）为空切片 → 零个合法用户\n5. 任何客户端连接都因 \"invalid request user id\" 被拒绝\n\n这意味着用错字段名的配置**可以正常启动、不报任何 warning**，但功能完全失效。这对排查问题极为不利。\n\n---\n\n## 复现指南\n\n以下步骤可在任何 Linux 环境复现本研究的结论。\n\n### 环境准备\n\n```bash\n# 下载最新稳定版 Xray（将得到 v26.3.27）\nbash -c \"$(curl -sL https://raw.githubusercontent.com/XTLS/Xray-install/main/install-release.sh)\" @ install\n```\n\n### 实验步骤\n\n**1. 创建 `users` 测试配置**\n\n```bash\ncat > /tmp/srv_users.json <<'EOF'\n{\n \"log\": {\"loglevel\": \"debug\"},\n \"inbounds\": [{\n \"listen\": \"127.0.0.1\", \"port\": 19997,\n \"protocol\": \"vless\",\n \"settings\": {\n \"users\": [{\"id\": \"test-user-uuid-00000000000000\"}],\n \"decryption\": \"none\"\n },\n \"tag\": \"vless-in\"\n }],\n \"outbounds\": [{\"protocol\": \"freedom\", \"tag\": \"direct\"}]\n}\nEOF\n```\n\n**2. 启动服务器并观察日志**\n\n```bash\nxray run -c /tmp/srv_users.json &\nsleep 2\n```\n\n**3. 用任意 VLESS 客户端连接，观察日志**\n\n```bash\n# 服务器日志将显示：\n# rejected proxy/vless/encoding: invalid request user id\n```\n\n**4. 将 `users` 改为 `clients`，重复测试**\n\n```bash\n# 服务器日志将显示：\n# accepted tcp: [vless-in >> direct]\n```\n\n### 验证版本边界\n\n```bash\n# 检查本地版本\nxray version\n\n# 查看 GitHub 最新稳定版\ncurl -s https://api.github.com/repos/XTLS/Xray-core/releases/latest | jq '.tag_name'\n\n# 查看所有版本（含 pre-release）\ncurl -s https://api.github.com/repos/XTLS/Xray-core/releases | jq '.[].tag_name'\n```\n\n---\n\n## 解决方案\n\n### 使用 `clients`\n\n如果通过标准安装方式获取 Xray，版本就是 v26.3.27 稳定版，**使用 `clients`**。\n\n```json\n{\n \"inbounds\": [{\n \"protocol\": \"vless\",\n \"settings\": {\n \"clients\": [\n {\n \"id\": \"your-uuid-here\",\n \"flow\": \"xtls-rprx-vision\"\n }\n ],\n \"decryption\": \"none\"\n }\n }]\n}\n```\n\n### 方案二：升级到 pre-release 并使用 `users`\n\n```bash\n# 指定 pre-release 版本安装\nXRAY_VERSION=v26.6.27 bash -c \"$(curl -sL https://raw.githubusercontent.com/XTLS/Xray-install/main/install-release.sh)\" @ install\n```\n\n然后配置文件使用 `users`。\n\n---\n\n## 时间线总结\n\n```\n2026-03-27 v26.3.27 稳定版发布（字段名: clients）\n │\n │ 4 月期间多个 pre-release（仍为 clients）\n │\n2026-05-07 PR #6083 合并 → main 分支字段名改为 users\n │\n2026-05-09 v26.5.9 pre-release（首个使用 users 的版本）\n │\n │ 5-6 月多个 pre-release（均为 users）\n │\n2026-06-27 v26.6.27 pre-release 发布\n │ 官方文档跟踪 main 分支 → 文档写 users\n │ GitHub API /releases/latest → 仍返回 v26.3.27\n │\n2026-06-28 本文撰写日期\n │ 稳定版用户 → 应用 clients\n │ 官方文档 → 写的是 users\n │ ═══════════════════════════\n │ 两者不一致，差距已达 52 天\n```\n\n---\n\n## 参考资料\n\n- [Xray-core PR #6083 — Config: Rename inbounds' clients/accounts to users](https://github.com/XTLS/Xray-core/pull/6083)\n- [VLESS 入站配置 proto 定义](https://github.com/XTLS/Xray-core/blob/main/proxy/vless/inbound/config.proto)\n- [VLESS 入站生成的 Go 代码](https://github.com/XTLS/Xray-core/blob/main/proxy/vless/inbound/config.pb.go)\n- [Xray 官方文档 — VLESS 入站](https://xtls.github.io/en/config/inbounds/vless.html)\n- [Xray-core Releases](https://github.com/XTLS/Xray-core/releases)\n- [3x-ui Issue #3872 — vless inbound clients becomes null](https://github.com/MHSanaei/3x-ui/issues/3872)","cooked":"

Xray VLESS 入站配置：`users` 还是 `clients`？

问题

按照 Xray 官方文档配置 VLESS 入站时，文档要求使用 users 字段：

{\n  \"inbounds\": [{\n    \"protocol\": \"vless\",\n    \"settings\": {\n      \"users\": [\n        { \"id\": \"5783a3e7-e373-51cd-8642-c83782b807c5\" }\n      ],\n      \"decryption\": \"none\"\n    }\n  }]\n}\n

但实际运行时，客户端连接被拒绝，服务器日志报错：

rejected  proxy/vless/encoding: invalid request user id\n

改为 clients 后一切正常。为什么文档和实际行为不一致？

本机环境

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

项目	值
Xray 版本	v26.3.27
协议	VLESS
操作系统	Linux (WSL2)
安装日期	2026-06-27
安装方式	官方安装脚本

实验：对照测试

实验设计

构建两个仅字段名不同的 VLESS 入站配置，用同一客户端分别连接，观察服务器日志。

步骤 1 — 准备配置文件

配置 A：使用 users 字段（官方文档写法）

{\n  \"log\": {\"loglevel\": \"debug\"},\n  \"inbounds\": [{\n    \"listen\": \"127.0.0.1\",\n    \"port\": 19997,\n    \"protocol\": \"vless\",\n    \"settings\": {\n      \"users\": [\n        { \"id\": \"test-user-uuid-00000000000000\" }\n      ],\n      \"decryption\": \"none\"\n    },\n    \"tag\": \"vless-in-users\"\n  }],\n  \"outbounds\": [{\"protocol\": \"freedom\", \"tag\": \"direct\"}]\n}\n

配置 B：使用 clients 字段（网络教程常见写法）

{\n  \"log\": {\"loglevel\": \"debug\"},\n  \"inbounds\": [{\n    \"listen\": \"127.0.0.1\",\n    \"port\": 19996,\n    \"protocol\": \"vless\",\n    \"settings\": {\n      \"clients\": [\n        { \"id\": \"test-user-uuid-00000000000000\" }\n      ],\n      \"decryption\": \"none\"\n    },\n    \"tag\": \"vless-in-clients\"\n  }],\n  \"outbounds\": [{\"protocol\": \"freedom\", \"tag\": \"direct\"}]\n}\n

客户端配置（出站始终使用 users——VLESS 出站未受影响）

{\n  \"log\": {\"loglevel\": \"debug\"},\n  \"inbounds\": [{\n    \"listen\": \"127.0.0.1\",\n    \"port\": 29998,\n    \"protocol\": \"dokodemo-door\",\n    \"settings\": {\"address\": \"httpbin.org\", \"port\": 80, \"network\": \"tcp\"},\n    \"tag\": \"dokodemo-in\"\n  }],\n  \"outbounds\": [{\n    \"protocol\": \"vless\",\n    \"settings\": {\n      \"vnext\": [{\n        \"address\": \"127.0.0.1\",\n        \"port\": 19997,\n        \"users\": [{\n          \"id\": \"test-user-uuid-00000000000000\",\n          \"encryption\": \"none\"\n        }]\n      }]\n    },\n    \"streamSettings\": {\"network\": \"tcp\"},\n    \"tag\": \"vless-out\"\n  }]\n}\n

步骤 2 — 运行测试

测试 A：users 配置

# 启动服务器\n/tmp/xray run -c server_users.json &\nSERVER_PID=$!\n\n# 等待服务器就绪\nsleep 2\n\n# 启动客户端并发起请求\n/tmp/xray run -c client.json &\nCLIENT_PID=$!\n\n# 通过 dokodemo-door 代理访问 httpbin.org\ncurl -x http://127.0.0.1:29998 http://httpbin.org/ip\n

测试 B：clients 配置

# 同上，仅将服务器配置和端口替换为 server_clients.json / 19996\n

步骤 3 — 对比日志

测试 A 的服务器日志（users）：

from 127.0.0.1:46619 rejected\n  proxy/vless/encoding: invalid request user id: 14268965-70cd-5490-ac03-e71afae4f108\n\n[Info] proxy/vless/inbound: firstLen = 159\n[Info] app/proxyman/inbound: connection ends > proxy/vless/inbound:\n  invalid request from 127.0.0.1:46619 >\n  proxy/vless/encoding: invalid request user id: ...\n

测试 B 的服务器日志（clients）：

[Info] proxy/vless/inbound: firstLen = 159\n[Info] proxy/vless/inbound: received request for tcp:httpbin.org:80\n[Info] app/dispatcher: default route for tcp:httpbin.org:80\n[Info] transport/internet/tcp: dialing TCP to tcp:httpbin.org:80\nfrom 127.0.0.1:43385 accepted tcp:httpbin.org:80 [vless-in-clients >> direct]\n[Info] proxy/freedom: connection opened to tcp:httpbin.org:80,\n  local endpoint 192.168.1.249:44725, remote endpoint 198.18.56.109:80\n

结论

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

字段名	连接结果	服务器行为
`users`	❌ 拒绝	用户列表为空，不认识任何客户端
`clients`	✅ 接受	正确识别用户，成功转发到目标

根因分析

追溯源码

VLESS 入站配置由 Protobuf 定义。检查 Xray-core 源码：

文件：proxy/vless/inbound/config.proto

message Config {\n  repeated xray.common.protocol.User users = 1;\n  repeated Fallback fallbacks = 2;\n  string decryption = 3;\n  // ...\n}\n

对应生成的 Go 结构体（config.pb.go）：

type Config struct {\n    Users     []*protocol.User `protobuf:\"bytes,1,rep,name=users,proto3\" json:\"users,omitempty\"`\n    Fallbacks []*Fallback      `protobuf:\"bytes,2,rep,name=fallbacks,proto3\" json:\"fallbacks,omitempty\"`\n    Decryption string          `protobuf:\"bytes,3,opt,name=decryption,proto3\" json:\"decryption,omitempty\"`\n    // ...\n}\n

JSON tag 是 json:\"users,omitempty\"——这和官方文档一致。但本机版本为什么不是这样？

字段名在 2026 年 5 月被重命名

通过 Git 历史追踪，找到了决定性 commit：

c42deab55c  2026-05-07  Config: Rename inbounds' `clients`/`accounts` to `users` (#6083)\n

PR #6083 的作者（Meo597）将以下入站协议的字段统一重命名：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

协议	旧字段名	新字段名	向后兼容
VLESS	`clients`	`users`	无别名，直接破坏
VMess	`clients`	`users`	同上
Trojan	`clients`	`users`	同上
Shadowsocks	`clients`	`users`	同上
Socks	`accounts`	`users`	保留别名
HTTP	`accounts`	`users`	保留别名

PR 讨论中明确了 VLESS/VMess/Trojan/Shadowsocks 不保留别名，这意味着旧配置必须手动修改字段名。

版本发布情况

PR 于 2026-05-07 合并。之后的发布记录：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

版本	日期	类型	`users` 支持
v26.3.27	2026-03-27	稳定版	❌ 只有 `clients`
v26.3.23	2026-03-23	pre-release	❌
v26.4.x	2026-04	pre-release	❌
v26.5.3	2026-05-03	pre-release	❌
v26.5.9	2026-05-09	pre-release	✅
v26.6.x	2026-06	pre-release	✅
v26.6.27	2026-06-27	pre-release	✅

v26.3.27 是最新的稳定版。 所有带 users 字段的版本（v26.5.9+）至今都是 pre-release。

为什么下载到的是 \"旧版\"

GitHub 的 /releases/latest API 返回 最新的非 pre-release 版本：

$ curl -s \"https://api.github.com/repos/XTLS/Xray-core/releases/latest\"\n→ \"tag_name\": \"v26.3.27\"    (2026-03-27)\n

官方安装脚本默认调用此 API，因此任何用户通过标准方式安装都会得到 v26.3.27——即使有更新的 pre-release。

文件时间戳证实了这一点：

$ stat /tmp/xray\n  Birth: 2026-06-27 00:01:29   ← 确实是昨天下载的\n  Version: 26.3.27              ← 但版本是 3 月的\n

没有做错任何事——官方文档已经更新为 users，但官方稳定版还在用 clients，而安装脚本默认装稳定版。这是一个文档与稳定发布之间的同步滞后问题。

Protobuf 的静默忽略机制

一个关键问题：为什么用 users 字段时 Xray 不报错，而是静默失败？

Protobuf 的 JSON 解析器默认行为是忽略未知字段。在 v26.3.27 的代码中：

JSON 中出现 \"users\" → Protobuf 在 Config 消息中查找字段名 users
v26.3.27 的 Config 定义中，字段名叫 clients，没有 users
Protobuf 将 \"users\" 视为未知字段，静默丢弃
结果：Config.Users（Go 字段）为空切片 → 零个合法用户
任何客户端连接都因 \"invalid request user id\" 被拒绝

这意味着用错字段名的配置可以正常启动、不报任何 warning，但功能完全失效。这对排查问题极为不利。

复现指南

以下步骤可在任何 Linux 环境复现本研究的结论。

环境准备

# 下载最新稳定版 Xray（将得到 v26.3.27）\nbash -c \"$(curl -sL https://raw.githubusercontent.com/XTLS/Xray-install/main/install-release.sh)\" @ install\n

实验步骤

1. 创建 users 测试配置

cat > /tmp/srv_users.json <<'EOF'\n{\n  \"log\": {\"loglevel\": \"debug\"},\n  \"inbounds\": [{\n    \"listen\": \"127.0.0.1\", \"port\": 19997,\n    \"protocol\": \"vless\",\n    \"settings\": {\n      \"users\": [{\"id\": \"test-user-uuid-00000000000000\"}],\n      \"decryption\": \"none\"\n    },\n    \"tag\": \"vless-in\"\n  }],\n  \"outbounds\": [{\"protocol\": \"freedom\", \"tag\": \"direct\"}]\n}\nEOF\n

2. 启动服务器并观察日志

xray run -c /tmp/srv_users.json &\nsleep 2\n

3. 用任意 VLESS 客户端连接，观察日志

# 服务器日志将显示：\n# rejected  proxy/vless/encoding: invalid request user id\n

4. 将 users 改为 clients，重复测试

# 服务器日志将显示：\n# accepted tcp:<target> [vless-in >> direct]\n

验证版本边界

# 检查本地版本\nxray version\n\n# 查看 GitHub 最新稳定版\ncurl -s https://api.github.com/repos/XTLS/Xray-core/releases/latest | jq '.tag_name'\n\n# 查看所有版本（含 pre-release）\ncurl -s https://api.github.com/repos/XTLS/Xray-core/releases | jq '.[].tag_name'\n

解决方案

使用 `clients`

如果通过标准安装方式获取 Xray，版本就是 v26.3.27 稳定版，使用 clients。

{\n  \"inbounds\": [{\n    \"protocol\": \"vless\",\n    \"settings\": {\n      \"clients\": [\n        {\n          \"id\": \"your-uuid-here\",\n          \"flow\": \"xtls-rprx-vision\"\n        }\n      ],\n      \"decryption\": \"none\"\n    }\n  }]\n}\n

方案二：升级到 pre-release 并使用 `users`

# 指定 pre-release 版本安装\nXRAY_VERSION=v26.6.27 bash -c \"$(curl -sL https://raw.githubusercontent.com/XTLS/Xray-install/main/install-release.sh)\" @ install\n

然后配置文件使用 users。

时间线总结

2026-03-27  v26.3.27 稳定版发布（字段名: clients）\n     │\n     │  4 月期间多个 pre-release（仍为 clients）\n     │\n2026-05-07  PR #6083 合并 → main 分支字段名改为 users\n     │\n2026-05-09  v26.5.9 pre-release（首个使用 users 的版本）\n     │\n     │  5-6 月多个 pre-release（均为 users）\n     │\n2026-06-27  v26.6.27 pre-release 发布\n     │          官方文档跟踪 main 分支 → 文档写 users\n     │          GitHub API /releases/latest → 仍返回 v26.3.27\n     │\n2026-06-28  本文撰写日期\n     │          稳定版用户 → 应用 clients\n     │          官方文档   → 写的是 users\n     │          ═══════════════════════════\n     │          两者不一致，差距已达 52 天\n

参考资料

\n","createdAt":"2026-06-28 08:43:40.061655","updatedAt":"2026-06-28 08:43:40.061655","replyToPostNumber":null,"replyCount":0,"likeCount":0,"wordCount":2020,"liked":false,"bookmarked":false,"polls":[],"reactions":[],"wiki":false,"version":1,"publicVersion":1,"deletedAt":null,"isAnonymous":false,"user":{"id":8156,"username":"setsuna","name":"做回自己世莉架","avatarUrl":"/uploads/image/cc/3a/cc3acf27f130c3875e247a5a040c3e822cf414ecbc78a12f2c11798096606cc2.avif","admin":false,"moderator":false,"signatureRaw":null,"signatureCooked":null}},{"id":72435,"postNumber":2,"raw":"注：本文由deepseek创作","cooked":"

注：本文由deepseek创作

\n","createdAt":"2026-06-28 08:45:01.022654","updatedAt":"2026-06-28 08:45:01.022654","replyToPostNumber":null,"replyCount":0,"likeCount":0,"wordCount":8,"liked":false,"bookmarked":false,"polls":[],"reactions":[],"wiki":false,"version":1,"publicVersion":1,"deletedAt":null,"isAnonymous":false,"user":{"id":8156,"username":"setsuna","name":"做回自己世莉架","avatarUrl":"/uploads/image/cc/3a/cc3acf27f130c3875e247a5a040c3e822cf414ecbc78a12f2c11798096606cc2.avif","admin":false,"moderator":false,"signatureRaw":null,"signatureCooked":null}},{"id":72442,"postNumber":3,"raw":"突然意识到为什么xjtu.app叫土原，大概相对于上交的水源吧？","cooked":"

突然意识到为什么xjtu.app叫土原，大概相对于上交的水源吧？

\n","createdAt":"2026-06-28 09:14:00.764951","updatedAt":"2026-06-28 09:14:00.764951","replyToPostNumber":null,"replyCount":0,"likeCount":2,"wordCount":25,"liked":false,"bookmarked":false,"polls":[],"reactions":[{"reaction":"💯️","count":2,"users":[{"id":7364,"username":"青年杰出贡献上交大門人","name":"紫金港第一皮革<・)))><<"},{"id":7830,"username":"stateless_trash_can","name":"无状态垃圾桶"}],"hasReacted":false},{"reaction":"❤️","count":2,"users":[{"id":7364,"username":"青年杰出贡献上交大門人","name":"紫金港第一皮革<・)))><<"},{"id":7830,"username":"stateless_trash_can","name":"无状态垃圾桶"}],"hasReacted":false}],"wiki":false,"version":1,"publicVersion":1,"deletedAt":null,"isAnonymous":false,"user":{"id":8156,"username":"setsuna","name":"做回自己世莉架","avatarUrl":"/uploads/image/cc/3a/cc3acf27f130c3875e247a5a040c3e822cf414ecbc78a12f2c11798096606cc2.avif","admin":false,"moderator":false,"signatureRaw":null,"signatureCooked":null}},{"id":72443,"postNumber":4,"raw":"以前一直是x-ui一键配置，这次尝试手动写xray配置文件，方遇到问题","cooked":"

以前一直是x-ui一键配置，这次尝试手动写xray配置文件，方遇到问题

\n","createdAt":"2026-06-28 09:15:33.265594","updatedAt":"2026-06-28 09:15:33.265594","replyToPostNumber":null,"replyCount":0,"likeCount":0,"wordCount":29,"liked":false,"bookmarked":false,"polls":[],"reactions":[],"wiki":false,"version":1,"publicVersion":1,"deletedAt":null,"isAnonymous":false,"user":{"id":8156,"username":"setsuna","name":"做回自己世莉架","avatarUrl":"/uploads/image/cc/3a/cc3acf27f130c3875e247a5a040c3e822cf414ecbc78a12f2c11798096606cc2.avif","admin":false,"moderator":false,"signatureRaw":null,"signatureCooked":null}},{"id":72444,"postNumber":5,"raw":"xray 文档有点神人，很多模块都没写清楚，也不知道是不是故意的（\n不过写了的部分还挺清楚的\n\n倒是现在可以直接让 agent explore 一下","cooked":"

xray 文档有点神人，很多模块都没写清楚，也不知道是不是故意的（
\n不过写了的部分还挺清楚的

倒是现在可以直接让 agent explore 一下

\n","createdAt":"2026-06-28 10:52:46.856026","updatedAt":"2026-06-28 10:52:46.856026","replyToPostNumber":null,"replyCount":0,"likeCount":1,"wordCount":54,"liked":false,"bookmarked":false,"polls":[],"reactions":[{"reaction":"❤️","count":1,"users":[{"id":8156,"username":"setsuna","name":"做回自己世莉架"}],"hasReacted":false}],"wiki":false,"version":1,"publicVersion":1,"deletedAt":null,"isAnonymous":false,"user":{"id":7830,"username":"stateless_trash_can","name":"无状态垃圾桶","avatarUrl":"/uploads/image/f4/69/f469375c27cd72c6970425e94b999be00fed8fe6234b977b14f5bdb65da24b4e.avif","admin":false,"moderator":false,"signatureRaw":"

","signatureCooked":"

"}},{"id":72446,"postNumber":6,"raw":"我当时是真的一点都不想看，直接丢给AI然后让它帮我配了VLESS，最后还是成功了；但是因为我VPS本身烂，是香港的，啥AI服务都用不了，所以实际上没啥用。","cooked":"

我当时是真的一点都不想看，直接丢给AI然后让它帮我配了VLESS，最后还是成功了；但是因为我VPS本身烂，是香港的，啥AI服务都用不了，所以实际上没啥用。

\n","createdAt":"2026-06-29 06:01:27.955104","updatedAt":"2026-06-29 06:01:50.732935","replyToPostNumber":null,"replyCount":0,"likeCount":1,"wordCount":68,"liked":false,"bookmarked":false,"polls":[],"reactions":[{"reaction":"❤️","count":1,"users":[{"id":8156,"username":"setsuna","name":"做回自己世莉架"}],"hasReacted":false}],"wiki":false,"version":1,"publicVersion":1,"deletedAt":null,"isAnonymous":false,"user":{"id":7242,"username":"sunxiaochuan258","name":"Nullptr","avatarUrl":"/uploads/image/12/97/12973e1e301c1fc274d5882581dc4f2b23055cea8c26e5e67c7c3a7ad071566e.avif","admin":false,"moderator":false,"signatureRaw":null,"signatureCooked":null}}],"hasMore":false,"lastReadPostNumber":2,"hasUrlPostNumber":true}

Xray VLESS 入站配置：users 还是 clients？

问题