feat: Add multi-server support #3269

javadtgh · 2025-07-24T05:06:27Z

This commit introduces a multi-server architecture to the Sanai panel, allowing you to manage clients across multiple servers from a central panel.

Key changes include:

Database Schema: Added a servers table to store information about slave servers.
Server Management: Implemented a new service and controller (MultiServerService and MultiServerController) for CRUD operations on servers.
Web UI: Created a new web page for managing servers, accessible from the sidebar.
Client Synchronization: Modified the InboundService to synchronize client additions, updates, and deletions across all active slave servers via a REST API.
API Security: Added an API key authentication middleware to secure the communication between the master and slave panels.
Multi-Server Subscriptions: Updated the subscription service to generate links that include configurations for all active servers.
Installation Script: Modified the install.sh script to generate a random API key during installation.

Known Issues:

The integration test for client synchronization (TestInboundServiceSync) is currently failing. It seems that the API request to the mock slave server is not being sent correctly or the API key is not being included in the request header. Further investigation is needed to resolve this issue.

What is the pull request?

Which part of the application is affected by the change?

Frontend
Backend

Type of Changes

Bug fix
New feature
Refactoring
Other

Screenshots

alireza0 · 2025-07-24T12:29:29Z

Thank you for contributing.
Everything is nice so far except our main problem: Sync client/inbound traffics.

For this important problem we should use "sync-sofar" solution to make sure that every usages in all slave servers will count.
Personal prefered solution is to clear all usages from slaves after sync. During traffic sync, all slaves traffics should be added to the master, then evaluate traffic exhaustion. If a client/inbound is exhausted, then disable it on all master/slave.

Other concerns:
Slaves:

Disable web interface.
Limit api communication only by master source
Sync ip limit
Sync certificate files
Consider Listen IP of each inbound (to be ignored or updatable via master)
Consider MultiDomain (to be empty or reserve one config per server)
Consider Outbounds specially for tunnels.
Consider Reverse Proxy

APT-ZERO · 2025-07-25T13:03:43Z

3X-UI is growing faster than all other panels!
I'm waiting for Sing-box and PostgreSQL support :D

MK0ltra · 2025-07-25T15:45:18Z

Currently it doesn't support already created inbounds/clients. When user adds a slave, I think there should be an option to select which inbounds (along with all their clients) the user wants to duplicate on the slave server (with 0 up and down usage stats).

This commit introduces a multi-server architecture to the Sanai panel, allowing you to manage clients across multiple servers from a central panel. Key changes include: - **Database Schema:** Added a `servers` table to store information about slave servers. - **Server Management:** Implemented a new service and controller (`MultiServerService` and `MultiServerController`) for CRUD operations on servers. - **Web UI:** Created a new web page for managing servers, accessible from the sidebar. - **Client Synchronization:** Modified the `InboundService` to synchronize client additions, updates, and deletions across all active slave servers via a REST API. - **API Security:** Added an API key authentication middleware to secure the communication between the master and slave panels. - **Multi-Server Subscriptions:** Updated the subscription service to generate links that include configurations for all active servers. - **Installation Script:** Modified the `install.sh` script to generate a random API key during installation. **Known Issues:** - The integration test for client synchronization (`TestInboundServiceSync`) is currently failing. It seems that the API request to the mock slave server is not being sent correctly or the API key is not being included in the request header. Further investigation is needed to resolve this issue.

AliAkhgar · 2025-08-03T18:38:07Z

such a nice feature, would love to contrib on it!

AliAkhgar · 2025-08-04T09:26:05Z

@alireza0 @javadtgh
Please also take External Traffic Inform feature into account, as we are already using this feature to track and maintain a different central server to control, monitor and manage users.
Thanks.

liamnees · 2025-08-17T14:10:29Z

To make it multi-server, just add traffic equalization and that's it. The problem with the previous scripts was that in addition to equalizing traffic, they also managed time and clients. Please add a script that has no capabilities other than equalizing traffic and that also does this equalization every 2 minutes. I don't think there will be any problems this way.

liamnees · 2025-08-28T04:59:24Z

