跳转到主要内容

BookStack Docker 安装手册

基于 LinuxServer.io 镜像，在 Docker 中快速搭建个人/团队知识库，并启用 TOTP 双因素认证（2FA）。 适用：Docker 20+ / Compose v2，x86-64 与 ARM64（树莓派、飞腾等）均可运行。

目录

一、简介与架构

BookStack 是一个自托管的开源 Wiki / 文档平台（MIT 协议，基于 Laravel + PHP），组织方式为：

书架（Shelf） → 书（Book） → 章节（Chapter） → 页面（Page）

支持 Markdown、富文本、附件、全文搜索、角色权限、LDAP/SAML/OIDC 认证。

容器架构（本手册方案）：

┌─────────────────────────────────────────┐
│  宿主机 / 反向代理（Nginx/Caddy，可选）   │
└──────────────┬──────────────────────────┘
               │ :6875
┌──────────────┴──────────────┐   ┌──────────────────────┐
│  bookstack（应用容器）        │───│  mariadb（数据库容器） │
│  lscr.io/linuxserver/        │   │  mariadb:10.11       │
│  bookstack:latest            │   └──────────────────────┘
│  /config → 宿主机持久化        │
└─────────────────────────────┘
组件 说明
应用镜像 lscr.io/linuxserver/bookstack（多架构，自动匹配 x86/ARM）
数据库 MariaDB 10.11（BookStack 官方支持 MySQL/MariaDB）
持久化 应用 /config、数据库 /var/lib/mysql 均挂载宿主机目录
端口 容器内 80 → 宿主机 6875（可自定义）

二、环境准备

# 确认 Docker 与 Compose 已安装
docker --version
docker compose version

# 创建专用目录
mkdir -p ~/bookstack && cd ~/bookstack

💡 时区建议设置为 Asia/Shanghai，见下文环境变量。 查看当前用户 UID/GID（用于 PUID/PGID）：id $USER，一般为 1000/1000。

三、快速安装（docker compose）

3.1 生成 APP_KEY（必做）

APP_KEY 是 Laravel 的应用加密密钥，首次启动前必须生成并填入，否则容器初始化会中断。它也用于加密 2FA 凭据，迁移/恢复时必须有它。

docker run -it --rm \
  --entrypoint /bin/bash \
  lscr.io/linuxserver/bookstack:latest \
  appkey

输出形如 base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx，复制保留（包含 base64: 前缀）。

3.2 编写 docker-compose.yml

在 ~/bookstack/ 下创建 docker-compose.yml：

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    restart: unless-stopped
    ports:
      - "6875:80"
    environment:
      PUID: "1000"
      PGID: "1000"
      TZ: "Asia/Shanghai"
      APP_URL: "http://localhost:6875"   # 有域名/反代后改为 https://your.domain
      APP_KEY: "base64:粘贴上面生成的密钥"
      DB_HOST: bookstack-db
      DB_PORT: "3306"
      DB_DATABASE: bookstack
      DB_USERNAME: bookstack
      DB_PASSWORD: "改成强密码"          # 需与 mariadb 中一致
      # QUEUE_CONNECTION: database       # 如需异步邮件/Webhook 取消注释
    volumes:
      - ./bookstack_data:/config
    depends_on:
      - bookstack-db

  bookstack-db:
    image: mariadb:10.11
    container_name: bookstack-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: "改成root强密码"
      MYSQL_DATABASE: bookstack
      MYSQL_USER: bookstack
      MYSQL_PASSWORD: "改成强密码"       # 与上方 DB_PASSWORD 完全一致
    volumes:
      - ./db_data:/var/lib/mysql
    # 数据库无需对外暴露端口，仅供内网容器访问
    # ports:
    #   - "3306:3306"

⚠️ 三个必须一致：DB_PASSWORD = MYSQL_PASSWORD；DB_USERNAME = MYSQL_USER；DB_DATABASE = MYSQL_DATABASE。 ⚠️ 密码若含特殊字符，在 YAML 中务必加引号。

3.3 启动与初始化

cd ~/bookstack
docker compose up -d

# 查看日志，等待 "Application ready" 之类提示
docker compose logs -f bookstack

启动后访问 http://服务器IP:6875。

四、首次登录与安全加固

