LibreKB 2.3.3 配置参数详解

目标：把 LibreKB 2.3.3 的两层配置体系——文件层 config.php（数据库/系统/邮件/错误报告）与数据库层 settings 表（后台五分区 12 个键）——逐字段讲清取值规则、校验行为与生效路径。所有校验与生效结论均为 2026-11-01 在 http://192.168.1.200:8139（LibreKB 2.3.3 + PHP 8.4.27 + MySQL 8.0.46）实测。

一、环境信息

• 软件：LibreKB 2.3.3（version.php 实测 version='2.3.3'、channel='release'）
• 运行时：PHP 8.4.27 / Apache 2.4.69 (Debian) / MySQL Community Server 8.0.46
• 部署形态：Docker Compose（详见《LibreKB 2.3.3 Docker Compose 部署指南》，https://www.quzuo.net/document/D9sq72QJvLb6）
• 配置文件：应用根目录 config.php（由 config.example.php 复制修改）
• 数据库配置表：settings（name/value 两列，安装后初始 12 键）

二、前置条件

1. 已完成部署并通过 /install 安装向导（管理员 admin@kb.example.com / q1w2e3r4）；
2. 具备后台管理会话（所有 settings/* 表单 POST 需携带 csrf_token）；
3. 有应用根目录文件读写权限（改 config.php）与数据库访问权限（直查 settings 表）。

三、参数查看与修改方式

LibreKB 配置分两层，修改方式各不相同：

后台表单带服务端校验，非法值被拒绝且不落库。实测例：把 api_key 改成 15 字符短值后，回读设置页看到 flash 错误且数据库保持原值：

POST(api_key=short) -> HTTP 302
API key must be 16 to 128 characters and may contain only letters, numbers, periods, underscores, tildes, and hyphens. Leave it blank when no key is required.

$ docker exec librekb-233-db mysql -ulibrekb -pq1w2e3r4 librekb -e "SELECT name,value FROM settings WHERE name='api_key';"
name     value
api_key  librekb-demo-key-2026

命令行直查全表：

$ docker exec librekb-233-db mysql -ulibrekb -pq1w2e3r4 librekb -e "SELECT name,value FROM settings ORDER BY name;"
name                 value
api_cors_origin      *
api_enabled          enabled
api_key              librekb-demo-key-2026
custom_css           body{font-size:16px}
editor_toolbar
google_fonts_css_url
kb_visibility        public
maintenance_message
maintenance_mode     disabled
site_color           #1e40af
site_logo
site_name            LibreKB Demo

四、参数总览

• config.php 共 15 个属性：数据库 4（db_host/db_user/db_pass/db_name）+ 系统 2（systemURL/bypassRequirements）+ 邮件 7（mailHost/mailSMTPAuth/mailUsername/mailPassword/mailSMTPSecure/mailPort/mailFrom）+ 构造函数内错误报告策略 1 + docker 探测分支；
• settings 表 12 键：General 2（site_name/kb_visibility）、Appearance 4（site_color/site_logo/custom_css/google_fonts_css_url）、Editor 1（editor_toolbar）、API 3（api_enabled/api_key/api_cors_origin）、Maintenance 2（maintenance_mode/maintenance_message）。

💡 技术拓展：知识库类应用配置形态常见三种——纯文件（DokuWiki 的 dokuwiki.php）、文件+数据库混合（LibreKB、BookStack 的 .env+设置页）、纯数据库（WordPress 全部走 options 表）。LibreKB 把「连不上库就必须能跑」的引导参数放文件层，业务参数放库层，是典型的混合式设计。

五、核心参数分类详解

5.1 config.php：数据库四要素

5.2 config.php：系统项与 docker 探测分支

构造函数内置 /.dockerenv 探测：文件存在（容器环境）时自动套用一组 Docker 默认值，否则走手填分支。官方 config.example.php 的 docker 分支默认是 db_host='librekb-db'、systemURL='http://localhost:8080/'，与官方 compose 的容器名/APP_PORT 默认值一一对应。本部署改写为：

if (file_exists('/.dockerenv')) {
    $this->db_host = 'librekb-233-db';
    $this->db_user = 'librekb';
    $this->db_pass = 'q1w2e3r4';
    $this->db_name = 'librekb';
    $this->systemURL = 'http://192.168.1.200:8139/';
    $this->bypassRequirements = true;
}

⚠️ 注意：该分支优先级高于「标准分支」，容器里改标准分支的值无效；同时 systemURL 与实际访问地址不一致时，前台样式链接和 API 附件绝对 URL 都会指向错误主机。

5.3 config.php：SMTP 邮件七参数

密码重置邮件经 PHPMailer 发出（models/Email.php），七项均在此文件配置：

未配置（保持 X 占位）时，/password/reset 提交后邮件发送失败，但重置流程本身不报错——生产环境务必先测通 SMTP。

5.4 config.php：错误报告与版本通道

configureErrorReporting() 按 version.php 的 channel 决定错误显示：beta 显示全部错误（error_reporting(E_ALL) + display_errors=1），release 全部静默（error_reporting(0)）。实测当前包：

$ docker exec librekb-233-app grep -E "version|channel" /var/www/html/version.php
    public $version;
    public $channel;
        $this->version = '2.3.3';
        $this->channel = 'release';

排障期间可临时把 channel 改为 beta 让白屏暴露 PHP 错误，查完改回。

5.5 General 分区：site_name 与 kb_visibility

private 时前台要求登录，且对 API 有联动影响（见 5.8）。

5.6 Appearance 分区：品牌定制四键

生效实测：保存 custom_css=body{font-size:16px} 后，匿名请求首页即回显该规则：

$ curl -s http://192.168.1.200:8139/ | grep -oE 'font-size:16px' | head -1
font-size:16px

5.7 Editor 分区：editor_toolbar

勾选 TinyMCE 工具栏按钮，存储为 editor_toolbar 单键（序列化字符串）。至少保留一个按钮，否则提示 Choose at least one toolbar button.。空值（默认）使用内置默认工具栏。

5.8 API 分区：api_enabled / api_key / api_cors_origin

关键联动实测：api_key 留空 + kb_visibility=private 时，即使 API 已开启也拒绝访问：

POST(api_key 置空) -> HTTP 302
POST(kb_visibility=private) -> HTTP 302
$ curl -s -w "\nHTTP %{http_code}\n" http://192.168.1.200:8139/api/v1/categories
{"error":"An API key is required when the knowledge base is private."}
HTTP 403

恢复 public+key 后回到 200。密钥比对走 hash_equals(sha256,sha256)，长度恒定，防时序探测。

5.9 Maintenance 分区：maintenance_mode / maintenance_message

开启后前台显示维护页、API 统一 503（实测见《LibreKB 2.3.3 API 使用详解》）；maintenance_message 留空使用默认文案。后台 /admin 不受维护模式影响，管理员可继续操作。

5.10 附件与 PHP 层限制（FileStorage + php.ini）

应用层硬编码（models/FileStorage.php，不可配置）：单文件 MAX_BYTES=10485760（10 MB）、单次最多 MAX_FILES=10 个、扩展名白名单 19 种（pdf/txt/csv/rtf/doc/docx/xls/xlsx/ppt/pptx/odt/ods/odp/png/jpg/jpeg/gif/webp/zip），并用 finfo 实测 MIME 与扩展名交叉校验；php/phtml/exe/sh/js/html/svg 等危险扩展与双重后缀（如 x.php.txt）直接拒绝。

PHP 层限制由官方 Dockerfile 写入 uploads.ini，实测生效值：

$ docker exec librekb-233-app php -i | grep -E "^(upload_max_filesize|post_max_size|memory_limit)"
memory_limit => 128M => 128M
post_max_size => 128M => 128M
upload_max_filesize => 12M => 12M

upload_max_filesize 必须 > 应用层 10 MB（官方取 12M），post_max_size 要覆盖多文件并发上传（官方取 128M）。若上传总体积超过 post_max_size，PHP 会静默丢弃整个请求体，应用检测到后提示 The upload is larger than the server allows. Increase post_max_size and upload_max_filesize, then try again.

六、生产配置模板

适用场景：内网 2–20 人团队知识库，1000 篇以内文章，单实例部署，1 GB 内存 / 10 GB 磁盘起步（MySQL 8.0 空闲占用约 500 MB，LibreKB 本身极轻）。

// config.php（生产：改标准分支或 docker 分支均可，关键是全部显式）
$this->db_host = '127.0.0.1';
$this->db_user = 'librekb';
$this->db_pass = '<强密码，勿复用示例值>';
$this->db_name = 'librekb';
$this->systemURL = 'https://kb.example.com/';
$this->bypassRequirements = false;
$this->mailHost = 'smtp.example.com';
$this->mailSMTPAuth = true;
$this->mailUsername = 'kb-noreply@example.com';
$this->mailPassword = '<SMTP 密码>';
$this->mailSMTPSecure = 'tls';
$this->mailPort = 587;
$this->mailFrom = 'kb-noreply@example.com';

settings 表建议值（后台分区界面操作）：

七、常见问题

7.1 改了 config.php 标准分支但容器里不生效

容器环境命中 /.dockerenv 探测分支，标准分支被跳过。容器部署请改 docker 分支，或注释掉整个 if 判断。

7.2 保存设置报 CSRF 403

后台表单 token 与 session 绑定，跨会话复用旧 token 必 403；脚本化时先 GET 表单页取 csrf_token 再 POST（实测流程见部署指南 4.5 节）。

7.3 API 明明开了却 403

api_key 留空且 kb_visibility=private 的组合行为（403 而非 401），文案 An API key is required when the knowledge base is private.；设置一个 key 即可。

7.4 上传大附件报「exceeds the server upload limit」

先分清两层限制：>10 MB 是应用层 FileStorage 拒绝；≤10 MB 但整包 POST 超 post_max_size 时 PHP 丢请求体，应用提示增大 post_max_size/upload_max_filesize。官方镜像值 12M/128M，改法：覆盖 /usr/local/etc/php/conf.d/uploads.ini 后重载。

7.5 白屏无报错

channel=release 时错误全静默。临时把 version.php 的 channel 改为 beta 复现错误，或查 Apache/PHP-FPM 日志。

八、参考链接

• 源码文件（v2.3.3 实查）：config.example.php、version.php、models/FileStorage.php、models/Database.php、controllers/AdminController.php、controllers/ApiController.php
• 官方仓库：https://github.com/michaelstaake/LibreKB
• 本专栏：《LibreKB 介绍与选型指南》（https://www.quzuo.net/document/0oRDysMn1EDG）、《LibreKB 2.3.3 Docker Compose 部署指南》（https://www.quzuo.net/document/D9sq72QJvLb6）
• PHP 上传限制文档：https://www.php.net/manual/features.file-configuration.php ；TinyMCE：https://www.tiny.cloud