Muse
58cdfe73b0
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。
126 lines
4.9 KiB
Markdown
126 lines
4.9 KiB
Markdown
# 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 新建一个）：
|
||
|
||
```bash
|
||
# 生成 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（不含明文）：
|
||
|
||
```bash
|
||
curl -sk -H "Authorization: Bearer <PANEL_API_TOKEN>" \
|
||
https://主控地址:2053/panel/api/agent/tokens
|
||
```
|
||
|
||
## 二、节点安装
|
||
|
||
```bash
|
||
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）：
|
||
|
||
```bash
|
||
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）：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
# 查看当前 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"]`）会自动补齐，
|
||
不用手写，写了也不会重复。
|
||
- 传空数组会清空该项、回退到模板默认。
|
||
|
||
## 五、验证
|
||
|
||
1. agent 日志出现 `Xray config applied successfully`。
|
||
2. 节点上 `ss -tlnp | grep xray` 能看到入站端口在监听。
|
||
3. 主控 `GET /panel/api/agent/tokens` 里该 token 的 `last_seen` 在更新。
|
||
4. 客户端用入站链接连通；约 60 秒后主控面板上该节点入站/用户的流量开始涨。
|
||
5. 吊销 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://` 内网地址 |
|