LibreBooking 7.1.0 配置参数详解

目标：以实测运行的 LibreBooking 7.1.0 为样本，逐组讲清 config.php 配置体系的查看方法、参数语义、修改生效方式与生产推荐组合。本文全部参数清单与默认值导出自实测环境的应用配置文件（801 行、15 个配置组），关键行为均经实测验证（API 开关、密码策略、时区、日志）。部署与版本背景见《LibreBooking 7.1.0 Docker Compose 部署指南》。

一、环境信息

二、前置条件

• 已完成部署与安装向导（config.php 已生成），见本站部署篇；
• 具备应用侧文件读写能力：docker compose exec app bash 进入应用，配置目录为 /config（命名卷 lb_config）；
• 演示账号：admin + q1w2e3r4。

三、参数查看与修改方式

3.1 查看当前生效配置

docker compose exec app cat /config/config.php    # 查看全部生效配置（在编排目录执行）

配置为标准 PHP 返回数组，点号键名（如 'api.enabled' 风格的语义）对应嵌套路径 settings['api']['enabled']。管理后台另有可视化配置页（管理员登录 → 系统配置），由 pages.configuration.enabled 控制（默认 true）。

3.2 两条修改通道与生效方式

环境变量映射规则（源码 lib/Config/ConfigKeysMeta.php）：LB_ + 配置键大写、. 换 _，实测样本：script.url→LB_SCRIPT_URL、api.enabled→LB_API_ENABLED、install.password→LB_INSTALL_PASSWORD、database.hostspec→LB_DATABASE_HOSTSPEC、password.upper.and.lower→LB_PASSWORD_UPPER_AND_LOWER、logging.folder→LB_LOGGING_FOLDER。

⚠️ 注意：同一键两处都设置时，环境变量随每次 up -d 重建重新写入 config.php，会覆盖手工编辑结果——同一键不要混用两条通道。

3.3 修改生效实测

以 API 开关为例：默认 api.enabled => false 时接口返回 503（实测报错 "LibreBooking API is disabled"）；改为 LB_API_ENABLED=true 并 up -d 重建后，POST /Web/Services/index.php/Authentication/Authenticate 返回 200 与 "isAuthenticated":true（实测回显）。

四、参数总览

config.php 顶层为一个 settings 数组，含以下 15 个配置组（实测全量清点）：

五、核心参数分类详解

5.1 应用基础

5.2 语言与时区

⚠️ 注意：default.timezone 只影响新排程与显示换算；每个排程自带时区。实测教训：导入示例数据自带的默认排程时区为 America/New_York，跨夏令时边界（2026-11-01）后同一每周周期预约的实例 UTC 时间偏移 1 小时（10-31 实例 06:00Z、11-03 实例 07:00Z）——改 default.timezone 不会修正既有排程，需重建排程。

5.3 前端与访问

5.4 数据库（database 组）

5.5 邮件（phpmailer + email 组）

发信通道：phpmailer.mailer 可选 mail/smtp/sendmail（默认 smtp）；SMTP 常规五件套 host/port/secure(tls/ssl)/auth/username/password，smtp.autotls 默认 true。通知行为由 email 组控制：enabled（默认 true，不发信场景设 false 可避免报错）、default.from.address/name、enforce.custom.template。预约提醒（reservation.reminders.enabled）依赖邮件通道与计划任务（/config/lb-jobs-cron）同时工作。

5.6 日志（logging 组）

5.7 上传与附件（uploads 组）

图片目录 image.upload.directory/url（Web/uploads/images）；预约附件默认关闭（reservation.attachments.enabled=false），开启后落盘 reservation.attachment.path（uploads/reservation），扩展名白名单实测默认 csv,doc,docx,gif,jpeg,jpg,pdf,png,ppt,pptx,txt,xls,xlsx——内网部署建议保持白名单收紧。

5.8 预约策略（reservation + schedule + reservation.notify 组）

预约行为（reservation）——实测核心开关：

排程显示（schedule）：auto.scroll.today（默认 true）、show.week.numbers、hide.blocked.periods、show.inaccessible.resources（默认 true，无权限资源也显示置灰）、reservation.label（默认 {name}，可嵌 {title}/{resourcename}/{att1} 等占位符）、use.per.user.colors、update.highlight.minutes、fast.reservation.load、load.mobile.views。

