配置 | PasarGuard Documentation

配置概述

PasarGuard 面板通过存储在 /opt/pasarguard/.env 的 .env 文件中的环境变量进行配置。

环境变量

管理员配置

变量	类型	默认值	描述
`SUDO_USERNAME`	string	-	初始管理员账户的超级用户用户名
`SUDO_PASSWORD`	string	-	初始管理员账户的超级用户密码

SUDO_USERNAME 和 SUDO_PASSWORD 仅在启用 DEBUG 模式时有效。生产环境请使用 pasarguard cli generate-temp-key，通过仪表板设置表单创建所有者账号。

数据库配置

变量	类型	默认值	描述
`SQLALCHEMY_DATABASE_URL`	string	-	数据库连接字符串（SQLite、MySQL、MariaDB、PostgreSQL、TimescaleDB）

数据库 URL 示例：

# TimescaleDB/PostgreSQL（默认）
SQLALCHEMY_DATABASE_URL = "postgresql+asyncpg://user:password@localhost/pasarguard"

# MySQL/MariaDB
SQLALCHEMY_DATABASE_URL = "mysql+asyncmy://user:password@localhost/pasarguard"

# SQLite
SQLALCHEMY_DATABASE_URL = "sqlite+aiosqlite:////var/lib/pasarguard/db.sqlite3"

UVICORN Web 服务器

变量	类型	默认值	描述
`UVICORN_HOST`	string	`0.0.0.0`	Web 服务器绑定的主机地址
`UVICORN_PORT`	int	`8000`	Web 服务器的端口号
`UVICORN_UDS`	string	-	Unix socket 路径；设置后 Uvicorn 会绑定 socket，而不是 host/port
`UVICORN_SSL_CERTFILE`	string	-	SSL 证书文件路径
`UVICORN_SSL_KEYFILE`	string	-	SSL 私钥文件路径
`UVICORN_SSL_CA_TYPE`	string	`public`	SSL 验证使用的证书机构类型
`UVICORN_WORKERS`	int	`1`	Uvicorn worker 进程数量
`UVICORN_LOOP`	string	`auto`	Uvicorn event loop 设置
`UVICORN_PROXY_HEADERS`	bool	`false`	信任代理头，例如 forwarded 客户端 IP
`UVICORN_FORWARDED_ALLOW_IPS`	string/list	`127.0.0.1`	允许使用 forwarded headers 的可信代理 IP；只有可信私有网络才使用 `*`

示例：

UVICORN_HOST = "0.0.0.0"
UVICORN_PORT = 8000
UVICORN_SSL_CERTFILE = "/var/lib/pasarguard/cert.pem"
UVICORN_SSL_KEYFILE = "/var/lib/pasarguard/key.pem"
UVICORN_PROXY_HEADERS = true
UVICORN_FORWARDED_ALLOW_IPS = "127.0.0.1"

只有当 PasarGuard 位于可信 reverse proxy 后面时才启用 UVICORN_PROXY_HEADERS。不要在不可信网络中使用 UVICORN_FORWARDED_ALLOW_IPS = "*"。

身份验证与安全

变量	类型	默认值	描述
`JWT_ACCESS_TOKEN_EXPIRE_MINUTES`	int	`1440`	JWT 令牌过期时间（分钟）（默认：24 小时）

示例：

# 令牌在 24 小时后过期
JWT_ACCESS_TOKEN_EXPIRE_MINUTES = 1440

# 令牌在 7 天后过期
JWT_ACCESS_TOKEN_EXPIRE_MINUTES = 10080

面板设置

变量	类型	默认值	描述
`DOCS`	bool	`false`	启用/禁用 API 文档端点
`DEBUG`	bool	`false`	启用调试模式以获取详细日志
`ROLE`	string	`all-in-one`	运行角色：`backend`、`node`、`scheduler` 或 `all-in-one`
`DASHBOARD_PATH`	string	`/dashboard/`	Dashboard 服务的 URL 路径
`VITE_BASE_API`	string	`/`	Dashboard 使用的 API 基础 URL
`ALLOWED_ORIGINS`	string	`*`	逗号分隔的 CORS origins

示例：

DOCS = true
DEBUG = false

WireGuard

