Froxlor 2.3.16 配置参数详解

目标：把 Froxlor 2.3.16 的全部配置参数（panel_settings 表 276 行、20 个分组）按"在哪看、怎么改、什么含义、改完怎么生效"讲透，并给出生产配置模板与三条改值/排障实录。已在 Ubuntu 22.04 服务器 + Froxlor 2.3.16（PHP 8.2.35 / MariaDB 10.11.19 / Apache 2.4.69）实测通过。

Froxlor 没有传统面板的"主配置文件"：除数据库连接凭据外，所有配置参数都存在 MySQL/MariaDB 的 panel_settings 表里，Web 界面只是这张表的编辑器，CLI 任务作业读取同一张表渲染下游服务配置。部署过程见《Froxlor 2.3.16 Docker Compose 部署指南》，组件背景见《Froxlor 介绍与选型指南》。

一、环境信息

二、前置条件

1. 面板已完成安装并可登录（安装链路见部署篇 4.9–4.11；未安装时 panel_settings 只有 276 行出厂值，改参数无意义）；
2. 具备进入服务执行命令的通道（主机形态直接 SSH；本演示环境为 docker compose exec froxlor bash）；
3. 能连上面板数据库：凭据在 userdata.inc.php，本环境业务账号 froxlor/q1w2e3r4、全权限安装账号 froxroot/q1w2e3r4、主机名 db；
4. 改参数前建议备份：mysqldump -h db -u froxroot -pq1w2e3r4 froxlor > settings-backup.sql。

三、参数查看与修改方式

Froxlor 的配置分三层，互相独立、职责不同：

3.1 GUI 层：分组设置页

后台路径 System（系统）→ Settings（设置），每个分组一张编辑表单。分组页 URL 形态为 admin_settings.php?part=<分组名>，实测抓取 panel 分组页并核对 paging 参数当前值：

curl -s -b cookies.txt -o settings.html -w "GET admin_settings.php?part=panel -> %{http_code}\n" \
  http://127.0.0.1:8141/admin_settings.php?part=panel
grep -o -m1 'panel_paging[^<]*' settings.html
grep -o -m1 'value="20"' settings.html

GET admin_settings.php?part=panel -> 200
panel_paging" class="col-sm-6 col-form-label pe-3">
value="20"

表单字段命名规则为 <settinggroup>_<varname>（如 panel_paging、session_sessiontimeout），保存即 UPDATE panel_settings。

💡 说明：GUI 有"简单/专家"两种模式（panel.settings_mode，实测出厂 0=简单模式），简单模式会隐藏标记为不常用/不兼容的参数（system.hide_incompatible_settings 实测 1）；要看全量 276 项请切专家模式，或直接走 SQL 层。

3.2 SQL 层：panel_settings 表

表结构一行一参数：settinggroup（分组）、varname（参数名）、value（值），读取时拼成 组.参数（代码里 Settings::Get('panel.paging')）。实测读取与修改闭环：

mysql -h db -u froxroot -pq1w2e3r4 froxlor -e \
  "SELECT settinggroup, varname, value FROM panel_settings WHERE varname='paging'"
mysql -h db -u froxroot -pq1w2e3r4 froxlor -e \
  "UPDATE panel_settings SET value='25' WHERE settinggroup='panel' AND varname='paging'"
mysql -h db -u froxroot -pq1w2e3r4 froxlor -e \
  "SELECT settinggroup, varname, value FROM panel_settings WHERE varname='paging'"

settinggroup	varname	value
panel	paging	20
settinggroup	varname	value
panel	paging	25

改回 20 后复核（见 7.2 实录与注意事项）。

⚠️ 注意：SQL 层改值立即对面板进程生效（每次请求现读），但凡是"影响下游服务配置文件"的参数（vhost、DNS、邮件表等），必须等一次 froxlor:cron 'tasks' 任务作业重新渲染才落到 /etc/apache2 等目录——手动触发：php /var/www/html/froxlor/bin/froxlor-cli froxlor:cron 'tasks' -f（实测回显见部署篇 4.11）。

3.3 连接层：userdata.inc.php

安装器生成（实测 ls -l：-rw------- 1 www-data www-data 303），内容节选：

<?php
// autogenerated froxlor file

