配置 | PasarGuard Documentation

配置概述

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

环境变量

管理员配置

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

SUDO_USERNAME 和 SUDO_PASSWORD 仅在启用 DEBUG 模式时有效。对于生产环境，请使用 TUI 创建管理员用户：pasarguard tui

数据库配置

变量	类型	默认值	描述
`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_SSL_CERTFILE`	string	-	SSL 证书文件路径
`UVICORN_SSL_KEYFILE`	string	-	SSL 私钥文件路径

示例：

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"

身份验证与安全

变量	类型	默认值	描述
`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`	启用调试模式以获取详细日志

示例：

DOCS = true
DEBUG = false

完整配置示例

生产环境设置

# 管理员配置
SUDO_USERNAME = "admin"
SUDO_PASSWORD = "your-secure-password"

# 数据库（推荐使用 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"

# 安全
JWT_ACCESS_TOKEN_EXPIRE_MINUTES = 1440

# 面板设置
DOCS = false
DEBUG = false

开发/测试环境设置

# 管理员配置
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