通知分发（reservation.notify）：12 个开关，按「应用管理员/群组管理员/资源管理员」×「创建/修改/删除/待审批」矩阵独立控制，全部默认 false——上生产按需打开 add 与 approval 两组。

标签模板（reservation.labels）：ics.summary/ics.my.summary、rss.description、my.calendar、resource.calendar、reservation.popup 六个模板键，支持 {name}/{title}/{startdate} 等占位符。

5.9 注册与隐私（registration + privacy 组）

自注册 allow.self.registration 默认 true（内部部署建议关闭，改为管理员建号）；表单可要求/隐藏 phone/position/organization；captcha.enabled 默认 true（注册验证码）；require.email.activation 默认 false；notify.admin 注册通知。隐私组：privacy.view.schedules 默认 true（未登录可看排程框架）、view.reservations 默认 false（未登录只见时段被占不可见详情）、hide.user.details、allow.guest.reservations 默认 false、public.future.days=30。大屏模式 tablet.view.allow.reservations 默认 true。

5.10 密码策略（password 组）

默认策略即报错原文对应的规则，实测改密 q1w2e3r4（无大写、无特殊字符）被拒：Password must contain a combination of at least 8 upper and lower case letters, 1 numbers, and 1 special characters.；设 LB_PASSWORD_UPPER_AND_LOWER=false + LB_PASSWORD_MINIMUM_SPECIALCHAR=0 重建后改密成功（实测 200）。生产建议保留默认策略，仅演示环境放宽。

5.11 安全（recaptcha + security 组）

reCAPTCHA v3 四键（enabled 默认 false + public/private.key + request.method=curl）。安全响应头组默认整体关闭（security.headers=false），开启后下发：strict-transport（max-age=31536000）、x-frame（deny）、x-content-type（nosniff）、content-security-policy（可自定义）——上 HTTPS 后建议打开。

5.12 认证源（authentication + plugins 组）

内置 OAuth 登录源五套，均默认关闭：Google、Microsoft（tenant 默认 common）、Facebook、Keycloak、自定义 OAuth2（authorize/token/userinfo 三端点 + client 凭据），回调路径约定 /Web/{provider}-auth.php。另有 captcha.on.login、required.email.domains（限定注册邮箱域）。

插件挂载（plugins 组，8 个键）——authentication 可选 12 种：ActiveDirectory、Apache、CAS、Drupal、Krb5、Ldap、Mellon、Moodle、MoodleAdv、Saml、Shibboleth、WordPress（实测 /config 下 10 个对应插件配置文件就绪，命名如 Ldap.config.php、Saml.config.php）；其余挂载点：authorization、export、permission、postregistration、prereservation（AdminCheckOnly/PreReservationExample）、postreservation（PostReservationExample）、styling。

5.13 ICS、积分与数据清理（ics + credits + cleanup 组）

ICS 订阅：enabled 默认 true、subscription.key（订阅密钥）、future.days=30/past.days=0。积分系统：credits.enabled 默认 false（配套 allow.purchase）。数据清理 cleanup：years.old.data=3，delete.old.announcements/blackouts/reservations 均默认 false——注意注释明确需要 deleteolddata.php 跑计划任务才会生效。

5.14 REST API（api 组）

💡 技术拓展：api 组的 ro/rw group 设计把「谁能调哪些接口」下沉到群组维度，相当于内置的 API 网关级授权；只需要报表对接时只开 reservations.ro.group 即可，避免整库暴露。API 端点与鉴权头（X-Booked-SessionToken/X-Booked-UserId）的调用实录见本站运维篇。

六、生产配置模板

适用场景：约 4 核 8 GB、200 名内部员工、20 间会议室的会议室预约（内网/VPN 访问）。环境变量保持部署篇最小集，config.php 推荐基线：

