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.
14 KiB
English | فارسی | العربية | 中文 | Español | Русский | Türkçe
3X-UI, Xray-core sunucularını yönetmek için geliştirilmiş profesyonel, açık kaynaklı bir web kontrol panelidir. Tek bir sanal sunucudan (VPS) çok düğümlü (multi-node) dağıtımlara kadar çok çeşitli proxy ve VPN protokollerini kurmak, yapılandırmak ve izlemek için temiz, çok dilli bir arayüz sağlar.
Orijinal X-UI projesinin geliştirilmiş bir çatallaması (fork) olarak inşa edilen 3X-UI; çok daha geniş protokol desteği, artırılmış kararlılık, kullanıcı başına trafik hesaplama ve kullanım kolaylığı sağlayan birçok yeni özellik sunar.
Important
Bu proje yalnızca kişisel kullanım için tasarlanmıştır. Lütfen yasadışı amaçlar için veya üretim (production) ortamında kullanmayın.
Özellikler
- Çoklu protokol destekli gelen bağlantılar (Inbounds) — VLESS, VMess, Trojan, Shadowsocks, WireGuard, AmneziaWG, Hysteria2, MTProto, HTTP, SOCKS (Karma), Dokodemo-door / Tunnel ve TUN.
- Modern aktarımlar (transports) ve güvenlik — TCP (Raw), mKCP, WebSocket, gRPC, HTTPUpgrade ve XHTTP; TLS, XTLS ve REALITY ile güvene alınmıştır.
- Dahili AmneziaWG — DPI'ya dayanıklı WireGuard, panelin içinde bir kullanıcı alanı ağ yığını üzerinde çalışır; çekirdek modülü, DKMS veya ek paket kurulumu gerektirmez.
- MTProto proxy'leri — İstemci başına FakeTLS gizli anahtarları, reklam etiketleri (ad-tag) ve kotalar, mevcut bağlantılar kopmadan anlık olarak uygulanır.
- Geri Dönüş (Fallbacks) — Xray'in fallback desteğini kullanarak tek bir port üzerinde birden fazla protokole (ör. 443 üzerinde hem VLESS hem Trojan) hizmet verin.
- Kullanıcı başına yönetim — Trafik kotaları, bitiş tarihleri, güvenilir adreslere muafiyet tanınabilen IP sınırları, HWID cihaz sınırları, zamanlanmış yenileme döngüleri, canlı çevrimiçi (online) durumu ve tek tıkla paylaşım bağlantıları, QR kodları ve abonelikler.
- Trafik istatistikleri — Gelen bağlantı (Inbound), istemci ve giden bağlantı (Outbound) bazında istatistikler ve sıfırlama kontrolleri.
- Çoklu düğüm (Multi-node) desteği — Tek bir panel üzerinden birden fazla sunucuyu yönetin ve ölçeklendirin; gelen bağlantıları diğer düğümlere klonlayın.
- Giden bağlantı (Outbound) ve yönlendirme — WARP, NordVPN, PIA, özel yönlendirme kuralları, dengeleyiciler arası yük devretme destekli yük dengeleyiciler (load balancers) ve giden bağlantı proxy zincirleme (proxy chaining). Pakete dahil geosite ve geoip kategorileri doğrudan kural düzenleyicisinden taranabilir.
- Dahili abonelik sunucusu — İstemcinin User-Agent bilgisine göre otomatik seçilen raw, JSON ve Clash çıktısı ve özel sayfa şablonları.
- Uzaktan izleme ve yönetim için Telegram botu.
- Kapsamı sınırlanmış, isteğe bağlı olarak süresi dolan token'lar ve panel içi API referansı sunan RESTful API.
- Kurulabilir panel (PWA) — 3X-UI'yi masaüstüne veya telefon ana ekranına sabitleyin.
- Esnek depolama — SQLite (varsayılan) veya PostgreSQL.
- Koyu ve açık tema seçenekleriyle 13 farklı UI dili.
- Kullanıcı başına IP limitlerini zorunlu kılmak için Fail2ban entegrasyonu.
Ekran Görüntüleri
Genişletmek için tıklayın
Hızlı Başlangıç
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
Belirli bir sürümü kurmak için, etiketini (ör. v3.7.0) ekleyin:
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.7.0
Sürekli güncellenen dev sürümünü (kararlı bir sürüm değil; main dalından her commit'te oluşturulan en son ön sürüm) kurmak için dev-latest değerini geçirin:
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest
Kurulum sırasında rastgele bir kullanıcı adı, şifre ve erişim yolu oluşturulur. Kurulumdan sonra, hizmeti başlatabileceğiniz/durdurabileceğiniz, giriş bilgilerinizi görüntüleyebileceğiniz veya sıfırlayabileceğiniz, SSL sertifikalarını yönetebileceğiniz ve çok daha fazlasını yapabileceğiniz yönetim menüsünü açmak için terminalde x-ui komutunu çalıştırın.
Her yayın dosyası, yanında bir .sha256 sağlama toplamıyla birlikte yayımlanır. Hem install.sh hem de güncelleyici, arşivi bu toplama karşı doğrular ve uyuşmazlık halinde işlemi durdurur.
Tam dokümantasyon — kurulum, yapılandırma, işletim ve eksiksiz API referansı — için docs.sanaei.dev adresini ziyaret edin.
Etkileşimsiz kurulum
Yükleyici, cloud-init için etkileşimsiz olarak da çalışır.
XUI_NONINTERACTIVE=1 ayarlayın (veya TTY olmadan boru hattına aktarın); kurulum baştan
sona hiçbir soru sormadan tamamlanır, rastgele kimlik bilgileri oluşturup bunları
/etc/x-ui/install-result.env dosyasına yazar. Şunlar için deploy/ klasörüne bakın:
- Cloud-init user-data — herhangi bir bulutta etkileşimsiz kurulum (Hetzner/AWS/DO/Vultr/GCP/Azure/Oracle)
- Hetzner Cloud notları — Hetzner üzerinde cloud-init tabanlı dağıtım
Desteklenen Platformlar
İşletim sistemleri: Ubuntu, Debian, Armbian, Fedora, CentOS, RHEL, AlmaLinux, Rocky Linux, Oracle Linux, Amazon Linux, Virtuozzo, Arch, Manjaro, Parch, openSUSE (Tumbleweed / Leap), Alpine ve Windows.
Mimariler: amd64 · 386 · arm64 (aarch64) · armv7 · armv6 · armv5 · s390x.
Veritabanı Seçenekleri
3X-UI kurulum sırasında seçilebilecek iki arka uç (backend) destekler:
- SQLite (varsayılan) —
/etc/x-ui/x-ui.dbkonumunda tek bir dosya. Kurulum gerektirmez, küçük ve orta ölçekli dağıtımlar için idealdir. - PostgreSQL — Yüksek kullanıcı sayıları veya çoklu düğüm (multi-node) kurulumları için önerilir. Yükleyici sizin için yerel olarak PostgreSQL kurabilir veya mevcut bir sunucuya DSN bağlantısı kabul edebilir.
Çalışma anında veritabanı türü ortam değişkenleri (environment variables) ile seçilir (yükleyici bunları sizin için /etc/default/x-ui dosyasına yazar):
XUI_DB_TYPE=postgres
XUI_DB_DSN=postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable
Mevcut bir SQLite Kurulumunu PostgreSQL'e Taşıma
x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable"
# ardından /etc/default/x-ui içindeki XUI_DB_TYPE ve XUI_DB_DSN değerlerini ayarlayıp yeniden başlatın:
systemctl restart x-ui
Kaynak SQLite dosyasına dokunulmaz; yeni veritabanının düzgün çalıştığını doğruladıktan sonra eski SQLite dosyasını manuel olarak silebilirsiniz.
Docker
Varsayılan docker compose up -d komutu SQLite kullanmaya devam eder. Birlikte paketlenmiş PostgreSQL servisi ile çalıştırmak için, docker-compose.yml dosyasındaki iki XUI_DB_* değişken satırının yorumunu kaldırın ve profille başlatın:
docker compose --profile postgres up -d
Docker imajı, kullanıcı başına IP limitlerini zorunlu kılmak için Fail2ban ile (varsayılan olarak etkindir) paketlenmiştir. Fail2ban, ihlalcileri iptables ile engeller ve bunun için NET_ADMIN yetkisine ihtiyaç duyar. docker-compose.yml bunu zaten cap_add üzerinden vermektedir; ancak konteyneri bunun yerine docker run ile başlatırsanız bu yetkileri kendiniz eklemelisiniz, aksi takdirde yasaklamalar günlüğe kaydedilir ancak uygulanmaz:
docker run -d --cap-add=NET_ADMIN --cap-add=NET_RAW ... ghcr.io/mhsanaei/3x-ui
Ortam Değişkenleri (Environment Variables)
| Değişken | Açıklama | Varsayılan |
|---|---|---|
XUI_DB_TYPE |
Veritabanı türü: sqlite veya postgres |
sqlite |
XUI_DB_DSN |
PostgreSQL bağlantı dizesi (eğer XUI_DB_TYPE=postgres ise) |
— |
XUI_DB_FOLDER |
SQLite veritabanı dizini | /etc/x-ui |
XUI_DB_MAX_OPEN_CONNS |
Maksimum açık bağlantı sayısı (PostgreSQL havuzu) | — |
XUI_DB_MAX_IDLE_CONNS |
Maksimum boşta bekleme bağlantısı (PostgreSQL havuzu) | — |
XUI_INIT_WEB_BASE_PATH |
Web paneli için başlangıç URI yolu | / |
XUI_ENABLE_FAIL2BAN |
Fail2ban tabanlı IP limit uygulamasını etkinleştir | true |
XUI_LOG_LEVEL |
Günlük (Log) ayrıntı seviyesi (debug, info, warning, error) |
info |
XUI_DEBUG |
Hata ayıklama (debug) modunu etkinleştir | false |
XUI_TUNNEL_HEALTH_MONITOR |
Tünel sağlık izleyicisini etkinleştir (bir URL'yi yoklar ve tekrarlanan başarısızlıklardan sonra xray'i yeniden başlatır; yeniden başlatma tüm istemcilerin bağlantısını düşürür) | false |
XUI_TUNNEL_HEALTH_PROXY |
Yoklamanın gönderildiği proxy; yoklamanın tüneli test etmesi için bunu yerel bir xray gelen bağlantısına yönlendirin (ör. socks5://127.0.0.1:1080). Boş bırakılırsa yoklama yalnızca ana makine bağlantısını kontrol eder |
— |
XUI_TUNNEL_HEALTH_URL |
Tünel sağlığı için yoklanan URL | https://www.cloudflare.com/cdn-cgi/trace |
XUI_TUNNEL_HEALTH_INTERVAL |
Yoklamalar arasındaki aralık | 30s |
XUI_TUNNEL_HEALTH_TIMEOUT |
Yoklama başına zaman aşımı | 10s |
XUI_TUNNEL_HEALTH_FAILURES |
Yeniden başlatma tetiklenmeden önceki ardışık başarısızlık sayısı | 3 |
XUI_TUNNEL_HEALTH_COOLDOWN |
Ardışık yeniden başlatmalar arasındaki minimum gecikme | 5m |
NODE_TOKEN_ENCRYPTION |
Düğüm API token'ları için beklemede şifreleme: off, migration veya required (XUI_ öneki yoktur) |
off |
XUI_NODE_TOKEN_KEY_FILE |
Etkin anahtar kimliğini ve base64 kodlu 32 baytlık anahtarlarını içeren JSON anahtarlığı (mod 0600) |
/etc/x-ui/node_token_key.json |
XUI_NODE_TOKEN_KEY |
Tek bir base64 kodlu 32 baytlık anahtar; yalnızca anahtar dosyası yüklenemediğinde kullanılır | — |
Tam liste ortam değişkenleri referansında yer alır.
Desteklenen Diller
Panel arayüzü 13 farklı dilde mevcuttur:
İngilizce · Farsça · Arapça · Çince (Basitleştirilmiş) · Çince (Geleneksel) · İspanyolca · Rusça · Ukraynaca · Türkçe · Vietnamca · Japonca · Endonezce · Portekizce (Brezilya)
Katkıda Bulunma
Katkılarınızı her zaman bekliyoruz. Bir sorun (issue) açmadan veya pull request (PR) göndermeden önce lütfen Katkıda Bulunma Kılavuzunu okuyun.
Özel Teşekkürler
Teşekkür & Atıf
- Iran v2ray rules (Lisans: GPL-3.0): Geliştirilmiş v2ray/xray ve v2ray/xray-clients yönlendirme (routing) kuralları; yerleşik İran alan adları ile güvenlik ve reklam engelleme odaklıdır.
- Russia v2ray rules (Lisans: GPL-3.0): Bu depo, Rusya'daki engellenen alan adları ve adreslere dayalı otomatik olarak güncellenen V2Ray yönlendirme kurallarını içerir.
Topluluk Araçları
3x-ui çevresindeki topluluk tarafından oluşturulmuş araçlar ve entegrasyonlar.
- terraform-provider-3x-ui (Lisans: MIT): Gelen bağlantılarnı, kullanıcıları, panel ayarlarını ve Xray yapılandırmasını Terraform / OpenTofu ile kod olarak (as code) yönetin.
Projeyi Destekleyin
Eğer bu proje size faydalı olduysa, bir yıldız verebilirsiniz🌟
Yıldız Tablosu
