使用Docker Compose部署BookStack：构建私有知识库的完整实践指南

1. 项目概述与核心价值

最近在整理个人项目和团队文档时，一直在寻找一个既美观又实用的知识库系统。要求很简单：能像写书一样结构化地组织内容，支持Markdown，权限管理要清晰，最关键的是部署和维护要足够简单。在试用了不少开源方案后，BookStack进入了我的视野。它完全符合我的需求，而用Docker Compose来部署，更是将“简单”二字发挥到了极致。如果你也在为团队文档分散、知识难以沉淀而头疼，或者想搭建一个私人的读书笔记、项目文档库，那么这次关于BookStack的Docker Compose部署实践，或许能给你提供一个“开箱即用”的参考方案。

BookStack本质上是一个基于PHP Laravel框架开发的开源Wiki平台，但它将自己定位为“一个简单、开箱即用的平台，用于组织和存储信息”。这一定位非常准确，它不像一些功能庞杂的Wiki系统，BookStack的核心就是围绕“书-章节-页面”的层级来管理内容，逻辑清晰，上手极快。通过Docker Compose，我们可以将BookStack及其依赖的数据库（通常是MySQL或MariaDB）打包在一起，用几行配置文件就能在任意支持Docker的服务器上快速拉起一个完整、独立的知识库服务，彻底免去了配置PHP运行环境、安装扩展、处理数据库连接等繁琐步骤。

2. 部署架构与核心组件解析

2.1 为什么选择Docker Compose部署方案？

在部署BookStack时，我们通常有几种选择：传统的手动安装、使用一键脚本、或者容器化部署。我之所以强烈推荐Docker Compose，是基于以下几个核心考量：

首先，环境隔离与一致性。BookStack依赖特定的PHP版本、扩展以及数据库。手动安装时，不同Linux发行版（如Ubuntu、CentOS）的软件源和配置方式差异很大，极易出现“在我机器上好好的，到服务器就不行”的问题。Docker容器将应用及其所有依赖打包成一个独立的运行环境，确保了从开发到测试再到生产，环境完全一致。

其次，简化依赖管理与升级。BookStack需要Web服务器（如Nginx/Apache）、PHP-FPM和MySQL。使用Docker Compose，我们通过一个docker-compose.yml文件就定义清楚了各个服务（Service）之间的关系、网络和存储。升级时，只需拉取新版本的镜像并重启服务，所有依赖都会自动处理，避免了手动升级PHP或数据库可能带来的兼容性风险。

最后，资源可控与易于迁移。通过Compose文件，我们可以精确控制每个容器使用的CPU、内存限制，以及数据卷的挂载路径。整个知识库的数据（数据库和上传的文件）都持久化在宿主机的指定目录下。当需要迁移服务器时，只需要备份这个目录和Compose文件，在新的服务器上安装好Docker和Docker Compose，然后一条命令就能恢复服务，迁移成本极低。

2.2 BookStack Docker部署的组件构成

一个典型的BookStack Docker Compose部署，通常包含两个核心服务：

  1. bookstack服务：这是BookStack应用本身。社区最常用的是LinuxServer.io维护的lscr.io/linuxserver/bookstack:latest镜像。这个镜像已经集成了Nginx、PHP-FPM以及所有必需的PHP扩展（如GD、MySQL PDO、LDAP等），并做好了优化配置，开箱即用。

  2. bookstack-db服务：这是数据库服务。官方推荐使用MySQL或MariaDB。在Docker环境下，我们通常直接使用官方的mysql:8.0或mariadb:10.11镜像。将数据库独立为一个服务，符合应用与数据分离的最佳实践，也方便单独备份和管理数据库。

这两个服务会通过Docker Compose创建的内部网络进行通信。bookstack容器内的应用通过数据库服务名（如bookstack-db）和端口（3306）来连接数据库。所有用户上传的附件、图片以及数据库文件，都会通过“数据卷”持久化保存到宿主机的磁盘上，这样即使删除并重建容器，知识库的内容也不会丢失。

3. 详细部署流程与配置解读

3.1 基础环境准备

在开始之前，你需要一台已经安装好Docker和Docker Compose的Linux服务器。这可以是云服务器、本地虚拟机甚至是NAS设备。以Ubuntu 22.04为例，安装命令如下：