$sql = [
	'debug' => false,
	'host' => 'db',
	'user' => 'froxlor',
	'password' => 'q1w2e3r4',
	'db' => 'froxlor',
];
$sql_root = [
	'0' => [
		'caption' => 'Default',
		'host' => 'db',
		'user' => 'froxroot',
		'password' => 'q1w2e3r4',
	],
];

• $sql：面板日常读写用的业务账号（仅需 froxlor 库权限）；
• $sql_root：数组，可登记多套 root 级凭据——多数据库服务器场景（admin_mysqlserver.php 里每加一台就追加一项）；面板建客户库/账号走这里，所以必须带转授权限；
• 'debug' => true 可让面板把 SQL 错误详情打到页面，排障用，生产保持 false。

3.4 安装层：install.json

无人值守安装的 JSON 字段（mysql_*/admin_*/distribution/serveripv4/webserver 等，见部署篇 4.9）本质是"一次性批量写上述三层"：mysql_* → userdata.inc.php，其余 → panel_settings。已装环境改参不走这条路，用 froxlor:config-services -i <file> 导入另一台安装的设置属于迁移范畴（见 CLI 篇相关命令）。

四、参数总览

4.1 总量与分组分布（实测）

mysql -h db -u froxroot -pq1w2e3r4 froxlor -e "SELECT COUNT(*) AS total FROM panel_settings"
mysql -h db -u froxroot -pq1w2e3r4 froxlor -e \
  "SELECT settinggroup, COUNT(*) AS n FROM panel_settings GROUP BY settinggroup ORDER BY n DESC"

total
276
settinggroup	n
system	170
panel	43
phpfpm	16
antispam	7
customer	6
logger	5
defaultwebsrverrhandler	5
admin	3
login	3
api	2
session	2
mail	2
spf	2
dmarc	2
customredirect	2
perl	2
catchall	1
2fa	1
caa	1
nginx	1

解读：system 组独占 170 行（62%），是"面板接管主机哪些服务、怎么接管"的总账；panel 组 43 行管界面与品牌；其余小分组各管一个功能域（phpfpm 进程池、antispam 反垃圾、spf/dmarc/caa 邮件 DNS 记录模板、login/session/2fa/api 登录与会话……）。没启用的功能域参数保持出厂默认即可，不必清理。

4.2 第二张设置表：domain_ssl_settings

库内匹配 %setting% 的表实测只有两张：

Tables_in_froxlor (%setting%)
domain_ssl_settings
panel_settings

panel_settings 是全局参数；domain_ssl_settings 是按域名覆盖的 SSL 参数表（每个域名的证书类型/SSL 特殊设置等，对应后台域名编辑页的 SSL 区块），不属于全局配置体系，本文不展开。

五、核心参数分类详解

以下逐项取自本环境实测值（SELECT settinggroup, varname, value FROM panel_settings 全量 276 行导出），"本环境值"即 2.3.16 出厂默认或安装器写入值。

5.1 system：主机与网络

5.2 system：Web 服务器与站点

💡 技术拓展：Froxlor 支持三种 PHP 运行模式，客户站点行为由此分岔——

模式	开关参数	隔离性
mod_php	面板自身使用（安装 webserver_backend）	无，全部站点同 httpuser
PHP-FPM	phpfpm.enabled（本环境 0）	每客户/域名独立进程池，隔离最好
FCGID	system.mod_fcgid（本环境 0）	按 Unix 用户隔离，配 mod_fcgid_* 12 项

生产托管建议至少启用 PHP-FPM（见第六章模板），本演示环境保持 mod_php 单模式。

5.3 system：邮件与 FTP

5.4 system：DNS、TLS 与 Let's Encrypt

5.5 system：任务作业、发行版模板与更新

5.6 panel 组：界面、品牌与口令策略

5.7 login / session / 2fa / api：登录安全四组

5.8 customer / phpfpm：默认资源与进程池

customer 组 6 项是新客户命名/默认值模板（真正的配额在 panel_plans/panel_customers 表）：

phpfpm 组 16 项（本环境 enabled=0，启用后生效）：

5.9 功能域小组速查

六、生产配置模板

适用场景：单台 16GB 内存 / NVMe SSD 的 Debian 12（bookworm）真机、对外提供 Web+邮件托管、Apache 2.4。以下为相对出厂值的建议改项（值为推荐口径，改法用 3.1 GUI 或 3.2 SQL 均可；改完跑一次 froxlor:cron 'tasks' -f 落盘）：

