Flarum 2.0 配置参数详解

目标：系统讲解 Flarum 2.0 的全部配置载体与参数——站点主配置 config.php、运行时配置 settings 表、PHP-FPM 与 Nginx 层参数，逐项给出来源、默认值、修改方法与生效验证，已在 Ubuntu 22.04.5 LTS + PHP 8.3.36 + MySQL 8.0.46 + Flarum 2.0.2 环境逐项实测通过。

一、环境信息

本篇实测环境（与安装篇同一台服务器，配置参数均可在此环境复现）：

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Web 服务器：Nginx 1.18.0
PHP：8.3.36（FPM + CLI）
数据库：MySQL 8.0.46
Flarum：2.0.2（2026-10-22 实查 GitHub Releases 的最新稳定版）
站点路径：/var/www/flarum（Web root 指向 public/）
论坛地址：http://192.168.146.128
数据库账号：flarum / q1w2e3r4（示例演示口令）

Flarum 的配置分布在四个层面，先建立全局认知再逐层详解：

层面	载体	管什么	修改方式
站点引导层	`config.php`	数据库连接、站点 URL、调试开关、队列驱动	手工编辑文件
运行时配置层	`settings` 表	论坛名称、权限、主题、邮件等一切后台可改项	后台管理界面（推荐）或 SQL
PHP 运行层	`php.ini`（FPM/CLI 两套）	内存、上传体积、执行时长	编辑 ini 后重载 FPM
Web 服务器层	Nginx 站点配置 + `.nginx.conf`	重写规则、静态缓存、gzip	编辑后 reload

二、前置条件

本篇是配置专题篇，不重复安装步骤；开始前请确认以下两项，各给验证命令与实测回显。

已有一套可用的 Flarum 2.0 站点（安装过程见站内《Ubuntu 22.04 安装 Flarum 指南》第四章）：

cd /var/www/flarum && php flarum info | head -3

实测回显：

Flarum core: 2.0.2
PHP version: CLI: 8.3.36, Web: 8.3.36
MySQL version: 8.0.46 (below the recommended MySQL 8.4.0)

能以 flarum 数据库账号直连数据库（settings 表直改演示要用）：

mysql -uflarum -pq1w2e3r4 flarum -e "SELECT COUNT(*) AS tables_cnt FROM information_schema.tables WHERE table_schema='flarum';" 2>/dev/null

实测回显：

tables_cnt
31

三、参数查看与修改方式

3.1 config.php：站点主配置

config.php 位于站点根目录（/var/www/flarum/config.php），由安装向导自动生成，是 Flarum 启动的第一层配置。查看：

cat /var/www/flarum/config.php

实测回显（2.0.2 向导生成的完整内容）：

<?php return array (
  'debug' => false,
  'database' =>
  array (
    'driver' => 'mysql',
    'database' => 'flarum',
    'prefix' => '',
    'prefix_indexes' => true,
    'host' => 'localhost',
    'port' => 3306,
    'username' => 'flarum',
    'password' => 'q1w2e3r4',
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'engine' => 'InnoDB',
    'strict' => false,
  ),
  'url' => 'http://192.168.146.128',
  'paths' =>
  array (
    'api' => 'api',
    'admin' => 'admin',
  ),
  'headers' =>
  array (
    'poweredByHeader' => true,
    'referrerPolicy' => 'same-origin',
  ),
  'queue' =>
  array (
    'driver' => 'sync',
  ),
);

它就是一个返回数组的 PHP 文件，没有独立解析器；改完保存即生效（下一次请求生效，无需清缓存），但改坏 PHP 语法会白屏，所以改动前先备份：cp config.php config.php.bak。

3.2 settings 表：论坛运行时配置

后台管理界面里改的每一项，最终都落到数据库 settings 表（键值对结构）。查看全表：

mysql -uflarum -pq1w2e3r4 flarum -e "SELECT * FROM settings;" 2>/dev/null

实测回显（本站全量 42 键，2.0.2 + 已启用 17 个扩展的状态）：

