ISPConfig 3.3.2p1 配置参数详解

目标：讲清 ISPConfig 3.3.2p1 的四层参数体系（应用配置文件、服务端配置文件、数据库配置表、安全策略文件）以及各层关键参数的含义、默认值、查看与修改方法，帮助读者在不破坏自动安装成果的前提下安全调整面板行为。本文基于 Ubuntu 22.04.5 LTS 上按官方自动安装器实装的 3.3.2p1 环境，所有配置文件内容与数据库查询结果均为实测照抄。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS；主机名 server1.example.com（FQDN）
• ISPConfig：3.3.2p1（实测 grep ISPC_APP_VERSION /usr/local/ispconfig/interface/lib/config.inc.php 第 62 行 → define('ISPC_APP_VERSION', '3.3.2p1');）
• 安装方式：官方自动安装器（--lang=en --channel=stable --no-quota --use-php=system --no-pma），组件版本 MariaDB 10.6.23 / Apache 2.4.52 / PHP 8.1.34 / Postfix 3.6.4 / Dovecot 2.3.16 / BIND 9.18.39 / Rspamd 4.2.3
• 面板端口：8080（管理界面）、8081（Apps 站点）
• 数据库：dbispconfig（面板业务与配置库），连接用户 ispconfig

二、前置条件

• 已按官方自动安装器完成 ISPConfig 3.3.2p1 安装（完整流程见 《Ubuntu 22.04 安装 ISPConfig 3.3.2p1 指南》），systemctl is-active apache2 mariadb 均为 active。
• 具备 root 权限；能以系统 root 身份执行 mariadb dbispconfig 直连数据库（Ubuntu 22.04 的 MariaDB root 默认 unix_socket 认证，无需密码）。
• 修改配置前建议备份：cp -a /usr/local/ispconfig/interface/lib/config.inc.php{,.bak}；数据库级修改前 mariadb-dump dbispconfig > /root/dbispconfig.sql。

三、参数查看与修改方式

ISPConfig 的参数分布在四个层面，先给全景再逐层展开：

💡 技术拓展：面板类软件的配置存放常见三种形态——纯文件（Nginx/Apache 式）、纯数据库（如部分 SaaS 面板）、文件+数据库混合。ISPConfig 属于混合形态：安装路径、数据库连接等"引导参数"在 PHP 配置文件中；业务级配置（服务器角色、邮件/站点/客户默认值）在数据库 dbispconfig 中；安全策略另立 INI 文件。改错层的后果：把业务参数写进配置文件不会生效（会被数据库值覆盖），反之亦然。

3.1 文件层修改与覆盖机制

config.inc.php 文件头部有官方警告（实测原文）：

 *  WARNING, changes made in this file WILL BE OVERRIDDEN. Use config.inc.local.php for local overrides.

即：直接改 config.inc.php 的改动会被升级覆盖，本地定制应写入同目录的 config.inc.local.php（升级保留）。改动后无需重启面板（PHP-FPM 每请求加载），但改数据库连接类参数后建议用浏览器验证登录。

3.2 数据库层查看与修改

mariadb dbispconfig -e "select server_id,server_name,mail_server,web_server,dns_server,file_server,db_server,active from server;"

实测回显：

server_id      server_name          mail_server  web_server  dns_server  file_server  db_server  active
1              server1.example.com  1            1           1           1            1          1

该行即"服务器角色开关"：1 表示本机承担邮件/Web/DNS/文件/数据库五种服务角色（单机全栈安装的典型结果）。把某列改 0（面板 Server Config 里对应服务开关）后，服务端下轮同步即停止管理该域配置。

全局业务配置存于 sys_ini 表（config 字段，INI 格式）：

mariadb dbispconfig -e "select config from sys_ini where sysini_id=1;"

实测节选（字段与值原样照抄）：

[global]

[admin]

[client]

[mail]
enable_custom_login=n
show_per_domain_relay_options=n
mailbox_show_autoresponder_tab=y
mailbox_show_mail_filter_tab=y
mailbox_show_custom_rules_tab=y
mailboxlist_webmail_link=y
webmail_url=https://[SERVERNAME]:8081/webmail
dkim_path=/var/lib/amavis/dkim
smtp_enabled=y
smtp_host=localhost
enable_welcome_mail=y

[monitor]

