SMF 2.1.8 配置参数详解

目标：系统梳理 SMF 2.1.8 的两层配置体系——文件层 Settings.php（34 个变量，本文全部实测导出）与数据库层 smf_settings 表（后台「论坛/服务器设置」写入），逐组给出含义、默认值、修改方式与生效验证。本文参数与回显均在 Ubuntu 24.04.5 LTS（x86_64）+ PHP 8.2.35 + MariaDB 11.4.13 的 SMF 2.1.8 实例上实测（2026-11-02）。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• 软件版本：SMF 2.1.8（官方最新稳定版，GitHub tag v2.1.8，2026-10-11 发布，2026-11-02 查询）
• 运行环境：PHP 8.2.35（Apache 模块形态）+ MariaDB 11.4.13
• 论坛目录：/var/www/html（Apache 站点根；Settings.php 位于其中）
• 数据库：库名 smf，账号 smf，表前缀 smf_，共 73 张表
• 演示账号：管理员 admin，密码 q1w2e3r4
• 访问地址：http://192.168.1.172:8138
• 部署方式：本文实例按本专栏部署篇完成；未部署的读者按该篇 4.6 节跑完安装向导即可得到与本文完全一致的 Settings.php

二、前置条件

1. 论坛已完成安装（Settings.php 已由安装向导生成，见本专栏部署篇 4.7 节验证）；
2. 具备论坛目录的文件读写权限（编辑 Settings.php）；
3. 具备数据库访问方式：mariadb -usmf -pq1w2e3r4 smf；
4. 具备管理员账号（后台「服务器设置/论坛设置」页面是改 smf_settings 的推荐入口）。

三、参数查看与修改方式

SMF 的配置分两层，修改入口和生效方式不同：

实测查看文件层全部变量：

grep -E '^\$[a-z_]+ *=' /var/www/html/Settings.php

输出节选（实测首尾，完整清单见「四、参数总览」）：

$maintenance = 0;
...
$db_type = 'mysql';
...
$db_character_set = 'utf8';

实测查看数据库层（共 100+ 键，节选）：

mariadb -usmf -pq1w2e3r4 smf -e \
  "SELECT variable, value FROM smf_settings WHERE variable IN
   ('registration_type','allow_guestAccess','enableErrorLogging','cache_enable','mail_method','timezone','time_format','max_image_width','attachmentEnable','hotTopicsEnable','spiders_enabled') ORDER BY variable;"

实测回显：

variable            value
allow_guestAccess   1
attachmentEnable    1
enableErrorLogging  1
max_image_width     0
time_format         %b %d, %Y, %I:%M %p

💡 说明：未出现在 smf_settings 表里的键表示走代码内置默认值（SMF 只把「改过的/必要的」设置写表）。上表 registration_type、cache_enable、mail_method、timezone、hotTopicsEnable、spiders_enabled 均无行，即当前为默认状态（文件层 $cache_enable = 0 与之呼应）。

修改方式的三种实操：

1. 后台界面：action=admin →「论坛设置 / 服务器设置」各页，保存即写 smf_settings（推荐，带校验）；
2. 编辑文件：vi /var/www/html/Settings.php，只影响文件层；
3. SQL 直改（批量/脚本化场景）：

mariadb -usmf -pq1w2e3r4 smf -e \
  "UPDATE smf_settings SET value='0' WHERE variable='allow_guestAccess';"

实测改后游客访问首页被要求登录（后台「安全与 Mod 设置 → 注册」中对应「允许游客浏览」开关）；验证完毕恢复：

mariadb -usmf -pq1w2e3r4 smf -e \
  "UPDATE smf_settings SET value='1' WHERE variable='allow_guestAccess';"

⚠️ 注意：SQL 直改不会自动清缓存，改完到后台「维护 → 清空所有缓存」或按《SMF 2.1.8 常用 CLI 命令与工具详解》的命令删 cache/ 内文件，否则页面仍读旧值。

四、参数总览

安装向导生成的 Settings.php 实测含 34 个变量，分组如下（默认值列为本文实例实测值）：

五、核心参数分类详解

5.1 数据库连接组

