BookStack 文档知识库搭建教程

BookStack 是一款简洁易用的开源 Wiki 和文档管理平台，基于 PHP Laravel 框架构建。它采用"书架 > 书籍 > 章节 > 页面"的四级层级结构来组织内容，就像管理一个虚拟图书馆。BookStack 的特色是上手简单、界面清晰、支持 WYSIWYG 和 Markdown 双编辑器。本文将介绍如何在搬瓦工 VPS 上使用 Docker 部署 BookStack。部署前请确保已安装好 Docker 和 Docker Compose。

一、系统要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 512MB，建议 1GB。
磁盘：至少 5GB 可用空间。

二、Docker Compose 部署

mkdir -p /opt/bookstack
cd /opt/bookstack

cat > /opt/bookstack/docker-compose.yml <<'EOF'
version: '3.8'

services:
  db:
    image: mariadb:10.11
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: your_root_password
      MYSQL_DATABASE: bookstack
      MYSQL_USER: bookstack
      MYSQL_PASSWORD: your_db_password
    volumes:
      - db_data:/var/lib/mysql

  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    restart: always
    depends_on:
      - db
    ports:
      - "6875:80"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - APP_URL=https://docs.yourdomain.com
      - DB_HOST=db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=your_db_password
      - DB_DATABASE=bookstack
    volumes:
      - bookstack_data:/config

volumes:
  db_data:
  bookstack_data:
EOF

docker compose up -d

三、配置 Nginx 反向代理

cat > /etc/nginx/sites-available/bookstack <<'EOF'
server {
    listen 80;
    server_name docs.yourdomain.com;

    client_max_body_size 50M;

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

ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d docs.yourdomain.com

四、登录与初始设置

访问 https://docs.yourdomain.com，使用默认管理员账户登录：

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

登录后务必立即修改默认密码和管理员邮箱。进入 Settings > Users 修改。

五、内容组织结构

BookStack 使用四级层级结构管理内容：

书架（Shelves）：最高层级的分类容器，用于归类相关书籍。
书籍（Books）：一个独立的知识主题或项目文档。
章节（Chapters）：书籍中的分组，用于组织相关页面。
页面（Pages）：实际的内容页面，是最基本的内容单元。

这种结构非常适合技术文档、产品手册、操作指南等内容的组织。

六、编辑器功能

BookStack 提供两种编辑器：

WYSIWYG 编辑器：所见即所得编辑器，支持富文本格式、插入图片、表格、代码块、链接等。
Markdown 编辑器：支持标准 Markdown 语法和实时预览。在用户设置中可以切换默认编辑器。

两种编辑器都支持代码语法高亮、数学公式（需启用）和图片拖拽上传。

七、页面模板

BookStack 支持创建页面模板来标准化文档格式。在任意页面中，点击 "More Actions" > "Save as Template" 即可将当前页面保存为模板。创建新页面时可以从模板列表中选择。

八、用户与权限

BookStack 提供了灵活的角色权限系统：

内置角色：Admin（管理员）、Editor（编辑者）、Viewer（查看者）。
自定义角色：可以创建自定义角色并精确控制每种操作的权限。
内容权限：每个书架、书籍、章节和页面都可以独立设置权限。

九、导出功能

BookStack 支持将页面导出为多种格式：

PDF：导出为 PDF 文档。
HTML：导出为独立的 HTML 文件。
Markdown：导出为 Markdown 纯文本。
纯文本：导出为无格式文本。

十、配置邮件通知

在 BookStack 的环境变量中配置 SMTP 以启用邮件功能：

- MAIL_DRIVER=smtp
- MAIL_HOST=smtp.example.com
- MAIL_PORT=587
- MAIL_USERNAME=your-email@example.com
- MAIL_PASSWORD=your-smtp-password
- MAIL_ENCRYPTION=tls
- MAIL_FROM=noreply@yourdomain.com
- MAIL_FROM_NAME=BookStack

十一、数据备份

# 备份数据库
docker exec bookstack-db-1 mysqldump -u bookstack -p'your_db_password' bookstack > /opt/bookstack/backup_$(date +%Y%m%d).sql

# 备份上传文件和配置
tar -czf /opt/bookstack/backup_files_$(date +%Y%m%d).tar.gz /opt/bookstack/bookstack_data/

十二、常见问题

PDF 导出失败

BookStack 使用 wkhtmltopdf 或 Dompdf 生成 PDF。LinuxServer 镜像已内置 wkhtmltopdf。如果导出失败，检查容器日志中的错误信息。

图片上传失败

检查 bookstack_data 目录的权限，确保容器内的用户有写入权限。

总结

BookStack 是一款上手简单、结构清晰的文档知识库工具。"书架-书籍-章节-页面"的组织方式非常直观，适合搭建技术文档库、产品手册和团队知识库。在搬瓦工 VPS 上部署 BookStack 只需较少的资源即可流畅运行。更多知识管理工具请参考：Wiki.js 部署、Outline 部署、Memos 笔记部署。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的循环折扣。