PufferPanel 3.0.9 配置参数详解

目标：讲透 PufferPanel 3.0.9 的配置加载机制与优先级，给出全量参数速查表与逐项解读，并对改端口、关注册、品牌定制、控制台外发、关闭 unshare 沙箱、切换数据库、配置邮件等高频场景给出实测验证的操作路径。文中行为与回显均来自 Ubuntu 22.04.5 + PufferPanel 3.0.9 实测环境（实测日期 2026-10-24）。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• 面板版本：PufferPanel 3.0.9（pufferpanel version → PufferPanel 3.0.9 (94ded99f2d691762c09c6df076a2f76c475b481e)）
• 配置文件：/etc/pufferpanel/config.json（deb/rpm 包安装默认路径；systemd 单元 WorkingDirectory=/etc/pufferpanel）
• 服务管理：pufferpanel.service（Type=notify，以 pufferpanel 专用用户运行）
• 参数表来源：官方 Configuration 指南（https://docs.pufferpanel.com/en/3.x/guides/config.html，查询日期 2026-10-24），默认值已在实测环境中抽样核对（核对点在 §四 各表「实测」列标注）

二、配置加载机制与优先级

2.1 配置的三个来源与查找顺序

PufferPanel 支持 JSON 配置文件与环境变量两种配置方式，环境变量统一以 PUFFER 为前缀（来源：官方 Configuration 页原文，查询日期 2026-10-24）：

• 配置文件默认位置 /etc/pufferpanel/config.json；
• 文件不存在时，还会检查进程当前工作目录下的 config.json；
• 路径本身可用环境变量 PUFFER_CONFIG 覆盖；
• 官方提示：配置项中的相对路径均相对于进程工作目录解析。

2.2 环境变量命名规则

JSON 键路径去掉分隔点后拼接，加 PUFFER_ 前缀、整体大写。实测对照：

2.3 优先级实测：环境变量 > config.json

实验设计：config.json 中设置 web.host=0.0.0.0:8100，同时通过 systemd drop-in 注入 PUFFER_WEB_HOST=0.0.0.0:8080，重启后探测两个端口：

8080:200
8100:000

结论：环境变量优先生效（监听 8080），config.json 的 8100 被覆盖。移除 drop-in 并重启后再次探测：

8100:200
8080:000

config.json 路径独立生效。两条路径均为官方 Configuration 页声明的方式（来源查询日期 2026-10-24），实测确认了它们的相对优先级。

2.4 运行时自动回写：sessionKey 与 token

首次启动后，面板自动生成并回写两个安全凭据到 config.json 的 panel 段（实测回写后的 config.json 结构）：

{
  "panel": {
    "sessionkey": "<启动时自动生成的随机串>",
    "token": "<启动时自动生成的随机串>"
  }
}

⚠️ 两个字段为敏感凭据：sessionKey 用于会话 Cookie 签名，token 用于守护层 JWT 签发（实测登录响应同时返回 scopes 与守护令牌，客户端调用节点 API 时使用）。回写值为随机生成，本文按规范脱敏展示，严禁将其纳入模板或版本库。若需轮换，停止服务后删除这两个字段再启动即可重新生成（重新生成后既有登录会话失效）。

三、参数速查总表

以下为官方 Configuration 页参数表全量转录（来源：docs.pufferpanel.com/en/3.x/guides/config.html，查询日期 2026-10-24）。「实测」列为本批次抽样核对结果，未标注者为官方文档值。

💡 技术拓展：panel.web.files 的存在意味着前端资源默认内嵌于 Go 二进制（实测面板 Web 根目录为空仍能正常服务页面，静态资源由 /js/index-*.js 等路径直接由二进制吐出）。该目录用于在不重新编译的前提下覆盖单个前端文件，属于官方留给主题/补丁的扩展点。

四、核心参数逐项解读

4.1 web.host —— 监听地址与端口

默认 0.0.0.0:8080。要点：值必须带端口；监听 127.0.0.1:8080 可实现仅内网/反代访问；反代场景保持面板监听内网地址、由 Nginx/Caddy 终结 HTTPS（官方提供 nginx/apache/caddy 三份反代指南，来源：官方文档目录，查询日期 2026-10-24）。

4.2 panel.database —— 数据库

