From 8da3cde4946cccc503199d963e2185900bfab4c2 Mon Sep 17 00:00:00 2001
From: Muse <muse@local>
Date: Tue, 20 Oct 2026 12:27:21 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E6=94=B9=E7=89=88=E4=B8=BA=20?=
 =?UTF-8?q?fork=20=E5=8F=A3=E5=BE=84=E2=80=94=E2=80=94=E5=88=A0=E4=B8=8A?=
 =?UTF-8?q?=E6=B8=B8/=E5=B7=B2=E5=B0=81=20GitHub=20=E7=9A=84=E4=B8=80?=
 =?UTF-8?q?=E9=94=AE=E5=AE=89=E8=A3=85=E5=91=BD=E4=BB=A4=EF=BC=8C=E6=94=B9?=
 =?UTF-8?q?=E4=B8=BA=20Gitea=20Releases=20=E6=89=8B=E5=8A=A8=E9=83=A8?=
 =?UTF-8?q?=E7=BD=B2=E4=B8=BB=E6=8E=A7/agent=20=E4=B8=A4=E6=A8=A1=E5=BC=8F?=
 =?UTF-8?q?=EF=BC=8C=E8=A1=A5=E5=8D=B8=E8=BD=BD=E7=AB=A0=E8=8A=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 74 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 8709e26..5941fb9 100644
--- a/README.md
+++ b/README.md
@@ -1,39 +1,98 @@
 # 3x-ui-agent
 
-基于 3x-ui v3.7.0 的二次开发：节点 agent 化。节点鸡不再跑完整面板，只跑一个轻量 agent（约 60MB 内存），由主控统一管理、下发 xray 配置。
+基于上游 3x-ui v3.7.0 的二次开发 fork：节点 agent 化。节点鸡不再跑完整面板，只跑一个轻量 agent（约 60MB 内存），由主控统一管理、下发 xray 配置。
+
+本仓库托管在自建 Gitea：<https://git.881218.xyz/rogue/3x-ui-agent>，二进制从本仓库的 Releases 下载。**不要**使用上游的一键安装脚本/命令（`install.sh`、`update.sh` 等仍指向原版，会装成上游原版，与本 fork 不兼容）。
 
 ## 架构
 
 - **主控**：完整 3x-ui 面板，唯一的配置可信源。管理节点、入站、客户端，下发完整 xray 配置（含出站、路由）到各 agent。
-- **Agent**：跑在节点鸡上，通过 token 向主控注册。定时拉取主控下发的 xray 配置并应用，上报心跳和流量。只提供 VLESS / SS2022 入站。
+- **Agent**：跑在节点鸡上，通过注册 token 向主控注册。定时拉取主控下发的 xray 配置并应用，上报心跳和流量。节点下发仅支持 VLESS / SS2022 两类入站（本 fork 的取向）。
+
+同一个二进制、两种角色：不带参数运行是主控面板，`x-ui agent --config /etc/x-ui/agent.json` 运行是 agent。
 
 ## 安装
 
