协议模板与入站

读者：配置入站与线路模板的运维人员。

协议能力目录回答「XUI 支持哪些协议组合」；协议模板回答「这条线路具体怎么配」。二者配合 逻辑节点 完成入站物料化与 实时下发。

1. 适用场景

• 新建 VLESS Reality、VMess、Trojan、Shadowsocks、Hysteria2、WireGuard 等线路前，确认组合合法
• 复用一套 SNI / 传输 / 安全参数，避免每台机器手写 JSON
• XUI 升级后出现新协议，在目录中启用而无需发版 Master

2. 协议能力目录

控制台 → 协议目录（或「网络 → 协议目录」）：

概念	说明
type_key	唯一组合键，如 vless-tcp-reality、hysteria2-udp-none
protocol / network / security	协议、传输、安全分层
enabled	是否允许新建模板与逻辑节点引用

目录为数据驱动：内置种子来自 3x-ui 能力矩阵，超管可导入或编辑。一个 type_key 对应目录中的一行。

协议驱动映射（重点）

XCTL 以 XUI 支持矩阵为准，不同协议由不同内核/驱动落地。建议按下表理解：

协议族	典型 type_key	落地驱动	备注
VLESS / VMess / Trojan / Shadowsocks	vless-tcp-reality、vmess-ws-tls 等	Xray-core	主要走 Xray 入站能力
Hysteria2	hysteria2-udp-none	sing-box	Hysteria2 入站
WireGuard	wireguard	sing-box	与通用 client 列表模型不同，见下节

若某 type_key 在目录里不存在，优先以当前 3x-ui 版本的支持情况为准，而不是手工假设「Xray 或 sing-box 一定支持」。

3. 协议模板

控制台 → 协议模板：

1. 选择 type_key（只能选目录中已启用的项）
2. 填写 settings / stream 片段（占位符由 Master 在渲染时替换）
3. 保存模板，获得稳定 template_key 供逻辑节点引用

模板只描述「这一类入站长什么样」；Reality 密钥、统一端口、shortIds 等节点级变量在创建 逻辑节点 时一次性生成并固化，保证绑定到多台 Host 后配置一致。

占位符示例

占位符	来源
{{node.port}}	逻辑节点分配的统一端口
{{reality.privateKey}} 等	逻辑节点 node_vars，Master 本地生成
{{wg.privateKey}}	WireGuard 静态骨架；peer 由 Master 动态注入

可在模板详情页使用 试渲染（dry-run） 预览替换后的 JSON（若控制台已提供该入口）。

WireGuard 单独机制（与其它协议不同）

WireGuard 需要单独理解，不能按「普通订阅协议」处理：

1. 通用协议（VLESS/VMess/Trojan/SS/HY2）通常把用户写入 settings.clients[]
2. WireGuard 把用户写入 settings.peers[]，每个 peer 需要密钥与内网地址
3. 模板阶段只渲染 WireGuard 静态骨架（端口、私钥、MTU 等）
4. 同步下发前由 Master 的 WireGuard peer 服务把有效 peer 注入
5. 用户侧消费的是 .conf（或二维码），不是通用 vless:// 这类订阅项

4. 与逻辑节点的关系

协议目录 (type_key)
    → 协议模板 (template_key，可多个同 type)
        → 逻辑节点 (引用模板 + node_vars + 准入)
            → 绑定 Host → 配置同步 → 3x-ui inbound

规则摘要：

• 一个逻辑节点一种 type_key；要多协议就建多个逻辑节点
• 同逻辑节点可挂多个模板（例如多套 SNI），渲染为多份 inbound，tag 在节点内唯一
• WireGuard 模板只渲染静态骨架；用户 peer 不入通用订阅 URL

5. 操作步骤（新建一条 Reality 线路）

1. 在 协议目录 确认 vless-tcp-reality 已启用
2. 在 协议模板 新建模板，填写 stream / reality 相关字段
3. 在 逻辑节点 选择该 type_key 与模板，填写域名与准入
4. 绑定 Host，在 配置同步队列 确认 synced
5. 创建测试用户，验证订阅与连通

6. 注意事项

• 禁用目录中的 type_key 不会自动删除已存在的模板与逻辑节点，但新建时会不可选
• 改模板会触发关联逻辑节点重新入队同步，请在低峰期操作
• 勿在 3x-ui 面板手工改 inbound 字段，否则会出现 drift
• WireGuard 建议独立逻辑节点管理，避免与通用订阅协议混在同一排障路径
• TLS / HY2：需服务端证书，推荐 证书中心 引用；面板 config 只给 SNI

7. 常见问题

Q：目录里没有我想要的组合？
A：确认 XUI 版本是否支持；必要时导入新版目录 JSON 或联系支持获取种子更新。

Q：模板和逻辑节点都可以改端口吗？
A：业务端口以逻辑节点 node_vars 为准；模板里用占位符引用。

Q：sing-box 与 Xray 双核？
A：以协议目录里的 type_key 与当前能力矩阵为准：VLESS/VMess/Trojan/SS 通常走 Xray；HY2 与 WireGuard 通常走 sing-box。最终以 Host 上实际落地的 inbound 类型为准。

Q：为什么 WireGuard 要单独说？
A：它不是通用 clients[] 模型，而是 peers[] 模型，且用户侧交付 .conf，生命周期与普通订阅协议不同。

相关链接

• 逻辑节点
• 证书中心
• 配置同步队列