To make it multi-server, just add traffic equalization and that's it. The problem with the previous scripts was that in addition to equalizing traffic, they also managed time and clients. Please add a script that has no capabilities other than equalizing traffic and that also does this equalization every 2 minutes. I don't think there will be any problems this way.

@aliglzr

Copilot

Pull Request Overview

This pull request adds multi-server support to the Sanai panel, enabling centralized management of clients across multiple slave servers from a master panel.

Implements complete multi-server architecture with database schema, service layer, and web UI
Adds automatic client synchronization between master and slave servers via REST API
Introduces API key-based authentication for secure inter-panel communication

Reviewed Changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`database/model/model.go`	Adds Server model for storing slave server information
`database/db.go`	Registers Server model for auto-migration
`web/service/multi_server_service.go`	Implements CRUD operations for server management
`web/service/setting.go`	Adds API key management functionality
`web/service/inbound.go`	Adds client synchronization to slave servers
`web/controller/multi_server_controller.go`	HTTP endpoints for server management
`web/middleware/auth.go`	API key authentication middleware
`web/controller/xui.go`	Adds servers page route
`web/html/servers.html`	Web interface for managing slave servers
`web/html/component/aSidebar.html`	Adds servers menu item
`sub/subService.go`	Modifies subscription links to include all active servers
`main.go`	Adds API key command-line parameter
`install.sh`	Generates random API key during installation

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-09-12T10:16:13Z

web/service/inbound.go

+		body, _ := json.Marshal(data)
+		s.syncWithSlaves("POST", "/panel/inbound/api/addClient", bytes.NewReader(body))


The JSON marshaling error is being silently ignored with _. This could lead to silent failures when syncing with slave servers. The error should be handled properly, and if marshaling fails, the sync operation should be skipped or logged.

Suggested change

body, _ := json.Marshal(data)

s.syncWithSlaves("POST", "/panel/inbound/api/addClient", bytes.NewReader(body))

body, marshalErr := json.Marshal(data)

if marshalErr != nil {

logger.Error("Failed to marshal data for syncWithSlaves:", marshalErr)

} else {

s.syncWithSlaves("POST", "/panel/inbound/api/addClient", bytes.NewReader(body))

}

Copilot · 2025-09-12T10:16:13Z

web/service/inbound.go

+		body, _ := json.Marshal(data)
+		s.syncWithSlaves("POST", fmt.Sprintf("/panel/inbound/api/updateClient/%s", clientId), bytes.NewReader(body))


The JSON marshaling error is being silently ignored with _. This could lead to silent failures when syncing with slave servers. The error should be handled properly, and if marshaling fails, the sync operation should be skipped or logged.

Suggested change

body, _ := json.Marshal(data)

s.syncWithSlaves("POST", fmt.Sprintf("/panel/inbound/api/updateClient/%s", clientId), bytes.NewReader(body))

body, marshalErr := json.Marshal(data)

if marshalErr != nil {

logger.Warning("Failed to marshal data for syncWithSlaves:", marshalErr)

} else {

s.syncWithSlaves("POST", fmt.Sprintf("/panel/inbound/api/updateClient/%s", clientId), bytes.NewReader(body))

}

Copilot · 2025-09-12T10:16:14Z

web/service/inbound.go

+		req, err := http.NewRequest(method, url, body)
+		if err != nil {
+			logger.Warningf("Failed to create request for server %s: %v", server.Name, err)
+			continue
+		}


The body parameter is being reused for multiple requests when syncing with multiple servers. After the first request reads from the io.Reader, subsequent requests will receive an empty body. Each server sync should use a fresh copy of the request body.

dimasmir03 · 2025-09-16T14:43:08Z

как продвигается создание управления несколькими серверами? а то я щас собираюсь свой простой api backend делать для управления несколькими серверами. Может лучше присоединиться к вам и доделать эту классную важную фичу?
А еще, не вижу где, кто, и как разрабатывает фичу эту в данный момент. или может забросили? (извиняюсь, если слепой)

how is the creation of multi-server management progressing? otherwise, I'm going to make my simple backend api for managing multiple servers right now. Maybe it's better to join you and finish this cool important feature?
Also, I don't see where, who, or how this feature is being developed at the moment. or maybe abandoned? (I'm sorry if I'm blind)

