LibreBooking 7.1.0 Docker Compose 部署指南

目标：用 Docker Compose 在单机上完成 LibreBooking 7.1.0（Web 应用 + MariaDB 双服务）的部署、安装向导初始化与管理员账号接管，并沉淀本团队部署全程实测排障结论。已在 Ubuntu 22.04（Docker 29.9.2 + Compose v5.6.1）实测通过：运行版本 v7.1.0-27-g1bcf4c7aa，入口 http://localhost:8135，登录、预约、REST API 全链路可用。软件定位与版本背景见《LibreBooking 7.1.0 介绍与选型指南》。

一、环境信息

二、镜像选型说明

• 应用镜像：官方维护仓库为 LibreBooking/docker，对应 Docker Hub 仓库 librebooking/librebooking（累计拉取量约 150k，2026-10-30 shields.io 徽章取证）。标签策略：develop 跟踪开发分支、随代码构建；生产环境应钉住与最新 Release 对应的版本标签——LibreBooking 安全修复不回移（见选型篇），跑旧版有已知严重漏洞风险；
• 本团队实测说明：实测采用 develop 标签（页脚版本 v7.1.0-27-g1bcf4c7aa，即 7.1.0 后 27 个提交的快照），功能验证完整可用；但该快照存在 REST API 创建用户权限判定的已知缺陷（见 11.4），生产部署请换用 release 版本标签；
• 数据库镜像：官方要求 MySQL ≥ 8.0 或 MariaDB ≥ 10.6，实测选用 mariadb:11.8；
• 拉取加速：Docker Hub 直连受限的网络，可在镜像名前加可用加速前缀（本文以 hub.rat.dev 为例），仅前缀不同、层内容一致。

三、前置条件

• Docker Engine ≥ 20.10 与 Compose v2+（本文用到顶层 name: 字段与 docker compose 子命令）；
• 宿主端口 8135 空闲；
• 能访问镜像源（应用镜像约数百 MB）；
• 一个工作目录，如 /opt/librebooking。

四、部署步骤

4.1 编写 docker-compose.yml

在 /opt/librebooking/docker-compose.yml 写入以下内容（本团队实测原样文件）：

name: librebooking-v7.1.0-stack

services:
  db:
    image: hub.rat.dev/library/mariadb:11.8
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=q1w2e3r4
      - MYSQL_DATABASE=librebooking
      - MYSQL_USER=librebooking
      - MYSQL_PASSWORD=q1w2e3r4
      - TZ=Asia/Shanghai
    volumes:
      - db_data:/var/lib/mysql
    networks:
      librebooking-net:
        ipv4_address: 10.89.63.10

  app:
    image: hub.rat.dev/librebooking/librebooking:develop
    restart: always
    depends_on:
      - db
    environment:
      - LB_INSTALL_PASSWORD=q1w2e3r4
      - LB_DATABASE_USER=librebooking
      - LB_DATABASE_PASSWORD=q1w2e3r4
      - LB_DATABASE_NAME=librebooking
      - LB_DATABASE_HOSTSPEC=db
      - LB_SCRIPT_URL=http://localhost:8135/Web
      - LB_API_ENABLED=true
      - LB_PASSWORD_UPPER_AND_LOWER=false
      - LB_PASSWORD_MINIMUM_SPECIALCHAR=0
      - LB_DEFAULT_TIMEZONE=Asia/Shanghai
      - LB_LOGGING_FOLDER=/var/log/librebooking
      - LB_LOGGING_LEVEL=none
      - LB_LOGGING_SQL=false
    volumes:
      - lb_config:/config
    ports:
      - "8135:8080"
    networks:
      librebooking-net:
        ipv4_address: 10.89.63.11

volumes:
  db_data:
  lb_config:

networks:
  librebooking-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.63.0/24

💡 说明：LB_PASSWORD_UPPER_AND_LOWER=false 与 LB_PASSWORD_MINIMUM_SPECIALCHAR=0 是为放宽默认密码策略、让演示口令 q1w2e3r4 可用而设（默认策略要求大小写+数字+特殊字符，见 11.3）；对外域名部署时把 LB_SCRIPT_URL 换成实际地址（含 /Web 路径）。

4.2 启动与就绪观察

docker compose up -d        # 在 compose 文件所在目录执行
docker compose ps           # 观察两个服务状态

实测 docker compose ps 回显：

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

数据库就绪标志（docker compose logs db 实测行）：

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

看到 ready for connections 即可进行下一步。若 app 因早于数据库就绪而退出，见 11.1。

4.3 运行安装向导

浏览器打开 http://localhost:8135/Web/install：

1. 输入安装口令：即环境变量 LB_INSTALL_PASSWORD 的值（本栈为 q1w2e3r4）；
2. 数据库信息由 LB_DATABASE_* 预填：数据库主机 db、用户/密码/库名 librebooking，勾选导入示例数据（自带默认排程、示例资源与 admin 示例账号）；
3. 点击执行安装。本团队实测 25 个步骤全部 Success（建库表结构、版本升级脚本、示例数据导入、写配置文件等）。

