mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-06-03 10:59:34 +00:00
28330e60d8
The image bundles fail2ban (enabled by default) to enforce per-client IP limits via iptables, but docker-compose.yml granted no capabilities. The job logs the ban and fail2ban reports it as banned, yet the iptables action fails with "Permission denied (you must be root)" and no rule is inserted, so the client is never actually blocked. Add cap_add NET_ADMIN/NET_RAW to the service and document the docker run flags.
102 lines
4.9 KiB
Markdown
102 lines
4.9 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
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
## 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)
|