xzyone · 2025-09-18T14:01:13Z

Is it possible for other servers to be managed by low-overhead subprograms and controlled via APIs?

dimasmir03 · 2025-09-22T08:38:35Z

@alireza0 @javadtgh can you tell me if I can join and how can I join the development of this feature and speed up its release?
I see a fork and a separate branch in that fork, but how do I create a PR for it?

konstpic · 2025-09-28T20:57:09Z

@javadtgh @alireza0 @dimasmir03 @MHSanaei

Hi everyone,

I wanted to share my thoughts on the multi-server approach. From my experience, full server management or separate slave panels aren’t strictly necessary for scaling. In my setup, I have two panels running on different servers but using a centralized MySQL database. A simple TCP proxy handles requests in a round-robin manner, and it works reliably while keeping the setup simple.

I would suggest migrating the panel to PostgreSQL first. If your servers are configured identically, there’s no need for an extra “server management” layer. A centralized database plus a proxy load balancer is sufficient. This approach is simpler and already resembles a node-based architecture like n8n.

Thanks for your work! 😊

Wasdalt · 2025-09-29T03:58:36Z

Can you tell me where I can write about the API bug?

MHSanaei · 2025-09-29T06:50:13Z

@Wasdalt direct telegram channel
https://t.me/XrayUI

dimasmir03 · 2025-09-29T14:08:42Z

@MHSanaei and where did the issue go, you could write about bugs and features there

Dreyk-Zer0 · 2025-10-05T21:33:27Z

@javadtgh I ask you to consider the scenario where the multi -server panel will be able to work with Proxy Chain settings, where the inbound of one server serves the outbound another. I use such settings in my installations, but now everything has to be steamed by a separate panels.

dimasmir03 · 2025-10-06T03:07:45Z

where the inbound of one server serves the outbound another

1 panel -> 2 panel -> 3 panel chain?

Dreyk-Zer0 · 2025-10-07T17:47:07Z

where the inbound of one server serves the outbound another

1 panel -> 2 panel -> 3 panel chain?

Yes, but i use 2 step chains.

1 panel -> 2 panel
3 panel -> 4 panel

I need to use inbounds via Wireguard in some infrastructures, but it does not go across the country border. It is also convenient for me to have entry points inside the country and the out nodes are changed as it is conveniently depending on the changing situation.

Jabi83 · 2025-11-01T17:59:50Z

Have you seen Nodex Script?
It does exactly sync All data between Main server and Nodes..
Nodex - Unofficial version of the 3X-ui Node

mengyoubenr · 2025-11-07T16:15:07Z

Why is sock5 creation not supported?

dimasmir03 · 2025-11-07T16:19:31Z

Why is sock5 creation not supported?

In this feature?

zhaoxueqingxiuyuansoftware · 2025-11-17T05:28:55Z

@javadtgh @alireza0 @dimasmir03 @MHSanaei

Hi everyone,

I wanted to share my thoughts on the multi-server approach. From my experience, full server management or separate slave panels aren’t strictly necessary for scaling. In my setup, I have two panels running on different servers but using a centralized MySQL database. A simple TCP proxy handles requests in a round-robin manner, and it works reliably while keeping the setup simple.

I would suggest migrating the panel to PostgreSQL first. If your servers are configured identically, there’s no need for an extra “server management” layer. A centralized database plus a proxy load balancer is sufficient. This approach is simpler and already resembles a node-based architecture like n8n.

Thanks for your work! 😊

I agree with your idea and fully support you.

MHSanaei changed the title ~~feat: Add multi-server support for Sanai panel~~ feat: Add multi-server support Jul 24, 2025

dev30na approved these changes Jul 25, 2025

View reviewed changes

MHSanaei force-pushed the feature/multi-server-support branch from 2a6b2ca to 11dc068 Compare July 27, 2025 15:26

MHSanaei added 2 commits August 4, 2025 10:33

Merge branch 'main' into feature/multi-server-support

d65233c

Merge branch 'main' into feature/multi-server-support

ae82373

Merge branch 'main' into feature/multi-server-support

3299d15

MHSanaei marked this pull request as draft September 4, 2025 10:12

MHSanaei force-pushed the main branch 4 times, most recently from 1208faf to 5420e64 Compare September 8, 2025 12:32