默认管理员账号（首次登录后立即修改）：

邮箱：admin@admin.com
密码：password

登录后依次操作：

  1. 右上角头像 → Settings → Users，编辑 admin 用户，修改邮箱和密码。
  2. Settings → Features & Security：
    • 关闭「允许公开注册」Allow public registration（个人使用建议关闭）。
    • 按需设置「默认角色」。
  3. Settings → General：设置应用名称、语言（中文在 Codeberg 有社区翻译，可在 Languages 中切换）。

🔒 生产环境务必通过反向代理配置 HTTPS，并将 APP_URL 改为 https:// 开头后重启。

五、启用双因素认证（2FA / TOTP）

BookStack v21.08 起原生支持双因素认证，无需额外插件 [citation:3]。支持两种机制 [citation:6][citation:9]：

方式 说明
TOTP（"Mobile App"） 使用 Google / Microsoft / Authy 等认证器 App 扫码，基于时间的一次性密码（SHA1，兼容性最佳）
Backup Codes（备份码） 16 个一次性备用码，剩余 < 5 个时会提醒重新生成

5.1 为当前账户启用 2FA

  1. 右上角头像 → My Account → Security（或直接访问 /mfa）。
  2. 点击 Setup Multi-Factor Authentication。
  3. 选择 Mobile App（TOTP） → 用认证器 App 扫描二维码 → 输入 App 中生成的 6 位码 → Confirm and Enable。
  4. （可选）再启用 Backup Codes，将 16 个码安全保存（下载/离线存储），每个仅能用一次。

此后每次登录，输入账号密码后，还需输入动态验证码。

5.2 强制所有用户启用 2FA（按角色）

进入 Settings → Roles，编辑目标角色（如 Admin / Default），勾选：

☑ Requires Multi-Factor Authentication
  • 已勾选角色的用户，下次登录时会被强制要求至少配置一种 2FA 方式 [citation:3][citation:6]。
  • 适合个人/团队强制安全策略。

5.3 忘记 2FA / 迁移恢复

若丢失认证器，可在宿主机执行命令清除某用户的 MFA（需进入容器）：

docker exec -it bookstack \
  php /app/www/artisan bookstack:reset-mfa --email=admin@example.com

🔐 务必保管好 APP_KEY：2FA 密钥加密存储在数据库中，迁移/恢复实例时必须使用同一把 APP_KEY，否则无法解密 [citation:3]。

六、反向代理 + HTTPS

推荐用 Nginx Proxy Manager 或 Caddy 做反代 + 自动证书。以 Caddy 为例（Caddyfile）：

wiki.yourdomain.com {
  reverse_proxy localhost:6875
}

Nginx 关键配置：

location / {
  proxy_pass http://localhost:6875;
  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;
}

改完 APP_URL 后重启应用：

# 若 URL 已初始化，需同步数据库中的旧值
docker exec -it bookstack \
  php /app/www/artisan bookstack:update-url "http://old-url" "https://new-url"

docker compose restart bookstack

七、SMTP 邮件配置

在 bookstack 服务的 environment 中追加（以 Gmail 为例）：

MAIL_DRIVER: smtp
MAIL_HOST: smtp.gmail.com
MAIL_PORT: "587"
MAIL_ENCRYPTION: tls
MAIL_USERNAME: "your@gmail.com"
MAIL_PASSWORD: "应用专用密码"
MAIL_FROM: "bookstack@yourdomain.com"
MAIL_FROM_NAME: "BookStack"

修改后 docker compose up -d 重启生效。邮件用于注册验证、密码找回、导出通知等。

八、数据备份与迁移

BookStack 数据由两部分组成：数据库 + 上传文件（/config）。

8.1 应用内导出（简单）

BookStack 自带 Export / API，可在页面级导出为 HTML / PDF / Markdown。

8.2 文件系统级备份（完整）

cd ~/bookstack

# 1. 备份数据库（推荐先停写或锁表，个人使用可直接导）
docker exec bookstack-db \
  mariadb-dump -u root -p"root密码" bookstack > bookstack_db_$(date +%F).sql

# 2. 备份上传文件与配置
tar czf bookstack_config_$(date +%F).tar.gz bookstack_data/

# 3. 记录当前 APP_KEY（.env 中的值）

