mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-06-06 13:14:11 +00:00
e0f41362e2
Lets operators with large client counts or multi-node setups pick PostgreSQL at install time without breaking the existing SQLite default. Backend is selected at runtime via XUI_DB_TYPE/XUI_DB_DSN, a small dialect layer keeps the five JSON_EXTRACT/JSON_EACH queries portable, and a new `x-ui migrate-db` subcommand copies SQLite data into PostgreSQL in FK-aware order.
95 lines
4.5 KiB
Markdown
95 lines
4.5 KiB
Markdown
[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)
|
|
|
|
<p align="center">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="./media/3x-ui-dark.png">
|
|
<img alt="3x-ui" src="./media/3x-ui-light.png">
|
|
</picture>
|
|
</p>
|
|
|
|
[](https://github.com/MHSanaei/3x-ui/releases)
|
|
[](https://github.com/MHSanaei/3x-ui/actions)
|
|
[](#)
|
|
[](https://github.com/MHSanaei/3x-ui/releases/latest)
|
|
[](https://www.gnu.org/licenses/gpl-3.0.en.html)
|
|
[](https://pkg.go.dev/github.com/mhsanaei/3x-ui/v3)
|
|
[](https://goreportcard.com/report/github.com/mhsanaei/3x-ui/v3)
|
|
|
|
**3X-UI** — advanced, open-source web-based control panel designed for managing Xray-core server. It offers a user-friendly interface for configuring and monitoring various VPN and proxy protocols.
|
|
|
|
> [!IMPORTANT]
|
|
> This project is only for personal usage, please do not use it for illegal purposes, and please do not use it in a production environment.
|
|
|
|
As an enhanced fork of the original X-UI project, 3X-UI provides improved stability, broader protocol support, and additional features.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
|
|
```
|
|
|
|
For full documentation, please visit the [project Wiki](https://github.com/MHSanaei/3x-ui/wiki).
|
|
|
|
## 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/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 env vars (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
|
|
```
|
|
|
|
## 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:
|
|
|
|
<a href="https://www.buymeacoffee.com/MHSanaei" target="_blank">
|
|
<img src="./media/default-yellow.png" alt="Buy Me A Coffee" style="height: 70px !important;width: 277px !important;" >
|
|
</a>
|
|
|
|
</br>
|
|
<a href="https://nowpayments.io/donation/hsanaei" target="_blank" rel="noreferrer noopener">
|
|
<img src="./media/donation-button-black.svg" alt="Crypto donation button by NOWPayments">
|
|
</a>
|
|
|
|
## Stargazers over Time
|
|
|
|
[](https://starchart.cc/MHSanaei/3x-ui)
|