From 17e0712a2f463dc655fd5b641203a52aeaf63ece Mon Sep 17 00:00:00 2001
From: konstpic <156318483+konstpic@users.noreply.github.com>
Date: Tue, 13 Jan 2026 12:11:21 +0300
Subject: [PATCH] Create README_node_mode.md

---
 README_node_mode.md | 172 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 172 insertions(+)
 create mode 100644 README_node_mode.md

diff --git a/README_node_mode.md b/README_node_mode.md
new file mode 100644
index 00000000..f2e22387
--- /dev/null
+++ b/README_node_mode.md
@@ -0,0 +1,172 @@
+# Installing 3x-ui with Multi-Node Support (Beta)
+
+This guide describes the complete process of installing the panel and nodes from scratch.
+
+------------------------------------------------------------------------
+
+## Requirements
+
+Before starting, make sure you have installed:
+- Docker
+- Docker Compose (v2)
+
+Check:
+
+```bash
+docker --version
+docker compose version
+```
+
+------------------------------------------------------------------------
+
+## Step 1. Clone the Repository
+
+```bash
+git clone https://github.com/konstpic/3x-ui-dev-beta.git
+cd 3x-ui-dev-beta
+```
+
+------------------------------------------------------------------------
+
+## Step 2. Switch to the Multi-Node Support Branch
+
+```bash
+git checkout 3x-new
+```
+
+------------------------------------------------------------------------
+
+## Step 3. Launch the Panel (Core)
+
+In the repository root, build and start the panel:
+
+```bash
+docker compose build
+docker compose up -d
+```
+
+------------------------------------------------------------------------
+
+### (Optional) Configure Panel Ports
+
+By default, `network_mode: host` may be used.
+
+If you want to use standard port mapping:
+1. Open `docker-compose.yml` in the project root
+2. Remove `network_mode: host`
+3. Add port mapping:
+
+```yaml
+ports:
+  - "2053:2053"   # Web UI
+  - "2096:2096"   # Subscriptions
+```
+
+After making changes, restart the containers:
+
+```bash
+docker compose down
+docker compose up -d
+```
+
+------------------------------------------------------------------------
+
+## Step 4. Launch the Node
+
+Navigate to the `node` folder:
+
+```bash
+cd node
+docker compose build
+docker compose up -d
+```
+
+------------------------------------------------------------------------
+
+## Important ❗ About Node Network and Ports (Xray)
+
+Nodes use the **Xray** core, and it's the nodes that accept user connections to **Inbounds**.
+
+### Option 1 (recommended): `network_mode: host`
+
+Use `network_mode: host` if:
+- you don't want to manually manage ports
+- you plan to use different inbound ports
+- you want behavior as close as possible to bare-metal
+
+In this case, **no additional port mapping is required**.
+
+------------------------------------------------------------------------
+
+### Option 2: Using `ports` (without host network)
+
+If `network_mode: host` is **not used**, you need to:
+
+1. Define in advance the ports on which users will connect to inbounds
+2. Map these ports in the node's `docker-compose.yml`
+
+Example:
+
+```yaml
+ports:
+  - "8080:8080"     # Node API
+  - "443:443"       # Inbound (example)
+  - "8443:8443"     # Inbound (example)
+```
+
+⚠️ In this mode, **each inbound port must be explicitly mapped**.
+
+------------------------------------------------------------------------
+
+### Node API Port
+
+Regardless of the chosen mode:
+- The node API runs on port **8080**
+- This port must be accessible to the panel
+
+------------------------------------------------------------------------
+
+## Step 5. Enable Multi-Node Mode
+
+1. Open the panel web interface
+2. Go to **Panel Settings**
+3. Enable **Multi-Node**
+4. Save settings
+
+After this, the **Nodes** section will appear.
+
+------------------------------------------------------------------------
+
+## Step 6. Register Nodes
+
+1. Go to the **Nodes** section
+2. Add a new node, specifying:
+   - node server address
+   - node API port: **8080**
+3. Save
+
+If everything is configured correctly, the node will appear with **Online** status.
+
+------------------------------------------------------------------------
+
+## Step 7. Using Nodes in Inbounds
+
+After registration:
+- nodes can be selected when creating and editing **Inbounds**
+- user connections will be accepted **by nodes, not by the panel**
+
+------------------------------------------------------------------------
+
+## Possible Issues
+
+If a node has `Offline` status or users cannot connect:
+- make sure the containers are running
+- check accessibility of port **8080**
+- check that inbound ports are:
+  - mapped (if host network is not used)
+  - not blocked by firewall
+- check Docker network settings
+
+------------------------------------------------------------------------
+
+⚠️ The project is in **beta stage**. Bugs and changes are possible.