key                                value
allow_hide_own_posts               reply
allow_post_editing                 reply
allow_renaming                     10
allow_sign_up                      1
allow_user_color_scheme            1
assets_dirty.admin                 1
avatar_driver                      default
color_scheme                       auto
custom_less
default_locale                     en
default_route                      /all
display_name_driver                username
extensions_enabled                 ["flarum-flags","flarum-suspend","flarum-approval","flarum-tags","fof-user-directory","flarum-subscriptions","flarum-sticky","flarum-statistics","flarum-mentions","flarum-markdown","flarum-lock","flarum-likes","flarum-lang-english","flarum-lang-chinese-simplified","flarum-extension-manager","flarum-emoji","flarum-bbcode"]
flarum-markdown.mdarea             1
flarum-mentions.allow_username_format  1
flarum-tags.max_primary_tags       1
flarum-tags.max_secondary_tags     3
flarum-tags.min_primary_tags       1
flarum-tags.min_secondary_tags     0
fontawesome_cdn_url
fontawesome_kit_url
fontawesome_source                 local
forum_description
forum_title                        Quzuo 技术社区
locale_revision                    1792600428.9284
mail_driver                        mail
mail_format                        multipart
mail_from                          noreply@192.168.146.128
slug_driver_Flarum\\User\\User     default
theme_colored_header               0
theme_primary_color                #4D698E
theme_secondary_color              #4D698E
version                            2.0.2
welcome_message                    Enjoy your new forum! Hop over to discuss.flarum.org if you have any questions, or to join our community!
welcome_title                      Welcome to Quzuo 技术社区

💡 说明：extensions_enabled 是扩展开关的白名单 JSON——后台启停扩展就是改这个键；version 记录当前核心版本，升级脚本据此判断迁移；assets_dirty.admin 是资产重建标记（1 表示下次访问需重编译后台资产）。

日常修改以后台管理界面为准（地址 http://192.168.146.128/admin），它同时处理键值写入与缓存重建；SQL 直改是排障与批量场景的备用手段（用法与坑见 3.3、7.2 节）。

3.3 修改生效机制与验证

config.php 与 settings 表的改动都是即时生效的，不需要重启服务。实测验证：把论坛标题改为「Quzuo 演示论坛」后立即请求首页：

mysql -uflarum -pq1w2e3r4 --default-character-set=utf8mb4 flarum \
  -e "UPDATE settings SET value='Quzuo 演示论坛' WHERE \`key\`='forum_title';"
curl -s http://192.168.146.128/ | grep -o '<title>[^<]*</title>'

实测回显：

<title>Quzuo 演示论坛</title>

改回并复验：

mysql -uflarum -pq1w2e3r4 --default-character-set=utf8mb4 flarum \
  -e "UPDATE settings SET value='Quzuo 技术社区' WHERE \`key\`='forum_title';"
curl -s http://192.168.146.128/ | grep -o '<title>[^<]*</title>'

实测回显：

<title>Quzuo 技术社区</title>

要点：

settings 表改动下一次 HTTP 请求即生效（Flarum 每次请求加载 settings 缓存，写入时同步失效缓存），无需 php flarum cache:clear；
php flarum cache:clear 的职责是重建编译产物（LESS、JS bundle、格式化器、视图缓存），适合改了 extend.php、升级版本、资产异常的场景，与改参数无关；
注意 settings 表主键列名是 key（MySQL 保留字），SQL 中必须用反引号包裹；
用 mysql 客户端直改含中文的键值时必须加 --default-character-set=utf8mb4，否则中文会以 latin1 写入导致页面乱码（实测排障过程见 7.2 节）。

四、config.php 参数详解

逐项详解 3.1 节文件中的每个键。改任何一项后无需重启，下一次请求即生效。

4.1 debug：调试模式

类型：布尔，安装向导默认 false。
true 时页面直接显示异常堆栈与详细错误，用于定位 500 白屏、扩展冲突；false 时错误只进 storage/logs/ 日志。
⚠️ 调试模式会向访客暴露路径与代码细节，排障完必须改回 false。

验证方法（开启后首页源码将带调试信息，日志目录同时有写入）：

ls /var/www/flarum/storage/logs/

实测回显：

flarum-2026-10-21.log

4.2 database：数据库连接段

键	实测值	说明
`driver`	`mysql`	驱动名。2.0 起支持 `mysql` / `mariadb` / `pgsql` / `sqlite` 四种；MySQL 与 MariaDB 是独立驱动，必须与服务端真实类型一致，混写会导致连接失败或兼容性异常
`database`	`flarum`	库名
`prefix`	`''`（空）	表前缀，多站共用一个库时才需要，本站未用
`prefix_indexes`	`true`	索引名是否跟随表前缀，保持默认
`host`	`localhost`	走 Unix socket 连接；写 `127.0.0.1` 则走 TCP，跨机部署填数据库服务器 IP
`port`	`3306`	仅 TCP 连接时生效
`username` / `password`	`flarum` / `q1w2e3r4`	数据库账号（演示口令，生产用强口令）
`charset` / `collation`	`utf8mb4` / `utf8mb4_unicode_ci`	字符集与排序规则，支撑 emoji 与中文，勿改小
`engine`	`InnoDB`	存储引擎，Flarum 的外键与事务依赖 InnoDB，勿改 MyISAM
`strict`	`false`	关闭 SQL 严格模式。Flarum 官方默认值，保持不动；某些托管平台强制 strict 可能引发写入报错

