Files

T

Muse 6a5ee8f77b rename: 3x-ui/x-ui -> L-UI/l-ui/lui-agent (paths, services, env, assets)

Display L-UI; panel binary/process l-ui, agent lui-agent.
Dirs /usr/local/l-ui, /etc/l-ui, /var/log/l-ui; DB /etc/l-ui/l-ui.db
(name file drives it via GetName), probe.db beside it, cert
/etc/l-ui/cert, bin /usr/local/l-ui/bin. Services l-ui.service /
lui-agent.service, OpenRC lui-agent, l-ui.sh, cmd/lui-agent.
Env prefix XUI_ -> LUI_ (code reads new prefix only). Release
assets l-ui-linux-* / lui-agent-linux-*; Gitea repo rogue/l-ui is
a placeholder pending user confirmation (see selfupdate.go note).
Go module path github.com/mhsanaei/3x-ui/v3 intentionally kept.
Versions unchanged: panel V2.6.0 / agent A2.5.0.

2026-10-24 12:00:55 +00:00

4.9 KiB

Raw Blame History

L-UI Agent 模式安装说明

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

架构

主控：完整 L-UI（v3.7.0+agent 补丁），负责生成配置、下发、管理出站与路由规则。
节点：l-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/l-ui/bin /etc/l-ui

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

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

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

说明：

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

三、启动 agent

systemd（Debian/Ubuntu）：

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

OpenWrt（procd）：

cp openrc/lui-agent /etc/init.d/lui-agent
chmod +x /etc/init.d/lui-agent
/etc/init.d/lui-agent enable
/etc/init.d/lui-agent start
logread -f | grep lui-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/l-ui/bin/xray` 是否存在可执行；`xray -test -c /usr/local/l-ui/bin/config.json` 看配置报错
流量不上报	xray 的 api 入站端口是否被占用；agent 日志看 `Traffic report failed`
主控连不上	`master_url` 拼错；https 自签证书改走 `http://` 内网地址

4.9 KiB Raw Blame History Unescape Escape