Sanaei
3ef06b7000
The READMEs had not moved since 2026-07-07, 341 commits ago, and had drifted far enough to misdescribe the panel: AmneziaWG and MTProto inbounds were missing from the protocol list entirely, the outbound list predated PIA, and the API section still advertised Swagger rather than scoped, optionally expiring tokens. Add the two missing protocols plus a bullet each for what makes them notable — AmneziaWG runs on the embedded userspace netstack, so unlike the DKMS/awg-quick shape it originally shipped with there is nothing to install, and MTProto client edits hot-apply through the mtg-multi management API instead of bouncing the process. Fold the smaller additions into the bullets they belong to (HWID device limits, IP-limit exemptions, renewal cycles, inbound cloning, balancer-to-balancer fallback, geosite/geoip browsing, named subscription formats) and add one for PWA installability. Point documentation at docs.sanaei.dev, which the panel sidebar already links to and which supersedes the wiki, using each README's own locale where the docs site has one (fa/ru/zh). Bump the pinned install example to the current stable tag, note the .sha256 verification install.sh and update.sh now perform, and document XUI_NODE_TOKEN_KEY_FILE / XUI_NODE_TOKEN_KEY, which no markdown in the repo covered. All seven files move together so the language picker keeps pointing at equivalent documents.
17 KiB
English | فارسی | العربية | 中文 | Español | Русский | Türkçe
3X-UI یک پنل کنترل وب پیشرفته و متنباز برای مدیریت سرورهای Xray-core است. این پنل یک رابط کاربری تمیز و چندزبانه برای استقرار، پیکربندی و نظارت بر طیف گستردهای از پروتکلهای پراکسی و VPN ارائه میدهد — از یک VPS تکی تا استقرارهای چندنودی.
3X-UI که بهعنوان یک فورک بهبودیافته از پروژهی اصلی X-UI ساخته شده است، پشتیبانی گستردهتر از پروتکلها، پایداری بهتر، حسابداری ترافیک بهازای هر کلاینت و بسیاری از ویژگیهای رفاهی را اضافه میکند.
Important
این پروژه فقط برای استفادهی شخصی در نظر گرفته شده است. لطفاً از آن برای اهداف غیرقانونی یا در محیط تولید (production) استفاده نکنید.
ویژگیها
- اینباندهای چندپروتکلی — VLESS، VMess، Trojan، Shadowsocks، WireGuard، AmneziaWG، Hysteria2، MTProto، HTTP، SOCKS (Mixed)، Dokodemo-door / Tunnel و TUN.
- ترنسپورتها و امنیت مدرن — TCP (Raw)، mKCP، WebSocket، gRPC، HTTPUpgrade و XHTTP، ایمنشده با TLS، XTLS و REALITY.
- AmneziaWG داخلی — نسخهی مقاوم در برابر DPI از WireGuard مستقیماً درون پنل و روی یک پشتهی شبکهی فضای کاربر اجرا میشود؛ بدون ماژول کرنل، DKMS یا بستههای اضافی.
- پراکسیهای MTProto — سکرتهای FakeTLS، ad-tag و سهمیهها بهازای هر کلاینت، که بهصورت زنده و بدون قطع اتصالهای موجود اعمال میشوند.
- فالبک (Fallback) — ارائهی چند پروتکل روی یک پورت واحد (مثلاً VLESS و Trojan روی پورت 443) با استفاده از قابلیت fallback در Xray.
- مدیریت بهازای هر کلاینت — سهمیهی ترافیک، تاریخ انقضا، محدودیت IP با امکان استثنا کردن آدرسهای مورد اعتماد، محدودیت دستگاه (HWID)، چرخههای تمدید زمانبندیشده، وضعیت آنلاینِ زنده و لینکهای اشتراکگذاری، کدهای QR و سابسکریپشنها با یک کلیک.
- آمار ترافیک — بهازای هر اینباند، هر کلاینت و هر اوتباند، همراه با کنترل بازنشانی (reset).
- پشتیبانی از چند نود — مدیریت و مقیاسدهی روی چندین سرور از یک پنل واحد، از جمله کلونکردن اینباندها روی نودهای دیگر.
- اوتباند و مسیریابی — WARP، NordVPN، PIA، قوانین مسیریابی سفارشی، متعادلکنندههای بار (load balancer) با فالبک بین متعادلکنندهها و زنجیرهکردن پراکسی اوتباند. دستهبندیهای geosite و geoip همراهشده مستقیماً از ویرایشگر قوانین قابل مرور هستند.
- سرور سابسکریپشن داخلی — خروجی raw، JSON و Clash که بر پایهی User-Agent کلاینت بهصورت خودکار انتخاب میشود، بههمراه قالبهای صفحهی سفارشی.
- ربات تلگرام برای نظارت و مدیریت از راه دور.
- RESTful API با توکنهای محدودشده (scoped) و دارای انقضای اختیاری، بههمراه مرجع API درونپنل.
- پنل قابل نصب (PWA) — 3X-UI را به دسکتاپ یا صفحهی اصلی گوشی خود سنجاق کنید.
- ذخیرهسازی منعطف — SQLite (پیشفرض) یا PostgreSQL.
- ۱۳ زبان رابط کاربری با تمهای تیره و روشن.
- یکپارچگی با Fail2ban برای اعمال محدودیت IP بهازای هر کلاینت.
اسکرینشاتها
برای باز شدن کلیک کنید
شروع سریع
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
برای نصب یک نسخهی مشخص، تگ آن را در انتها اضافه کنید (مثلاً v3.7.0):
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.7.0
برای نصب نسخهی غلتانِ dev (آخرین پیشانتشار بهازای هر کامیت از شاخهی main، نه یک انتشار پایدار)، مقدار dev-latest را پاس دهید:
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest
در حین نصب، یک نام کاربری، رمز عبور و مسیر دسترسی تصادفی تولید میشود. پس از نصب، دستور x-ui را اجرا کنید تا منوی مدیریت باز شود؛ در آنجا میتوانید سرویس را شروع/متوقف کنید، اطلاعات ورود خود را ببینید یا بازنشانی کنید، گواهیهای SSL را مدیریت کنید و کارهای دیگری انجام دهید.
هر فایل انتشار بههمراه یک جمع کنترلی .sha256 در کنارش منتشر میشود. هم install.sh و هم بهروزرسان، آرشیو را در برابر آن جمع کنترلی بررسی میکنند و در صورت عدم تطابق متوقف میشوند.
برای مستندات کامل — نصب، پیکربندی، بهرهبرداری و مرجع کامل API — به docs.sanaei.dev مراجعه کنید.
نصب بدون نظارت
نصبکننده بهصورت غیرتعاملی نیز برای 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 |
NODE_TOKEN_ENCRYPTION |
رمزگذاری توکنهای API نود در حالت سکون: off، migration یا required (بدون پیشوند XUI_) |
off |
XUI_NODE_TOKEN_KEY_FILE |
حلقهکلید JSON (با دسترسی 0600) شامل شناسهی کلید فعال و کلیدهای ۳۲ بایتی base64 |
/etc/x-ui/node_token_key.json |
XUI_NODE_TOKEN_KEY |
یک کلید ۳۲ بایتی base64 که تنها در صورت بارگذارینشدن فایل کلید استفاده میشود | — |
فهرست کامل در مرجع متغیرهای محیطی موجود است.
زبانهای پشتیبانیشده
رابط کاربری پنل به ۱۳ زبان در دسترس است:
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.
پشتیبانی از پروژه
اگر این پروژه برای شما مفید است، میتوانید به آن یک🌟 بدهید
ستارهها در طول زمان
