phpBB 配置参数详解

目标：逐层拆解 phpBB 3.3.19 的全部配置载体——config.php 主配置（12 项逐项）、数据库 phpbb_config 表（355 个运行参数按 9 大类分组逐项实测）、phpbb_config_text 表与 PHP 层关联配置（php.ini / FPM 进程池），含"SQL 直改不生效 → 清缓存才生效"的生效机制实测与生产模板，基于 3.3.19 实测环境逐值核对。

一、环境信息

本文所有参数值与实验均在以下环境实测采集（安装过程见 《Ubuntu 22.04 安装 phpBB 指南》）：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• phpBB：3.3.19（官方完整包安装，数据库 phpbb，表前缀 phpbb_）
• Web 服务：Nginx 1.18.0 + PHP 8.1.2-1ubuntu2.28（FPM）/ MariaDB 10.6.23
• 演示站点名：phpBB 演示社区（管理员 admin / q1w2e3r4）
• 配置采集命令：mariadb --default-character-set=utf8mb4 -uphpbb -pq1w2e3r4 phpbb -e "..."（所有 SQL 均实测）

二、前置条件

• 一台按安装指南篇完成 0→1 安装的 phpBB 3.3.19（本文示例命令中的库名/表前缀/账号与之对应，读者替换为自己的实值即可）；
• 数据库命令行访问权限（mariadb 客户端）或 phpMyAdmin 等等价工具；
• phpBB 目录的文件系统访问权限（config.php 与 cache/）；
• 不需要重启 Web 服务：本文涉及的配置修改均不触碰 Web 层。

三、参数查看与修改方式

3.1 三层配置体系总览

phpBB 的配置分三层，各自的角色与生效方式不同（这是理解 phpBB 配置的第一件事）：

3.2 查看方式

SQL 查看（本篇所有实值的采集方式）：

mariadb --default-character-set=utf8mb4 -uphpbb -pq1w2e3r4 phpbb \
  -e "SELECT config_name, config_value FROM phpbb_config WHERE config_name='sitename';"

实测回显：

config_name     config_value
sitename        phpBB 演示社区

ACP 查看：管理员登录后台（http://<站点>/adm/），"常规（GENERAL）"标签下的 Board settings、Attachment settings、E-mail settings 等页面即 phpbb_config 表的图形化视图；"Maintenance → Admin log" 可追溯后台改过什么。

配置文件查看：

cat /var/www/phpbb/config.php

3.3 修改方式与生效机制（实测）

方式一：ACP 修改（推荐）——后台保存后立即生效，无需任何手工操作。

方式二：SQL 直改（自动化/批量场景）——必须手动清缓存才生效。 以下为完整实测过程（站点名从 phpBB 演示社区 改为 phpBB 缓存实验站）：

第一步，SQL 更新配置行：

mariadb --default-character-set=utf8mb4 -uphpbb -pq1w2e3r4 phpbb \
  -e "UPDATE phpbb_config SET config_value='phpBB 缓存实验站' WHERE config_name='sitename';"

第二步，立即访问首页验证——仍显示旧值（实测回显）：

<title>phpBB 演示社区 - Index page</title>

原因：phpBB 把 phpbb_config 全表缓存进 cache/production/data_global.php，页面读取的是缓存值。

第三步，用官方 CLI 清缓存（在 phpBB 根目录执行，以 Web 运行用户身份）：

cd /var/www/phpbb
su -s /bin/bash www-data -c 'php bin/phpbbcli.php cache:purge'

实测回显：

 [OK] Cache successfully purged.

第四步，再次访问首页——新值生效（实测回显）：

<title>phpBB 缓存实验站 - Index page</title>

⚠️ 注意：SQL 直改后忘了清缓存，是"明明改了数据库却不生效"这一 phpBB 高频问题的根源。等价的清缓存手段还有：删除 cache/production/ 下的缓存数据文件（保留 .htaccess），或等缓存过期。改完实验记得把值改回（同样要清缓存）。

四、参数总览

4.1 静态层 config.php（12 项）

4.2 动态层 phpbb_config（实测 355 个键）

全表统计（实测 SELECT COUNT(*) FROM phpbb_config; → 355），按前缀分组的规模如下：

另有 phpbb_config_text 表存放大文本配置（实测 4 键：contact_admin_info 及其 bitfield/flags/uid 三项伴随字段），BBCode 集合、自定义资料字段默认值等大块文本也在该表。

💡 技术拓展：为什么拆成 config 与 config_text 两张表——phpbb_config 的 config_value 列类型是 varchar，键多值短，且全表进缓存，追求内存占用小；长文本（联系方式说明、用户协议等）放 phpbb_config_text（text 类型）单独存取。改 config_text 同样受缓存影响（对应缓存文件为 data_*.php），生产上以 ACP 修改最稳妥。

五、config.php 参数逐项详解