⚠️ 注意：安装完成后应删除或封锁 Web/install 路径（migrate.php 曾有未授权管理员接管漏洞 GHSA-3356-vjx2-5pg8，7.0.0 已修复但该目录日常无需保留对外可访问）。

4.4 登录验证

示例数据导入后，内置管理员账号为 admin，默认密码是 password（注意不是安装口令 q1w2e3r4，本团队实测验证）。浏览器登录 http://localhost:8135/Web 即可；命令行验证登录链路（先 GET 拿会话，再完整提交表单字段）：

curl -s -c /tmp/lb_cookies.txt http://localhost:8135/Web/ -o /dev/null
curl -s -o /dev/null -w 'login HTTP %{http_code} -> %{redirect_url}\n' \
  -b /tmp/lb_cookies.txt -c /tmp/lb_cookies.txt \
  --data-urlencode 'email=admin' --data-urlencode 'password=password' \
  --data-urlencode 'captcha=' --data-urlencode 'resume=' \
  --data-urlencode 'login=submit' http://localhost:8135/Web/index.php

实测回显（登录成功跳转）：

login HTTP 302 -> http://localhost:8135/Web/dashboard.php

REST API 认证验证（LB_API_ENABLED=true 时可用）：

curl -s -X POST http://localhost:8135/Web/Services/index.php/Authentication/Authenticate \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"password"}'

实测回显（节选）：

{
  "sessionToken": "dfa7f5672885bf6e...",
  "sessionExpires": "2026-10-30T12:32:51+0000",
  "userId": "2",
  "isAuthenticated": true,
  "version": "4"
}

4.5 接管管理员账号

首次登录后立即改密：Web 端在「我的资料」修改，或走 API（POST /Web/Services/index.php/Accounts/{userId}/Password，字段 currentPassword/newPassword，实测返回 200 与 "userId":"2"）。本演示环境将 admin 口令统一改为 q1w2e3r4，因此 compose 中预置了两条策略放宽变量（见 4.1 说明）；若保留默认策略，新口令需满足「8 位以上 + 大小写 + 数字 + 特殊字符」。改密后示例数据中其余演示账号（user 等）建议全部改密或停用。

五、数据持久化说明

实测 docker volume ls（节选）：

librebooking-v710-stack_db_data
librebooking-v710-stack_lb_config

两个命名卷均独立于容器生命周期：docker compose down / up -d / 应用镜像升级重建后，预约数据与配置均保留（本团队实测：应用容器多次重建，资源与预约记录不丢）。docker compose down -v 会连卷一起删除，仅确认放弃数据时使用。

六、环境变量表

LibreBooking 镜像通过 LB_* 环境变量覆盖配置，映射规则：LB_ + 配置键名大写、. 换成 _（源码 lib/Config/ConfigKeysMeta.php）。本栈实测变量：

app 服务（LibreBooking）

db 服务（MariaDB 官方变量）：MYSQL_ROOT_PASSWORD、MYSQL_DATABASE、MYSQL_USER、MYSQL_PASSWORD、TZ。

未设置的配置项使用镜像内置默认值；改环境变量后需 docker compose up -d 重建应用生效。运行期细粒度参数（注册开关、附件、隐私、提醒等）在 config.php 层调整，见本站《LibreBooking 7.1.0 配置参数详解》。

七、配置参数说明

部署期有两层配置：

1. 环境变量（本篇第六节）：随容器启动注入，安装向导执行时会将其落成 /config/config.php（实测该文件 27953 字节、www-data 属主、修改时间与向导执行时间一致）；
2. config.php（运行期）：新体系为分组数组（database、settings.password、api、logging 等段），是后续运维调参的主战场；认证插件另有独立配置文件（见第八节）。

💡 说明：修改 config.php 后执行 docker compose restart app 生效；改环境变量则需 up -d 重建。两处同键时环境变量优先级更高，避免混用同一键。

八、配置文件挂载

lb_config:/config 命名卷承载全部配置文件，实测目录结构：

/config
├── config.php                 # 主配置（安装向导生成，27953 字节）
├── lb-jobs-cron               # 计划任务（预约提醒等）定义
├── ActiveDirectory.config.php # 认证插件配置（按需启用）
├── CAS.config.php
├── Drupal.config.php
├── Ldap.config.php
├── Mellon.config.php
├── Moodle.config.php
├── MoodleAdv.config.php
├── Saml.config.php
├── Shibboleth.config.php
└── WordPress.config.php

改用宿主机目录（bind mount）便于版本管理与备份，把卷行替换为：

    volumes:
      - ./config:/config

注意：配置文件属主需为 www-data（应用运行用户）且可写，否则安装向导无法落盘 config.php。

九、等价 docker run

单容器启动应用（需自行提供数据库并保证同网络可达）：

