From 2f2efdac424a571e16bffc17641b969c75ab0536 Mon Sep 17 00:00:00 2001 From: Muse Date: Mon, 19 Oct 2026 20:44:10 +0800 Subject: [PATCH] =?UTF-8?q?README=20=E9=87=8D=E5=86=99=E4=B8=BA=20agent=20?= =?UTF-8?q?=E7=89=88=E5=AE=89=E8=A3=85=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 220 +++++++++--------------------------------------------- 1 file changed, 35 insertions(+), 185 deletions(-) diff --git a/README.md b/README.md index 8c25145..442a02a 100644 --- a/README.md +++ b/README.md @@ -1,206 +1,56 @@ -[English](/README.md) | [فارسی](/README.fa_IR.md) | [العربية](/README.ar_EG.md) | [中文](/README.zh_CN.md) | [Español](/README.es_ES.md) | [Русский](/README.ru_RU.md) | [Türkçe](/README.tr_TR.md) +# 3x-ui-agent -

- - - 3x-ui - -

+基于 3x-ui v3.7.0 的二次开发：节点 agent 化。节点鸡不再跑完整面板，只跑一个轻量 agent（约 60MB 内存），由主控统一管理、下发 xray 配置。 -

- Release - Build - GO Version - Downloads - License - Go Reference -