连接验证（改后先在命令行确认账号可用，再改文件）：

mysql -uflarum -pq1w2e3r4 -h localhost flarum -e "SELECT 1 AS ok;" 2>/dev/null

实测回显：

ok
1

4.3 url：站点基础 URL

实测值：http://192.168.146.128。这是全站链接（讨论、头像、API、管理后台）的生成基准，安装向导按访问地址自动写入。
换域名/加 HTTPS 时改这里，例如 https://forum.example.com；改后建议顺手跑 php flarum cache:clear 重建含绝对 URL 的资产。
⚠️ url 与实际访问地址不一致时，会出现「页面能开但头像/样式 404」「登录后跳回旧地址」的典型故障。

4.4 paths：路径别名

实测值：api 与 admin，即 API 前缀 /api、管理后台前缀 /admin。
可改为任意不冲突的路径（如把 admin 改成 manage 降低扫描暴露面），改完无需清缓存。

4.5 headers：HTTP 响应头

键	实测值	说明
`poweredByHeader`	`true`	响应头带 `X-Powered-By: Flarum`；安全加固场景建议改 `false`
`referrerPolicy`	`same-origin`	Referrer-Policy 头，限制引用来源外泄，保持默认

实测验证响应头：

curl -sI http://192.168.146.128/ | grep -iE 'x-powered-by|referrer'

实测回显：

X-Powered-By: Flarum
Referrer-Policy: same-origin

4.6 queue：队列驱动

实测值：sync，即同步执行（注册邮件、通知推送等后台任务在请求内直接完成）。
2.0 支持 sync 与数据库队列等驱动；小站用 sync 足够。大流量站点换队列驱动后需另配守护进程消费任务。
队列积压可查表：

mysql -uflarum -pq1w2e3r4 flarum -e "SELECT COUNT(*) AS pending FROM queue_jobs;" 2>/dev/null

实测回显（空队列）：

pending
0

五、settings 表核心参数详解

以下按功能域分组详解 3.2 节实测表中的关键键。除特殊说明，这些键都能在后台管理界面找到对应开关，SQL 值仅作底层对照。

5.1 论坛基本信息

键	实测值	后台位置	说明
`forum_title`	`Quzuo 技术社区`	Appearance → Forum Title	论坛名称，页面 title 与 header 主标题
`forum_description`	（空）	Appearance → Forum Description	论坛一句话简介，SEO 与首页描述用
`welcome_title`	`Welcome to Quzuo 技术社区`	Appearance → Welcome Banner	首页欢迎横幅标题
`welcome_message`	`Enjoy your new forum!...`	Appearance → Welcome Banner	横幅正文，支持 BBCode
`default_locale`	`en`	Basics → Default Language	默认语言。装了简体中文语言包后可在后台切 `zh-Hans`，切换后新用户默认中文
`default_route`	`/all`	Basics → Default Route	登录后首页路由，`/all` 显示全部讨论，可改 `/following` 等
`locale_revision`	`1792600428.9284`	（系统维护）	翻译资源版本号，语言包更新时自动刷新，勿手改

5.2 注册与内容权限

键	实测值	后台位置	说明
`allow_sign_up`	`1`	Basics → Allow Sign Up	是否开放注册。`0` 为仅邀请（管理员后台建号）。实测验证：改 `0` 后注册入口从首页消失
`allow_post_editing`	`reply`	Permissions	用户可编辑自己帖子的窗口：`reply`（直到有人回复）/ `immediately` / `forever`，或数字（秒数）
`allow_hide_own_posts`	`reply`	Permissions	用户可删除自己帖子的窗口，取值同上
`allow_renaming`	`10`	Permissions	用户可改名自己标题的窗口：数字为秒数，`reply`/`immediately`/`forever` 同上。实测值 `10` 表示发帖 10 秒后不能再改标题

5.3 主题外观

