3x-ui环境变量
3x-ui 的 XUI_* 环境变量完整参考——涵盖数据库、面板、日志、内存、节点令牌加密以及隧道健康监测器。
3x-ui 从 XUI_* 环境变量中读取其运行时配置。使用脚本安装时，安装程序会将
这些变量写入服务环境文件（/etc/default/x-ui，或视发行版而定的
/etc/conf.d/x-ui / /etc/sysconfig/x-ui）；使用 Docker 时，则在
docker-compose.yml 或 docker run -e 中设置。默认值已足够合理——只需设置
你需要更改的项，然后重启即可：systemctl restart x-ui。
数据库
| Variable | Default | Description |
|---|---|---|
XUI_DB_TYPE | sqlite | 后端：sqlite，或 postgres（也接受 postgresql / pg）。 |
XUI_DB_FOLDER | /etc/x-ui | SQLite 数据库文件（x-ui.db）所在的文件夹。 |
XUI_DB_DSN | — | PostgreSQL 连接字符串（当 XUI_DB_TYPE=postgres 时使用）。 |
XUI_DB_MAX_OPEN_CONNS | — | PostgreSQL 连接池中的最大打开连接数。 |
XUI_DB_MAX_IDLE_CONNS | — | PostgreSQL 连接池中的最大空闲连接数。 |
默认的 SQLite 数据库路径为 /etc/x-ui/x-ui.db。有关 SQLite ↔ PostgreSQL 的
细节，参见 数据库。
面板
| Variable | Default | Description |
|---|---|---|
XUI_PORT | — | 覆盖面板端口（1–65535）。优先级高于已存储的设置。 |
XUI_INIT_WEB_BASE_PATH | / | 首次启动时的初始 Web 根路径（例如 /panel）。 |
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，因此无法轮换。 |
密钥文件同时记录活动密钥和所有仍需用于解密的旧密钥：
{ "active": "k1", "keys": { "k1": "<base64 32-byte key>" } }使用 openssl rand -base64 32 生成密钥；密钥绝不接受通过命令行参数传入。启用某个
模式后，用活动密钥重新加密数据库中已有的记录：
x-ui encrypt-tokens该命令处理节点记录；PIA 令牌会在下次读取时重新加密。轮换密钥时，将新密钥加入
keys，把 active 指向它，保留旧密钥用于解密，然后再次运行 x-ui encrypt-tokens。
日志与二进制文件
| Variable | Default | Description |
|---|---|---|
XUI_LOG_LEVEL | info | debug、info、notice、warning 或 error。 |
XUI_DEBUG | false | 调试模式（强制将日志级别设为 debug）。 |
XUI_LOG_FOLDER | /var/log/x-ui | 日志输出目录。 |
XUI_BIN_FOLDER | bin | 存放 Xray-core 二进制文件及 geosite/geoip 文件的文件夹。 |
内存与性能分析
面板通过 GOGC 和定期释放来保持低内存占用。这些是高级调节项——除非你正在
为受限主机做调优，否则请保持不设置。
| Variable | Default | Description |
|---|---|---|
XUI_GOGC | — | Go GC 目标百分比；值越低 = 占用 RAM 越少，CPU 略增。 |
XUI_MEMORY_RELEASE_INTERVAL | — | 两次 FreeOSMemory 调用之间的分钟数；0 表示禁用。 |
XUI_MEMORY_LIMIT | — | Go 软内存限制，单位 MiB。 |
GOMEMLIMIT | — | Go 语法的软限制（例如 400MiB）；优先级高于上一项。 |
XUI_PPROF | false | 在 127.0.0.1:6060 上暴露 pprof 性能分析。 |
Xray
| Variable | Default | Description |
|---|---|---|
XRAY_VMESS_AEAD_FORCED | false | 强制启用 VMess AEAD。 |
隧道健康监测器
可选的看门狗：它探测一个 URL（可选择经由本地 Xray 入站进行），并在反复 失败后重启 Xray。重启会断开所有已连接的客户端，因此请审慎启用。
| Variable | Default | Description |
|---|---|---|
XUI_TUNNEL_HEALTH_MONITOR | false | 启用监测器。 |
XUI_TUNNEL_HEALTH_PROXY | — | 用于发送探测的代理，例如 socks5://127.0.0.1:1080。留空 = 仅检查主机连通性。 |
XUI_TUNNEL_HEALTH_URL | https://www.cloudflare.com/cdn-cgi/trace | 要探测的 URL。 |
XUI_TUNNEL_HEALTH_INTERVAL | 30s | 探测之间的间隔。 |
XUI_TUNNEL_HEALTH_TIMEOUT | 10s | 单次探测的超时时间。 |
XUI_TUNNEL_HEALTH_FAILURES | 3 | 触发重启前的连续失败次数。 |
XUI_TUNNEL_HEALTH_COOLDOWN | 5m | 两次重启之间的最小延迟。 |
无人值守安装
| Variable | Description |
|---|---|
XUI_NONINTERACTIVE | 设为 1（或在无 TTY 的环境下运行）即可在零提示的情况下完成安装；生成的凭据会写入 /etc/x-ui/install-result.env。参见 安装。 |