mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-09-16 15:17:14 +00: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.
This commit is contained in:
Sanaei
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Environment Variables
|
||||
description: Complete reference for 3x-ui's XUI_* environment variables — database, panel, logging, memory, and the tunnel health monitor.
|
||||
description: Complete reference for 3x-ui's XUI_* environment variables — database, panel, logging, memory, node token encryption, and the tunnel health monitor.
|
||||
icon: Variable
|
||||
---
|
||||
|
||||
@@ -33,6 +33,36 @@ The default SQLite database path is `/etc/x-ui/x-ui.db`. See
|
||||
| `XUI_ENABLE_FAIL2BAN` | `true` | Enable Fail2ban-based IP-limit enforcement. |
|
||||
| `XUI_SKIP_HSTS` | `false` | Skip the HSTS header — set `true` when TLS is terminated by a reverse proxy. |
|
||||
|
||||
## Node token encryption
|
||||
|
||||
Node API bearer tokens — and the stored PIA token — are kept in plaintext by
|
||||
default. Encryption at rest is opt-in and fails closed: with any mode other than
|
||||
`off`, the panel refuses to start unless it can load a key.
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `NODE_TOKEN_ENCRYPTION` | `off` | `off`, `migration` (reads accept plaintext or ciphertext, writes encrypt), or `required` (same writes, startup fails without a key). Note the missing `XUI_` prefix. |
|
||||
| `XUI_NODE_TOKEN_KEY_FILE` | `/etc/x-ui/node_token_key.json` | JSON keyring, mode `0600` or stricter. Loaded first. |
|
||||
| `XUI_NODE_TOKEN_KEY` | — | A single base64 32-byte key, read only when the key file fails to load. Its key id is fixed to `env`, so it cannot rotate. |
|
||||
|
||||
The key file names the active key plus every older key still needed to decrypt:
|
||||
|
||||
```json
|
||||
{ "active": "k1", "keys": { "k1": "<base64 32-byte key>" } }
|
||||
```
|
||||
|
||||
Generate a key with `openssl rand -base64 32`; keys are never accepted as
|
||||
command-line arguments. After enabling a mode, re-encrypt the rows already in
|
||||
the database under the active key:
|
||||
|
||||
```bash
|
||||
x-ui encrypt-tokens
|
||||
```
|
||||
|
||||
That covers node rows; the PIA token is re-encrypted the next time it is read.
|
||||
To rotate, add the new key to `keys`, point `active` at it, keep the old key for
|
||||
decryption, and run `x-ui encrypt-tokens` again.
|
||||
|
||||
## Logging & binaries
|
||||
|
||||
| Variable | Default | Description |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: متغیرهای محیطی
|
||||
description: مرجع کامل متغیرهای محیطی `XUI_*` در 3x-ui — پایگاهداده، پنل، لاگگیری، حافظه و پایشگر سلامت تونل.
|
||||
description: مرجع کامل متغیرهای محیطی `XUI_*` در 3x-ui — پایگاهداده، پنل، لاگگیری، حافظه، رمزگذاری توکن نود و پایشگر سلامت تونل.
|
||||
icon: Variable
|
||||
---
|
||||
|
||||
@@ -33,6 +33,36 @@ icon: Variable
|
||||
| `XUI_ENABLE_FAIL2BAN` | `true` | فعالسازی اعمالِ محدودیت IP مبتنی بر Fail2ban. |
|
||||
| `XUI_SKIP_HSTS` | `false` | رد کردن هدر HSTS — وقتی TLS توسط یک پروکسی معکوس خاتمه مییابد، `true` تنظیم کنید. |
|
||||
|
||||
## رمزگذاری توکن نود
|
||||
|
||||
توکنهای حامل (bearer) API نود — و توکن ذخیرهشدهی PIA — بهصورت پیشفرض به شکل
|
||||
متن ساده نگهداری میشوند. رمزگذاری در حالت سکون اختیاری است و بهصورت ایمن شکست
|
||||
میخورد: با هر حالتی بهجز `off`، اگر پنل نتواند کلیدی را بارگذاری کند، اجرا نمیشود.
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `NODE_TOKEN_ENCRYPTION` | `off` | `off`، `migration` (خواندن هم متن ساده و هم متن رمزشده را میپذیرد، نوشتن همیشه رمز میکند) یا `required` (نوشتن یکسان، اما بدون کلید اجرا شکست میخورد). به نبودِ پیشوند `XUI_` توجه کنید. |
|
||||
| `XUI_NODE_TOKEN_KEY_FILE` | `/etc/x-ui/node_token_key.json` | حلقهکلید JSON با دسترسی `0600` یا محدودتر. نخست همین بارگذاری میشود. |
|
||||
| `XUI_NODE_TOKEN_KEY` | — | یک کلید ۳۲ بایتی base64 که فقط هنگام شکست بارگذاری فایل کلید خوانده میشود. شناسهی کلید آن ثابت و برابر `env` است، پس امکان چرخش ندارد. |
|
||||
|
||||
فایل کلید، کلید فعال بههمراه هر کلید قدیمیای را که هنوز برای رمزگشایی لازم است نام میبرد:
|
||||
|
||||
```json
|
||||
{ "active": "k1", "keys": { "k1": "<base64 32-byte key>" } }
|
||||
```
|
||||
|
||||
کلید را با `openssl rand -base64 32` بسازید؛ کلیدها هرگز بهعنوان آرگومان خط فرمان
|
||||
پذیرفته نمیشوند. پس از فعالکردن یک حالت، ردیفهایی را که از پیش در پایگاهداده
|
||||
هستند با کلید فعال دوباره رمز کنید:
|
||||
|
||||
```bash
|
||||
x-ui encrypt-tokens
|
||||
```
|
||||
|
||||
این دستور ردیفهای نود را پوشش میدهد؛ توکن PIA در نوبت بعدیِ خواندن دوباره رمز
|
||||
میشود. برای چرخش کلید، کلید جدید را به `keys` اضافه کنید، `active` را به آن اشاره
|
||||
دهید، کلید قدیمی را برای رمزگشایی نگه دارید و دوباره `x-ui encrypt-tokens` را اجرا کنید.
|
||||
|
||||
## لاگگیری و باینریها
|
||||
|
||||
| Variable | Default | Description |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Переменные окружения
|
||||
description: Полный справочник по переменным окружения XUI_* в 3x-ui — база данных, панель, логирование, память и монитор работоспособности туннеля.
|
||||
description: Полный справочник по переменным окружения XUI_* в 3x-ui — база данных, панель, логирование, память, шифрование токенов узлов и монитор работоспособности туннеля.
|
||||
icon: Variable
|
||||
---
|
||||
|
||||
@@ -34,6 +34,36 @@ icon: Variable
|
||||
| `XUI_ENABLE_FAIL2BAN` | `true` | Включить ограничение по IP на основе Fail2ban. |
|
||||
| `XUI_SKIP_HSTS` | `false` | Не отправлять заголовок HSTS — установите `true`, когда TLS терминируется обратным прокси. |
|
||||
|
||||
## Шифрование токенов узлов
|
||||
|
||||
API-токены узлов — и сохранённый токен PIA — по умолчанию хранятся в открытом
|
||||
виде. Шифрование при хранении включается явно и отказывает безопасно: при любом
|
||||
режиме, кроме `off`, панель не запустится, если не сможет загрузить ключ.
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `NODE_TOKEN_ENCRYPTION` | `off` | `off`, `migration` (чтение принимает открытый текст или шифротекст, запись всегда шифрует) или `required` (запись та же, но без ключа запуск не удастся). Префикса `XUI_` здесь нет. |
|
||||
| `XUI_NODE_TOKEN_KEY_FILE` | `/etc/x-ui/node_token_key.json` | JSON-связка ключей с правами `0600` или строже. Загружается первой. |
|
||||
| `XUI_NODE_TOKEN_KEY` | — | Один 32-байтный ключ в base64, читается только при неудачной загрузке файла ключей. Его идентификатор фиксирован (`env`), поэтому ротация невозможна. |
|
||||
|
||||
Файл ключей задаёт активный ключ и все прежние ключи, ещё нужные для расшифровки:
|
||||
|
||||
```json
|
||||
{ "active": "k1", "keys": { "k1": "<base64 32-byte key>" } }
|
||||
```
|
||||
|
||||
Сгенерируйте ключ командой `openssl rand -base64 32`; ключи никогда не
|
||||
принимаются в аргументах командной строки. После включения режима перешифруйте
|
||||
строки, уже находящиеся в базе, активным ключом:
|
||||
|
||||
```bash
|
||||
x-ui encrypt-tokens
|
||||
```
|
||||
|
||||
Команда обрабатывает строки узлов; токен PIA перешифровывается при следующем
|
||||
чтении. Для ротации добавьте новый ключ в `keys`, укажите его в `active`,
|
||||
сохраните старый ключ для расшифровки и снова выполните `x-ui encrypt-tokens`.
|
||||
|
||||
## Логирование и бинарные файлы
|
||||
|
||||
| Variable | Default | Description |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: 环境变量
|
||||
description: 3x-ui 的 XUI_* 环境变量完整参考——涵盖数据库、面板、日志、内存以及隧道健康监测器。
|
||||
description: 3x-ui 的 XUI_* 环境变量完整参考——涵盖数据库、面板、日志、内存、节点令牌加密以及隧道健康监测器。
|
||||
icon: Variable
|
||||
---
|
||||
|
||||
@@ -32,6 +32,33 @@ icon: Variable
|
||||
| `XUI_ENABLE_FAIL2BAN` | `true` | 启用基于 Fail2ban 的 IP 限制强制执行。 |
|
||||
| `XUI_SKIP_HSTS` | `false` | 跳过 HSTS 标头——当 TLS 由反向代理终结时设为 `true`。 |
|
||||
|
||||
## 节点令牌加密
|
||||
|
||||
节点 API bearer 令牌以及已保存的 PIA 令牌默认以明文存储。静态加密需显式开启，
|
||||
且采取失败即拒绝的策略：只要模式不是 `off`，面板在无法加载密钥时就拒绝启动。
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `NODE_TOKEN_ENCRYPTION` | `off` | `off`、`migration`（读取时接受明文或密文，写入一律加密）或 `required`（写入相同，但缺少密钥时启动失败）。注意此处没有 `XUI_` 前缀。 |
|
||||
| `XUI_NODE_TOKEN_KEY_FILE` | `/etc/x-ui/node_token_key.json` | JSON 密钥环，权限须为 `0600` 或更严格。优先加载。 |
|
||||
| `XUI_NODE_TOKEN_KEY` | — | 单个 base64 编码的 32 字节密钥，仅在密钥文件加载失败时读取。其密钥 ID 固定为 `env`，因此无法轮换。 |
|
||||
|
||||
密钥文件同时记录活动密钥和所有仍需用于解密的旧密钥：
|
||||
|
||||
```json
|
||||
{ "active": "k1", "keys": { "k1": "<base64 32-byte key>" } }
|
||||
```
|
||||
|
||||
使用 `openssl rand -base64 32` 生成密钥；密钥绝不接受通过命令行参数传入。启用某个
|
||||
模式后，用活动密钥重新加密数据库中已有的记录：
|
||||
|
||||
```bash
|
||||
x-ui encrypt-tokens
|
||||
```
|
||||
|
||||
该命令处理节点记录；PIA 令牌会在下次读取时重新加密。轮换密钥时，将新密钥加入
|
||||
`keys`，把 `active` 指向它，保留旧密钥用于解密，然后再次运行 `x-ui encrypt-tokens`。
|
||||
|
||||
## 日志与二进制文件
|
||||
|
||||
| Variable | Default | Description |
|
||||
|
||||
Reference in New Issue
Block a user