mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-10-16 10:55:00 +03:00
MHSanaei
3fc3992a46
FileKeySource rejected any key file whose mode had group or other bits, but Windows has no such bits: Stat reports every writable file as 0666. On the Windows builds release.yml ships, the key file therefore never loaded, not even one written 0600, and only XUI_NODE_TOKEN_KEY could supply a key. The mode check now applies off Windows only, the stance the DB permission tests already take; there the file's NTFS ACL guards it, and env-vars.mdx says so in all four locales. The load test is split so the half that must hold everywhere, an owner-only file loading, also runs on Windows, and the rejection half asserts the exact error instead of any error.
110 lines
8.4 KiB
Plaintext
110 lines
8.4 KiB
Plaintext
---
|
|
title: 环境变量
|
|
description: 3x-ui 的 XUI_* 环境变量完整参考——涵盖数据库、面板、日志、内存、节点令牌加密以及隧道健康监测器。
|
|
icon: Variable
|
|
---
|
|
|
|
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 的
|
|
细节，参见 [数据库](/docs/reference/database)。
|
|
|
|
## 面板
|
|
|
|
| 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` 或更严格（Windows 上不检查，由 NTFS 权限保护）。优先加载。 |
|
|
| `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 |
|
|
| ---------------- | ---------------- | ----------------------------------------------------------- |
|
|
| `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`。参见 [安装](/docs/guide/installation#unattended--cloud-init)。 |
|