键	实测值	后台位置	说明
`theme_primary_color`	`#4D698E`	Appearance → Colors	主色，按钮/链接/高亮
`theme_secondary_color`	`#4D698E`	Appearance → Colors	辅色，Hero 横幅背景渐变
`theme_colored_header`	`0`	Appearance → Colored Header	顶栏是否用主色填充，`0` 白底
`color_scheme`	`auto`	Appearance → Color Scheme	`auto`（跟随系统亮暗）/ `light` / `dark`
`allow_user_color_scheme`	`1`	Appearance	允许用户自选亮暗主题
`custom_less`	（空）	Appearance → Custom Styles	自定义 LESS 样式，后台保存时实时编译进 CSS
`fontawesome_source`	`local`	Appearance → Icons	图标来源：`local`（本地字体文件）或 `cdn`
`fontawesome_cdn_url` / `fontawesome_kit_url`	（空）	Appearance → Icons	CDN/Pro Kit 地址，仅 source 为 cdn 时使用

5.4 邮件

键	实测值	后台位置	说明
`mail_driver`	`mail`	Mail → Driver	邮件驱动。实测默认 `mail`（PHP mail()，仅适合本机有 MTA 的场景）；生产推荐 `smtp`，另有 `mailgun`/`log`（测试用，只写日志不真发）
`mail_format`	`multipart`	（系统维护）	邮件正文格式：multipart 同时含纯文本与 HTML
`mail_from`	`noreply@192.168.146.128`	Mail → Address	发件人地址，默认按站点 URL 生成，生产应改为真实可回信域名邮箱

SMTP 切换示例（后台 Mail 页等价表单）：驱动 smtp、主机 smtp.example.com、端口 587、加密 tls、账号密码填邮箱凭据，保存后用后台「Send Test Mail」验证收信。

5.5 头像、显示名与 URL 别名

键	实测值	说明
`avatar_driver`	`default`	头像存储驱动：`default`（本地 `storage/` 文件）；接入对象存储由扩展提供
`display_name_driver`	`username`	用户显示名策略：`username`（用户名）；装 Nickname 扩展后可切昵称驱动
`slug_driver_Flarum\\User\\User`	`default`	用户 URL slug 生成策略：`default`（用户 ID 数字型，如 `/u/1`）。配合 Slug 扩展可换成拼音/自定义 slug

5.6 扩展参数（扩展名前缀键）

每个启用的扩展会把自己的配置以 <扩展名>.<键> 写进同一张 settings 表。本站实测到的：

键	实测值	说明
`extensions_enabled`	17 个扩展的 JSON 数组	扩展开关白名单。命令行启停扩展（`php flarum extension:enable flarum-tags`）改的就是它
`flarum-tags.max_primary_tags`	`1`	每个讨论最多挂的主标签数
`flarum-tags.min_primary_tags`	`1`	至少要挂的主标签数
`flarum-tags.max_secondary_tags`	`3`	最多挂的副标签数
`flarum-tags.min_secondary_tags`	`0`	至少挂的副标签数
`flarum-mentions.allow_username_format`	`1`	@提及允许用户名格式（`@username`），`0` 时仅 Reply-to-post 引用提及
`flarum-markdown.mdarea`	`1`	编辑器启用 Markdown 区域渲染

💡 说明：扩展级参数与核心参数同表存储，是 Flarum「一张表管全部」的设计——好处是备份/迁移论坛配置只需 mysqldump 一张 settings 表；代价是键名靠约定隔离，删扩展前应先在后台停用（由扩展自行清理键值），避免遗留孤儿键。

六、生产配置模板

以下模板面向「2 核 4GB 内存、NVMe SSD、日活 1k~5k 的中型社区」单机场景，可直接套用（路径与账号按实际替换）：

<?php return array (
  'debug' => false,                        // 生产必须 false
  'database' => array (
    'driver' => 'mysql',                   // MariaDB 服务端改为 'mariadb'
    'database' => 'flarum',
    'prefix' => '',
    'prefix_indexes' => true,
    'host' => 'localhost',
    'port' => 3306,
    'username' => 'flarum',
    'password' => 'q1w2e3r4',              // 生产替换为强口令
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'engine' => 'InnoDB',
    'strict' => false,
  ),
  'url' => 'https://forum.example.com',    // 生产启用 HTTPS 并填正式域名
  'paths' => array (
    'api' => 'api',
    'admin' => 'admin',
  ),
  'headers' => array (
    'poweredByHeader' => false,            // 关闭版本暴露
    'referrerPolicy' => 'same-origin',
  ),
  'queue' => array (
    'driver' => 'sync',                    // 日活过万或邮件量大时评估换队列驱动
  ),
);

