LibreBooking 7.1.0 管理与运维实战

LibreBooking 7.1.0 运维实战：巡检脚本、mariadb-dump 备份与恢复演练实测、监控告警、升级回滚纪律与九类故障排查实录（含 API 建用户缺陷与夏令时偏移）。

LibreBooking自托管预约调度PHPMariaDB2026/10/30

LibreBooking 7.1.0 管理与运维实战

目标：给已上线的 LibreBooking 7.1.0 一套可落地的日常运维动作——巡检、备份恢复、监控、扩缩容、升级回滚与故障排查手册，全部环节在本团队实测环境（Docker Compose 双服务，入口 http://localhost:8135，运行版本 v7.1.0-27-g1bcf4c7aa）逐条演练并保留真实回显。部署过程见《LibreBooking 7.1.0 Docker Compose 部署指南》，参数语义见《LibreBooking 7.1.0 配置参数详解》。

一、环境信息

项目内容
实测版本LibreBooking v7.1.0-27-g1bcf4c7aa（页脚实显）+ MariaDB 11.8（镜像 11.8.9-MariaDB-ubu2404，dump 头实测）
编排Docker Compose v5.6.1，项目 librebooking-v710-stack，服务 app(8135→8080) + db(3306)
数据卷librebooking-v710-stack_db_data（数据库）、librebooking-v710-stack_lb_config（配置）
数据规模样本57 张表、88 KB 全量 dump（含示例数据与实测预约，见第三节）
演示账号admin + q1w2e3r4

二、日常巡检

2.1 服务与应用巡检

cd /opt/librebooking && docker compose ps     # 双服务应为 Up
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8135/Web/   # 期望 200

实测回显：

NAME                            IMAGE                                           COMMAND                  SERVICE   CREATED          STATUS          PORTS
librebooking-v710-stack-app-1   hub.rat.dev/librebooking/librebooking:develop   "/usr/local/bin/entr…"   app       33 minutes ago   Up 33 minutes   80/tcp, 0.0.0.0:8135->8080/tcp, [::]:8135->8080/tcp
librebooking-v710-stack-db-1    hub.rat.dev/library/mariadb:11.8                "docker-entrypoint.s…"   db        3 hours ago      Up 3 hours      3306/tcp
200

响应头抽查（版本与运行时核对）：Server: Apache/2.4.69 (Debian)、X-Powered-By: PHP/8.5.12（实测）。

2.2 数据库巡检

docker compose exec -T db mariadb-admin -u root -pq1w2e3r4 ping     # 存活探测
docker compose logs db 2>&1 | grep -i 'ready for connections' | tail -2

实测回显：

mysqld is alive
db-1  | 2026-10-30 16:58:01 0 [Note] mariadbd: ready for connections.
db-1  | 2026-10-30 16:58:03 0 [Note] mariadbd: ready for connections.

数据面核对（行数与权限表抽查，实测回显）：

docker compose exec -T db mariadb -u root -pq1w2e3r4 librebooking -e \
  'SHOW TABLES;' | wc -l
docker compose exec -T db mariadb -u root -pq1w2e3r4 librebooking -e \
  'SELECT COUNT(*) AS users FROM users; SELECT COUNT(*) AS series FROM reservation_series;'

58
users  3
series 3

（58 = 表头 + 57 张业务表；3 条预约系列与实测建约记录一致。）

2.3 配置巡检要点

  • 页脚版本号是否与预期 release 一致；
  • /config/config.php 存在且修改时间符合预期（丢失会导致 500，见 7.2）；
  • install.password 是否已置空（向导入口应关闭）；
  • 日志目录有新写入（logging.level=error 时）。

一键巡检脚本骨架：

#!/usr/bin/env bash
set -e
cd /opt/librebooking
docker compose ps | grep -q 'app' && echo '[OK] app running'
curl -sf -o /dev/null http://localhost:8135/Web/ && echo '[OK] web 200'
docker compose exec -T db mariadb-admin -u root -pq1w2e3r4 ping
docker compose exec -T app sh -c 'test -s /config/config.php' && echo '[OK] config.php present'

三、备份与恢复

3.1 备份范围

对象内容方式
数据库（db_data）用户/资源/预约全部业务数据mariadb-dump 全量
配置（lb_config）config.php + 认证插件配置打包 /config
编排docker-compose.yml纳入配置库

3.2 数据库备份（实测）

docker compose exec -T db mariadb-dump -u root -pq1w2e3r4 \
  --single-transaction librebooking > backup-$(date +%F).sql

实测结果：全量 dump 88119 字节、57 个 CREATE TABLE，文件头确认来源：

-- MariaDB dump 10.20-11.8.9-MariaDB, for debian-linux-gnu (x86_64)
-- Host: localhost    Database: librebooking
-- Server version	11.8.9-MariaDB-ubu2404

--single-transaction 保证 InnoDB 一致性快照，业务不中断。

3.3 配置备份（实测）

