Docker Compose部署BookStack：快速搭建私有知识库的完整指南-尧图网络科技

1. 项目缘起：为什么选择BookStack来搭建个人知识库？

最近在整理手头积累的技术笔记、项目文档和零散想法时，我越来越觉得需要一个统一的、结构化的地方来存放它们。尝试过各种笔记软件，从Notion到Obsidian，各有各的好，但也各有各的“水土不服”。Notion的在线依赖和网络延迟有时让人着急，Obsidian的纯本地和Markdown生态虽然强大，但在团队协作和Web友好分享上又略显繁琐。我的核心需求很明确：一个私有化部署、支持富文本和Markdown、有清晰层级（书-章节-页面）、搜索强大且部署维护简单的知识库系统。

正是在这种背景下，我发现了BookStack。它是一款开源的、自托管的文档和知识库平台，其设计哲学非常像一本真正的书，通过“书架 -> 书 -> 章节 -> 页面”的层级来组织内容，直观又符合逻辑。最关键的是，它原生支持Docker部署，这意味着我可以用一套docker-compose.yml文件，在几分钟内就在自己的服务器（甚至是一台闲置的旧电脑）上拉起一个功能完整、数据完全自主的知识库服务，无需关心复杂的PHP环境配置、数据库初始化等问题。这完美契合了我对“简单可控”的追求。

网络上关于“个人知识库”、“开源知识库”、“docker-compose部署”的讨论热度一直很高，像Obsidian搭建、Dify知识库流水线、各类大模型本地部署（如Ollama、Minimax）等方案层出不穷，这反映了大家对于知识管理和私有化工具的普遍需求。BookStack在其中提供了一个非常成熟、稳定且“开箱即用”的选项，特别适合那些希望快速拥有一个私有知识库，又不愿在环境配置上花费太多精力的个人或小团队。

接下来，我将详细记录我使用Docker Compose部署BookStack的完整过程，包括其中的关键配置、遇到的坑以及一些优化实践。整个过程在Ubuntu 22.04 LTS服务器上完成，但思路同样适用于CentOS、Debian等主流Linux发行版。

2. 部署前的核心准备：理解架构与选型

在动手敲命令之前，我们先花点时间理解一下BookStack的Docker部署架构。这能帮助我们在后续配置和排错时心里有底。

BookStack作为一个典型的LAMP（Linux, Apache, MySQL, PHP）栈应用，在Docker化部署时，通常涉及三个核心服务容器：

应用容器 (bookstack): 运行BookStack本身的PHP代码，包含Apache Web服务器和PHP运行时环境。这是用户直接交互的界面。
数据库容器 (bookstack-db): 运行MySQL或MariaDB，用于存储所有的书籍、页面、用户、设置等结构化数据。
缓存容器（可选，但推荐）: 运行Redis或Memcached，用于会话（Session）存储和页面片段缓存，能显著提升应用响应速度，尤其是在多人协作时。

使用Docker Compose的好处在于，它用一个YAML文件定义了这三个服务之间的关系、网络、数据卷和依赖启动顺序。我们无需手动创建网络、链接容器，一切通过声明式配置完成。

为什么选择官方的linuxserver/bookstack镜像？在Docker Hub上有多个BookStack镜像，例如官方的solidnerd/bookstack和linuxserver/bookstack。我选择了后者（linuxserver/bookstack），主要基于以下几点考虑：

维护活跃: LinuxServer.io团队维护的镜像通常更新及时，跟随上游应用版本发布。
配置友好: 其环境变量配置逻辑清晰，与LinuxServer.io的其他镜像（如Nextcloud、Jellyfin）风格一致，易于理解和管理。
基础镜像可靠: 基于Alpine Linux，镜像体积小，安全性相对较好。

数据库选型：MySQL vs MariaDBBookStack官方支持MySQL和MariaDB。在Docker环境下，两者几乎可以无缝替换。我选择使用mariadb:latest镜像，一是因为它是MySQL的一个流行分支，完全兼容；二是在一些资源受限的环境中，MariaDB的默认配置有时更轻量。当然，使用mysql:8镜像也完全没有问题。

理解了这些，我们的docker-compose.yml文件骨架就有了。接下来，我们进入具体的环境准备和配置环节。

3. 实战部署：从零到一的完整操作流程

3.1 服务器基础环境准备

首先，确保你有一台运行Linux的服务器（本地虚拟机、云服务器、NAS或树莓派均可），并拥有root或具有sudo权限的用户。这里以Ubuntu 22.04为例。

第一步：更新系统并安装必要工具

