Sanaei
6214ff4edc
* fix(mtproto): split the mtg fingerprint into structural and secrets parts A reordered clients array in the stored settings used to read as a config change because the fingerprint concatenated secrets in array order, and one opaque fingerprint could not tell a restart-worthy change (bind address, fronting, throttle) from a secret-set change a reload-capable mtg can absorb in place. Sort the secret pairs so order stops mattering, and split the value so the upcoming hot-reload path can decide between keeping, reloading, and restarting the process. * fix(mtproto): stop restarting mtg on every inbound edit Saving an mtproto inbound tore down and respawned its mtg sidecar even when nothing material changed, dropping every live Telegram connection: the update path pushed DelInbound+AddInbound, and Remove deletes the manager's map entry, so Ensure's fingerprint no-op gate could never fire. Route mtproto updates through a single Ensure call so an edit that leaves the generated TOML alone keeps the process, and only real config changes restart it. Capturing the pre-edit protocol also fixes a latent leak: changing an inbound's protocol away from mtproto never stopped the sidecar, because the snapshot handed to the runtime already carried the new protocol and the removal took the xray branch, leaving an orphaned mtg holding the port. An mtproto push failure no longer requests an xray restart - xray cannot fix the sidecar, and the 10s reconcile job self-heals it. The regression test fakes mtg by re-executing the test binary, counting spawns through a pid file: an unchanged save and a remark-only edit must keep the process, a re-keyed secret must restart it. * fix(mtproto): exclude depleted clients from the reconcile job to match the sync push The 10s reconcile job derived mtg secret sets from raw inbound settings while the interactive push filtered clients through buildRuntimeInboundForAPI, which drops client_traffics-disabled (depleted or expired) clients. The two paths therefore disagreed on the fingerprint - each disagreement one needless mtg restart dropping live connections - and worse, the job kept serving depleted clients' secrets indefinitely, so running out of traffic never actually cut an mtproto client's access. DesiredMtprotoInstances now builds the job's desired state with the same depletion overlay the push uses (one bulk client_traffics query), drops inbounds whose every secret is filtered away so their sidecar stops, and AddInbound pushes the filtered payload too so an imported inbound carrying disabled stats does not seed a fingerprint the next reconcile disagrees with. * feat(mtproto): hot-reload mtg secrets in place instead of restarting A client add, removal, re-key, or enable-toggle changes only the [secrets] section of the generated config, yet the panel could apply it only by killing and respawning the mtg sidecar, dropping every Telegram connection on that inbound. Split the ensure decision three ways: an identical config is a no-op, a secrets-only change rewrites the TOML on the same api port and asks mtg to hot-swap it via POST /reload, and a structural change (or a failed reload) falls back to the full stop-and-start. The reload endpoint is served by the mhsanaei/mtg-multi fork; against an older binary the POST 404s and the manager restarts exactly as before, so panel and binary upgrades stay order-independent. * feat(mtproto): apply single-client edits to the sidecar immediately Client CRUD on an mtproto inbound was a runtime no-op, so an add, delete, re-key, or enable-toggle only reached mtg on the next 10s reconcile. With the sidecar now able to hot-reload, push the change straight after the edit commits: applyLocalMtproto rebuilds the inbound's filtered client set and re-applies it, so a new client works within a moment (and, on a reload-capable binary, without disturbing the others) and deleting the last client stops the process. The three interactive single-client paths (add, update, delete) call it; bulk operations still ride the reconcile job, which converges to the same state. * chore(mtproto): pin mtg-multi to the mhsanaei fork v1.13.3 The reload endpoint the panel now uses lives in the mhsanaei/mtg-multi fork, so point the source-build pin (DockerInit.sh + both release.yml matrices) at it and bump to v1.13.3. The install still produces the same mtg-multi binary name, so the mtg-<os>-<arch> rename and everything downstream are unchanged. Docs and the package comment note the hot-reload path and its restart fallback. * feat(mtproto): apply live secret updates via the management API and add ad-tag Two capabilities the mhsanaei/mtg-multi v1.13.3 fork exposes are now surfaced by the sidecar manager. Live updates go through PUT /secrets on the fork's management API instead of POST /reload: the panel already holds the whole desired set per inbound, so it sends secrets and the advertising tag as one JSON call that mtg applies atomically, keeping every unchanged connection and closing only removed or re-keyed ones. The config file is still written first so a restart or crash recovery reproduces the state, and any non-200 (an older binary, a refused connection) still falls back to a full restart. Per-inbound ad-tag adds an optional 32-hex Telegram advertising tag plus public-ipv4/public-ipv6 overrides. The ad-tag rides the reloadable secrets fingerprint, so changing it hot-applies without dropping connections; the public IPs are proxy-construction parameters and sit in the structural fingerprint, so a change there restarts the process. Empty public IPs are omitted so mtg auto-detects the reachable address. * feat(inbounds): expose the mtproto ad-tag and public IP in the inbound form Adds an Ad-tag field (validated as 32 hex characters) plus optional Public IPv4 and Public IPv6 overrides to the MTProto inbound form, backed by the same-named settings the sidecar writes into the mtg config. The public IPs are optional — left blank, mtg auto-detects the reachable address the ad-tag middle proxy needs. English strings are added to every locale; the non-English ones carry the English text until translated and fall back to it meanwhile. * ci(mtproto): install mtg-multi from prebuilt release binaries The fork now publishes release archives for every platform we package, so download and unpack the matching mtg-multi-<ver>-<os>-<arch> binary instead of compiling it from source with go install. Faster builds and no toolchain step, and the archive's platform labels line up with our matrix; the produced mtg-<os>-<arch> filenames are unchanged. * i18n(mtproto): localize the ad-tag and public IP strings The six mtgAdTag*/mtgPublicIp* keys shipped with English text in every locale as a placeholder. Translate them into the twelve non-English locales (Arabic, Spanish, Persian, Indonesian, Japanese, Portuguese-BR, Russian, Turkish, Ukrainian, Vietnamese, and Simplified/Traditional Chinese); en-US is unchanged. * retired goreportcard.com
15 KiB
English | فارسی | العربية | 中文 | Español | Русский | Türkçe
3X-UI یک پنل کنترل وب پیشرفته و متنباز برای مدیریت سرورهای Xray-core است. این پنل یک رابط کاربری تمیز و چندزبانه برای استقرار، پیکربندی و نظارت بر طیف گستردهای از پروتکلهای پراکسی و VPN ارائه میدهد — از یک VPS تکی تا استقرارهای چندنودی.
3X-UI که بهعنوان یک فورک بهبودیافته از پروژهی اصلی X-UI ساخته شده است، پشتیبانی گستردهتر از پروتکلها، پایداری بهتر، حسابداری ترافیک بهازای هر کلاینت و بسیاری از ویژگیهای رفاهی را اضافه میکند.
Important
این پروژه فقط برای استفادهی شخصی در نظر گرفته شده است. لطفاً از آن برای اهداف غیرقانونی یا در محیط تولید (production) استفاده نکنید.
ویژگیها
- اینباندهای چندپروتکلی — VLESS، VMess، Trojan، Shadowsocks، WireGuard، Hysteria2، HTTP، SOCKS (Mixed)، Dokodemo-door / Tunnel و TUN.
- ترنسپورتها و امنیت مدرن — TCP (Raw)، mKCP، WebSocket، gRPC، HTTPUpgrade و XHTTP، ایمنشده با TLS، XTLS و REALITY.
- فالبک (Fallback) — ارائهی چند پروتکل روی یک پورت واحد (مثلاً VLESS و Trojan روی پورت 443) با استفاده از قابلیت fallback در Xray.
- مدیریت بهازای هر کلاینت — سهمیهی ترافیک، تاریخ انقضا، محدودیت IP، وضعیت آنلاینِ زنده و لینکهای اشتراکگذاری، کدهای QR و سابسکریپشنها با یک کلیک.
- آمار ترافیک — بهازای هر اینباند، هر کلاینت و هر اوتباند، همراه با کنترل بازنشانی (reset).
- پشتیبانی از چند نود — مدیریت و مقیاسدهی روی چندین سرور از یک پنل واحد.
- اوتباند و مسیریابی — WARP، NordVPN، قوانین مسیریابی سفارشی، متعادلکنندههای بار (load balancer) و زنجیرهکردن پراکسی اوتباند.
- سرور سابسکریپشن داخلی با چندین فرمت خروجی و قالبهای صفحهی سفارشی.
- ربات تلگرام برای نظارت و مدیریت از راه دور.
- RESTful API همراه با مستندات Swagger درونپنل.
- ذخیرهسازی منعطف — SQLite (پیشفرض) یا PostgreSQL.
- ۱۳ زبان رابط کاربری با تمهای تیره و روشن.
- یکپارچگی با Fail2ban برای اعمال محدودیت IP بهازای هر کلاینت.
اسکرینشاتها
برای باز شدن کلیک کنید
شروع سریع
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
برای نصب یک نسخهی مشخص، تگ آن را در انتها اضافه کنید (مثلاً v3.4.0):
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.4.0
برای نصب نسخهی غلتانِ dev (آخرین پیشانتشار بهازای هر کامیت از شاخهی main، نه یک انتشار پایدار)، مقدار dev-latest را پاس دهید:
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest
در حین نصب، یک نام کاربری، رمز عبور و مسیر دسترسی تصادفی تولید میشود. پس از نصب، دستور x-ui را اجرا کنید تا منوی مدیریت باز شود؛ در آنجا میتوانید سرویس را شروع/متوقف کنید، اطلاعات ورود خود را ببینید یا بازنشانی کنید، گواهیهای SSL را مدیریت کنید و کارهای دیگری انجام دهید.
برای مستندات کامل، لطفاً به ویکی پروژه مراجعه کنید.
نصب بدون نظارت
نصبکننده بهصورت غیرتعاملی نیز برای cloud-init اجرا میشود.
XUI_NONINTERACTIVE=1 را تنظیم کنید (یا بدون TTY از طریق pipe اجرا کنید) تا نصب بهصورت سرتاسری و بدون
هیچ پرسشی انجام شود، اطلاعات ورود تصادفی تولید کرده و آنها را در
/etc/x-ui/install-result.env مینویسد. برای موارد زیر به deploy/ مراجعه کنید:
- user-data مربوط به Cloud-init — نصب بدون نظارت روی هر ابری (Hetzner/AWS/DO/Vultr/GCP/Azure/Oracle)
- یادداشتهای Hetzner Cloud — استقرار مبتنی بر cloud-init روی Hetzner
پلتفرمهای پشتیبانیشده
سیستمعاملها: Ubuntu، Debian، Armbian، Fedora، CentOS، RHEL، AlmaLinux، Rocky Linux، Oracle Linux، Amazon Linux، Virtuozzo، Arch، Manjaro، Parch، openSUSE (Tumbleweed / Leap)، Alpine و Windows.
معماریها: amd64 · 386 · arm64 (aarch64) · armv7 · armv6 · armv5 · s390x.
گزینههای پایگاهداده
3X-UI از دو بکاند پشتیبانی میکند که در حین نصب انتخاب میشوند:
- SQLite (پیشفرض) — یک فایل واحد در مسیر
/etc/x-ui/x-ui.db. بدون نیاز به تنظیمات، ایدهآل برای استقرارهای کوچک و متوسط. - PostgreSQL — برای تعداد کلاینت بالا یا راهاندازیهای چندنودی توصیه میشود. نصبکننده میتواند PostgreSQL را بهصورت محلی برایتان نصب کند، یا یک DSN به یک سرور موجود را بپذیرد.
در زمان اجرا، بکاند از طریق متغیرهای محیطی انتخاب میشود (نصبکننده این موارد را برای شما در /etc/default/x-ui مینویسد):
XUI_DB_TYPE=postgres
XUI_DB_DSN=postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable
انتقال یک نصب موجود SQLite به PostgreSQL
x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable"
# سپس XUI_DB_TYPE و XUI_DB_DSN را در /etc/default/x-ui تنظیم کرده و ریاستارت کنید:
systemctl restart x-ui
فایل اصلی SQLite دستنخورده باقی میماند؛ پس از اطمینان از صحت بکاند جدید، آن را بهصورت دستی حذف کنید.
Docker
دستور پیشفرض docker compose up -d همچنان از SQLite استفاده میکند. برای اجرا با سرویس PostgreSQL همراه، دو خط متغیر محیطی XUI_DB_* را در docker-compose.yml از حالت کامنت خارج کنید و با پروفایل زیر اجرا کنید:
docker compose --profile postgres up -d
این ایمیج، Fail2ban را (که بهصورت پیشفرض فعال است) برای اعمال محدودیتهای IP بهازای هر کلاینت همراه دارد. Fail2ban متخلفان را با iptables مسدود میکند که به مجوز NET_ADMIN نیاز دارد. فایل docker-compose.yml این مجوز را از قبل از طریق cap_add میدهد؛ اگر بهجای آن کانتینر را با docker run اجرا میکنید، خودتان مجوزها را اضافه کنید، در غیر این صورت مسدودسازیها فقط ثبت میشوند اما هرگز اعمال نمیشوند:
docker run -d --cap-add=NET_ADMIN --cap-add=NET_RAW ... ghcr.io/mhsanaei/3x-ui
متغیرهای محیطی
| متغیر | توضیحات | پیشفرض |
|---|---|---|
XUI_DB_TYPE |
بکاند پایگاهداده: sqlite یا postgres |
sqlite |
XUI_DB_DSN |
رشتهی اتصال PostgreSQL (وقتی XUI_DB_TYPE=postgres) |
— |
XUI_DB_FOLDER |
پوشهی فایل پایگاهدادهی SQLite | /etc/x-ui |
XUI_DB_MAX_OPEN_CONNS |
حداکثر اتصالات باز (استخر PostgreSQL) | — |
XUI_DB_MAX_IDLE_CONNS |
حداکثر اتصالات بیکار (استخر PostgreSQL) | — |
XUI_INIT_WEB_BASE_PATH |
مسیر URI اولیه برای پنل وب | / |
XUI_ENABLE_FAIL2BAN |
فعالسازی اعمال محدودیت IP مبتنی بر Fail2ban | true |
XUI_LOG_LEVEL |
سطح گزارشگیری (debug، info، warning، error) |
info |
XUI_DEBUG |
فعالسازی حالت دیباگ | false |
XUI_TUNNEL_HEALTH_MONITOR |
فعالسازی پایشگر سلامت تونل (یک URL را پروب میکند و پس از خطاهای مکرر، xray را ریاستارت میکند؛ یک ریاستارت همهی کلاینتها را قطع میکند) | false |
XUI_TUNNEL_HEALTH_PROXY |
پراکسیای که پروب از طریق آن ارسال میشود؛ آن را به یک اینباند محلی xray اشاره دهید تا پروب خودِ تونل را آزمایش کند (مثلاً socks5://127.0.0.1:1080). خالی بودن یعنی پروب فقط اتصال به هاست را بررسی میکند |
— |
XUI_TUNNEL_HEALTH_URL |
URL ای که برای سلامت تونل پروب میشود | https://www.cloudflare.com/cdn-cgi/trace |
XUI_TUNNEL_HEALTH_INTERVAL |
فاصلهی زمانی بین پروبها | 30s |
XUI_TUNNEL_HEALTH_TIMEOUT |
مهلت زمانی هر پروب | 10s |
XUI_TUNNEL_HEALTH_FAILURES |
تعداد خطاهای متوالی پیش از آنکه یک ریاستارت فعال شود | 3 |
XUI_TUNNEL_HEALTH_COOLDOWN |
حداقل تأخیر بین ریاستارتهای متوالی | 5m |
زبانهای پشتیبانیشده
رابط کاربری پنل به ۱۳ زبان در دسترس است:
English · فارسی · العربية · 中文（简体） · 中文（繁體） · Español · Русский · Українська · Türkçe · Tiếng Việt · 日本語 · Bahasa Indonesia · Português (Brasil)
مشارکت
از مشارکتها استقبال میشود. لطفاً پیش از باز کردن issue یا pull request، راهنمای مشارکت را مطالعه کنید.
تشکر ویژه از
قدردانی
- Iran v2ray rules (مجوز: GPL-3.0): قوانین مسیریابی بهبود یافته v2ray/xray و v2ray/xray-clients با دامنههای ایرانی داخلی و تمرکز بر امنیت و مسدود کردن تبلیغات.
- Russia v2ray rules (مجوز: GPL-3.0): این مخزن شامل قوانین مسیریابی V2Ray بهروزرسانی شده خودکار بر اساس دادههای دامنهها و آدرسهای مسدود شده در روسیه است.
ابزارهای جامعه
ابزارها و یکپارچهسازیهایی که توسط جامعه پیرامون 3x-ui ساخته شدهاند.
- terraform-provider-3x-ui (مجوز: MIT): مدیریت اینباندها، کلاینتها، تنظیمات پنل و پیکربندی Xray بهصورت کد با Terraform / OpenTofu.
پشتیبانی از پروژه
اگر این پروژه برای شما مفید است، میتوانید به آن یک🌟 بدهید
ستارهها در طول زمان