变量	类型	默认值	描述
`WIREGUARD_ENABLED`	bool	`true`	启用 WireGuard peer IP 分配和 WireGuard 订阅输出
`WIREGUARD_GLOBAL_POOL`	CIDR	`10.0.0.0/8`	用于自动分配用户 WireGuard peer IP 并验证手动 peer IP 的 IPv4 池
`WIREGUARD_RESERVED`	CIDR list	`10.0.0.0/31`	逗号分隔的 IPv4 CIDR 范围，永远不会被分配

示例：

WIREGUARD_ENABLED = false
WIREGUARD_GLOBAL_POOL = "10.66.0.0/16"
WIREGUARD_RESERVED = "10.66.0.0/31,10.66.0.10/32"

当 WIREGUARD_ENABLED = false 时，WireGuard 订阅输出会被跳过，自动 peer IP 分配也会禁用。

用量记录

变量	类型	默认值	描述
`DISABLE_RECORDING_NODE_USAGE`	bool	`false`	禁用节点用量采样记录
`ENABLE_RECORDING_NODES_STATS`	bool	`false`	启用详细节点统计记录；仅 PostgreSQL/TimescaleDB 可用
`RESET_USER_USAGE_CLEAN_CHART_DATA`	bool	`false`	重置用户用量时删除用户图表历史

示例：

DISABLE_RECORDING_NODE_USAGE = false
ENABLE_RECORDING_NODES_STATS = true
RESET_USER_USAGE_CLEAN_CHART_DATA = false

完整配置示例

生产环境设置

# 数据库（推荐使用 TimescaleDB）
SQLALCHEMY_DATABASE_URL = "postgresql+asyncpg://pasarguard:password@localhost/pasarguard"

# Web 服务器
UVICORN_HOST = "0.0.0.0"
UVICORN_PORT = 8000
UVICORN_SSL_CERTFILE = "/var/lib/pasarguard/cert.pem"
UVICORN_SSL_KEYFILE = "/var/lib/pasarguard/key.pem"
UVICORN_PROXY_HEADERS = true
UVICORN_FORWARDED_ALLOW_IPS = "127.0.0.1"

# 安全
JWT_ACCESS_TOKEN_EXPIRE_MINUTES = 1440

# 面板设置
DOCS = false
DEBUG = false

# WireGuard
WIREGUARD_ENABLED = true
WIREGUARD_GLOBAL_POOL = "10.0.0.0/8"
WIREGUARD_RESERVED = "10.0.0.0/31"

开发/测试环境设置

# 管理员配置
SUDO_USERNAME = "admin"
SUDO_PASSWORD = "admin123"

# 数据库（用于测试的 SQLite）
SQLALCHEMY_DATABASE_URL = "sqlite+aiosqlite:////var/lib/pasarguard/db.sqlite3"

# Web 服务器
UVICORN_HOST = "127.0.0.1"
UVICORN_PORT = 8000

# 安全
JWT_ACCESS_TOKEN_EXPIRE_MINUTES = 1440

# 面板设置
DOCS = true
DEBUG = true

配置管理

查看当前配置

cat /opt/pasarguard/.env

编辑配置

sudo nano /opt/pasarguard/.env

应用更改

修改配置后，重启面板：

pasarguard restart

验证配置

检查服务是否正常运行：

pasarguard status

查看日志以排查问题：

pasarguard logs

多节点设置

要配置多个节点：

在每台服务器上安装和配置 PasarGuard Node（参见节点安装）
在每个节点服务器上配置节点 API 凭据
在面板界面中添加节点：
- 在仪表板中导航到节点部分
- 点击"添加节点"
- 输入节点连接详细信息（地址、端口、API 密钥等）
- 检查连接

安全最佳实践

保护数据库凭据

使用强密码进行数据库连接：

# 生成安全密码
openssl rand -base64 32

使用 SSL 证书

在生产环境中始终使用有效的 SSL 证书：

# 使用 Let's Encrypt
sudo certbot certonly --standalone -d your-domain.com

# 更新 .env
UVICORN_SSL_CERTFILE = "/etc/letsencrypt/live/your-domain.com/fullchain.pem"
UVICORN_SSL_KEYFILE = "/etc/letsencrypt/live/your-domain.com/privkey.pem"

在生产环境中禁用调试模式

DEBUG = false
DOCS = false

配置

On this page