Files

T

Muse 58cdfe73b0 feat(agent): P12 改名 xui-agent——独立二进制文件+改名覆盖+存量迁移清理

install-agent.sh: AGENT_BIN 改 /usr/local/x-ui/xui-agent，下载走 .new 改名
覆盖（agent 自升级不撞 Text file busy），全程不写主控 x-ui 文件；新增
stop_legacy_agent 只精确匹配旧形态 'x-ui agent' 进程（主控裸 x-ui 无参数、
天然不误杀）；生成的 systemd/OpenRC 服务改指 xui-agent。仓库 systemd/
x-ui-agent.service 与 openrc/x-ui-agent( procd ) 同步改指；README/docs 的
agent 手动部署段落位改 xui-agent。Go 代码无硬引用、零改动。
fake-root 模拟（systemd/OpenRC/存量重跑）23/23 PASS，见 P12-REPORT.md。

2026-10-22 09:46:46 +00:00

4.9 KiB

Raw Permalink Blame History

3x-ui Agent 模式安装说明

节点鸡不再跑完整 3x-ui 面板，只跑一个轻量 agent：用 token 向主控注册，主控下发完整 xray 配置（含入站、出站、路由规则），agent 写配置并管理 xray 进程，每 60 秒向主控上报流量/在线数。

架构

主控：完整 3x-ui（v3.7.0+agent 补丁），负责生成配置、下发、管理出站与路由规则。
节点：x-ui agent 二进制 + xray 二进制 + geo 文件，无面板、无数据库。
出站/路由规则只能在主控上建和改（面板是唯一可信源），agent 只管应用下发的完整配置，不上报本地配置。

一、主控准备：生成 agent token

先在主控的「节点管理」里建好（或复用）该节点，记下节点 id。然后用面板 API token 调用（面板 → 设置 → API Token 新建一个）：

# 生成 token，绑定到节点 id=3
curl -sk -H "Authorization: Bearer <PANEL_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"node_id":3,"name":"hk-node-1"}' \
  https://主控地址:2053/panel/api/agent/tokens
# 返回 {"success":true,"obj":{"id":1,"token":"...","token_prefix":"...","node_id":3}}

token 只返回一次，请保存好。查看已发 token（不含明文）：

curl -sk -H "Authorization: Bearer <PANEL_API_TOKEN>" \
  https://主控地址:2053/panel/api/agent/tokens

二、节点安装

mkdir -p /usr/local/x-ui/bin /etc/x-ui

# 1. 放 x-ui 二进制（agent 补丁版，与主控同版本），在节点上改名为 xui-agent（与主控进程区分）
cp x-ui /usr/local/x-ui/xui-agent && chmod +x /usr/local/x-ui/xui-agent

# 2. 放 xray 二进制与 geo 文件（agent 不负责下载，手动放置）
cp xray-linux-amd64 /usr/local/x-ui/bin/xray && chmod +x /usr/local/x-ui/bin/xray
cp geoip.dat geosite.dat /usr/local/x-ui/bin/

# 3. 写 agent 配置
cat > /etc/x-ui/agent.json <<'EOF'
{
  "master_url": "http://主控内网地址:2053",
  "token": "<上一步生成的 token>",
  "node_name": "hk-node-1"
}
EOF
chmod 600 /etc/x-ui/agent.json

说明：

master_url 用 http://（内网）或 https://（需可信证书；自签证书连不上， agent 默认校验 TLS）。
poll_interval 可省略，默认 30 秒轮询一次配置。
不要在节点上再启动完整面板（x-ui 不带 agent 参数的模式）。

三、启动 agent

systemd（Debian/Ubuntu）：

cp systemd/x-ui-agent.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now x-ui-agent
journalctl -u x-ui-agent -f

OpenWrt（procd）：

cp openrc/x-ui-agent /etc/init.d/x-ui-agent
chmod +x /etc/init.d/x-ui-agent
/etc/init.d/x-ui-agent enable
/etc/init.d/x-ui-agent start
logread -f | grep x-ui-agent

四、主控管理该节点的出站与路由规则

出站/路由规则按 agent 存（节点特异的内网地址如 10.240.64.2:23183 必须按节点配，不能做全局模板）。<TOKEN> 用第一步生成的完整 token：

# 查看当前 egress（未设置时返回空数组，走模板默认 direct/blocked）
curl -sk -H "Authorization: Bearer <PANEL_API_TOKEN>" \
  https://主控地址:2053/panel/api/agent/egress/<TOKEN>

# 写入出站+路由规则（完整数组，直接替换模板默认）
curl -sk -H "Authorization: Bearer <PANEL_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"outbounds":[{"tag":"PPFL3-L1","protocol":"socks","settings":{"servers":[{"address":"10.240.64.2","port":23183}]}}],
       "routing_rules":[{"type":"field","inboundTag":["in-18692-tcp"],"outboundTag":"PPFL3-L1"}]}' \
  -X PUT https://主控地址:2053/panel/api/agent/egress/<TOKEN>

下发配置里的 stats API 路由规则（inboundTag: ["api"]）会自动补齐，不用手写，写了也不会重复。
传空数组会清空该项、回退到模板默认。

五、验证

agent 日志出现 Xray config applied successfully。
节点上 ss -tlnp | grep xray 能看到入站端口在监听。
主控 GET /panel/api/agent/tokens 里该 token 的 last_seen 在更新。
客户端用入站链接连通；约 60 秒后主控面板上该节点入站/用户的流量开始涨。
吊销 token：curl -sk -H "Authorization: Bearer <PANEL_API_TOKEN>" -X DELETE https://主控地址:2053/panel/api/agent/tokens/<id>， agent 下次心跳/取配置会收到 401 并在日志报错。

故障排查

现象	查
`register failed ... 401`	token 贴错，或 token 没在主控生成
`config fetch failed ... 409`	token 未绑定节点（生成时没传 `node_id`）
xray 起不来	`/usr/local/x-ui/bin/xray` 是否存在可执行；`xray -test -c /usr/local/x-ui/bin/config.json` 看配置报错
流量不上报	xray 的 api 入站端口是否被占用；agent 日志看 `Traffic report failed`
主控连不上	`master_url` 拼错；https 自签证书改走 `http://` 内网地址

4.9 KiB Raw Permalink Blame History Unescape Escape