# 安装Docker curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # 将当前用户加入docker组，避免每次用sudo newgrp docker # 刷新用户组，或重新登录生效 # 安装Docker Compose Plugin (推荐，替代旧的docker-compose命令) sudo apt-get update sudo apt-get install docker-compose-plugin

安装完成后，运行docker --version和docker compose version验证是否成功。这里使用的是Docker Compose V2插件，其命令是docker compose（中间有空格），与旧的docker-compose（带横杠）不同，但功能更强，是当前的主流。

接下来，为BookStack创建一个独立的工作目录，所有相关文件都将放在这里：

mkdir -p ~/bookstack && cd ~/bookstack

3.2 编写Docker Compose配置文件

这是整个部署的核心。在~/bookstack目录下，创建一个名为docker-compose.yml的文件。

version: '3.8' services: bookstack: image: lscr.io/linuxserver/bookstack:latest container_name: bookstack environment: - PUID=1000 # 设置容器内运行进程的用户ID，应与宿主机非root用户ID一致 - PGID=1000 # 设置容器内运行进程的组ID - TZ=Asia/Shanghai # 设置时区 - APP_URL=https://wiki.yourdomain.com # 非常重要！你的知识库访问地址 - DB_HOST=bookstack-db - DB_PORT=3306 - DB_DATABASE=bookstack - DB_USERNAME=bookstack - DB_PASSWORD=your_strong_db_password_here # 请务必修改为强密码 volumes: - ./bookstack_app_data:/config # 持久化BookStack配置、缓存、上传的文件 ports: - "8080:80" # 将容器内80端口映射到宿主机8080端口 depends_on: - bookstack-db restart: unless-stopped networks: - bookstack-network bookstack-db: image: mysql:8.0 container_name: bookstack-db environment: - MYSQL_ROOT_PASSWORD=your_very_strong_root_password # 请务必修改 - MYSQL_DATABASE=bookstack - MYSQL_USER=bookstack - MYSQL_PASSWORD=your_strong_db_password_here # 必须与上面bookstack服务中的DB_PASSWORD一致 volumes: - ./bookstack_db_data:/var/lib/mysql # 持久化MySQL数据库文件 command: - --default-authentication-plugin=mysql_native_password # MySQL 8.0兼容性设置 - --character-set-server=utf8mb4 - --collation-server=utf8mb4_unicode_ci restart: unless-stopped networks: - bookstack-network networks: bookstack-network: driver: bridge

关键配置解读与注意事项：

  1. PUID/PGID：这两个参数用于控制容器内进程的文件权限。你需要将其设置为宿主机上你用来运行Docker的普通用户的UID和GID（可通过id -u和id -g命令查看）。这能保证容器内生成的文件（如图片附件）在宿主机上有正确的可读可写权限，避免后续出现权限错误。
  2. APP_URL：这是最容易出错的地方之一。这个环境变量必须设置为用户最终访问你BookStack站点的完整URL（包括http://或https://）。它直接影响站内链接生成、密码重置邮件等功能的正确性。即使你暂时通过IP和端口访问，也应将其设置为最终的域名。如果设置错误，会导致页面样式丢失、链接跳转404等问题。
  3. 数据库密码：DB_PASSWORD和MYSQL_PASSWORD必须完全相同，这是应用连接数据库的凭证。MYSQL_ROOT_PASSWORD是MySQL的root用户密码，用于管理。务必在生产环境中使用高强度、随机的密码。
  4. 数据卷：./bookstack_app_data和./bookstack_db_data是相对路径，意味着会在当前目录（~/bookstack）下创建这两个文件夹，分别保存应用数据和数据库数据。务必定期备份这两个目录。
  5. 端口映射：这里将容器80端口映射到宿主机的8080端口。你可以根据情况修改，例如“80:80”（直接占用80端口，需确保无冲突）或“8443:443”（如果容器内配置了HTTPS）。

3.3 启动服务与初始化

配置完成后，在docker-compose.yml文件所在目录，执行以下命令启动所有服务：

docker compose up -d

-d参数代表在后台运行。Docker会拉取镜像（首次运行）并启动容器。使用docker compose logs -f可以实时查看启动日志，当看到BookStack和MySQL的启动成功信息后，即可进行下一步。

首次访问，打开浏览器，输入http://你的服务器IP:8080。你应该会看到BookStack的安装引导页面。由于我们已经通过环境变量提供了所有数据库配置，所以页面会自动检测并跳转到登录页。