sudo apt update && sudo apt upgrade -y sudo apt install -y curl git vim

第二步：安装Docker Engine和Docker Compose PluginDocker官方已经推荐使用docker-compose-plugin（即docker compose命令，注意中间没有横线），它作为Docker Engine的一个插件存在，比独立的docker-compose二进制文件更容易管理。

# 安装Docker官方GPG密钥和仓库 curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh # 将当前用户加入docker组，避免每次都要sudo sudo usermod -aG docker $USER # **重要**：执行此命令后，你需要**退出当前终端并重新登录**，或者新开一个终端，用户组变更才会生效。 # 验证Docker安装 docker --version # 安装Docker Compose Plugin (对于使用脚本安装的Docker，通常已包含) # 如果没有，可以手动安装 sudo apt install -y docker-compose-plugin # 验证 docker compose version

注意：docker compose（插件）和docker-compose（独立二进制文件）是两个不同的东西，但命令用法几乎相同。本文统一使用docker compose命令。如果你的环境只有docker-compose，将下文中的docker compose替换为docker-compose即可。

3.2 编写与解析docker-compose.yml文件

这是最核心的一步。在你的服务器上选择一个目录，例如/opt/bookstack，然后创建并编辑docker-compose.yml文件。

sudo mkdir -p /opt/bookstack cd /opt/bookstack sudo vim docker-compose.yml

将以下配置内容粘贴进去。我会逐段解释关键配置项的含义。

version: '3.8' services: bookstack: image: lscr.io/linuxserver/bookstack:latest container_name: bookstack environment: - PUID=1000 - PGID=1000 - TZ=Asia/Shanghai - APP_URL=http://你的服务器IP或域名:6875 - DB_HOST=bookstack-db - DB_USER=bookstack - DB_PASS=你的强密码 - DB_DATABASE=bookstackapp volumes: - ./app_data:/config ports: - "6875:80" depends_on: - bookstack-db restart: unless-stopped networks: - bookstack-net bookstack-db: image: mariadb:latest container_name: bookstack-db environment: - MYSQL_ROOT_PASSWORD=你的root强密码 - MYSQL_DATABASE=bookstackapp - MYSQL_USER=bookstack - MYSQL_PASSWORD=你的强密码（与上面DB_PASS一致） volumes: - ./db_data:/var/lib/mysql restart: unless-stopped networks: - bookstack-net command: --default-authentication-plugin=mysql_native_password networks: bookstack-net: driver: bridge volumes: app_data: db_data:

关键配置项深度解析：

PUID/PGID(1000): 这是LinuxServer镜像的惯例，用于指定容器内运行进程的用户和组ID。通常设置为宿主机上你的非root用户的UID和GID（可通过id -u和id -g查看）。这确保了容器内生成的文件（在/config卷中）的属主正确，方便宿主机直接管理。如果你用root操作，可以设为0，但出于安全考虑，不建议。
TZ: 设置容器时区，保证日志、文件时间戳正确。务必根据你的实际位置修改。
APP_URL:这是最容易出错的地方之一！必须设置为外部访问BookStack时使用的完整URL（包括端口）。例如，如果你打算用IP直接访问，就是http://192.168.1.100:6875；如果用了域名和反向代理（如Nginx），就是https://wiki.yourdomain.com。这个值直接影响BookStack生成链接、重定向和头像URL等，设置错误会导致CSS/JS加载失败或页面循环重定向。
数据库连接参数 (DB_HOST,DB_USER,DB_PASS,DB_DATABASE):DB_HOST直接写服务名bookstack-db，Docker Compose的网络会自动解析。密码请务必使用强密码，并保持bookstack服务中的DB_PASS与bookstack-db服务中的MYSQL_PASSWORD一致。MYSQL_DATABASE和DB_DATABASE也需一致。
数据卷 (volumes):
- ./app_data:/config: 将宿主机当前目录下的app_data文件夹映射到容器的/config，这里存放BookStack的配置文件、上传的图片附件、日志等。即使容器销毁，你的知识和上传的文件也在这里。
- ./db_data:/var/lib/mysql: 将宿主机当前目录下的db_data文件夹映射到容器的数据库数据目录。这是你所有文档内容的数据库存储位置，至关重要。
- 使用相对路径./意味着卷数据保存在docker-compose.yml文件所在的目录。你也可以改为绝对路径，如/data/bookstack/app_data。
端口映射 (ports):"6875:80"将容器的80端口映射到宿主机的6875端口。你可以根据需要修改冒号前的宿主机端口（如8080:80），但要确保防火墙开放该端口。
网络 (networks): 创建一个名为bookstack-net的桥接网络，让bookstack和bookstack-db两个容器在同一个隔离网络内通信，既安全又方便（直接通过服务名访问）。
数据库命令 (command):--default-authentication-plugin=mysql_native_password对于某些版本的MariaDB/MySQL是必需的，以确保与BookStack使用的数据库驱动兼容。