$db_type = 'mysql';        // 可选 mysqli/pgsql；安装向导按所选驱动写死
$db_server = 'db';         // 主机[:端口] 或 socket 路径；数据库独立主机时填其主机名/地址
$db_port = 0;              // 0 = 驱动默认端口（3306）
$db_name = 'smf';
$db_user = 'smf';
$db_passwd = 'q1w2e3r4';   // 演示值；生产改密需同步 UPDATE 用户并重启
$db_prefix = 'smf_';       // 表前缀，同库多论坛靠它隔离
$db_persist = false;       // 持久连接；向导勾选 dbsession 与此无关（那是会话存库）
$db_error_send = false;    // 数据库错误是否邮件给管理员
$db_character_set = 'utf8';// 连接字符集（2.1 安装档案 UTF-8 即此值）

• $db_server 是迁移/排障最常改的项：Web 与数据库不同机时，填 localhost 指向的是 Web 本机，必错；
• $db_mb4 控制 utf8mb4 支持（实测本实例未显式写入，即默认探测）；
• 改连接参数后无需重启：文件即时生效（OPcache 约 2s），实测把 $db_passwd 改错后首页直接报数据库连接错误页，改回即恢复。

5.2 维护模式组（实测三态）

$maintenance = 0;   // 0 正常；1 访客拦截、管理员可进；2 完全关闭
$mtitle = 'Maintenance Mode';
$mmessage = 'Okay faithful users...we\'re attempting to restore an older backup...';

实测行为（同一实例，curl 验证）：

实测 503 响应正文（节选）：

<title>Maintenance Mode
...
older backup of the database...news will be posted once we're back!

⚠️ 注意：$maintenance = 2 是「不可触碰」档——若管理员也登不进，只能回到文件层把值改回 0/1。改回后首页状态码约 2 秒才从 503 变 200（OPcache 文件重校验周期，实测），不要误判为「改了没生效」。

5.3 站点身份与 URL

$mbname = 'My Community';                  // 论坛标题（页面 <title> 前缀）
$boardurl = 'http://192.168.1.172:8138';   // 站点基址，所有站内链接的根
$webmaster_email = 'admin@quzuo.net';      // 系统邮件发件人/联系邮箱
$language = 'english';                     // 默认语言（语言包名）

• $boardurl 必须含协议与对外端口；HTTPS 反代场景填对外 https://域名，否则混合内容/跳转回 HTTP；
• 改 $boardurl 后必须清缓存（实测：清 cache/ 前页面链接仍指向旧值）；
• $webmaster_email 同时是「忘记密码」等系统邮件的发件人，需与 SMTP 域一致否则易进垃圾箱。

5.4 会话与 Cookie 组

$cookiename = 'SMFCookie956';   // 登录 Cookie 名，后缀为 $boardurl 的派生值
$auth_secret = '11ff38eff9479b8a177a762dcc21c4aed2420d2c1c1ad2b7ad6fca689b88125a';

• $auth_secret 是安装时随机生成的登录态签名密钥：泄露等于可伪造管理员会话，禁止提交进版本库、禁止跨站复用；
• 同库多论坛务必让 $cookiename 互不相同（实测本实例为 SMFCookie956，改 $boardurl 端口/域名会改变该派生名）；
• 数据库会话开关在向导第 3 步 dbsession（实测勾选后会话写入 smf_sessions 表，SELECT session_id, last_update FROM smf_sessions 可见活跃行）。

5.5 缓存组

$cache_accelerator = '';      // 可选：redis / apc / memcached / sqlite（空=内置 SQLite 文件缓存）
$cache_enable = 0;            // 0 关闭；1 查询缓存；2 + 数据缓存；3 全部
$cache_memcached = '';        // memcached/redis 服务器串，如 127.0.0.1:11211
$cachedir = '/var/www/html/cache';
$cachedir_sqlite = '/var/www/html/cache';

实测默认（$cache_accelerator='' + $cache_enable=0）：cache/ 目录不写缓存数据文件，仅 .htaccess、index.php、db_last_error.php 三项；删除缓存文件后连续浏览首页/版块/帖子/统计/搜索页均不再生成（实测）。在后台「服务器设置 → 缓存」选择 SQLite 并启用后，cache/ 出现 SQLite3Cache.db3（本实例实测 16 KB，随访问增长）；同一页面也可切 Redis/Memcached 并选启用级别。清缓存 = 删 cache/ 下 *.db3 文件（可再生，命令见《SMF 2.1.8 常用 CLI 命令与工具详解》）。

5.6 图片代理组