默认 SQLite3 单文件，?cache=shared 参数保证多连接下的可见性。四种方言的官方连接串语法见 §五.6。panel.database.log=true 会在日志输出全部 SQL，排障性能问题时临时开启（日志量极大，勿在生产常开）。

4.3 panel.sessionKey / panel.token —— 安全凭据

见 §二.4。两者丢失/轮换的行为差异：sessionKey 轮换只踢登录会话；token 轮换会使守护层签发的令牌失效，远程节点需重新认证。

4.4 panel.registrationEnabled —— 自助注册开关

默认 false。开启后登录页出现注册入口，配合邮件功能完成验证。实测改值后无需改库，GET /api/config 直接反映新值：

{"general":{"registrationEnabled":false,...}}

4.5 daemon.console.forward —— 控制台输出外发

默认 false。开启后，每台服务器的控制台输出（进程 stdout/stderr）同步写入面板进程 stdout，systemd 环境下即进入 journald。实测效果（journalctl -u pufferpanel 节选）：

[echo1] Starting process in directory [/var/lib/pufferpanel/servers/echo1]: sleep 600

适合已统一接入 journald/采集器的运维体系；面板自身日志（logs 目录文件）仍独立存在。

4.6 daemon.data.crashLimit —— 崩溃自动重启上限

进程异常退出时守护层自动拉起，连续超过 crashLimit（默认 3）次后停止自动重启，防止崩溃循环刷盘。调试坏模板时配合 journalctl 观察重启计数。

4.7 security.disableUnshare —— 沙箱总开关

仅影响 standard 环境（游戏服务器进程直接运行）的 unshare 用户命名空间沙箱。默认 false（沙箱开启）。受限主机上会出现 fork/exec /usr/bin/bash: permission denied（完整排障实录见《安装指南》篇 Q2）。开启后服务器进程仍以 pufferpanel 专用用户运行，但失去文件系统级沙箱，安全边界收窄——官方文档将 standard 环境整体标注为仅测试用途，生产请用 docker 环境。

4.8 daemon.sftp —— SFTP 文件服务

默认 0.0.0.0:5657。SFTP 私钥自动生成（实测数据目录出现 sftp.key 文件）。每个可登录服务器的用户都可通过 SFTP 访问其被授权的服务器目录；仅修改监听端口无需重生成密钥。

4.9 docker.* —— Docker 环境参数

docker.data.root 决定 docker 环境下服务器文件落位；docker.disallowHost（官方镜像内预置 true，实测镜像 Env PUFFER_DOCKER_DISALLOWHOST=true）强制禁止游戏服务器使用 host 网络，防逃逸。面板以 docker 环境运行游戏服务器的前提是面板进程可访问 Docker 守护进程套接字（安装指南篇 Q3 的故障即源于此）。

五、常用配置场景（实测验证）

5.1 修改 Web 端口

# /etc/pufferpanel/config.json
"web": { "host": "0.0.0.0:8100" }
systemctl restart pufferpanel
curl -s -o /dev/null -w "8100:%{http_code}\n" http://localhost:8100/

实测回显：

8100:200
8080:000

改端口后注意同步防火墙放行与反代 upstream；若同时使用 masterUrl，一并更新。

5.2 关闭自助注册 + 定制品牌名

# /etc/pufferpanel/config.json
"panel": {
  "registrationEnabled": false,
  "settings": { "companyName": "Quzuo Game Panel" }
}

重启后实测 GET /api/config 回显：

{"general":{"registrationEnabled":false,...},"branding":{"name":"Quzuo Game Panel",...}}

5.3 控制台输出转发到 journald

"daemon": { "console": { "buffer": 50, "forward": true } }

重启并启动服务器实例后，实测 journalctl -u pufferpanel 出现 [echo1] 前缀的服务器输出（见 §四.5）。

5.4 受限主机关闭 unshare 沙箱

"security": { "disableUnshare": true }

重启后服务器启动成功，实测状态接口回显 {"running":true,"installing":false}。注意此开关的边界与代价（见 §四.7 与安装指南篇 Q2）。

5.5 systemd 层环境变量注入

systemctl edit pufferpanel
# 写入：
[Service]
Environment=PUFFER_WEB_HOST=0.0.0.0:8080