[sites]
dbname_prefix=c[CLIENTID]
dbuser_prefix=c[CLIENTID]
ftpuser_prefix=[CLIENTNAME]
shelluser_prefix=[CLIENTNAME]
webdavuser_prefix=[CLIENTNAME]
dblist_phpmyadmin_link=y
phpmyadmin_url=https://[SERVERNAME]:8081/phpmyadmin
webftp_url=
vhost_subdomains=n
vhost_aliasdomains=n
client_username_web_check_disabled=n
backups_include_into_web_quota=n
reseller_can_use_options=n
web_php_options=no,php-fpm
show_aps_menu=n
client_protection=y

3.3 变更生效机制（改完为什么"没生效"）

生效链路为：面板/SQL 写库 → server.sh 每分钟从库拉取变更 → 生成底层服务配置并重载服务。root crontab 实测（crontab -l）：

* * * * * /usr/local/ispconfig/server/server.sh 2>&1 | while read line; do echo `/bin/date` "$line" >> /var/log/ispconfig/cron.log; done
* * * * * /usr/local/ispconfig/server/cron.sh 2>&1 | while read line; do echo `/bin/date` "$line" >> /var/log/ispconfig/cron.log; done

不想等下一分钟，手动触发一次同步：

cd /usr/local/ispconfig/server && php -q server.php

实测回显：

finished server.php.

四、参数总览

以下两张表汇总本文详解的核心参数（默认值均为实测环境原值）：

文件层（config.inc.php，实测第 62~123 行范围内关键项）

数据库层（sys_ini.config，实测节选释义）

五、核心参数分类详解

5.1 数据库连接组（db_* 与 dbmaster_*）

文件层最关键的一组参数，决定面板连哪个库。实测原值：

$conf['db_type'] = 'mysql';
$conf['db_host'] = 'localhost';
$conf['db_port'] = '3306';
$conf['db_database'] = 'dbispconfig';
$conf['db_user'] = 'ispconfig';
$conf['db_password'] = 'X6wH2U1JCEj9Kyv';
$conf['db_charset'] = 'utf8mb4'; // same charset as html-charset - (HTML --> MYSQL: "utf-8" --> "utf8mb4", "iso-8859-1" --> "latin1")
$conf['db_new_link'] = false;
$conf['db_client_flags'] = 0;

• db_password 为安装器随机生成（连库用户 ispconfig，仅对本库有权限）。修改 MariaDB 侧口令后，此处须同步改。
• db_charset 保持 utf8mb4；注释原文说明它与界面 HTML 字符集联动。
• dbmaster_* 组（实测默认 host/user 为空、password 为空串之外的默认散列值）只在多服务器部署时填写主库连接，从服务器凭它连主库同步配置；单机保持不动。

5.2 路径与日志组

$conf['ispconfig_log_dir'] = '/var/log/ispconfig';
define('ISPC_ROOT_PATH', realpath(dirname(__FILE__).'/../')); // Main ROOT is the parent directory to this file, ie interface/ or server/. NO trailing slashes.
define('ISPC_LIB_PATH', ISPC_ROOT_PATH.'/lib');
define('ISPC_CLASS_PATH', ISPC_ROOT_PATH.'/lib/classes');
define('ISPC_WEB_PATH', ISPC_ROOT_PATH.'/web');
define('ISPC_THEMES_PATH', ISPC_ROOT_PATH.'/web/themes');
define('ISPC_WEB_TEMP_PATH', ISPC_WEB_PATH.'/temp'); // Path for downloads, accessible via browser
define('ISPC_CACHE_PATH', ISPC_ROOT_PATH.'/cache');
define('ISPC_LOG_PATH', $conf['ispconfig_log_dir']);

路径常量按 interface/ 或 server/ 自身位置推导（注释原文说明"NO trailing slashes"），无需手改。实测 /var/log/ispconfig/ 下的文件（ls 实测）：auth.log、cron.log、httpd/、install.log、ispconfig.log——cron.log 即 3.3 节两条 crontab 的输出落点。

5.3 界面行为组（timezone / interface_base_url 等）

//* Complete timezone list: http://php.net/manual/en/timezones.php
$conf['timezone'] = 'Etc/UTC';

//** Misc.
$conf['interface_logout_url'] = ''; // example: http://www.domain.tld/
$conf['interface_base_url'] = ''; // example: http://www.domain.tld (no trailing slash)