docker run --rm -v librebooking-v710-stack_lb_config:/data -v $(pwd):/backup \
  hub.rat.dev/library/mariadb:11.8 tar czf /backup/lb-config-$(date +%F).tgz -C /data .

3.4 恢复演练（实测）

恢复到演练库核对行数后再动手，避免直接覆盖生产库：

docker compose exec -T db mariadb -u root -pq1w2e3r4 -e 'CREATE DATABASE lb_restore_test;'
docker compose exec -T db mariadb -u root -pq1w2e3r4 lb_restore_test < backup-2026-10-30.sql
docker compose exec -T db mariadb -u root -pq1w2e3r4 lb_restore_test -e \
  'SELECT COUNT(*) AS users FROM users; SELECT COUNT(*) AS series FROM reservation_series;'
docker compose exec -T db mariadb -u root -pq1w2e3r4 -e 'DROP DATABASE lb_restore_test;'

实测恢复后核对：users 3、series 3，与源库完全一致，演练闭环（演练库已删除）。

正式恢复路径：停应用（docker compose stop app）→ 灌回 librebooking 库 → up -d；必要时重建 db_data 卷后恢复。

3.5 定时备份建议

cron 每日凌晨 dump + 配置打包，保留 7 天滚动 + 每月 1 份长期；恢复演练建议每季度做一次（本文 3.4 即可复用为演练脚本）。

四、监控告警

监控点方法告警条件
Web 可用性curl -sf http://localhost:8135/Web/非零退出/非 200
数据库存活mariadb-admin ping非 "mysqld is alive"
应用错误日志docker compose logs app | grep -i error新增 ERROR
业务日志logging.level=error 时 /var/log/librebooking持续新增错误
提醒任务计划任务（/config/lb-jobs-cron）日志提醒未按时发出
容量水位information_schema 大表查询（下）单表异常膨胀

容量水位实测（前三大表）：

docker compose exec -T db mariadb -u root -pq1w2e3r4 -e \
 "SELECT table_name, ROUND((data_length+index_length)/1024,1) AS kb \
  FROM information_schema.tables WHERE table_schema='librebooking' \
  ORDER BY (data_length+index_length) DESC LIMIT 3;"

table_name               kb
resources                112.0
reservation_instances    96.0
user_resource_permissions 80.0

小样本基线供对比：57 表全库 dump 约 88 KB，业务数据增长主要看 reservation_instances。

五、扩容缩容

  • 架构约束：LibreBooking 是 PHP 单体 + 单库，无官方集群方案（选型篇已述）；纵向扩容是主路径，横向需自行处理会话与数据库层；
  • 应用资源限制（compose 示例，标准 Compose 语法）：
  app:
    mem_limit: 1g
    cpus: 2.0
  • 数据库连接数（MariaDB 镜像标准参数）：
  db:
    command: --max-connections=200
  • 容量收缩：预约历史膨胀可启用数据清理（config.php cleanup 组，需 deleteolddata.php 计划任务配合，见配置篇 5.13）；
  • 会话注意：PHP 会话存于应用本地，重建容器后所有用户需重新登录——扩缩容窗口选低峰，并提前告知。

六、升级与回滚

6.1 升级纪律

LibreBooking 安全修复不回移：老版本无补丁，必须跟进最新 release（仓库顶部两条严重漏洞通告均以"升级到 X 版本以上"为唯一修复方式，见选型篇 3.4）。升级前必做全量备份（第三节）。

6.2 升级步骤

# 1) 备份（见第三节）
# 2) 修改 compose 中 image 标签为目标 release 版本
docker compose pull app
docker compose up -d
# 3) 若系统提示需要数据库升级：进入 /Web/install 按向导完成 schema 升级
#    （安装向导含版本升级脚本步骤，实测安装时 25 步内含升级脚本执行）
# 4) 验证：页脚版本、登录、建资源、建预约各走一遍

6.3 回滚方案

# image 标签改回旧版本后：
docker compose up -d

⚠️ 注意：若新版本已执行过数据库 schema 升级，直接回滚旧镜像可能因表结构不兼容报错——此时用升级前备份恢复数据库（3.2 的 dump 文件）再回滚镜像，这是「先备份后升级」纪律的由来。

七、故障排查手册（实录沉淀）

以下案例全部来自本团队实测排障过程，含症状、定位与解决。

7.1 应用容器退出（Exited (0)），数据库连接拒绝

  • 症状：docker compose ps 中 app 状态 Exited (0)；docker compose logs app 可见数据库连接失败（SQLSTATE HY000 2002 Connection refused）；
  • 定位：MariaDB 尚未就绪时应用已启动并首连失败——纯时序问题，docker compose logs db 里确认 ready for connections 时间晚于 app 启动时间；
  • 解决：数据库就绪后 docker compose up -d 再拉起应用即恢复（实测）；restart: always 策略下应用也会自动重试。