+二进制下载：本仓库 [Releases](https://git.881218.xyz/rogue/3x-ui-agent/releases)，按架构选 `x-ui-linux-amd64` 或 `x-ui-linux-arm64`。
+
+> 仓库根目录的 `install-master.sh` / `install-agent.sh` 是早期一键脚本，其下载源仍指向已下线的 GitHub 账号，**暂不可用**；请按下面步骤手动部署。
+
 ### 主控
 
 ```bash
-bash <(curl -fL https://raw.githubusercontent.com/aaaamoooo/3x-ui-diy/main/install-master.sh)
+mkdir -p /usr/local/x-ui/bin /etc/x-ui
+
+# 1. 放主控二进制（Releases 下载的 x-ui-linux-<架构>）
+cp x-ui-linux-amd64 /usr/local/x-ui/x-ui && chmod +x /usr/local/x-ui/x-ui
+
+# 2. 放 xray 二进制与 geo 文件到 bin/ 子目录
+#    纯控制面部署（节点全走 agent）可禁用本机 xray：不放，或放了之后 chmod -x
+cp xray-linux-amd64 /usr/local/x-ui/bin/
+cp geoip.dat geosite.dat /usr/local/x-ui/bin/
 ```
 
-装完面板在 `http://主控IP:2053`，默认账号 `admin` / `admin`。
+启动（二选一）：
+
+- Debian/Ubuntu（systemd）：把仓库的 `x-ui.service.debian` 复制为 `/etc/systemd/system/x-ui.service`，然后 `systemctl daemon-reload && systemctl enable --now x-ui`。
+- OpenWrt（procd）：用 init 脚本以 `/usr/local/x-ui/x-ui` 为命令启动，工作目录 `/usr/local/x-ui`。
+
+数据库在 `/etc/x-ui/x-ui.db`。面板端口按设置，默认 2053，首次登录默认账号 `admin` / `admin`，请登录后立即修改。
 
 ### Agent（节点鸡）
 
-先在主控面板「节点管理」→「添加节点」→ 类型选 **Agent**，保存后弹窗会显示 token，复制下来。
-
-然后在节点鸡上：
+先在主控侧为该节点生成注册 token（建节点 → 用面板 API Token 签发绑定该节点的 agent token，完整步骤见 [docs/AGENT.md](docs/AGENT.md)），然后在节点鸡上：
 
 ```bash
-bash <(curl -fL https://raw.githubusercontent.com/aaaamoooo/3x-ui-diy/main/install-agent.sh) \
-  --master http://主控IP:2053 --token 你的TOKEN --name 节点名
+mkdir -p /usr/local/x-ui/bin /etc/x-ui
+
+# 1. 放同一个 x-ui 二进制（与主控同版本）
+cp x-ui-linux-amd64 /usr/local/x-ui/x-ui && chmod +x /usr/local/x-ui/x-ui
+
+# 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": "节点名"
+}
+EOF
+chmod 600 /etc/x-ui/agent.json
 ```
 
-agent 约 30 秒后拉到配置并启动 xray，节点在面板显示在线。
+- `master_url` 走内网用 `http://`；走 `https://` 需可信证书（自签连不上）。
+- agent 另有独立的运行时配置 `config-agent.json`（生成于 `bin/`）；`agent.json` 可选 `api_port` 指定 xray stats API 端口（部署口径 62790，metrics 端口为其下一位 62791）。
+- 启动：Debian 把仓库的 `systemd/x-ui-agent.service` 复制到 `/etc/systemd/system/` 后 `systemctl enable --now x-ui-agent`；OpenRC 用仓库的 `openrc/x-ui-agent` 放到 `/etc/init.d/x-ui-agent`。
+
+agent 约 30 秒后拉到配置并启动 xray，节点在面板显示在线。更细的 agent 说明（出站/路由下发、验证、故障排查）见 [docs/AGENT.md](docs/AGENT.md)。
+
+## 卸载
+
+### 主控
+
+```bash
+# 先停服务：systemctl disable --now x-ui（或 /etc/init.d/x-ui stop）
+rm -f /etc/systemd/system/x-ui.service   # 或删掉对应的 procd init 脚本
+rm -rf /usr/local/x-ui /etc/x-ui
+```
+
+### Agent
+
+```bash
+# 先停服务：systemctl disable --now x-ui-agent（或 rc-service x-ui-agent stop）
+rm -f /etc/systemd/system/x-ui-agent.service   # 或 /etc/init.d/x-ui-agent
+rm -rf /usr/local/x-ui /etc/x-ui
+```
+
+（`/etc/x-ui` 里含数据库与 token 配置，确认不再需要再删。）
 
 ## 使用流程
 
-1. 主控面板添加 Agent 类型节点，拿到 token
-2. 节点鸡一键安装 agent，填入主控地址和 token
+1. 主控侧建节点并签发 agent 注册 token（见 docs/AGENT.md）
+2. 节点鸡按上面步骤部署 agent，填入主控地址和 token
 3. 在「入站列表」创建入站（VLESS / SS2022），「部署到」选择在线的 agent 节点
 4. 主控自动把完整 xray 配置下发到节点，客户端即可连接
 
@@ -44,12 +103,14 @@ agent 约 30 秒后拉到配置并启动 xray，节点在面板显示在线。
 | agent + xray | 约 63MB |
 | 完整 3x-ui 面板 | 130–160MB |
 
+另有路由器主控精简版构建（剥离 xray-core 库，见仓库内 PANEL-LITE-SPEC.md），面向纯控制面部署，内存显著更低。
+
 ## 与原版的区别
 
 - 节点不再需要安装完整面板
 - 主控是唯一可信源，节点配置全部由主控下发
 - 节点在线状态由 agent 心跳维持
-- 添加节点支持 Agent 类型，自动生成注册 token
+- 添加节点支持 Agent 类型，使用注册 token 接入
 
 ## License