8.3 迁移到新机器

  1. 新机用同一份 docker-compose.yml（尤其 APP_KEY 保持一致）启动。
  2. 恢复数据库：docker exec -i bookstack-db mariadb -u root -p bookstack < backup.sql。
  3. 解压 bookstack_data/ 覆盖 /config。
  4. 重启：docker compose restart。

九、常用维护命令

# 启动 / 停止 / 重启
docker compose up -d
docker compose down               # 停止（保留数据卷）
docker compose down -v            # ⚠️ 连同数据卷删除，谨慎
docker compose restart bookstack

# 查看状态与日志
docker compose ps
docker compose logs -f bookstack

# 进入容器
docker compose exec bookstack bash

# 更新到新版本
docker compose pull
docker compose up -d

# 生成新 APP_KEY（仅首次/迁移用）
docker run -it --rm --entrypoint /bin/bash \
  lscr.io/linuxserver/bookstack:latest appkey

# 修改 URL（迁移/换域名后）
docker exec -it bookstack \
  php /app/www/artisan bookstack:update-url "旧URL" "新URL"

# 清除某用户 2FA
docker exec -it bookstack \
  php /app/www/artisan bookstack:reset-mfa --email=user@example.com

十、故障排查

问题 可能原因 / 解决
启动后访问空白 / 重定向异常 APP_URL 与实际访问地址不一致，检查协议+端口 [citation:2]
提示 APP_KEY 缺失或启动中断 未生成密钥，按 3.1 生成并填入 [citation:5]
数据库连接失败 密码/用户名不一致、数据库容器未就绪；检查 docker compose logs bookstack-db [citation:10]
权限问题（无法写文件） PUID/PGID 与宿主机目录属主不一致，执行 sudo chown -R 1000:1000 bookstack_data [citation:2]
迁移后图片链接失效 绝对地址含旧域名，用 bookstack:update-url 更新，或批量替换数据库
忘记 admin 密码 进入数据库重置，或配置 SMTP 走「找回密码」
丢失 2FA 无法登录 用宿主机执行 bookstack:reset-mfa 清除（见 5.3）
上传文件大小受限 调整 PHP upload_max_filesize / post_max_size（在 /config/www/.env 或反代配置）

附：完整 docker-compose.yml 一键文件

可直接复制保存为 docker-compose.yml，仅需替换密码和 APP_KEY 即可使用：

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    restart: unless-stopped
    ports:
      - "6875:80"
    environment:
      PUID: "1000"
      PGID: "1000"
      TZ: "Asia/Shanghai"
      APP_URL: "http://localhost:6875"
      APP_KEY: "base64:你的密钥"
      DB_HOST: bookstack-db
      DB_PORT: "3306"
      DB_DATABASE: bookstack
      DB_USERNAME: bookstack
      DB_PASSWORD: "你的强密码"
    volumes:
      - ./bookstack_data:/config
    depends_on:
      - bookstack-db

  bookstack-db:
    image: mariadb:10.11
    container_name: bookstack-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: "root强密码"
      MYSQL_DATABASE: bookstack
      MYSQL_USER: bookstack
      MYSQL_PASSWORD: "你的强密码"
    volumes:
      - ./db_data:/var/lib/mysql

启动：

mkdir -p ~/bookstack && cd ~/bookstack
# 放入上面文件，填好密钥和密码
docker compose up -d

安全清单（Checklist）

  • 已修改默认 admin 邮箱和密码
  • 已关闭公开注册
  • 已启用 TOTP 2FA（关键账户 + 强制角色策略）
  • 已保存 Backup Codes 与 APP_KEY
  • 已配置 HTTPS 反向代理，APP_URL 为 https://
  • 已配置定期备份（数据库 + /config）
  • 数据库端口未对外暴露

参考资源

  • 官方文档：https://www.bookstackapp.com/docs/
  • LinuxServer 镜像：https://github.com/linuxserver/docker-bookstack
  • 镜像仓库：https://hub.docker.com/r/linuxserver/bookstack
  • 安全说明：https://www.bookstackapp.com/docs/admin/security

适用版本：BookStack v26.x · LinuxServer 镜像 latest · MariaDB 10.11 · 更新于 2026-09-11

没有要显示的评论

回到顶部