7.2 /Web 返回 500

  • 症状：整站 500；
  • 定位：lb_config 卷被清空/重建，docker compose exec app ls -l /config/config.php 不存在——应用无配置可用；
  • 解决：重跑安装向导（/Web/install），数据库表已在，向导重建配置文件后恢复 200（实测）。

7.3 REST API 返回 503 "LibreBooking API is disabled"

API 默认关闭。LB_API_ENABLED=true 重建应用后恢复（实测 503 → 200）。参见配置篇 5.14。

7.4 改密返回 400 密码策略错误

报错原文（实测照录）：Password must contain a combination of at least 8 upper and lower case letters, 1 numbers, and 1 special characters. 默认策略四键见配置篇 5.10；演示环境放宽 LB_PASSWORD_UPPER_AND_LOWER=false、LB_PASSWORD_MINIMUM_SPECIALCHAR=0 后改密成功（实测 200）。

7.5 REST API 创建用户报 400 "Only application administrators may create users"

  • 症状：管理员会话（DB sessions 表 IsAdmin 实为 1）经 API POST /Web/Services/index.php/Users/ 建用户被拒；
  • 根因（源码定位，develop 分支快照）：ManageUsersService::AddUser 用 ServiceLocator::GetServer()->GetUserSession() 判定管理员——该调用取的是 PHP 会话上下文，REST API 请求运行在 API 会话上下文中，恒判非管理员；
  • 绕过/解决：改走 Web 管理界面建用户。注意管理页 AJAX 动作走 querystring 而非表单体：POST /Web/admin/manage_users.php?action=addUser，表单携带 CSRF_TOKEN 与用户字段，实测建号成功（user_id=3）。生产用 release 版本可规避该 develop 快照缺陷。

7.6 无权限资源预约被拒 400

报错原文（实测照录）：You do not have permission to access one or more of the requested resources. 资源 autoAssignPermissions=false 时须显式授权；授权落点为权限表，实测核对：

docker compose exec -T db mariadb -u root -pq1w2e3r4 librebooking -e \
  'SELECT user_id, resource_id FROM user_resource_permissions WHERE user_id = 3;'

user_id  resource_id
3        1
3        2
3        4
3        5

用户 3 被授权 1/2/4/5 四个资源——对未授权资源（6）发起预约即复现 400，授权后 201，行为与权限表完全对应。

7.7 周期预约跨夏令时偏移 1 小时

  • 症状：同一每周周期规则，实例间 UTC 时间相差 1 小时（实测 2026-10-31 实例 06:00Z、11-03 实例 07:00Z）；
  • 定位：示例数据默认排程时区为 America/New_York，2026-11-01 夏令时结束，墙钟不变、UTC 换算偏移；
  • 解决：重建本地时区（如 Asia/Shanghai）排程；config.php 的 default.timezone 不回溯既有排程（见配置篇 Q4）。

7.8 页面提示 script.url 与实际地址不符

LB_SCRIPT_URL 必须与浏览器实际访问地址（协议+主机+端口+/Web）完全一致；修正后重建应用（实测提示消除）。

7.9 脚本登录返回登录页（HTTP 200）

Web 登录要求先 GET 建立会话，且 POST 必须带完整表单字段（email、password、captcha、resume、login=submit——缺 submit 按钮字段时登录不被处理，实测对比 200/302）。可用性验证推荐改走 API Authenticate（4.4 节回显）。

八、常见问题（FAQ）

Q1：备份文件多大算正常？ 57 张表全量 dump 实测 88 KB（示例数据 + 少量预约）；增长主要看 reservation_instances（实测 96 KB 档位）。长期为 0 或异常膨胀都值得排查。

Q2：恢复到新环境要改什么？ 改 config.php 的 database 组（hostspec/name/user/password）指向新库即可；script.url 按新地址同步（7.8）。

Q3：升级后登录不了？ 先核对页脚版本是否变化成功；再查 /Web/install 是否提示数据库升级未完成；最后用升级前备份回滚（6.3）。

Q4：提醒邮件没发？ 三条件：reservation.reminders.enabled=true、SMTP 通道可用、计划任务常驻（/config/lb-jobs-cron）。逐项核对（见配置篇 Q6）。

九、参考链接

  1. GitHub 仓库与 Releases（升级跟踪）：https://github.com/LibreBooking/librebooking/releases
  2. 安装文档 INSTALLATION.rst：https://github.com/LibreBooking/librebooking/blob/develop/docs/source/INSTALLATION.rst
  3. REST API 文档 API.rst：https://github.com/LibreBooking/librebooking/blob/develop/docs/source/API.rst
  4. 安全通告页（升级依据）：https://github.com/LibreBooking/librebooking/security/advisories
  5. MariaDB 备份文档：https://mariadb.com/kb/en/backup-and-restore-overview/

站内延伸阅读：版本与选型背景见《LibreBooking 7.1.0 介绍与选型指南》；部署实录见《LibreBooking 7.1.0 Docker Compose 部署指南》；参数逐项说明见《LibreBooking 7.1.0 配置参数详解》。