• timezone 默认 UTC；国内服务器可改 Asia/Shanghai（写入 config.inc.local.php）。
• interface_base_url 在 3.3.2 是安全相关参数：发布说明明确修复了密码重置链接由请求 Host 头构造的问题（#7044），新逻辑优先取 interface_base_url，未设置时退回面板服务器主机名。若通过反代或别的域名访问面板，务必设置该值为对外访问地址（无尾斜杠）。

5.4 服务器角色与同步参数（server 表）

server 表一行一台服务器，角色列见 3.2 实测。相关辅助列（实测默认）：

修改角色建议走面板"系统 > 服务器配置"，或 SQL 改后立即 php -q server.php 同步。

5.5 全局业务默认值（sys_ini.config 详解）

• [mail] webmail_url=https://[SERVERNAME]:8081/webmail：模板变量 [SERVERNAME] 在展示时替换为服务器名；Roundcube 实测安装在 8081 apps 站点下，该默认值与之匹配。
• [mail] dkim_path=/var/lib/amavis/dkim：DKIM 私钥目录（历史路径名带 amavis，Rspamd 时代仍沿用该默认位置）。
• [sites] dbname_prefix=c[CLIENTID]：建库自动命名为 c<客户ID>_<库名>，避免跨客户重名；ftpuser_prefix=[CLIENTNAME] 同理。改前缀只影响新建对象。
• [sites] web_php_options=no,php-fpm：站点表单可选的 PHP 模式集合（--use-php=system 环境下实测默认就这两项；装了多版本 PHP 的环境此处会随 PHP 版本扩展）。
• [sites] phpmyadmin_url：默认指向 8081 站点 /phpmyadmin。本文安装用了 --no-pma，如后补 phpMyAdmin，部署到该路径即可让库列表跳转生效。

5.6 安全策略（security_settings.ini）

实测 /usr/local/ispconfig/security/security_settings.ini 关键节（原样节选）：

[permissions]
allow_shell_user=yes
admin_allow_server_config=superadmin
admin_allow_server_services=superadmin
admin_allow_server_ip=superadmin
admin_allow_remote_users=superadmin
admin_allow_system_config=superadmin
admin_allow_server_php=superadmin
admin_allow_langedit=superadmin
admin_allow_new_admin=superadmin
admin_allow_del_cpuser=superadmin
admin_allow_cpuser_group=superadmin
admin_allow_firewall_config=superadmin
admin_allow_osupdate=superadmin
remote_api_allowed=yes
password_reset_allowed=yes
session_regenerate_id=yes
reverse_proxy_panel_allowed=none

[ids]
ids_anon_enabled=yes
ids_anon_log_level=1
ids_anon_warn_level=15
ids_anon_block_level=20
ids_user_enabled=yes
ids_user_log_level=1
ids_user_warn_level=27
ids_user_block_level=30
ids_admin_enabled=no
ids_admin_log_level=1

• [permissions] 中 admin_allow_*=superadmin 表示该功能仅"超级管理员"角色可见（这是 3.3.2 审计加固强化的 scope 机制：白名单条目按 any/user/admin 生效）。要给普通管理员放开某功能，把对应值改为 yes。
• remote_api_allowed=yes：远程 API 总开关，关闭后 Remote API 不可用。
• session_regenerate_id=yes：3.3.2 起登录时强制重建会话 ID（防会话固定），保持开启。
• [ids] 是内置入侵检测（IDS）阈值：匿名/登录用户/管理员三档 log/warn/block 级别，数值越低越敏感。误拦截高时先调高 *_block_level 并查 ids.htmlfield/ids.whitelist 清单（自定义白名单文件为 security/ids.whitelist.custom，3.3.2 起强制校验条目的 user/admin scope）。

5.7 面板 Web 服务参数（ispconfig.vhost / apps.vhost）

/etc/apache2/sites-available/ispconfig.vhost（8080 端口）实测关键原文：

  SSLEngine On
    SSLProtocol All -SSLv3 -TLSv1 -TLSv1.1
    SSLCertificateFile /usr/local/ispconfig/interface/ssl/ispserver.crt
  SSLCertificateKeyFile /usr/local/ispconfig/interface/ssl/ispserver.key

    IPCCommTimeout  7200
    MaxRequestLen 15728640

