一、速览：为什么选择 BookStack？

入门

BookStack 是一个基于 PHP (Laravel) 开发的开源文档管理平台。与 Wiki.js 或 Docusaurus 等工具不同，它不追求极致的自定义或 Markdown 原生体验，而是提供了一套强约束的内容组织结构。

它的核心逻辑模仿了实体书架：书架 (Shelves) -> 书籍 (Books) -> 章节 (Chapters) -> 页面 (Pages)。这种层级结构非常适合团队知识库、产品文档或个人笔记整理，避免了传统 Wiki 中常见的链接混乱和结构松散问题。

对于不想折腾前端构建流程、希望「开箱即用」且具备完善权限管理的开发者来说，BookStack 是一个极具性价比的自托管方案。它内置了所见即所得编辑器，支持实时协作预览，降低了非技术人员的使用门槛。

二、快速部署：Docker Compose 一键启动

入门

虽然官方提供了手动安装指南，但对于大多数用户，使用 Docker 是最稳妥的选择。BookStack 依赖 MySQL/MariaDB 数据库，手动配置环境容易出错。

我们推荐使用 linuxserver/bookstack 镜像，这是社区维护度最高、更新最及时的版本。创建一个 docker-compose.yml 文件，内容如下：

version: "2"
services:
  bookstack:
    image: linuxserver/bookstack
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=http://localhost:6875
      - DB_HOST=bookstack_db
      - DB_USER=bookstack
      - DB_PASS=secret_password
      - DB_DATABASE=bookstackapp
    volumes:
      - ./config:/config
    ports:
      - 6875:80
    depends_on:
      - bookstack_db
    restart: unless-stopped

  bookstack_db:
    image: linuxserver/mariadb
    container_name: bookstack_db
    environment:
      - MYSQL_ROOT_PASSWORD=secret_root_password
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=secret_password
    volumes:
      - ./db_data:/config
    restart: unless-stopped

注意修改 APP_URL 为你实际的访问地址（IP 或域名）。执行 docker-compose up -d 即可启动服务。首次访问可能需要几分钟初始化数据库。

三、配置详解：关键环境变量与数据持久化

进阶 · 推荐细读

BookStack 的配置主要通过环境变量注入。除了上述基础连接信息，以下几个参数在生产环境中至关重要：

注意：APP_URL 如果配置错误，会导致登录后重定向失败或图片资源加载异常。务必确保该地址与浏览器访问地址完全一致。

数据持久化方面，linuxserver/bookstack 镜像将配置文件和上传的附件存储在 /config 目录。在上面的 compose 文件中，我们将其挂载到了宿主机的 ./config 目录。

数据库数据则通过 linuxserver/mariadb 镜像持久化到 ./db_data。切勿删除这两个本地文件夹，否则所有文档和用户数据将丢失。建议定期备份这两个目录。

四、功能导览：从创建到协作

入门

登录系统后（默认管理员账号通常为 admin@admin.com / password，首次登录请强制修改），你会看到清晰的层级视图。

1. 建立知识结构
先创建一个「书架」，例如「后端开发规范」。在书架内创建「书籍」，如「API 接口文档」。在书籍中，你可以添加「章节」来区分模块，最后在章节下编写具体「页面」。

2. 编辑体验
BookStack 提供两种编辑器：WYSIWYG（所见即所得）和 Markdown。对于普通团队成员，WYSIWYG 更友好；对于开发者，Markdown 模式支持代码高亮和快捷插入。

3. 权限管理
点击「设置」->「角色」，你可以精细控制谁可以查看、创建、更新或删除内容。支持基于角色的访问控制（RBAC），例如设置「实习生」只能查看不能编辑，「技术主管」拥有全部权限。

五、运维进阶：反向代理与 SSL 配置

深入 · 老手可选

生产环境不建议直接暴露 6875 端口。通常使用 Nginx 或 Caddy 作为反向代理，并配置 HTTPS。

以下是 Nginx 配置示例，假设你的域名为 docs.example.com：

server {
    listen 80;
    server_name docs.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name docs.example.com;

    ssl_certificate /etc/letsencrypt/live/docs.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/docs.example.com/privkey.pem;

    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;
    }
}

配置完成后，记得回到 Docker 环境变量中，将 APP_URL 更新为 https://docs.example.com，并重启容器使配置生效。

升级策略：当有新版本发布时，只需拉取最新镜像并重启容器即可：

docker-compose pull
docker-compose up -d

BookStack 会在启动时自动运行数据库迁移脚本，无需手动干预。但在大版本升级前，务必备份数据库和配置文件。

项目信息

参考链接

• GitHub 仓库
• 项目主页