⚠️ 注意：system.croncmdline、system.apacheconf_* 这类路径参数不要凭想象改——必须与真机实际布局一致（本演示环境 /usr/bin/php 缺失导致整条 cron 链失败的教训见部署篇 11.3）；改路径类参数后务必手动跑一次 froxlor:cron 'tasks' -f -d 验证渲染与重载成功。

七、常见问题

7.1 想查"分组字典表"，报 Table 'froxlor.panel_settinggroups' doesn't exist

现象（实测踩坑原样）：

SELECT groupid, settinggroup, description FROM panel_settinggroups ORDER BY groupid;

ERROR 1146 (42S02) at line 1: Table 'froxlor.panel_settinggroups' doesn't exist

按 panel_settings_groups 猜同样报错。定位：2.3.16 里 %setting% 匹配的表实测只有 panel_settings 与 domain_ssl_settings 两张，不存在分组字典表——分组名硬编码在代码与各 varname 的元数据里，settinggroup 列就是分组本身。解决：看分组分布直接用 GROUP BY settinggroup COUNT(*)（4.1 实测），分组含义对照本文第五章。

7.2 SQL 直改 panel.paging 实测闭环

3.2 节演示了 20 → 25（UPDATE 后 SELECT 立即回显 25）。收尾必须改回：

mysql -h db -u froxroot -pq1w2e3r4 froxlor -e \
  "UPDATE panel_settings SET value='20' WHERE settinggroup='panel' AND varname='paging'"
mysql -h db -u froxroot -pq1w2e3r4 froxlor -e \
  "SELECT varname, value FROM panel_settings WHERE varname='paging'"

varname	value
paging	20

要点：SQL 改值后GUI 分组页同步显示新值（同一张表），列表分页立即按新值走；不存在"要重启面板"的问题，但 GUI 里改过未保存的表单会把你的 SQL 值盖回去，两条路别并行用。

7.3 distro_mismatch=1 是怎么回事

实测本环境 system.distribution=bookworm、system.distro_mismatch=1（SQL 回显见 3.2 末与部署篇基底说明）：安装选了 bookworm 模板线，而运行基底的真实发行版是 Debian 13。面板启动时自检 OS 版本并记账，不改变行为（配置仍按所选模板渲染）。处理二选一：把 system.distribution 改成实际代号（trixie 在支持清单内，froxlor:config-diff -l 实测可见）；或维持 bookworm 并知晓差异范围——用 froxlor:config-diff bookworm trixie 可逐文件量化（实测差异集中在 proftpd 模块表，回显见 CLI 篇 config-diff 一节）。

7.4 GUI 设置页看不到某些参数

原因：panel.settings_mode=0（简单模式）+ system.hide_incompatible_settings=1 会隐藏与当前 Web 服务器/PHP 模式不兼容或非常用的参数（例如 nginx.*、mod_fcgid_* 在 Apache+mod_php 环境不可见）。解决：切专家模式，或按 3.2 直接 SQL 读写——参数在不在 panel_settings 表里与 GUI 显不显示无关（4.1 的 276 行全量包含所有隐藏项）。

7.5 改了 vhost 相关参数，站点没变化

定位：这类参数只写库，落盘靠任务队列。验证链：SELECT value FROM panel_settings WHERE varname='last_tasks_run' 看最近任务时刻 → 手动 php /var/www/html/froxlor/bin/froxlor-cli froxlor:cron 'tasks' -f -d（全量回显见部署篇 4.11）→ 检查生成的 vhost 文件与 Web 服务重载日志。

八、参考链接

• 官方设置文档：https://docs.froxlor.org/latest/admin-guide/settings/
• 官方系统设置（System settings）章节：https://docs.froxlor.org/latest/admin-guide/settings/system.html
• GitHub 源码（参数元数据定义于安装 SQL sql/*.sql 与 lib/Froxlor/Settings.php）：https://github.com/Froxlor/Froxlor
• 同系列：《Froxlor 介绍与选型指南》、《Froxlor 2.3.16 Docker Compose 部署指南》、《Froxlor 2.3.16 常用 CLI 命令与工具详解》