docker run -d --name librebooking -p 8135:8080 \
  -e LB_INSTALL_PASSWORD=q1w2e3r4 \
  -e LB_DATABASE_HOSTSPEC=172.17.0.1 \
  -e LB_DATABASE_USER=librebooking \
  -e LB_DATABASE_PASSWORD=q1w2e3r4 \
  -e LB_DATABASE_NAME=librebooking \
  -e LB_SCRIPT_URL=http://localhost:8135/Web \
  -e LB_DEFAULT_TIMEZONE=Asia/Shanghai \
  -v librebooking_lb_config:/config \
  librebooking/librebooking:develop

生产不建议裸 docker run：数据库就绪时序、配置持久化、升级重建都由 Compose 编排统一处理更稳妥（数据库自身的 docker run 起法略）。

十、常用运维命令

docker compose ps                      # 服务状态（在编排目录执行）
docker compose logs -f app             # 跟踪应用日志
docker compose logs db | grep -i ready # 数据库就绪确认
docker compose restart app             # 应用重启（config.php 变更后）
docker compose up -d                   # 环境变量/镜像变更后重建
docker compose down                    # 停止并删容器与网络（保留数据卷）
docker compose down -v                 # ⚠️ 连数据卷一起删除，弃用数据时才用
docker compose exec app bash           # 进入应用排障
docker compose exec db mariadb -u librebooking -p librebooking   # 进库核对

数据库备份一条命令（宿主机落盘）：

docker run --rm -v librebooking-v710-stack_db_data:/data -v $(pwd):/backup \
  hub.rat.dev/library/mariadb:11.8 \
  sh -c 'mariadb-dump -h localhost -u root -p"$MYSQL_ROOT_PASSWORD" --single-transaction librebooking' 2>/dev/null

💡 说明：dump 建议改用 docker compose exec db mariadb-dump ... 直接执行并重定向到宿主机文件；完整巡检/备份恢复/升级回滚流程见本站《LibreBooking 7.1.0 管理与运维实战》。

十一、常见问题（FAQ）

Q1：docker compose ps 里 app 状态是 Exited (0)，日志出现数据库连接拒绝？ 这是 MariaDB 就绪时序问题：应用比数据库先启动，首次连接失败（日志可见 SQLSTATE HY000 2002 Connection refused）。排障顺序：docker compose logs db 确认 ready for connections 后，再 docker compose up -d 拉起应用即可恢复（本团队实测即如此解决）。restart: always 策略下应用也会自动重试拉起。

Q2：访问 /Web 返回 500？ 实测成因：lb_config 卷被清空/重建后 /config/config.php 丢失，应用无配置可用。解决：重跑安装向导（http://localhost:8135/Web/install），数据库表已在、只需重建配置文件，向导执行完即恢复 200（实测）。

Q3：改密码报「Password must contain a combination of at least 8 upper and lower case letters, 1 numbers, and 1 special characters.」？ 默认密码策略要求 8 位以上且同时含大小写、数字、特殊字符。为让 q1w2e3r4 这类演示口令可用，在 compose 中设 LB_PASSWORD_UPPER_AND_LOWER=false、LB_PASSWORD_MINIMUM_SPECIALCHAR=0，docker compose up -d 重建后生效（实测改密返回 200）。生产环境建议保留默认策略而不是放宽。

Q4：/Web/Services/ 接口返回 503「LibreBooking API is disabled」？ REST API 默认关闭。compose 加 LB_API_ENABLED=true 重建应用即可（实测 503 → 200）。不用 API 的部署保持默认关闭更安全。

Q5：页面提示 script.url 与实际访问地址不符？ LB_SCRIPT_URL 必须与浏览器实际访问地址完全一致（协议+域名/端口+/Web 路径）。本栈实测取 http://localhost:8135/Web；换域名部署时同步修改并重建。

Q6：安装口令 q1w2e3r4 登录不上后台？ 安装口令只用于安装向导，不是登录口令。导入示例数据时内置管理员是 admin / password（实测），首次登录后立即改密。

Q7：项目名怎么变成 librebooking-v710-stack 了？ 顶层 name: librebooking-v7.1.0-stack 中的点号不合法，Compose 自动去除——容器、卷、网络实测前缀均为 librebooking-v710-stack-*。docker compose down -v 在编排目录内执行即可正确匹配，无需手工指定 -p。

十二、参考链接

1. 官方容器编排仓库：https://github.com/LibreBooking/docker
2. Docker Hub 镜像：https://hub.docker.com/r/librebooking/librebooking
3. 安装文档 INSTALLATION.rst：https://github.com/LibreBooking/librebooking/blob/develop/docs/source/INSTALLATION.rst
4. 配置文档 CONFIGURATION.rst：https://github.com/LibreBooking/librebooking/blob/develop/docs/source/CONFIGURATION.rst
5. GitHub 仓库：https://github.com/LibreBooking/librebooking

站内延伸阅读：软件定位、功能与竞品对比见《LibreBooking 7.1.0 介绍与选型指南》；配置参数逐项说明见《LibreBooking 7.1.0 配置参数详解》；日常巡检、备份恢复与故障排查见《LibreBooking 7.1.0 管理与运维实战》。