3.3 启动服务与初始化访问

配置好docker-compose.yml后，在/opt/bookstack目录下执行启动命令：

# 启动服务（-d 表示后台运行） docker compose up -d

Docker会自动拉取镜像并启动容器。使用以下命令查看状态：

# 查看容器运行状态 docker compose ps # 或 docker ps # 查看BookStack容器的实时日志，有助于排查启动问题 docker compose logs -f bookstack

当看到日志中出现类似[services.d] done.或BookStack is ready to serve的信息，并且docker compose ps显示所有容器状态为Up时，说明服务已成功启动。

现在，打开浏览器，访问http://你的服务器IP:6875。你应该能看到BookStack的初始化页面，提示你创建管理员账户。

初始化设置步骤：

在首次打开的页面上，设置你的管理员邮箱和密码。这个账户拥有最高权限。
点击“Create Admin Account”。
登录后，系统可能会提示你设置“站点名称”等基本信息，按照向导完成即可。
恭喜！你的个人知识库已经就绪。你可以开始创建第一个书架、第一本书了。

4. 部署后的关键配置与优化实践

部署完成只是第一步，要让BookStack更好用、更安全，还需要进行一些配置和优化。

4.1 配置反向代理与HTTPS（强烈推荐）

直接通过IP和端口访问既不安全也不方便。我强烈建议使用Nginx或Caddy作为反向代理，并配置HTTPS（使用Let‘s Encrypt的免费证书）。

这里以Nginx为例，假设你有一个域名wiki.yourdomain.com指向了服务器IP。

Nginx配置文件示例 (/etc/nginx/sites-available/bookstack):

