BookStack开发环境Docker Compose配置详解

概述

BookStack是一个开源的文档管理和知识库系统，使用PHP和MySQL构建。本文详细解析其开发环境下的Docker Compose配置文件，帮助开发者理解如何快速搭建BookStack的开发环境。

核心服务配置

1. MySQL数据库服务

配置中定义了一个MySQL 8.4数据库服务，专门用于BookStack开发环境：

db:
  image: mysql:8.4
  environment:
    MYSQL_DATABASE: bookstack-dev
    MYSQL_USER: bookstack-test
    MYSQL_PASSWORD: bookstack-test
    MYSQL_RANDOM_ROOT_PASSWORD: 'true'
  volumes:
    - ./dev/docker/init.db:/docker-entrypoint-initdb.d
    - db:/var/lib/mysql

关键点解析：

• 使用官方MySQL 8.4镜像
• 自动创建名为bookstack-dev的数据库
• 创建专用用户bookstack-test并设置密码
• 启用随机root密码增强安全性
• 挂载初始化脚本目录和持久化数据卷

2. BookStack应用服务

应用服务是BookStack的核心，配置如下：

app:
  build:
    context: .
    dockerfile: ./dev/docker/Dockerfile
  environment:
    APP_URL: http://localhost:${DEV_PORT:-8080}
    DB_CONNECTION: mysql
    DB_HOST: db
    DB_PORT: 3306
    DB_DATABASE: bookstack-dev
    DB_USERNAME: bookstack-test
    DB_PASSWORD: bookstack-test
    TEST_DATABASE_URL: mysql://bookstack-test:bookstack-test@db/bookstack-test
    MAIL_DRIVER: smtp
    MAIL_HOST: mailhog
    MAIL_PORT: 1025
  ports:
    - ${DEV_PORT:-8080}:80
  volumes:
    - ./:/app
    - ./dev/docker/php/conf.d/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
  entrypoint: /app/dev/docker/entrypoint.app.sh
  extra_hosts:
  - "host.docker.internal:host-gateway"

开发环境特色：

• 使用自定义Dockerfile构建
• 支持环境变量覆盖默认端口(8080)
• 挂载本地代码到容器实现热更新
• 配置Xdebug用于PHP调试
• 设置host.docker.internal方便容器访问宿主机服务

3. Node.js辅助服务

node:
  image: node:22-alpine
  working_dir: /app
  user: node
  volumes:
    - ./:/app
  entrypoint: /app/dev/docker/entrypoint.node.sh

用途说明：

• 使用Node.js 22 Alpine镜像
• 以非root用户(node)运行
• 挂载本地代码
• 用于前端资源编译和管理

4. MailHog邮件测试服务

mailhog:
  image: mailhog/mailhog
  ports:
    - ${DEV_MAIL_PORT:-8025}:8025

功能特点：

• 提供本地SMTP服务器
• 捕获所有发送的邮件
• 通过Web界面(8025端口)查看邮件
• 支持环境变量自定义端口

开发环境特色功能

1. 热重载开发：通过挂载本地代码目录(./:/app)，开发者可以直接修改本地文件，容器内应用会立即响应变化。

2. 调试支持：通过挂载Xdebug配置文件，为PHP开发者提供了完整的调试能力。

3. 邮件测试：集成MailHog服务，可以捕获所有应用发送的邮件，方便测试注册、密码重置等功能。

4. 前端开发：独立的Node服务容器，支持前端资源的实时编译和热更新。

5. 数据库持久化：使用命名卷(db:/var/lib/mysql)确保数据库数据不会随容器销毁而丢失。

使用建议

1. 启动开发环境前，建议先检查端口冲突，默认使用8080(应用)和8025(邮件)。

2. 数据库初始化脚本应放在./dev/docker/init.db目录下，Docker会在首次启动时执行这些脚本。

3. 对于前端开发，可以直接进入node容器执行npm/yarn命令。

4. 修改PHP配置时，只需编辑本地的xdebug.ini文件，无需重建容器。

5. 邮件服务可通过访问http://localhost:8025查看捕获的邮件。

总结

这份Docker Compose配置为BookStack开发者提供了完整的开发环境解决方案，包含了应用运行所需的所有服务(数据库、应用服务器、前端构建工具和邮件测试服务)。通过合理的容器编排和卷挂载，实现了开发效率的最大化，是BookStack项目开发的重要基础设施。