文件位于 phpBB 根目录（实测主实例 /var/www/phpbb/config.php，完整实测内容如下）：

<?php
// phpBB 3.3.x auto-generated configuration file
// Do not change anything in this file!
$dbms = 'phpbb\db\driver\mysqli';
$dbhost = 'localhost';
$dbport = '3306';
$dbname = 'phpbb';
$dbuser = 'phpbb';
$dbpasswd = 'q1w2e3r4';
$table_prefix = 'phpbb_';
$phpbb_adm_relative_path = 'adm/';
$acm_type = 'phpbb\cache\driver\file';

@define('PHPBB_INSTALLED', true);
@define('PHPBB_ENVIRONMENT', 'production');
// @define('DEBUG_CONTAINER', true);

逐项说明（默认值即上述实测值）：

5.1 $dbms——数据库驱动

• 实测值：phpbb\db\driver\mysqli
• 作用：数据库适配器（DBAL driver）。可选值由 phpbb\db\driver\ 命名空间下的驱动类决定：mysqli（MySQL/MariaDB，默认）、postgres、sqlite3、mssql_odbc、oracle 等。
• 实测注意：安装向导下拉框只列出当前 PHP 环境装了扩展的驱动；换驱动 = 换数据库，必须配合官方转换工具，不能只改这一行。

5.2 $dbhost / $dbport——数据库地址与端口

• 实测值：localhost / 3306
• 作用：连接目标。localhost 走本机 Unix socket，127.0.0.1 走 TCP——MariaDB 对两种方式的账号权限是分开的（'phpbb'@'localhost' 不等于 'phpbb'@'127.0.0.1'），数据库与应用分离部署时用 127.0.0.1 或远端 IP 并同步建对应 host 的账号。
• $dbport 留空时按驱动默认（MySQL 3306）。

5.3 $dbname / $dbuser / $dbpasswd——库、账号、密码

• 实测值：phpbb / phpbb / q1w2e3r4
• 作用：连接三要素。多实例共存时（见安装指南篇 5.4 节实测模式）靠 $dbname/$dbuser 区分。
• 实测注意：改密码要同时改数据库侧（ALTER USER）与这里；本文件是 644 可读的 PHP 文件，生产上务必确保 Web 目录外部不可列目录（Nginx 配置的 deny all 段已屏蔽其 HTTP 直读）。

5.4 $table_prefix——表前缀

• 实测值：phpbb_（安装器默认）
• 作用：全部 69 张表的统一前缀。同库部署两套论坛时用不同前缀隔离（如 phpbb_ 与 forum2_），改前缀 = 改全部表名，已装好的站点不要动。

5.5 $phpbb_adm_relative_path——后台目录

• 实测值：adm/
• 作用：管理后台相对路径。有人为安全改名为 myadm/（需同步 mv adm myadm），属可选加固项。

5.6 $acm_type——缓存驱动

• 实测值：phpbb\cache\driver\file
• 作用：缓存后端。可选：file（默认，落盘 cache/production/）、redis、memcached、apcu。单机小站 file 足够；多机/高并发换 redis（需装 php-redis 扩展并加 redis.host 等关联配置项）。
• 这是"改配置不生效"问题的另一面：file 驱动的缓存文件就是 3.3 节实验里的 data_global.php。

5.7 PHPBB_INSTALLED——安装标记

• 实测值：true
• 作用：区分"已安装/未安装"状态。安装器检测到 true 就拒绝再跑安装流程。全新重装时把这个 define 注释掉并清空缓存即可重新进向导（数据先备份）。

5.8 PHPBB_ENVIRONMENT——运行环境

• 实测值：production
• 作用：对应 Symfony 的内核环境。production（默认）使用预合成的服务依赖图与生产缓存；dev 会开启调试信息、实时重建服务依赖图，只用于本地排障，生产保持 production。
• 关联：文件尾注释掉的 // @define('DEBUG_CONTAINER', true); 打开后强制每次重建服务依赖图（开发用，代价是每请求变慢）。

六、phpbb_config 核心运行参数分类详解

以下每项均为实测值（来自 3.3.19 全新安装的 phpbb 库），含义以官方 ACP 页面与包内文档为准。修改通用规则见 3.3 节：ACP 改即生效；SQL 改需清缓存。

6.1 站点基本参数

6.2 用户与注册参数

6.3 版面浏览参数

6.4 服务器与 Cookie 参数

💡 说明：server_* 四项 + cookie_* 五项是迁移域名/上 HTTPS 时必改的九件套，全部改完清缓存，否则会出现"登录跳回/样式丢失/链接指向旧域名"。

6.5 会话与表单安全参数

6.6 邮件参数

6.7 搜索与验证码参数

6.8 附件参数

