2026-06-10 06:31:38 -07:00
[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 ) | [Türkçe ](/README.tr_TR.md )
2025-02-03 11:30:42 -08:00
< 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 >
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
< p align = "center" >
2026-06-01 18:16:54 -07:00
< a href = "https://github.com/MHSanaei/3x-ui/releases" > < img src = "https://img.shields.io/github/v/release/mhsanaei/3x-ui" alt = "Release" > < / a >
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
< a href = "https://github.com/MHSanaei/3x-ui/actions" > < img src = "https://img.shields.io/github/actions/workflow/status/mhsanaei/3x-ui/release.yml.svg" alt = "Build" > < / a >
< a href = "#" > < img src = "https://img.shields.io/github/go-mod/go-version/mhsanaei/3x-ui.svg" alt = "GO Version" > < / a >
< a href = "https://github.com/MHSanaei/3x-ui/releases/latest" > < img src = "https://img.shields.io/github/downloads/mhsanaei/3x-ui/total.svg" alt = "Downloads" > < / a >
< a href = "https://www.gnu.org/licenses/gpl-3.0.en.html" > < img src = "https://img.shields.io/badge/license-GPL%20V3-blue.svg?longCache=true" alt = "License" > < / a >
< a href = "https://pkg.go.dev/github.com/mhsanaei/3x-ui/v3" > < img src = "https://pkg.go.dev/badge/github.com/mhsanaei/3x-ui/v3.svg" alt = "Go Reference" > < / a >
docs(readme): refresh all seven READMEs for the current feature set
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.
2026-09-04 00:49:25 -07:00
< a href = "https://docs.sanaei.dev" > < img src = "https://img.shields.io/badge/docs-docs.sanaei.dev-22d3ee" alt = "Documentation" > < / a >
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
< / p >
2025-02-03 11:30:42 -08:00
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
**3X-UI** یک پنل کنترل وب پیشرفته و متنباز برای مدیریت سرورهای [Xray-core ](https://github.com/XTLS/Xray-core ) است. این پنل یک رابط کاربری تمیز و چندزبانه برای استقرار، پیکربندی و نظارت بر طیف گستردهای از پروتکلهای پراکسی و VPN ارائه میدهد — از یک VPS تکی تا استقرارهای چندنودی.
3X-UI که بهعنوان یک فورک بهبودیافته از پروژهی اصلی X-UI ساخته شده است، پشتیبانی گستردهتر از پروتکلها، پایداری بهتر، حسابداری ترافیک بهازای هر کلاینت و بسیاری از ویژگیهای رفاهی را اضافه میکند.
2025-02-03 11:30:42 -08:00
2025-06-05 04:56:33 -07:00
> [!IMPORTANT]
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
> این پروژه فقط برای استفادهی شخصی در نظر گرفته شده است. لطفاً از آن برای اهداف غیرقانونی یا در محیط تولید (production) استفاده نکنید.
2025-02-03 11:30:42 -08:00
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
## ویژگیها
docs: add TUIC v5 to READMEs, guides, and protocol references (#6511)
* docs: add TUIC v5 to READMEs, guides, and protocol references
* docs: address review feedback on TUIC architecture, external links, and i18n parity
* docs(tuic): drop the Xray-routing claim and qualify Limit IP for TUIC
The README feature bullet in all seven locales credited the TUIC sidecar
with "seamless Xray routing". A TUIC inbound never enters the Xray config
(internal/web/service/xray.go skips model.TUIC) and the generated
tuic-server config carries no forwarding target, so decrypted TUIC
traffic egresses from the sidecar directly and Xray routing rules never
see it; docs/architecture.md in this same branch already says so. An
operator reading the bullet would expect geo blocking and outbound
selection to cover TUIC clients.
The client field table marks Total (GB) as inbound-level for TUIC but
left Limit IP at "all". The IP-limit job's only data source is Xray's
online-stats API (internal/web/job/check_client_ip_job.go), which TUIC
clients never reach, so a Limit IP set on a TUIC client is silently
unenforced. Qualify that row the same way in en, fa, ru and zh.
---------
Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-14 02:36:59 -07:00
- **اینباندهای چندپروتکلی** — VLESS، VMess، Trojan، Shadowsocks، WireGuard، AmneziaWG، TUIC v5، Hysteria2، MTProto، HTTP، SOCKS (Mixed)، Dokodemo-door / Tunnel و TUN.
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
- **ترنسپورتها و امنیت مدرن** — TCP (Raw)، mKCP، WebSocket، gRPC، HTTPUpgrade و XHTTP، ایمنشده با TLS، XTLS و REALITY.
docs(readme): refresh all seven READMEs for the current feature set
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.
2026-09-04 00:49:25 -07:00
- ** AmneziaWG داخلی** — نسخهی مقاوم در برابر DPI از WireGuard مستقیماً درون پنل و روی یک پشتهی شبکهی فضای کاربر اجرا میشود؛ بدون ماژول کرنل، DKMS یا بستههای اضافی.
docs: add TUIC v5 to READMEs, guides, and protocol references (#6511)
* docs: add TUIC v5 to READMEs, guides, and protocol references
* docs: address review feedback on TUIC architecture, external links, and i18n parity
* docs(tuic): drop the Xray-routing claim and qualify Limit IP for TUIC
The README feature bullet in all seven locales credited the TUIC sidecar
with "seamless Xray routing". A TUIC inbound never enters the Xray config
(internal/web/service/xray.go skips model.TUIC) and the generated
tuic-server config carries no forwarding target, so decrypted TUIC
traffic egresses from the sidecar directly and Xray routing rules never
see it; docs/architecture.md in this same branch already says so. An
operator reading the bullet would expect geo blocking and outbound
selection to cover TUIC clients.
The client field table marks Total (GB) as inbound-level for TUIC but
left Limit IP at "all". The IP-limit job's only data source is Xray's
online-stats API (internal/web/job/check_client_ip_job.go), which TUIC
clients never reach, so a Limit IP set on a TUIC client is silently
unenforced. Qualify that row the same way in en, fa, ru and zh.
---------
Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-14 02:36:59 -07:00
- ** TUIC v5 داخلی** — پراکسی با کارایی بالا مبتنی بر QUIC با اندازهگیری بومی ترافیک رله UDP، دستدادنهای 0-RTT و کنترل ازدحام BBR.
docs(readme): refresh all seven READMEs for the current feature set
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.
2026-09-04 00:49:25 -07:00
- **پراکسیهای MTProto** — سکرتهای FakeTLS، ad-tag و سهمیهها بهازای هر کلاینت، که بهصورت زنده و بدون قطع اتصالهای موجود اعمال میشوند.
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
- **فالبک (Fallback)** — ارائهی چند پروتکل روی یک پورت واحد (مثلاً VLESS و Trojan روی پورت 443) با استفاده از قابلیت fallback در Xray.
docs(readme): refresh all seven READMEs for the current feature set
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.
2026-09-04 00:49:25 -07:00
- **مدیریت بهازای هر کلاینت** — سهمیهی ترافیک، تاریخ انقضا، محدودیت IP با امکان استثنا کردن آدرسهای مورد اعتماد، محدودیت دستگاه (HWID)، چرخههای تمدید زمانبندیشده، وضعیت آنلاینِ زنده و لینکهای اشتراکگذاری، کدهای QR و سابسکریپشنها با یک کلیک.
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
- **آمار ترافیک** — بهازای هر اینباند، هر کلاینت و هر اوتباند، همراه با کنترل بازنشانی (reset).
docs(readme): refresh all seven READMEs for the current feature set
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.
2026-09-04 00:49:25 -07:00
- **پشتیبانی از چند نود** — مدیریت و مقیاسدهی روی چندین سرور از یک پنل واحد، از جمله کلونکردن اینباندها روی نودهای دیگر.
- **اوتباند و مسیریابی** — WARP، NordVPN، PIA، قوانین مسیریابی سفارشی، متعادلکنندههای بار (load balancer) با فالبک بین متعادلکنندهها و زنجیرهکردن پراکسی اوتباند. دستهبندیهای geosite و geoip همراهشده مستقیماً از ویرایشگر قوانین قابل مرور هستند.
- **سرور سابسکریپشن داخلی** — خروجی raw، JSON و Clash که بر پایهی User-Agent کلاینت بهصورت خودکار انتخاب میشود، بههمراه [قالبهای صفحهی سفارشی ](docs/custom-subscription-templates.md ).
docs: add Discord bot to READMEs, architecture, operations guides, and locales (#6513)
* docs: add Discord bot to READMEs, architecture, operations guides, and locales
* docs: address review feedback on Discord bot formatting, backup commands, and architecture
* docs(discord): fix Persian typo and literal arrows on fa/zh bot pages
Senior review of #6513, two LOW findings in the two new pages:
- fa/operations/discord-bot.mdx:30 spelled "developers" with Cyrillic
"де" in place of Persian "ده", rendering a mixed-script word.
- Both pages copied `$\rightarrow$` from the en page. The docs site has
no math plugin (nothing in source.config.ts, no remark-math
installed), so the built HTML shows the literal string
"$\rightarrow$" in every menu path. Replaced with a Unicode arrow on
fa and zh; en and ru have carried the same since #6486 and are left
for a separate change.
---------
Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-14 02:53:22 -07:00
- **رباتهای تلگرام و دیسکورد** برای نظارت و مدیریت از راه دور.
docs(readme): refresh all seven READMEs for the current feature set
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.
2026-09-04 00:49:25 -07:00
- ** RESTful API** با توکنهای محدودشده (scoped) و دارای انقضای اختیاری، بههمراه مرجع API درونپنل.
- **پنل قابل نصب (PWA)** — 3X-UI را به دسکتاپ یا صفحهی اصلی گوشی خود سنجاق کنید.
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
- **ذخیرهسازی منعطف** — SQLite (پیشفرض) یا PostgreSQL.
2026-10-23 22:35:28 -07:00
- **۱۴ زبان رابط کاربری** با تمهای تیره و روشن.
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
- **یکپارچگی با Fail2ban** برای اعمال محدودیت IP بهازای هر کلاینت.
## اسکرینشاتها
< details >
< summary > برای باز شدن کلیک کنید< / summary >
< picture >
< source media = "(prefers-color-scheme: dark)" srcset = "./media/01-overview-dark.png" >
< img alt = "Overview" src = "./media/01-overview-light.png" >
< / picture >
< picture >
< source media = "(prefers-color-scheme: dark)" srcset = "./media/02-add-inbound-dark.png" >
< img alt = "Inbounds" src = "./media/02-add-inbound-light.png" >
< / picture >
< picture >
< source media = "(prefers-color-scheme: dark)" srcset = "./media/03-add-client-dark.png" >
< img alt = "Add client" src = "./media/03-add-client-light.png" >
< / picture >
< picture >
< source media = "(prefers-color-scheme: dark)" srcset = "./media/05-add-nodes-dark.png" >
< img alt = "Configs" src = "./media/05-add-nodes-light.png" >
< / picture >
< / details >
2025-06-05 04:56:33 -07:00
## شروع سریع
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
```bash
2025-06-10 08:47:31 -07:00
bash < (curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
2025-06-05 04:56:33 -07:00
```
docs(readme): refresh all seven READMEs for the current feature set
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.
2026-09-04 00:49:25 -07:00
برای نصب یک نسخهی مشخص، تگ آن را در انتها اضافه کنید (مثلاً `v3.7.0` ):
2026-06-24 17:36:30 -07:00
```bash
docs(readme): refresh all seven READMEs for the current feature set
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.
2026-09-04 00:49:25 -07:00
bash < (curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.7.0
2026-06-24 17:36:30 -07:00
```
برای نصب نسخهی غلتانِ **dev** (آخرین پیشانتشار بهازای هر کامیت از شاخهی `main` ، نه یک انتشار پایدار)، مقدار `dev-latest` را پاس دهید:
```bash
bash < (curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest
```
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
در حین نصب، یک نام کاربری، رمز عبور و مسیر دسترسی تصادفی تولید میشود. پس از نصب، دستور `x-ui` را اجرا کنید تا منوی مدیریت باز شود؛ در آنجا میتوانید سرویس را شروع/متوقف کنید، اطلاعات ورود خود را ببینید یا بازنشانی کنید، گواهیهای SSL را مدیریت کنید و کارهای دیگری انجام دهید.
docs(readme): refresh all seven READMEs for the current feature set
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.
2026-09-04 00:49:25 -07:00
هر فایل انتشار بههمراه یک جمع کنترلی `.sha256` در کنارش منتشر میشود. هم `install.sh` و هم بهروزرسان، آرشیو را در برابر آن جمع کنترلی بررسی میکنند و در صورت عدم تطابق متوقف میشوند.
برای مستندات کامل — نصب، پیکربندی، بهرهبرداری و مرجع کامل API — به ** [docs.sanaei.dev ](https://docs.sanaei.dev/fa )** مراجعه کنید.
2025-06-05 04:56:33 -07:00
2026-06-25 15:35:34 -07:00
### نصب بدون نظارت
2026-06-24 17:36:30 -07:00
2026-06-25 15:35:34 -07:00
نصبکننده بهصورت **غیرتعاملی** نیز برای cloud-init اجرا میشود.
2026-06-24 17:36:30 -07:00
`XUI_NONINTERACTIVE=1` را تنظیم کنید (یا بدون TTY از طریق pipe اجرا کنید) تا نصب بهصورت سرتاسری و بدون
هیچ پرسشی انجام شود، اطلاعات ورود تصادفی تولید کرده و آنها را در
`/etc/x-ui/install-result.env` مینویسد. برای موارد زیر به [`deploy/` ](deploy/ ) مراجعه کنید:
- [user-data مربوط به Cloud-init ](deploy/cloud-init/ ) — نصب بدون نظارت روی هر ابری (Hetzner/AWS/DO/Vultr/GCP/Azure/Oracle)
2026-06-25 15:35:34 -07:00
- [یادداشتهای Hetzner Cloud ](deploy/marketplace/hetzner/ ) — استقرار مبتنی بر cloud-init روی Hetzner
2026-06-24 17:36:30 -07:00
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
## پلتفرمهای پشتیبانیشده
**سیستمعاملها:** 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
```bash
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` از حالت کامنت خارج کنید و با پروفایل زیر اجرا کنید:
```bash
docker compose --profile postgres up -d
```
این ایمیج، Fail2ban را (که بهصورت پیشفرض فعال است) برای اعمال **محدودیتهای IP** بهازای هر کلاینت همراه دارد. Fail2ban متخلفان را با `iptables` مسدود میکند که به مجوز `NET_ADMIN` نیاز دارد. فایل `docker-compose.yml` این مجوز را از قبل از طریق `cap_add` میدهد؛ اگر بهجای آن کانتینر را با `docker run` اجرا میکنید، خودتان مجوزها را اضافه کنید، در غیر این صورت مسدودسازیها فقط ثبت میشوند اما هرگز اعمال نمیشوند:
```bash
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) | — |
2026-06-11 03:51:54 -07:00
| `XUI_INIT_WEB_BASE_PATH` | مسیر URI اولیه برای پنل وب | `/` |
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
| `XUI_ENABLE_FAIL2BAN` | فعالسازی اعمال محدودیت IP مبتنی بر Fail2ban | `true` |
| `XUI_LOG_LEVEL` | سطح گزارشگیری (`debug`، `info` ، `warning` ، `error` ) | `info` |
| `XUI_DEBUG` | فعالسازی حالت دیباگ | `false` |
2026-06-24 17:36:30 -07:00
| `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` |
docs(readme): refresh all seven READMEs for the current feature set
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.
2026-09-04 00:49:25 -07:00
| `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 که تنها در صورت بارگذارینشدن فایل کلید استفاده میشود | — |
فهرست کامل در [مرجع متغیرهای محیطی ](https://docs.sanaei.dev/fa/docs/reference/env-vars ) موجود است.
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
## زبانهای پشتیبانیشده
2026-10-23 22:35:28 -07:00
رابط کاربری پنل به ۱۴ زبان در دسترس است:
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
2026-10-23 22:35:28 -07:00
English · فارسی · العربية · 中文(简体) · 中文(繁體) · Español · Русский · Українська · Türkçe · Tiếng Việt · 日本語 · Bahasa Indonesia · Português (Brasil) · Slovenčina
docs(readme): revamp README and sync all translations
Rewrite the five translated READMEs (fa, ar, zh, es, ru) to match the overhauled English README: centered badge layout plus Features, Screenshots, Supported Platforms, Database/Docker, Environment Variables, Supported Languages, and Contributing sections. Add Windows to supported platforms and a fallback feature (multiple protocols on one port). Refresh the referenced screenshots.
2026-06-01 18:02:24 -07:00
## مشارکت
از مشارکتها استقبال میشود. لطفاً پیش از باز کردن issue یا pull request، [راهنمای مشارکت ](/CONTRIBUTING.md ) را مطالعه کنید.
2025-06-05 04:56:33 -07:00
## تشکر ویژه از
- [alireza0 ](https://github.com/alireza0/ )
## قدردانی
- [Iran v2ray rules ](https://github.com/chocolate4u/Iran-v2ray-rules ) (مجوز: **GPL-3.0** ): _قوا نین مسیریابی بهبود یافته v2ray/xray و v2ray/xray-clients با دامنههای ایرانی داخلی و تمرکز بر امنیت و مسدود کردن تبلیغات._
- [Russia v2ray rules ](https://github.com/runetfreedom/russia-v2ray-rules-dat ) (مجوز: **GPL-3.0** ): _ا ین مخزن شامل قوانین مسیریابی V2Ray بهروزرسانی شده خودکار بر اساس دادههای دامنهها و آدرسهای مسدود شده در روسیه است._
2026-05-14 06:54:52 -07:00
## ابزارهای جامعه
ابزارها و یکپارچهسازیهایی که توسط جامعه پیرامون 3x-ui ساخته شدهاند.
- [terraform-provider-3x-ui ](https://github.com/batonogov/terraform-provider-threexui ) (مجوز: **MIT** ): _مدیریت اینباندها، کلاینتها، تنظیمات پنل و پیکربندی Xray بهصورت کد با Terraform / OpenTofu._
2026-09-12 02:13:16 -07:00
- [3X-UI Manager ](https://github.com/yukh975/3X-UI-Manager ) (مجوز: **MIT** ): _کلا ینت بومی اندروید برای 3x-ui — داشبورد، اینباندها، کلاینتها با اشتراکگذاری QR، نودها و مدیریت چند پنل. در F-Droid در دسترس است._
2026-05-14 06:54:52 -07:00
2025-06-05 04:56:33 -07:00
## پشتیبانی از پروژه
**اگر این پروژه برای شما مفید است، میتوانید به آن یک**:star2: بدهید
2025-02-03 11:30:42 -08:00
2025-09-18 11:08:56 -07:00
< 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 >
2025-02-03 11:30:42 -08:00
2025-09-18 11:08:56 -07:00
< / 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 >
2025-02-03 11:30:42 -08:00
2026-09-12 02:33:46 -07:00
## تاریخچه ستارهها
2025-02-03 11:30:42 -08:00
2026-09-12 02:33:46 -07:00
< a href = "https://www.star-history.com/?repos=mhsanaei%2F3x-ui&type=date&legend=top-left" >
< picture >
< source media = "(prefers-color-scheme: dark)" srcset = "https://api.star-history.com/chart?repos=mhsanaei/3x-ui&type=date&theme=dark&legend=top-left" / >
< source media = "(prefers-color-scheme: light)" srcset = "https://api.star-history.com/chart?repos=mhsanaei/3x-ui&type=date&legend=top-left" / >
< img alt = "Star History Chart" src = "https://api.star-history.com/chart?repos=mhsanaei/3x-ui&type=date&legend=top-left" / >
< / picture >
< / a >
< p align = "center" >
< a href = "https://www.star-history.com/mhsanaei/3x-ui" >
< picture > < source media = "(prefers-color-scheme: dark)" srcset = "https://api.star-history.com/badge?repo=MHSanaei/3x-ui&type=rank&theme=dark" / > < source media = "(prefers-color-scheme: light)" srcset = "https://api.star-history.com/badge?repo=MHSanaei/3x-ui&type=rank" / > < img alt = "Star History Rank" src = "https://api.star-history.com/badge?repo=MHSanaei/3x-ui&type=rank" / > < / picture > < picture > < source media = "(prefers-color-scheme: dark)" srcset = "https://api.star-history.com/badge?repo=MHSanaei/3x-ui&type=trending&theme=dark" / > < source media = "(prefers-color-scheme: light)" srcset = "https://api.star-history.com/badge?repo=MHSanaei/3x-ui&type=trending" / > < img alt = "GitHub Trending Repository of the Day" src = "https://api.star-history.com/badge?repo=MHSanaei/3x-ui&type=trending" / > < / picture >
< / a >
< / p >