+## 架构 -**3X-UI** is an advanced, open-source web control panel for managing [Xray-core](https://github.com/XTLS/Xray-core) servers. It provides a clean, multi-language interface for deploying, configuring, and monitoring a wide range of proxy and VPN protocols — from a single VPS to multi-node deployments. +- **主控**：完整 3x-ui 面板，唯一的配置可信源。管理节点、入站、客户端，下发完整 xray 配置（含出站、路由）到各 agent。 +- **Agent**：跑在节点鸡上，通过 token 向主控注册。定时拉取主控下发的 xray 配置并应用，上报心跳和流量。只提供 VLESS / SS2022 入站。 -Built as an enhanced fork of the original X-UI project, 3X-UI adds broader protocol support, improved stability, per-client traffic accounting, and many quality-of-life features. +## 安装 -> [!IMPORTANT] -> This project is intended for personal use only. Please do not use it for illegal purposes or in a production environment. - -## Features - -- **Multi-protocol inbounds** — VLESS, VMess, Trojan, Shadowsocks, WireGuard, Hysteria2, HTTP, SOCKS (Mixed), Dokodemo-door / Tunnel, and TUN. -- **Modern transports & security** — TCP (Raw), mKCP, WebSocket, gRPC, HTTPUpgrade, and XHTTP, secured with TLS, XTLS, and REALITY. -- **Fallbacks** — serve multiple protocols on a single port (e.g. VLESS and Trojan on 443) using Xray's fallback support. -- **Per-client management** — traffic quotas, expiry dates, IP limits, live online status, and one-click share links, QR codes, and subscriptions. -- **Traffic statistics** — per inbound, per client, and per outbound, with reset controls. -- **Multi-node support** — manage and scale across multiple servers from a single panel. -- **Outbound & routing** — WARP, NordVPN, custom routing rules, load balancers, and outbound proxy chaining. -- **Built-in subscription server** with multiple output formats and [custom page templates](docs/custom-subscription-templates.md). -- **Telegram bot** for remote monitoring and management. -- **RESTful API** with in-panel Swagger documentation. -- **Flexible storage** — SQLite (default) or PostgreSQL. -- **13 UI languages** with dark and light themes. -- **Fail2ban integration** for enforcing per-client IP limits. - -## Screenshots - -
-Click to expand - - - - Overview - - - - - Inbounds - - - - - Add client - - - - - Configs - - -
- -## Quick Start +### 主控 ```bash -bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) +bash <(curl -fL https://raw.githubusercontent.com/imamoxilin/3x-ui-diy/main/install-master.sh) ``` -To install a specific version, append its tag (e.g. `v3.4.0`): +装完面板在 `http://主控IP:2053`，默认账号 `admin` / `admin`。 + +### Agent（节点鸡） + +先在主控面板「节点管理」→「添加节点」→ 类型选 **Agent**，保存后弹窗会显示 token，复制下来。 + +然后在节点鸡上： ```bash -bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.4.0 +bash <(curl -fL https://raw.githubusercontent.com/imamoxilin/3x-ui-diy/main/install-agent.sh) \ + --master http://主控IP:2053 --token 你的TOKEN --name 节点名 ``` -To install the rolling **dev** build (latest per-commit pre-release from `main`, not a stable release), pass `dev-latest`: +agent 约 30 秒后拉到配置并启动 xray，节点在面板显示在线。 -```bash -bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest -``` +## 使用流程 -During installation a random username, password, and access path are generated. After installation, run `x-ui` to open the management menu, where you can start/stop the service, view or reset your login credentials, manage SSL certificates, and more. +1. 主控面板添加 Agent 类型节点，拿到 token +2. 节点鸡一键安装 agent，填入主控地址和 token +3. 在「入站列表」创建入站（VLESS / SS2022），「部署到」选择在线的 agent 节点 +4. 主控自动把完整 xray 配置下发到节点，客户端即可连接 -For full documentation, please visit the [project Wiki](https://github.com/MHSanaei/3x-ui/wiki). +## 内存占用（实测） -### Unattended install +| | 内存 | +|---|---| +| agent + xray | 约 63MB | +| 完整 3x-ui 面板 | 130–160MB | -The installer also runs **non-interactively** for cloud-init. -Set `XUI_NONINTERACTIVE=1` (or pipe with no TTY) and it installs end-to-end with -zero prompts, generating random credentials and writing them to -`/etc/x-ui/install-result.env`. See [`deploy/`](deploy/) for: +## 与原版的区别 -- [Cloud-init user-data](deploy/cloud-init/) — unattended install on any cloud (Hetzner/AWS/DO/Vultr/GCP/Azure/Oracle) -- [Hetzner Cloud notes](deploy/marketplace/hetzner/) — cloud-init deployment on Hetzner +- 节点不再需要安装完整面板 +- 主控是唯一可信源，节点配置全部由主控下发 +- 节点在线状态由 agent 心跳维持 +- 添加节点支持 Agent 类型，自动生成注册 token -## Supported Platforms +## License -**Operating systems:** Ubuntu, Debian, Armbian, Fedora, CentOS, RHEL, AlmaLinux, Rocky Linux, Oracle Linux, Amazon Linux, Virtuozzo, Arch, Manjaro, Parch, openSUSE (Tumbleweed / Leap), Alpine, and Windows. - -**Architectures:** `amd64` · `386` · `arm64` (aarch64) · `armv7` · `armv6` · `armv5` · `s390x`. - -## Database Options - -3X-UI supports two backends, chosen during the install: - -- **SQLite** (default) — a single file at `/etc/x-ui/x-ui.db`. Zero setup, ideal for small and medium deployments. -- **PostgreSQL** — recommended for high client counts or multi-node setups. The installer can install PostgreSQL locally for you, or accept a DSN to an existing server. - -At runtime the backend is selected via environment variables (the installer writes these to `/etc/default/x-ui` for you): - -``` -XUI_DB_TYPE=postgres -XUI_DB_DSN=postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable -``` - -### Migrating an existing SQLite install to PostgreSQL - -```bash -x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable" -# then set XUI_DB_TYPE and XUI_DB_DSN in /etc/default/x-ui and restart: -systemctl restart x-ui -``` - -The source SQLite file is left untouched; remove it manually once you have verified the new backend. - -### Docker - -The default `docker compose up -d` keeps using SQLite. To run with the bundled PostgreSQL service, uncomment the two `XUI_DB_*` env lines in `docker-compose.yml` and start with the profile: - -```bash -docker compose --profile postgres up -d -``` - -The image bundles Fail2ban (enabled by default) to enforce per-client **IP limits**. Fail2ban bans offenders with `iptables`, which requires the `NET_ADMIN` capability. `docker-compose.yml` already grants it via `cap_add`; if you start the container with `docker run` instead, add the capabilities yourself, otherwise bans are logged but never applied: - -```bash -docker run -d --cap-add=NET_ADMIN --cap-add=NET_RAW ... ghcr.io/mhsanaei/3x-ui -``` - -## Environment Variables - -| Variable | Description | Default | -| --- | --- | --- | -| `XUI_DB_TYPE` | Database backend: `sqlite` or `postgres` | `sqlite` | -| `XUI_DB_DSN` | PostgreSQL connection string (when `XUI_DB_TYPE=postgres`) | — | -| `XUI_DB_FOLDER` | Directory for the SQLite database file | `/etc/x-ui` | -| `XUI_DB_MAX_OPEN_CONNS` | Maximum open connections (PostgreSQL pool) | — | -| `XUI_DB_MAX_IDLE_CONNS` | Maximum idle connections (PostgreSQL pool) | — | -| `XUI_INIT_WEB_BASE_PATH` | The initial URI path for the web panel | `/` | -| `XUI_ENABLE_FAIL2BAN` | Enable Fail2ban-based IP-limit enforcement | `true` | -| `XUI_LOG_LEVEL` | Log verbosity (`debug`, `info`, `warning`, `error`) | `info` | -| `XUI_DEBUG` | Enable debug mode | `false` | -| `XUI_TUNNEL_HEALTH_MONITOR` | Enable the tunnel health monitor (probes a URL and restarts xray after repeated failures; a restart drops all clients) | `false` | -| `XUI_TUNNEL_HEALTH_PROXY` | Proxy the probe is sent through; point it at a local xray inbound so the probe tests the tunnel (e.g. `socks5://127.0.0.1:1080`). Empty means the probe only checks host connectivity | — | -| `XUI_TUNNEL_HEALTH_URL` | URL probed for tunnel health | `https://www.cloudflare.com/cdn-cgi/trace` | -| `XUI_TUNNEL_HEALTH_INTERVAL` | Interval between probes | `30s` | -| `XUI_TUNNEL_HEALTH_TIMEOUT` | Per-probe timeout | `10s` | -| `XUI_TUNNEL_HEALTH_FAILURES` | Consecutive failures before a restart is triggered | `3` | -| `XUI_TUNNEL_HEALTH_COOLDOWN` | Minimum delay between consecutive restarts | `5m` | - -## Supported Languages - -The panel UI is available in 13 languages: - -English · فارسی · العربية · 中文（简体） · 中文（繁體） · Español · Русский · Українська · Türkçe · Tiếng Việt · 日本語 · Bahasa Indonesia · Português (Brasil) - -## Contributing - -Contributions are welcome. Please read the [Contributing Guide](/CONTRIBUTING.md) before opening an issue or pull request. - -## A Special Thanks to - -- [alireza0](https://github.com/alireza0/) - -## Acknowledgment - -- [Iran v2ray rules](https://github.com/chocolate4u/Iran-v2ray-rules) (License: **GPL-3.0**): _Enhanced v2ray/xray and v2ray/xray-clients routing rules with built-in Iranian domains and a focus on security and adblocking._ -- [Russia v2ray rules](https://github.com/runetfreedom/russia-v2ray-rules-dat) (License: **GPL-3.0**): _This repository contains automatically updated V2Ray routing rules based on data on blocked domains and addresses in Russia._ - -## Community Tools - -Tools and integrations built by the community around 3x-ui. - -- [terraform-provider-3x-ui](https://github.com/batonogov/terraform-provider-threexui) (License: **MIT**): _Manage inbounds, clients, panel settings, and Xray configuration as code with Terraform / OpenTofu._ - -## Support project - -**If this project is helpful to you, you may wish to give it a**:star2: - - -Buy Me A Coffee - - -
- - Crypto donation button by NOWPayments - - -## Stargazers over Time - -[![Stargazers over time](https://starchart.cc/MHSanaei/3x-ui.svg?variant=adaptive)](https://starchart.cc/MHSanaei/3x-ui) +GPL-3.0（继承上游 3x-ui）