return [
    'settings' => [
        'app.title' => '公司会议室预约',
        'app.debug' => false,                    // 生产必须关
        'default.timezone' => 'Asia/Shanghai',
        'default.language' => 'zh_cn',
        'script.url' => 'https://meeting.example.com/Web',
        'install.password' => '',                // 安装完成后留空 = 禁用向导
        'cache.templates' => true,
        'use.local.js.libs' => true,
        'inactivity.timeout' => 30,
        'css.theme' => 'default',
        'database' => [
            'type' => 'mysql',
            'hostspec' => 'db',
            'name' => 'librebooking',
            'user' => 'librebooking',
            'password' => 'q1w2e3r4',            // 演示值，生产换成强口令
        ],
        'email' => [
            'enabled' => true,
            'default.from.address' => 'meeting@example.com',
            'default.from.name' => '会议室预约',
        ],
        'phpmailer' => [
            'mailer' => 'smtp',
            'smtp.host' => 'smtp.example.com',
            'smtp.port' => 587,
            'smtp.secure' => 'tls',
            'smtp.auth' => true,
            'smtp.username' => 'meeting@example.com',
            'smtp.password' => 'q1w2e3r4',       // 演示值，生产换成强口令
        ],
        'logging' => [
            'folder' => '/var/log/librebooking',
            'level' => 'error',
            'sql' => false,
        ],
        'reservation' => [
            'reminders.enabled' => true,         // 需同时配置计划任务
            'start.time.constraint' => 'future',
            'title.required' => true,
        ],
        'reservation.notify' => [
            'application.admin.add' => true,
            'application.admin.approval' => true,
        ],
        'registration' => [
            'allow.self.registration' => false,  // 内部系统关闭自注册
            'captcha.enabled' => false,
        ],
        'privacy' => [
            'view.schedules' => false,           // 未登录不可见
            'view.reservations' => false,
        ],
        'security' => [
            'headers' => true,                   // 已上 HTTPS 时开启
            'x-frame' => 'deny',
            'x-content-type' => 'nosniff',
        ],
        'api' => [
            'enabled' => false,                  // 无对接需求保持关闭
        ],
    ],
];

配套纪律：安装完成后 install.password 置空；管理员口令走默认强策略；数据库密码独立强口令并定期备份（备份流程见本站运维篇）。

七、常见问题（FAQ）

Q1：改了 config.php 不生效？ 改文件后要 docker compose restart app；改的是环境变量则要 docker compose up -d（重建容器）。注意环境变量在重建时会重写 config.php，手工改动会被覆盖（见 3.2 优先级说明）。

Q2：接口 503 "LibreBooking API is disabled"？ api.enabled 默认 false。设 LB_API_ENABLED=true 重建生效（实测 503 → 200）；只读对接可再配合 reservations.ro.group 限定群组。

Q3：改密报密码策略错误？ 默认策略 8 位 + 大小写 + 数字 + 特殊字符（password 组四键）。演示环境可放宽 upper.and.lower 与 minimum.specialchar（实测报错与解法见 5.10），生产保留默认。

Q4：default.timezone 改了，老预约时间还是不对？ 排程自带时区，default.timezone 不回溯既有排程。示例数据排程时区为 America/New_York，跨夏令时边界周期预约偏移 1 小时（实测），需重建本地时区排程。

Q5：安装向导还能被别人访问吗？ install.password 留空即禁用 Web/install 入口（参数注释原文：Leave empty to disable the installation wizard）。安装完成后建议置空并辅以 Web 层封锁。

Q6：预约提醒没发出去？ 三个条件缺一不可：reservation.reminders.enabled=true、邮件通道（phpmailer 组）可用、计划任务在跑（/config/lb-jobs-cron 定义了 lb-jobs 计划任务，容器内需其常驻）。

八、参考链接

1. 配置文档 CONFIGURATION.rst：https://github.com/LibreBooking/librebooking/blob/develop/docs/source/CONFIGURATION.rst
2. GitHub 仓库（lib/Config/ConfigKeysMeta.php 环境变量映射源码）：https://github.com/LibreBooking/librebooking
3. 时区取值列表（PHP 官方）：https://www.php.net/manual/en/timezones.php
4. 官方文档站：https://librebooking.readthedocs.io/en/latest/

站内延伸阅读：版本背景与选型见《LibreBooking 7.1.0 介绍与选型指南》；部署与环境变量入门见《LibreBooking 7.1.0 Docker Compose 部署指南》；巡检备份与排障见《LibreBooking 7.1.0 管理与运维实战》。