初始管理员账号：

  • 用户名：admin@admin.com
  • 密码：password

请务必在登录后第一时间到“设置”->“用户”中，修改这个默认管理员账号的邮箱和密码！

4. 高级配置与生产环境优化

4.1 配置反向代理与HTTPS（Nginx示例）

直接通过IP和端口访问既不安全也不专业。在生产环境，我们通常使用Nginx或Caddy作为反向代理，并配置HTTPS。

首先，修改docker-compose.yml中的APP_URL为你的域名，例如https://wiki.yourdomain.com。同时，可以注释掉或删除ports映射，改为通过容器网络让Nginx与之通信。

然后，在宿主机上安装并配置Nginx。创建一个新的配置文件，如/etc/nginx/sites-available/bookstack：

server { listen 80; server_name wiki.yourdomain.com; # 你的域名 return 301 https://$server_name$request_uri; # HTTP强制跳转HTTPS } server { listen 443 ssl http2; server_name wiki.yourdomain.com; # SSL证书路径（假设使用Let‘s Encrypt） ssl_certificate /etc/letsencrypt/live/wiki.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/wiki.yourdomain.com/privkey.pem; # 其他SSL优化配置... ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512; ssl_prefer_server_ciphers off; client_max_body_size 100M; # 允许上传大文件，如图片、PDF location / { proxy_pass http://bookstack:80; # 关键！指向Docker Compose网络中的bookstack服务名 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $server_name; # 以下两行对BookStack正确处理URL至关重要 proxy_set_header X-Forwarded-Port $server_port; proxy_redirect off; } }

配置完成后，启用站点并重载Nginx。同时，你需要为域名申请SSL证书，可以使用Certbot自动获取Let‘s Encrypt免费证书。

注意：反向代理配置中，proxy_pass的地址是http://bookstack:80，这里的bookstack是Docker Compose中定义的服务名，Docker的内部DNS会将其解析到对应容器的IP。这要求Nginx容器与BookStack容器在同一个Docker网络中。如果Nginx安装在宿主机上（非容器化），则需要将bookstack改为127.0.0.1:8080（即宿主机映射的端口），并确保APP_URL和代理头设置正确。

4.2 邮件服务配置

BookStack的密码重置、通知等功能需要邮件服务。你可以在BookStack容器内配置SMTP。修改docker-compose.yml中bookstack服务的environment部分，添加以下变量（以QQ邮箱为例）：

environment: - APP_URL=https://wiki.yourdomain.com - DB_HOST=bookstack-db # ... 其他数据库变量 - MAIL_DRIVER=smtp - MAIL_HOST=smtp.qq.com - MAIL_PORT=465 - MAIL_USERNAME=your-email@qq.com - MAIL_PASSWORD=your-smtp-authorization-code # 注意是授权码，非登录密码 - MAIL_ENCRYPTION=ssl - MAIL_FROM_ADDRESS=your-email@qq.com - MAIL_FROM_NAME=BookStack

修改后，运行docker compose up -d重启服务使配置生效。之后可以在管理设置中测试邮件发送。

4.3 数据备份与恢复策略

知识库的数据是无价的。备份主要针对两个部分：

  1. 数据库：存储在./bookstack_db_data卷中。
  2. 上传文件与配置：存储在./bookstack_app_data卷中。

一个简单的备份脚本backup.sh可以这样写：

#!/bin/bash BACKUP_DIR="/path/to/your/backup/folder" DATE=$(date +%Y%m%d_%H%M%S) # 1. 备份数据库（使用docker exec执行mysqldump） docker exec bookstack-db mysqldump -u root -p"$MYSQL_ROOT_PASSWORD" bookstack > "$BACKUP_DIR/bookstack_db_$DATE.sql" # 2. 备份应用数据目录 tar -czf "$BACKUP_DIR/bookstack_app_data_$DATE.tar.gz" -C ~/bookstack bookstack_app_data # 3. （可选）删除7天前的旧备份 find $BACKUP_DIR -name "bookstack_*" -mtime +7 -delete

记得给脚本执行权限chmod +x backup.sh，并通过cron定时任务定期执行（如每天凌晨2点）。

恢复时：

  • 数据库：将备份的.sql文件复制到服务器，然后docker exec -i bookstack-db mysql -u root -p"$ROOT_PASSWORD" bookstack < backup.sql。
  • 应用数据：停止BookStack服务 (docker compose down)，用备份的tar.gz文件覆盖./bookstack_app_data目录，再启动服务 (docker compose up -d)。

5. 常见问题排查与维护心得

5.1 部署与启动常见问题

问题1：访问页面显示“502 Bad Gateway”或“连接被拒绝”。

  • 排查：首先运行docker compose ps查看两个容器状态是否为 “Up”。然后运行docker compose logs bookstack查看应用容器日志。常见原因：
    • 数据库连接失败：检查bookstack容器日志中是否有 “SQLSTATE[HY000] [2002]” 或 “Access denied for user” 错误。这通常是DB_PASSWORD配置不一致或数据库服务未完全启动所致。确保depends_on已设置，且密码完全一致。可以尝试先单独启动数据库容器docker compose up -d bookstack-db，等待30秒后再启动应用。
    • 权限问题：检查宿主机上./bookstack_app_data目录的所有者是否为PUID/PGID指定的用户。运行sudo chown -R 1000:1000 ./bookstack_app_data（假设PUID/PGID为1000）进行修复。

问题2：页面样式丢失，图片不显示，所有链接都是IP地址或错误端口。

  • 几乎可以断定是APP_URL环境变量设置错误。这个变量必须设置为用户浏览器中访问站点的完整基础URL。如果你配置了反向代理并使用域名访问，这里就必须是https://你的域名。修改后，需要重启BookStack容器：docker compose restart bookstack。

问题3：上传文件大小受限。

  • 这涉及两层配置：PHP上传限制和Web服务器限制。
    • LinuxServer.io的BookStack镜像默认PHP上传限制较大，通常不是瓶颈。
    • 关键在反向代理：如前面Nginx配置所示，必须在Nginx的server块中增加client_max_body_size 100M;（或更大）。
    • 如果直接通过端口访问，则需要修改Docker Compose文件，在bookstack服务的环境变量中添加- PHP_UPLOAD_MAX_FILESIZE=100M和- PHP_POST_MAX_SIZE=100M，然后重启。

5.2 日常维护与升级

升级BookStack版本：BookStack的镜像更新比较频繁。升级流程非常安全简单：

cd ~/bookstack # 1. 拉取最新镜像 docker compose pull # 2. 重新创建并启动容器（配置和数据卷保持不变） docker compose up -d # 3. 查看日志确认无异常 docker compose logs -f

注意：在升级前，务必执行一次数据备份。虽然升级过程通常平滑，但备份是必须的安全网。

查看日志与监控：

  • docker compose logs -f：实时查看所有容器日志。
  • docker compose logs bookstack：仅查看应用日志。
  • docker stats：查看容器资源占用（CPU、内存）。

清理无用数据：Docker会占用磁盘空间。定期清理无用的镜像和容器缓存：

# 删除所有已停止的容器、未被任何容器使用的网络、构建缓存 docker system prune -f # 谨慎使用：删除所有未被使用的镜像、卷、网络 # docker system prune -a -f --volumes

5.3 性能调优浅谈

对于小型团队或个人使用，默认配置已足够。如果页面加载缓慢或并发用户较多，可以考虑以下方向：

  1. 数据库优化：确保bookstack-db容器有足够的内存（可通过Compose文件deploy.resources.limits设置）。可以为MySQL容器添加优化参数，例如调整InnoDB缓冲池大小（--innodb-buffer-pool-size=256M）。
  2. PHP OPcache：LinuxServer.io镜像已启用OPcache。你可以通过添加环境变量- PHP_OPCACHE_ENABLE=1（默认已开启）并调整相关内存参数来进一步优化。
  3. 静态资源缓存：在反向代理（Nginx）配置中，对*.css，*.js，*.png，*.jpg等静态资源设置较长的缓存时间。
  4. 硬件资源：为Docker分配足够的CPU和内存资源。对于活跃的知识库，建议服务器至少有2核CPU和2GB以上内存。

经过以上步骤，一个功能完整、运行稳定、易于维护的BookStack知识库就已经部署完成了。这种基于Docker Compose的方式，将复杂的中间件部署抽象成了简单的配置文件，让开发者可以更专注于知识库内容本身的建设。从我的使用体验来看，BookStack的编辑体验流畅，权限体系清晰，非常适合中小型团队或个人作为核心的知识管理工具。