配套的 PHP-FPM（/etc/php/8.3/fpm/php.ini）生产建议值（对照实测默认值）：

memory_limit = 256M          ; 默认 128M，后台重建资产/批量操作峰值需要
upload_max_filesize = 20M    ; 默认 2M，附件场景按需
post_max_size = 25M          ; 默认 8M，需大于 upload_max_filesize
max_execution_time = 120     ; 默认 30，升级/迁移脚本时长
opcache.enable = On          ; 默认 On，保持

改 FPM 配置后重载并验证：

systemctl reload php8.3-fpm
php -i | grep -E '^(memory_limit|upload_max_filesize|post_max_size)'

实测回显（默认基线，改后对应项应变为新值）：

memory_limit => 128M => 128M
upload_max_filesize => 2M => 2M
post_max_size => 8M => 8M

⚠️ 生产口令红线：示例中的 q1w2e3r4 仅为演示；真实环境的数据库口令与管理员口令务必使用独立强口令，且 config.php 属主收紧为 www-data（chmod 640 config.php）。

七、常见问题（FAQ）

Q1：改了 config.php 后整站白屏 500？ 九成是 PHP 语法错误（少逗号、中文引号）。先开语法检查：php -l /var/www/flarum/config.php，输出 No syntax errors detected 才算文件没问题；若确实改坏了，用改动前的备份（3.1 节建议的 config.php.bak）回滚。恢复后 curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128/ 应为 200。

Q2：SQL 直改 settings 后页面中文变乱码？ 实测排障实录：把 forum_title 更新为中文后，页面 title 显示为 Quzuo å®žéªŒè®ºå›（UTF-8 字节按 latin1 解读的典型形态）。原因是 mysql 客户端默认连接字符集为 latin1，中文字节被错误转码入库。修复与预防：

# 用显式字符集重写正确的值
mysql -uflarum -pq1w2e3r4 --default-character-set=utf8mb4 flarum \
  -e "UPDATE settings SET value='Quzuo 技术社区' WHERE \`key\`='forum_title';"
curl -s http://192.168.146.128/ | grep -o '<title>[^<]*</title>'

实测回显（已恢复正常）：

<title>Quzuo 技术社区</title>

预防：所有含中文的 SQL 直改都带 --default-character-set=utf8mb4；后台界面操作则无此问题。

Q3：settings 表的 WHERE 条件报语法错误？ settings 的主键列名是 key——MySQL 保留字，SQL 里必须写成 WHERE `key`='forum_title'（反引号包裹），否则报 ERROR 1064 (42000)。

Q4：后台改了参数但前台没变化？ 分三步排查：① 确认改动真的入库：SELECT value FROM settings WHERE \key`='<键名>';；② 浏览器强刷（Ctrl+F5）排除浏览器缓存；③ 若改的是主题色/自定义样式仍不生效，跑 php flarum cache:clear 强制重建前端资产（实测输出会列出 Rebuilt assets 表格，forum.css的 Revision 变为new → 新指纹` 即重建成功）。settings 本身改动即时生效（3.3 节实测），需要清缓存的只有编译类产物。

Q5：换域名/上 HTTPS 后图片和登录异常？ config.php 的 url 还是旧地址所致。改为新 URL（含协议），跑 php flarum cache:clear 重建资产；若 HTTPS 由 Nginx 反代终结，还需确认站点配置把 X-Forwarded-Proto 传给 PHP，否则 Flarum 生成的链接仍会是 http。

Q6：启用扩展时报「The extension could not be enabled」？ 先用 CLI 复现拿完整报错：php flarum extension:enable <扩展ID>（扩展 ID 形如 flarum-tags，可从 php flarum info 的 Extensions 表读取）。常见原因是依赖未启用（如 flarum-tags 依赖 flarum-markdown）或 composer 包未安装（归档安装形态需先装包）。CLI 报错信息比后台界面详细得多。

八、参考链接

Flarum 官方文档 - 安装与配置：https://docs.flarum.org/install/
Flarum 官方文档 - Admin 面板：https://docs.flarum.org/admin/
config.php 与扩展开发参考：https://docs.flarum.org/extend/start
站内配套阅读：《Ubuntu 22.04 安装 Flarum 指南》、《Flarum 2.0 常用 CLI 命令与工具详解》、《Flarum 2.0 介绍与选型指南》