$image_proxy_enabled = false;
$image_proxy_secret = 'ba3bc01f876f626e062d';
$image_proxy_maxsize = 5192;   // KB，超限图片不走代理

HTTPS 站点引用 HTTP 外链图片时开启（走 proxy.php，URL 带 HMAC 签名防滥用，实测源码 Sources/Subs.php 中 hash_hmac('sha1', $url, $image_proxy_secret)）。后台「安全」页开关对应写 smf_settings，文件层这三项是底座。

5.7 目录组

$boarddir = '/var/www/html';                 // 论坛根
$sourcedir = '/var/www/html/Sources';        // 代码目录
$packagesdir = '/var/www/html/Packages';     // 软件包工作目录
$tasksdir = '/var/www/html/Sources/tasks';   // 计划任务类

迁移换路径时四项一起改；后台「软件包」安装失败九成是 $packagesdir 不可写（属主须为 Web 进程用户，实测 UID 33）。

5.8 数据库层常用键（smf_settings）

后台界面对应「论坛设置/服务器设置/安全」各页，实测键值节选与含义：

💡 技术拓展：smf_settings 与 Settings.php 的分工是「连接与密钥在文件，业务开关在库」——数据库连不上时论坛仍要靠文件层参数报错/降级，而业务设置量大且需后台热改，故入库。同类软件里 phpBB 的 config.php 是「全文件层」反例，Discourse 则全走环境变量。

六、生产配置模板

6.1 Settings.php 关键项（16GB 内存、单实例、NVMe、日活 ≤5000 场景）

$boardurl = 'https://forum.example.com';
$db_server = '127.0.0.1';
$db_persist = false;
$db_error_send = true;
$cache_accelerator = 'redis';
$cache_enable = 1;
$cache_memcached = '127.0.0.1:6379';
$image_proxy_enabled = true;
$maintenance = 0;

要点：HTTPS 对外 + 本地库 + Redis 查询级缓存（1 级最稳，2/3 级改配置后务必清缓存）+ 图片代理消除混合内容。

6.2 数据库层建议键

6.3 PHP 侧配套（smf.ini 实测项）

upload_max_filesize = 10M
post_max_size = 12M
memory_limit = 256M
max_execution_time = 120

post_max_size 必须 ≥ upload_max_filesize（实测 10M/12M 组合可正常上传 8 MB 附件）。

七、常见问题

Q1：改了 Settings.php 但行为没变？

等 2 秒以上再验（OPcache 重校验周期，实测 503→200 延迟约 2s）；仍无效则确认改的是 Web 进程实际加载的那份文件（多目录部署时注意对应关系，见本专栏部署篇「配置文件挂载」一节）。

Q2：UPDATE smf_settings 后页面不生效？

数据库层设置会被页面缓存。清缓存再验：删 cache/ 内 *.db3，或后台「维护 → 清空所有缓存」。

Q3：论坛整站 503，日志没有错误？

十有八九是 $maintenance 被置 1/2（升级或误操作遗留）。文件层改回 0 即可，实测行为见 5.2 表。

Q4：后台报「Your settings are wrong, or the database is unavailable」？

$db_server/$db_passwd 与库实际不符。先确认 $db_server 填的是数据库主机可达地址而非 localhost；用 mariadb -h<db主机> -usmf -p smf -e 'SELECT 1' 在 Web 进程同机验证连通。

Q5：能否把 Settings.php 纳入 Git 管理？

目录与开关类可以，但 $db_passwd、$auth_secret、$image_proxy_secret 属敏感值，仓库化时须用环境变量注入或 .gitignore 排除该文件（本文演示环境因是隔离测试栈才落明文口令）。

Q6：换域名/加 HTTPS 要动哪些参数？

$boardurl（必须）→ 清缓存 → 后台「Cookie 与安全」核对 $cookiename 派生名 → 若上 HTTPS 打开 $image_proxy_enabled。实测改 $boardurl 后首页 <title> 与资源链接全部指向新值。

八、参考链接

• 官方文档站（Settings.php 说明）：https://docs.simplemachines.org
• SMF 官方仓库：https://github.com/SimpleMachines/SMF
• 官方包内 other/Settings.php（带注释模板）：https://github.com/SimpleMachines/SMF/blob/v2.1.8/other/Settings.php
• 本专栏 CLI 篇：《SMF 2.1.8 常用 CLI 命令与工具详解》（部署与安装向导操作见本专栏部署篇）