⚠️ 注意：max_filesize 只是 phpBB 侧限制，还受 PHP 层 upload_max_filesize（实测 2M）与 post_max_size（实测 8M）钳制——附件上不去时先查 PHP 层（见第七章）。

6.9 性能开关参数（load_* / limit_*）

七、PHP 层关联配置

phpBB 的部分行为（上传大小、内存、超时）由 PHP 层决定。实测环境（Ubuntu 22.04 官方源 PHP 8.1）的关键值：

7.1 FPM 侧 php.ini（/etc/php/8.1/fpm/php.ini，Web 实际生效）

max_execution_time = 30
max_input_time = 60
memory_limit = 128M
post_max_size = 8M
upload_max_filesize = 2M
default_charset = "UTF-8"

💡 技术拓展：upload_max_filesize 与 post_max_size 的关系——post_max_size 是整个 POST 包上限（正文+文件+表单字段），文件上限受两者夹逼，实际可传 ≤ min(二者)。修改后需 sudo systemctl restart php8.1-fpm 生效（php.ini 不支持 reload 平滑热更）。

7.2 FPM 进程池（/etc/php/8.1/fpm/pool.d/www.conf，实测值）

listen = /run/php/php8.1-fpm.sock
pm = dynamic
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3

pm.max_children=5 是 Ubuntu 默认值，对应安装指南篇 Nginx 配置里 upstream 指向的 socket。小流量够用；并发上来出现 502 时优先查 FPM（pm.max_children 耗尽会在 php8.1-fpm 日志打 warning）。

7.3 必需扩展核对（实测清单）

curl  gd  intl  libxml  mbstring  mysqli  SimpleXML  xml  xmlreader  xmlwriter

与官方要求（json、mbstring、XML、getimagesize + 数据库驱动）对照，Ubuntu 官方源包 php8.1-mysql/php8.1-gd/php8.1-mbstring/php8.1-xml/php8.1-curl/php8.1-intl/php8.1-zip 一次装齐即达标。

八、生产配置模板

适用场景：2 核 4GB 内存、NVMe SSD、日均 5–10 万 PV 的中型中文社区（单机 LNMP）。

PHP 层（/etc/php/8.1/fpm/php.ini + pool.d/www.conf）：

; php.ini
memory_limit = 256M
upload_max_filesize = 20M
post_max_size = 25M
max_execution_time = 60
default_charset = "UTF-8"

; pool.d/www.conf
pm = dynamic
pm.max_children = 30
pm.start_servers = 6
pm.min_spare_servers = 4
pm.max_spare_servers = 10

phpBB 层（经 ACP 或 SQL+清缓存修改的推荐值）：

💡 说明：acm_type=redis 需先 apt install php8.1-redis 并运行 Redis 实例，改后清缓存生效；单机日均 PV < 1 万时 file 驱动更快更省心，不要无脑上 Redis。

九、常见问题（FAQ）

Q1：直接 UPDATE phpbb_config 后前台没变化。

缓存未失效——见 3.3 节实测：SQL 改表后页面仍读 cache/production/data_global.php 的旧值，执行 php bin/phpbbcli.php cache:purge（或经 ACP 重存一次）即生效。批量脚本化改配置的固定套路：UPDATE + cache:purge 成对出现。

Q2：config.php 里写了 @define('DEBUG_CONTAINER', true); 要不要保留？

不要。它强制每请求重建服务依赖图，是排障专用；生产环境保持 PHPBB_ENVIRONMENT=production 且该行注释（与 3.3.19 生成状态一致）。

Q3：改了 server_name / 上线 HTTPS 后登录异常或链接还是旧域名。

server_* 四项与 cookie_* 五项共九件套要一起改（见 6.4 节表），cookie_secure 置 1、server_protocol 改 https://，改完清缓存。漏改 cookie_domain 时会出现"登录成功但刷新即掉线"。

Q4：附件上传失败/大小不生效。

三层夹逼：PHP upload_max_filesize（实测 2M）→ PHP post_max_size（实测 8M）→ phpBB max_filesize（实测 262144 字节）。按第七章与 6.8 节顺序对齐，改 php.ini 记得 systemctl restart php8.1-fpm。

Q5：数据库密码换了，论坛报数据库连接错误。

同步改 config.php 的 $dbpasswd（该文件每次请求都会加载，保存即生效）；数据库侧同时确认账号 host 匹配（localhost 与 127.0.0.1 是两条账号记录，见 5.2 节）。

十、参考链接

• 官方配置文档（Board settings 等 ACP 说明）：https://www.phpbb.com/support/docs/en/3.3/ug/
• 3.3.19 包内 docs/INSTALL.html（环境要求与 config.php 权限说明）
• CLI 缓存清理与全部子命令：《phpBB 常用 CLI 命令详解》
• 安装与环境准备：《Ubuntu 22.04 安装 phpBB 指南》
• 选型与架构背景：《phpBB 介绍与选型指南》