# 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://` 内网地址 |