• SSLProtocol 禁用 SSLv3/TLS1.0/TLS1.1；证书为自签 ispserver.crt/.key（在面板服务器设置里开启 Let's Encrypt 后会被正式证书替换）。
• IPCCommTimeout 7200：FastCGI 处理超时 2 小时（面板内跑长任务不被掐断）。
• MaxRequestLen 15728640：请求体上限约 15MB（上传备份/主题包的上限）。
• apps.vhost（8081）同样 SSLEngine On，站点根 /var/www/apps，Roundcube 即部署于此。

5.8 底层服务常用键（MariaDB 示例）

ISPConfig 生成/管理的服务配置以标准发行版文件存在，以 /etc/mysql/mariadb.conf.d/50-server.cnf 实测关键行为例：

#bind-address            = 127.0.0.1
#max_connections        = 100
character-set-server  = utf8mb4
collation-server      = utf8mb4_general_ci
#innodb_buffer_pool_size = 8G

⚠️ 注意：这些文件由 ISPConfig 同步机制管理（服务器配置页对应的改动会写回），手工改动应在面板"系统 > 服务器配置"中做，避免下轮同步覆盖。

六、生产配置模板

适用场景：单机全栈托管（Web+邮件+DNS+数据库）、8GB 内存 / NVMe SSD / 500 客户以内。以下改动点均标注来源层：

# 1) 文件层覆盖（新建 /usr/local/ispconfig/interface/lib/config.inc.local.php）
<?php
$conf['timezone'] = 'Asia/Shanghai';
$conf['interface_base_url'] = 'https://panel.example.com';

# 2) 数据库层（面板 System > Main Config，或 SQL）
# [mail] webmail_url 保持 https://[SERVERNAME]:8081/webmail
# [sites] web_php_options 按需加入 no,php-fpm,php-fpm-8.1 等实际存在的模式

# 3) 安全层（/usr/local/ispconfig/security/security_settings.ini）
[permissions]
remote_api_allowed=no        ; 不用远程 API 时关闭
password_reset_allowed=yes   ; 保持
[ids]
ids_anon_block_level=25      ; 误拦截多时上调（默认 20）

# 4) MariaDB（面板服务器配置 > 数据库页签调整，勿直改文件）
# innodb_buffer_pool_size 建议为专用数据库内存的 50%~70%；8GB 单机面板+全栈建议 2G 起步

改完执行 php -q /usr/local/ispconfig/server/server.php（实测回显 finished server.php.）立即同步，再用 systemctl is-active 逐项确认服务状态。

七、常见问题

Q1：改了 config.inc.php 之后升级，改动丢了？ 按文件头官方警告，升级会覆盖该文件。本地定制写 config.inc.local.php（同目录，实测官方注释原文："Use config.inc.local.php for local overrides"）。

Q2：面板里改了参数但底层没变化？ 配置走"写库 → server.sh 每分钟同步"链路。等 1 分钟，或手动 php -q /usr/local/ispconfig/server/server.php（实测输出 finished server.php.）；仍无变化时看 /var/log/ispconfig/ispconfig.log 与 cron.log。

Q3：忘记 admin 密码怎么办？ 以系统 root 执行 mariadb dbispconfig，用 UPDATE sys_user SET passwort = md5('q1w2e3r4') WHERE username = 'admin'; 重置（md5 为面板兼容的历史哈希方式；重置后立即登录改密并建议开启更强的认证策略）。改库后无需重启服务。

Q4：密码重置邮件里的链接指向错误主机？ 3.3.2 已修复由 Host 头构造重置链接的漏洞（官方 #7044）：链接优先取 interface_base_url，未设置则取面板服务器主机名。经反代/别名访问面板时，把 $conf['interface_base_url'] 设为对外地址。

Q5：db_password 里的密码能改吗？ 能。流程：mariadb 中 SET PASSWORD FOR 'ispconfig'@'localhost' = PASSWORD('新密码');，然后同步更新 interface/lib/config.inc.php 与 server/lib/config.inc.php（或 local 覆盖文件）中的 db_password，最后浏览器登录验证。

八、参考链接

• 官方代码仓库（配置文件与安装器源码）：https://git.ispconfig.org/ispconfig/ispconfig3

• 3.3.2 发布说明（interface_base_url、admin_mail/server_sender_mail 等变更依据）：https://www.ispconfig.org/blog/ispconfig-3-3-2-released/

• 安装过程与参数选择见 《Ubuntu 22.04 安装 ISPConfig 3.3.2p1 指南》；命令行工具见《ISPConfig 3.3.2p1 常用 CLI 命令与工具详解》。

• 本专栏系列：《ISPConfig 介绍与选型指南》。