实测：注入后即使 config.json 写 8100，面板仍监听 8080（优先级实证见 §二.3）。该方式适合把敏感项与端口项从文件抽离到 systemd 凭据体系。

5.6 切换数据库引擎（安装前规划）

官方数据库指南明确：安装后更换数据库引擎不受支持，建议安装前即确定方言（来源：docs.pufferpanel.com/en/3.x/guides/database.html，查询日期 2026-10-24）。四种方言官方连接串示例：

// SQLite3（默认）
{"panel": {"database": {"dialect": "sqlite3", "url": "file:/var/lib/pufferpanel/database.db?cache=shared"}}}
// MySQL/MariaDB
{"panel": {"database": {"dialect": "mysql", "url": "user:pass@tcp(127.0.0.1:3306)/pufferpanel"}}}
// PostgreSQL
{"panel": {"database": {"dialect": "postgresql", "url": "user=pufferpanel password=pufferpanel dbname=pufferpanel port=9920 sslmode=disable"}}}
// SQL Server
{"panel": {"database": {"dialect": "sqlserver", "url": "sqlserver://username:password@localhost:9930?database=pufferpanel"}}}

已运行在 SQLite 且确需迁移的，CLI 提供 pufferpanel db migrate（实测帮助文本 Migrates the database to a new backend），迁移前务必备份 /var/lib/pufferpanel/ 并停止服务；官方文档未对该路径提供保障，生产慎用。连接串中的口令建议改由环境变量 PUFFER_PANEL_DATABASE_URL 注入而非明文写入 config.json。

5.7 配置邮件（注册/找回密码）

email 段支持 smtp / sendgrid / mailjet / mailgun / debug 五种提供商（来源：官方 Configuration 页，查询日期 2026-10-24）。未配置时的可观察现象（实测日志）：Error sending email: email not configured。SMTP 场景配置 provider=smtp 并填 host/port/username/password/from；debug 提供商将邮件内容直接打进日志，联调时先用它验证模板与收件人逻辑，再切真实提供商。

六、配置验证与生效流程

1. 修改 config.json 后执行 systemctl restart pufferpanel（官方无热加载，重启生效）；
2. 等待服务就绪（Type=notify，systemctl is-active 为 active 后再探测，避免启动窗口期 502）；
3. 探测 Web 端口与登录接口确认；
4. 面板级可见配置用 GET /api/config 交叉验证（注册开关、品牌名等）；
5. 启动日志核对监听端口：Listening for HTTP requests on [::]:<端口>、Started SFTP Server on 0.0.0.0:5657（实测日志行）。

七、常见问题（FAQ）

Q1：改了 config.json 不生效？ 大概率是环境变量在更高优先级覆盖（§二.3 实证）。排查 systemd drop-in（systemctl cat pufferpanel）、容器编排 environment、以及 PUFFER_CONFIG 是否指向了别的文件。

Q2：配置文件里出现我没写过的 sessionkey/token？ 首启自动生成并回写（§二.4 实测），属预期行为，勿删除或外传。

Q3：面板日志里 SQL 刷屏？ panel.database.log=true 被打开，改回 false 重启即可。

Q4：游戏服务器目录不在 /var/lib/pufferpanel？ 检查 daemon.data.root（standard）与 docker.data.root（docker 环境）是否被改；配置中的相对路径以进程工作目录为基准（官方提示），建议全部使用绝对路径。

Q5：重启后 Web 短暂 502？ Type=notify 启动窗口期的正常现象（安装指南篇 Q1 实证），就绪后自动恢复；对可用性敏感可在反代层配置健康检查重试。

八、参考链接

• 官方 Configuration 指南（参数总表与优先级声明的原始来源）：https://docs.pufferpanel.com/en/3.x/guides/config.html
• 官方数据库指南（方言连接串来源）：https://docs.pufferpanel.com/en/3.x/guides/database.html
• 官方邮件指南：https://docs.pufferpanel.com/en/3.x/guides/email.html
• 官方反代与 SSL 指南（nginx/Apache/Caddy）：https://docs.pufferpanel.com/en/3.x/guides/nginx.html
• 站内延伸阅读：《PufferPanel 3.0.9 介绍与选型指南》《PufferPanel 3.0.9 安装指南（Ubuntu 22.04）》《PufferPanel 3.0.9 API 使用详解》