Merge branch 'main' into feature/multi-server-support

a3ccccf

MHSanaei force-pushed the main branch from 903c803 to fe9f0d1 Compare September 9, 2025 00:32

Merge branch 'main' into feature/multi-server-support

747af37

MHSanaei requested a review from Copilot September 12, 2025 10:15

Copilot AI reviewed Sep 12, 2025

View reviewed changes

Merge branch 'main' into feature/multi-server-support

5e953ba

MHSanaei force-pushed the main branch 5 times, most recently from 212238b to 5408a2f Compare September 14, 2025 20:09

MHSanaei force-pushed the main branch 2 times, most recently from 1a6958c to 3757ae0 Compare September 18, 2025 20:04

alireza0 force-pushed the main branch from d70b739 to efa32e5 Compare September 18, 2025 21:01

MHSanaei force-pushed the main branch from efa32e5 to 054cb1d Compare September 18, 2025 21:12

MHSanaei added 2 commits September 19, 2025 13:24

Merge branch 'main' into feature/multi-server-support

edd8b12

Merge branch 'main' into feature/multi-server-support

4c7249c

MHSanaei force-pushed the main branch 3 times, most recently from 2c2a8c3 to 49430b3 Compare September 24, 2025 13:42

Merge branch 'main' into feature/multi-server-support

3b262cf

MHSanaei force-pushed the main branch 3 times, most recently from ffd4c06 to ee0e309 Compare September 25, 2025 13:08

		body, _ := json.Marshal(data)
		s.syncWithSlaves("POST", "/panel/inbound/api/addClient", bytes.NewReader(body))

-		body, _ := json.Marshal(data)
-		s.syncWithSlaves("POST", "/panel/inbound/api/addClient", bytes.NewReader(body))
+		body, marshalErr := json.Marshal(data)
+		if marshalErr != nil {
+			logger.Error("Failed to marshal data for syncWithSlaves:", marshalErr)
+		} else {
+			s.syncWithSlaves("POST", "/panel/inbound/api/addClient", bytes.NewReader(body))
+		}

		body, _ := json.Marshal(data)
		s.syncWithSlaves("POST", fmt.Sprintf("/panel/inbound/api/updateClient/%s", clientId), bytes.NewReader(body))

Uh oh!

feat: Add multi-server support #3269

Are you sure you want to change the base?

feat: Add multi-server support #3269

Uh oh!

Conversation

javadtgh commented Jul 24, 2025 • edited by MHSanaei Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the pull request?

Which part of the application is affected by the change?

Type of Changes

Screenshots

Uh oh!

alireza0 commented Jul 24, 2025

Uh oh!

APT-ZERO commented Jul 25, 2025

Uh oh!

MK0ltra commented Jul 25, 2025

Uh oh!

AliAkhgar commented Aug 3, 2025

Uh oh!

AliAkhgar commented Aug 4, 2025

Uh oh!

liamnees commented Aug 17, 2025

Uh oh!

liamnees commented Aug 28, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Sep 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 12, 2025

Choose a reason for hiding this comment

Uh oh!

dimasmir03 commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xzyone commented Sep 18, 2025

Uh oh!

dimasmir03 commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

konstpic commented Sep 28, 2025

Uh oh!

Wasdalt commented Sep 29, 2025

Uh oh!

MHSanaei commented Sep 29, 2025

Uh oh!

dimasmir03 commented Sep 29, 2025

Uh oh!

Dreyk-Zer0 commented Oct 5, 2025

Uh oh!

dimasmir03 commented Oct 6, 2025

Uh oh!

Dreyk-Zer0 commented Oct 7, 2025

Uh oh!

Jabi83 commented Nov 1, 2025

Uh oh!

mengyoubenr commented Nov 7, 2025

Uh oh!

dimasmir03 commented Nov 7, 2025

Uh oh!

zhaoxueqingxiuyuansoftware commented Nov 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

16 participants

javadtgh commented Jul 24, 2025 •

edited by MHSanaei

Loading

dimasmir03 commented Sep 16, 2025 •

edited

Loading

dimasmir03 commented Sep 22, 2025 •

edited

Loading