环境变量

文件 .env 由面板容器读取。必填变量用必填标记。默认值 —— 即代码中设置的值。

应用

变量	默认值	说明
`APP_PORT`	`3000`	HTTP API 和 Web 界面端口
`METRICS_PORT`	`3001`	Prometheus 指标端口
`API_INSTANCES`	`1`	API worker 数量。`max` —— 按核心数，`-1` —— 核心数减一。不要超过物理核心数
`IS_HTTP_LOGGING_ENABLED`	`false`	记录 HTTP 请求日志。请求体永远不会被写入
`ENABLE_DEBUG_LOGS`	`false`	应用的详细日志
`REMNAWAVE_BRANCH`	`dev`	应用在服务端点中报告的分支

数据库和缓存

变量	默认值	说明
`DATABASE_URL` 必填	—	连接字符串，例如 `postgresql://xpanel:pass@xpanel-db:5432/xpanel?schema=public`
`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`	—	仅由 PostgreSQL 容器使用，应用本身不读取它们
`REDIS_SOCKET`	—	Valkey/Redis 的 unix socket 路径（替代主机和端口）
`REDIS_HOST` / `REDIS_PORT`	— / `6379`	Valkey/Redis 地址
`REDIS_USERNAME` / `REDIS_PASSWORD`	—	如果启用了认证
`REDIS_DB`	`0`	数据库编号

密钥和域名

变量	默认值	说明
`APP_SECRET` 必填	—	64 个字符。密码哈希、JWT、TOTP 加密。启动后不可更改
`JWT_AUTH_LIFETIME` 必填	—	access 令牌有效期（小时），允许 12 到 168
`PANEL_DOMAIN` 必填	—	面板的公开地址，带 `https://`
`FRONT_END_DOMAIN`	`*`	允许发起 CORS 请求的来源
`SUB_PUBLIC_DOMAIN` 必填	—	订阅域名，不带 `https://`，结尾也不带斜杠；会写入 `profile-web-page-url`

指标

变量	说明
`METRICS_USER` 必填	`http://127.0.0.1:3001/metrics` 的 basic auth 用户名
`METRICS_PASS` 必填	basic auth 密码

注意

没有 METRICS_USER 和 METRICS_PASS，容器不会启动。

变量	默认值	说明
`IS_TELEGRAM_NOTIFICATIONS_ENABLED`	`false`	启用 Telegram 通知
`TELEGRAM_BOT_TOKEN`	—	机器人令牌
`TELEGRAM_BOT_API_ROOT`	`https://api.telegram.org`	Bot API 地址；如果使用本地 Bot API server 请修改
`TELEGRAM_BOT_PROXY`	—	访问 Telegram 的代理，例如 `socks5://proxy:1080`
`TELEGRAM_NOTIFY_USERS`	—	用户事件的通知会话
`TELEGRAM_NOTIFY_NODES`	—	节点事件的通知会话
`TELEGRAM_NOTIFY_CRM`	—	CRM 事件的通知会话
`TELEGRAM_NOTIFY_SERVICE`	—	服务通知
`TELEGRAM_NOTIFY_TBLOCKER`	—	torrent-blocker 事件

会话格式：chat_id，话题则为 chat_id:thread_id。多个值用逗号分隔。

Webhook

变量	默认值	说明
`WEBHOOK_ENABLED`	`false`	启用 webhook 发送
`WEBHOOK_URL`	—	接收地址；多个地址用逗号分隔。只允许 `http://` 和 `https://`
`WEBHOOK_SECRET_HEADER`	—	payload 签名密钥，正好 64 个 `[a-zA-Z0-9]` 字符

详见 Webhook 章节。

阈值通知

变量	默认值	说明
`BANDWIDTH_USAGE_NOTIFICATIONS_ENABLED`	`false`	在达到流量阈值时通知
`BANDWIDTH_USAGE_NOTIFICATIONS_THRESHOLD`	`[60, 80]`	百分比阈值，递增，25 到 95，最多 5 个值
`NOT_CONNECTED_USERS_NOTIFICATIONS_ENABLED`	`false`	对始终未连接的用户发出通知
`NOT_CONNECTED_USERS_NOTIFICATIONS_AFTER_HOURS`	`[6, 24, 48]`	用户创建后的小时数，1 到 168，最多 3 个值
`EXPIRATION_NOTIFICATIONS_ENABLED`	`false`	订阅到期通知
`EXPIRATION_NOTIFICATIONS`	`[-72, -48, -24, 24]`	相对于 `expireAt` 的小时数：负数表示到期前，正数表示到期后。范围 −168 到 168，不允许为 0

隐私与数据保留

自动清理默认关闭。一个每周 job 负责所有表：只要 SERVICE_CLEAN_USAGE_HISTORY 或 SERVICE_CLEAN_OLD_LOGS 中有一个开启，它就会运行。

变量	默认值	说明
`SERVICE_CLEAN_USAGE_HISTORY`	`false`	启用流量历史清理
`USAGE_HISTORY_RETENTION_DAYS`	`14`	`nodes_user_usage_history` 保留多少天
`SERVICE_CLEAN_OLD_LOGS`	`false`	启用个人数据和节点统计的清理
`NODES_USAGE_HISTORY_RETENTION_DAYS`	`90`	节点每小时统计
`HWID_DEVICES_RETENTION_DAYS`	`90`	用户设备（`hwid_user_devices`）；从设备最后一次出现开始计算
`SUBSCRIPTION_REQUEST_HISTORY_RETENTION_DAYS`	`30`	订阅请求历史
`AUDIT_LOG_RETENTION_DAYS`	`30`	管理员操作日志
`SERVICE_DISABLE_USER_USAGE_RECORDS`	`false`	完全不记录流量历史
`SERVICE_DISABLE_SRH_RECORDS`	`false`	完全不记录订阅请求历史
`USER_USAGE_IGNORE_BELOW_BYTES`	`0`	不记录小于指定字节数的流量突发

数据最小化

如果你不需要流量历史和订阅请求，与其事后清理，不如根本不采集： SERVICE_DISABLE_USER_USAGE_RECORDS=true 和 SERVICE_DISABLE_SRH_RECORDS=true。

订阅短标识符

变量	默认值	说明
`SHORT_UUID_METHOD`	`nanoid`	`nanoid` —— 随机字符串，`uuid` —— UUID v4，`custom` —— 自定义模板
`SHORT_UUID_LENGTH`	`16`	`nanoid` 方法的长度，16 到 64
`SHORT_UUID_CUSTOM_PATTERN`	—	`custom` 方法的模板。可用标记：`{nanoid:N}`, `{alpha:N}`, `{digits:N}`, `{hex:N}`, `{uuid}`

示例：SHORT_UUID_CUSTOM_PATTERN={hex:16}-{hex:16}-{digits:10}。模板必须生成 16 到 64 个字符，并且随机性不低于约 64 位。

导出到 Redis Streams

变量	默认值	说明
`EXPORT_TO_STREAM_ENABLED`	`false`	将面板事件发布到 Redis Streams
`EXPORT_TO_STREAM_MAXLEN`	`3000`	流中消息的近似上限（`MAXLEN ~`）

流：ioraw:export:user_usage（流量增量）、ioraw:export:subscription_requests （订阅请求）、ioraw:export:node_connections（连接快照，保留 1 小时）。适合导出到 ClickHouse 或 Vector。

应用​

数据库和缓存​

密钥和域名​

指标​

Telegram​

Webhook​

阈值通知​

隐私与数据保留​

订阅短标识符​

导出到 Redis Streams​

应用