server { listen 80; server_name wiki.yourdomain.com; # 强制跳转到HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name wiki.yourdomain.com; # SSL证书路径（通过Certbot获取） ssl_certificate /etc/letsencrypt/live/wiki.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/wiki.yourdomain.com/privkey.pem; # SSL优化配置（可参考Mozilla SSL配置生成器） ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512; ssl_prefer_server_ciphers off; # 反向代理核心配置 location / { proxy_pass http://localhost:6875; # 指向Docker Compose映射的端口 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_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; } # 静态文件缓存 location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg)$ { proxy_pass http://localhost:6875; expires 30d; add_header Cache-Control "public, immutable"; } }

配置完成后，创建软链接并测试、重载Nginx：

sudo ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx

获取Let‘s Encrypt SSL证书：

sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d wiki.yourdomain.com

Certbot会自动修改Nginx配置并启用HTTPS。

最后，也是最关键的一步：修改docker-compose.yml中的APP_URL环境变量。

environment: - APP_URL=https://wiki.yourdomain.com # 改为你的HTTPS域名

然后重启BookStack服务：

cd /opt/bookstack docker compose down docker compose up -d

现在，你应该可以通过https://wiki.yourdomain.com安全地访问你的知识库了。

4.2 配置邮件通知（密码重置、用户邀请等）

BookStack的密码重置、新用户注册邀请等功能需要邮件服务。你可以使用SMTP服务（如腾讯企业邮、阿里云邮件推送、SendGrid等）来配置。

编辑BookStack的配置文件。配置文件位于你映射的卷目录下：/opt/bookstack/app_data/www/.env（具体路径根据你的docker-compose.yml设定）。

找到并修改以下配置项（如果不存在则添加）：

MAIL_DRIVER=smtp MAIL_HOST=smtp.your-email-provider.com # 你的SMTP服务器地址 MAIL_PORT=465 # 或 587，根据服务商要求 MAIL_USERNAME=your-email@domain.com MAIL_PASSWORD=your-smtp-password MAIL_ENCRYPTION=ssl # 或 tls MAIL_FROM=your-email@domain.com MAIL_FROM_NAME=BookStack

修改后，需要重启BookStack容器使配置生效：

docker compose restart bookstack

4.3 数据备份策略

你的知识数据是无价的。必须建立可靠的备份机制。

备份方案：

直接备份数据卷目录：最简单直接。定期将/opt/bookstack目录下的app_data和db_data文件夹打包压缩，并传输到另一台机器或云存储。

# 示例备份脚本 backup_bookstack.sh #!/bin/bash BACKUP_DIR="/backup/bookstack" DATE=$(date +%Y%m%d_%H%M%S) SOURCE_DIR="/opt/bookstack" cd $SOURCE_DIR # 停止服务，确保数据库一致性（对于小型知识库，短暂停机可接受） docker compose down # 打包 tar -czf $BACKUP_DIR/bookstack_backup_$DATE.tar.gz app_data/ db_data/ docker-compose.yml # 启动服务 docker compose up -d # 删除7天前的备份 find $BACKUP_DIR -name "bookstack_backup_*.tar.gz" -mtime +7 -delete

然后通过crontab -e设置定时任务，例如每天凌晨2点执行：0 2 * * * /path/to/backup_bookstack.sh

使用mysqldump备份数据库：更轻量，但需要单独备份上传的文件（在app_data/uploads目录下）。

docker exec bookstack-db mysqldump -u bookstack -p你的密码 bookstackapp > /backup/bookstack_db_$(date +%Y%m%d).sql

4.4 性能与维护小贴士

升级BookStack版本：由于使用了latest标签，可以定期执行以下命令来更新到最新镜像：

cd /opt/bookstack docker compose pull # 拉取最新镜像 docker compose down # 停止服务 docker compose up -d # 重新启动，会自动使用新镜像

升级前务必做好备份！

查看日志与排错：

# 查看实时日志 docker compose logs -f bookstack # 查看数据库日志 docker compose logs -f bookstack-db # 查看最近100行日志 docker compose logs --tail=100 bookstack

清理Docker占用的空间：定期清理无用的镜像、容器和缓存。

docker system prune -a --volumes # 谨慎使用，会删除所有未使用的资源，包括未关联的卷 # 更安全的方式是分别清理 docker image prune # 删除悬空镜像 docker container prune # 删除停止的容器

5. 常见问题排查与解决方案

即使按照步骤操作，也可能会遇到一些问题。这里列举几个我遇到过或常见的问题。

问题1：访问页面出现“重定向过多”或CSS/JS无法加载。

原因：APP_URL环境变量设置错误。这是最常见的问题。如果你配置了反向代理和HTTPS，但APP_URL还是http://IP:端口，就会导致此问题。
解决：检查docker-compose.yml中的APP_URL，确保它与浏览器地址栏中访问的URL完全一致（包括http或https）。修改后重启服务。

问题2：启动时数据库连接失败。

原因：数据库容器尚未完全初始化完成，BookStack容器就尝试连接；或者数据库密码不一致。
解决：
1. 检查docker-compose.yml中bookstack和bookstack-db服务的环境变量DB_PASS和MYSQL_PASSWORD是否完全相同。
2. 使用docker compose logs bookstack-db查看数据库容器启动日志，确认MySQL/MariaDB已初始化完毕（看到mysqld: ready for connections）。
3. 可以尝试在bookstack服务配置中添加restart: on-failure或增加depends_on的健康检查条件（需要更复杂的配置），或者简单地先启动数据库，稍后再启动应用。

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

原因：PHP和Web服务器默认对上传文件大小有限制。
解决：需要修改BookStack容器内的PHP配置。可以通过Docker的卷映射覆盖默认配置。
1. 在宿主机/opt/bookstack目录下创建php-overrides.ini文件，内容如下：
```
upload_max_filesize = 50M post_max_size = 50M memory_limit = 256M max_execution_time = 300
```
2. 修改docker-compose.yml中bookstack服务的volumes部分，添加一行映射：
```
volumes: - ./app_data:/config - ./php-overrides.ini:/etc/php8/conf.d/99-overrides.ini # 路径根据镜像内PHP版本可能不同，linuxserver/bookstack通常是php8
```
3. 重启服务：docker compose restart bookstack。

问题4：忘记管理员密码。

解决：通过Docker命令进入应用容器，使用Artisan命令重置密码。

# 进入bookstack容器 docker exec -it bookstack /bin/bash # 在容器内执行密码重置命令，将 admin@example.com 替换为你的管理员邮箱 php artisan bookstack:reset-admin --email=admin@example.com

命令会生成一个新密码并显示在终端，使用新密码登录即可。

部署和运维的过程，其实就是不断解决问题的过程。BookStack的社区和文档都比较活跃，遇到更复杂的问题时，去其 GitHub Issues 或官方文档搜索，通常都能找到答案。这套基于Docker Compose的部署方案，已经为我提供了一个稳定运行了半年多的知识库服务，它让我能更专注于内容的创作和整理，而不是环境的维护。如果你也受困于碎片化的知识管理，不妨花上半小时，给自己搭建一个这样的数字书房。