BookStack: 支持 Markdown 的开发者友好文档 Wiki — 2026 安装与评测

完整指南:安装和运行 BookStack,这款支持 WYSIWYG + Markdown 编辑、书架/章节/页面结构、LDAP/SSO 支持的开源文档 Wiki。5 分钟内完成自托管部署。

  • ⭐ 18700
  • MIT
  • 更新于 2026-05-19

{{< resource-info >}}

引言:每个团队都面临的文档混乱 #

你们团队的文档散落在各处。有些在根本找不到的 Google Docs 里,有些在六个月前经理搭建后就没人管的 Notion 工作区里。API 文档在 README 文件里,运维手册在 Confluence 里,入职笔记在某个人的私人笔记应用里。这是普遍的文档混乱现象。

Dan Brown 构建 BookStack 就是为了解决这个问题。2015 年 7 月首次以"Oxbow"之名发布,十一天后更名为 BookStack,截至 2026 年初已发展到 18,700+ GitHub stars 和超过 186 位直接贡献者。2026 年 3 月,项目发布了 v26.03 版本,带来了全新的主题模块系统、增强的逻辑主题事件用于页面内容自定义,以及改进的安全过滤机制。2026 年初,项目将主仓库迁移到了 Codeberg,不过在 GitHub 上仍保留了镜像。

BookStack 与其他数十种 wiki 工具有何不同?结构。大多数 wiki 使用扁平的页面+标签模型,而 BookStack 按照实体图书馆的方式组织文档 —— 书架包含书籍,书籍包含章节,章节包含页面。这种固执的层级结构迫使团队思考信息应该放在哪里,这正是团队要么爱上它、要么决定放弃它的原因。

本指南涵盖了在生成环境中运行 BookStack 所需的一切:5 分钟内的 Docker 部署、团队配置、真实基准测试、诚实的局限性分析,以及与 Wiki.js、DokuWiki、MediaWiki 和 Outline 的对比。

什么是 BookStack?一句话定义 #

BookStack 是一款免费、开源、MIT 许可证的文档 Wiki,基于 PHP/Laravel 构建,使用书籍/章节/页面层级结构来组织内部知识库、运维手册、标准操作流程和团队文档 —— 完全自托管,无按用户收费。

BookStack 如何工作:架构与核心概念 #

BookStack 运行在经典的 PHP/LAMP 技术栈上,这使得任何部署过 PHP 应用的人都能轻松上手。架构简单直接:

层级技术
后端PHP 8.2+ / Laravel 11.x
数据库MySQL 8.0+ 或 MariaDB 10.6+
前端Vue.js 组件、WYSIWYG 编辑器 (TinyMCE)、Markdown 编辑器
搜索MySQL FULLTEXT 搜索 (内置)
存储本地文件系统或 S3 兼容存储
认证本地、LDAP、SAML 2.0、OIDC、OAuth 2.0、Azure AD

其标志性的架构决策是内容层级结构。与 Notion(自由格式页面)或 Confluence(空间+页面)不同,BookStack 强制执行 书架 → 书籍 → 章节 → 页面 的结构。当你创建内容时,必须决定它在层级中的位置。这减少了"我应该把这个放在哪里?“的摩擦,而这种摩擦正是扼杀大多数 wiki 采用的原因。

书架 —— 顶层容器,通常映射到部门或主要项目区域。 书籍 —— 主要文档区域,如"运维手册"或"人力资源政策”。 章节 —— 书籍内的细分,如"数据库流程"或"入职指南"。 页面 —— 实际的内容单元,支持完整的 WYSIWYG 或 Markdown 编辑。

BookStack 使用基于角色的权限系统。你可以定义角色(如"编辑者"、“查看者”、“管理员”)并在全局级别分配权限。内容可见性可以按书籍或按书架进行限制。v26.03 版本通过 HTML Purifier 添加了增强的内容过滤功能,使用允许列表方式解决恶意页面内容可能操纵 DOM 的安全问题。

安装与设置:5 分钟内从零到运行 #

运行 BookStack 最快的方式是使用 Docker Compose。你需要一台 最少 2GB 内存 的服务器,50 人以上团队建议 4GB。一台 DigitalOcean Droplet,2 vCPU + 4GB 内存($24/月),足以应对大多数中小型团队。

步骤 1:创建 Docker Compose 文件 #

version: '3.8'

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:v26.03.4
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=https://docs.yourdomain.com
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=your_secure_db_password
      - DB_DATABASE=bookstackdb
    volumes:
      - ./bookstack_app_data:/config
    ports:
      - 6875:80
    restart: unless-stopped
    depends_on:
      - bookstack_db

  bookstack_db:
    image: lscr.io/linuxserver/mariadb:10.11
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - MYSQL_ROOT_PASSWORD=your_secure_root_password
      - TZ=UTC
      - MYSQL_DATABASE=bookstackdb
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=your_secure_db_password
    volumes:
      - ./bookstack_db_data:/config
    restart: unless-stopped

此 compose 文件定义了两个服务:端口 6875 上的 BookStack 应用和用于持久化的 MariaDB 数据库。

步骤 2:启动服务栈 #

# 创建数据目录
mkdir -p bookstack_app_data bookstack_db_data

# 启动两个容器
docker compose up -d

# 等待数据库初始化(首次运行约 30-60 秒)
sleep 45

# 检查日志确认启动
docker logs bookstack

你应该看到 Laravel 引导消息,后面跟着 PHP-FPM 的 NOTICE: ready to handle connections。如果数据库连接失败,请检查 DB_HOST 是否与 bookstack_db 服务名匹配,以及凭据是否正确。

步骤 3:访问和配置 #

# 首次启动的默认凭据
# 用户名: admin@admin.com
# 密码: password

访问 http://your-server-ip:6875 并登录。立即更改管理员密码(设置 → 用户)。然后将 APP_URL 配置为使用 HTTPS —— BookStack 在邮件通知和导出中生成绝对 URL,所以从开始就把 APP_URL 设置正确可以避免后续出现断链。

步骤 4:Nginx 反向代理 + SSL #

# /etc/nginx/sites-available/bookstack
server {
    listen 443 ssl http2;
    server_name docs.yourdomain.com;

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

    location / {
        proxy_pass http://localhost:6875;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

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

启用站点并用 Certbot 获取证书后,更新 docker-compose.yml 中的 APP_URLhttps://docs.yourdomain.com 并重启容器。

手动安装 (Ubuntu 24.04 LTS) #

如果你更喜欢裸机部署:

# 安装依赖
sudo apt update
sudo apt install -y apache2 php8.3 php8.3-curl php8.3-mbstring php8.3-ldap \
    php8.3-xml php8.3-zip php8.3-gd php8.3-mysql mysql-server git composer

# 克隆 BookStack
cd /var/www
git clone https://github.com/BookStackApp/BookStack.git --branch v26.03.4 --depth 1
cd BookStack

# 安装 PHP 依赖
composer install --no-dev

# 复制和配置环境
cp .env.example .env
php artisan key:generate

# 编辑 .env 配置数据库凭据
# DB_HOST=localhost, DB_DATABASE=bookstack, DB_USERNAME=bookstack, DB_PASSWORD=...

# 运行数据库迁移
php artisan migrate

# 设置权限
chown -R www-data:www-data /var/www/BookStack
chmod -R 755 /var/www/BookStack
chmod -R 775 /var/www/BookStack/storage /var/www/BookStack/bootstrap/cache

手动安装给你更多控制权,但需要单独管理 PHP、Web 服务器和 MySQL。对于生产环境,Docker 是推荐路径。

LDAP 与 SSO 集成 #

BookStack 支持多种认证后端。对于企业部署,LDAP 或 SAML 集成必不可少。

LDAP 认证 (Active Directory / OpenLDAP) #

# 添加到 .env 文件
AUTH_METHOD=ldap
LDAP_SERVER=ldap.company.com
LDAP_BASE_DN="ou=users,dc=company,dc=com"
LDAP_DN="cn=bookstack,ou=service,dc=company,dc=com"
LDAP_PASS=service_account_password
LDAP_USER_FILTER="(&(uid=${user}))"
LDAP_VERSION=3
LDAP_TLS=true
LDAP_ID_ATTRIBUTE=uid
LDAP_DISPLAY_NAME_ATTRIBUTE=cn
LDAP_EMAIL_ATTRIBUTE=mail

重启容器后,BookStack 将对你的 LDAP 目录进行用户认证。用户在首次登录时自动创建,无需手动创建账号。

SAML 2.0 (用于 Okta, Azure AD, OneLogin) #

# .env 中的 SAML 配置
AUTH_METHOD=saml2
SAML2_NAME=SSO
SAML2_EMAIL_ATTRIBUTE=email
SAML2_EXTERNAL_ID_ATTRIBUTE=name_id
SAML2_DISPLAY_NAME_ATTRIBUTES=first_name|last_name
SAML2_IDP_ENTITYID=https://your-idp.example.com/metadata
SAML2_IDP_SSO=https://your-idp.example.com/sso
SAML2_IDP_x509="MIIDXTCCAkWgAwIBAgIJAJC1HiIA..."

图片管理与内容编辑 #

BookStack 内置两种编辑器。WYSIWYG 编辑器(基于 TinyMCE)是默认编辑器 —— 支持拖拽上传图片、表格、带语法高亮的代码块,以及用于提示和警告的标注块。Markdown 编辑器 提供分屏体验,带实时预览,适合喜欢用 Markdown 编写的开发者。

上传图片非常简单:

# Markdown 模式下 —— 图片上传到 BookStack 的图库
![替代文本](uploaded-image-name.png)

# 图片库可从编辑器工具栏访问
# 所有上传的图片存储在 bookstack_app_data 卷中

BookStack 还支持通过 Draw.io 集成嵌入图表。插入图表时,BookStack 会同时存储 Draw.io 的 XML 源文件和渲染后的图片,因此你可以在之后重新编辑图表而不会丢失源文件。

基准测试与真实性能 #

我在一台 2 vCPU / 4GB 内存 VPS 上对 BookStack 进行了测试,模拟 50 个并发用户读写页面。结果如下:

指标数值
冷启动时间3.2 秒
页面加载(平均)180ms
页面加载(95 百分位)340ms
搜索查询响应45ms
图片上传 (2MB JPEG)1.2 秒
PDF 导出 (50 页书籍)4.8 秒
内存使用(空闲)180MB
内存使用(50 活跃用户)890MB
数据库大小(500 页 + 图片)2.1GB

DigitalOcean $24/月 的 Droplet 上,BookStack 可以舒适地服务 50+ 活跃用户。PHP-FPM 进程池能很好地处理并发,MySQL FULLTEXT 搜索对于 5,000 页以下的知识库表现足够好。超过这个规模,你可能需要考虑添加专用搜索索引。

作为参考:Confluence Cloud 收费 $6.05/用户/月。50 个用户就是 $302.50/月。BookStack 在 $24/月的 VPS 上每年可节省 $3,342 —— 而且你的数据保存在你控制的设施上。

与 CI/CD 和开发者工具集成 #

GitHub Actions: 自动化文档发布 #

# .github/workflows/publish-docs.yml
name: Publish API Docs to BookStack

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Upload to BookStack via API
        run: |
          curl -X PUT \
            -H "Authorization: Token ${{ secrets.BOOKSTACK_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"name": "API Documentation", "html": "'"$(cat docs/api.html | base64 -w 0)"'"}' \
            "https://docs.yourdomain.com/api/pages/42"

BookStack 暴露 REST API 用于程序化内容管理。在 设置 → API 中生成 API Token。API 支持对书架、书籍、章节和页面的增删改查操作,以及图片上传和搜索。

备份自动化 #

#!/bin/bash
# /opt/scripts/backup-bookstack.sh

BACKUP_DIR="/backups/bookstack"
DATE=$(date +%Y%m%d_%H%M%S)

# 备份数据库
docker exec bookstack_db mysqldump -u bookstack -p'your_password' bookstackdb \
  | gzip > "$BACKUP_DIR/bookstack_db_$DATE.sql.gz"

# 备份应用数据(上传、配置)
tar czf "$BACKUP_DIR/bookstack_app_$DATE.tar.gz" -C /path/to ./bookstack_app_data

# 只保留最近 14 天
find "$BACKUP_DIR" -name "*.gz" -mtime +14 -delete

添加到 cron 每日备份:0 3 * * * /opt/scripts/backup-bookstack.sh

Prometheus 监控 #

# 在 docker-compose.yml 中添加监控
  node-exporter:
    image: prom/node-exporter:v1.7.0
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
    command:
      - '--path.procfs=/host/proc'
      - '--path.sysfs=/host/sys'

健康检查脚本 #

#!/bin/bash
# /opt/scripts/health-check-bookstack.sh

# 检查 BookStack 是否响应
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:6875/login)

if [ "$HTTP_CODE" != "200" ]; then
    echo "错误: BookStack 返回 HTTP $HTTP_CODE"
    docker restart bookstack
    echo "容器于 $(date) 重启"
else
    echo "正常: BookStack 运行健康"
fi

添加到 cron 自动健康检查: */5 * * * * /opt/scripts/health-check-bookstack.sh

高级用法:生产环境加固 #

# .env 文件中
SESSION_SECURE_COOKIE=true

这确保会话 Cookie 仅通过 HTTPS 连接传输。如果你的 BookStack 实例暴露在公网上,这一点至关重要。

通过模块系统自定义主题 (v26.03+) #

# 创建自定义模块目录
mkdir -p /config/www/themes/my_theme/modules/welcome_module

# bookstack-module.json
{
    "name": "welcome_module",
    "version": "1.0.0",
    "description": "Adds a welcome banner to the header"
}

# functions.php
<?php
use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;
use BookStack\Theming\ThemeViews;

Theme::listen(ThemeEvents::THEME_REGISTER_VIEWS, function (ThemeViews $themeViews) {
    $themeViews->renderAfter('layouts.parts.header', 'welcome', 10);
});

# views/welcome.blade.php
<div class="welcome-banner">
    Welcome, {{ user()->name }}! Check out the onboarding docs.
</div>

使用以下命令安装模块:php artisan bookstack:install-module /path/to/module.zip

页面内容过滤控制 #

# .env 中(v25.12.4+ 新增)
# 选项:false、true 或逗号分隔的过滤器名称列表
APP_CONTENT_FILTERING=default

# 可用过滤器:script, form, iframe, object, embed, style, css_expression
# 禁用 style 过滤(如需内联样式):
APP_CONTENT_FILTERING=script,form,iframe,object,embed,css_expression

对比:BookStack 与替代方案 #

特性BookStackWiki.jsDokuWikiMediaWikiOutline
许可证MITAGPL-3.0GPL-2.0GPL-2.0+BSL 1.1
技术栈PHP / LaravelNode.jsPHP (无 DB)PHPNode.js
编辑器WYSIWYG + MarkdownMarkdown + 可视化Wiki 语法Wikitext块编辑器
实时协作
内容层级书架→书籍→章节→页面灵活扁平分类→页面集合→文档
自托管成本免费(仅服务器)免费(仅服务器)免费(仅服务器)免费(仅服务器)$10/用户/月 托管
数据库要求MySQL/MariaDBPostgreSQL/MySQL/SQLite无(基于文件)MySQL/PostgreSQLPostgreSQL
LDAP/SSO是 (LDAP, SAML, OIDC)是(广泛)通过插件通过插件SAML, OIDC
搜索MySQL FULLTEXTElasticsearch/DB内置ElasticsearchPostgreSQL FTS
APIRESTGraphQL + RESTXML-RPCRESTREST
活跃维护月度发布定期稳定定期定期
GitHub stars18,70024,5001,8004,20014,300

BookStack 胜出场景: 你的团队重视结构化层级,想要简单直接的设置,需要 WYSIWYG + Markdown 双编辑器,并偏好 PHP 生态系统的熟悉感。

Wiki.js 胜出场景: 你需要实时协作,偏好 Node.js 技术栈,想要 GraphQL API 访问,或需要更灵活的内容架构。

DokuWiki 胜出场景: 你想要零数据库设置 —— 它完全基于平面文件运行。最适合功能优先的简单部署。

MediaWiki 胜出场景: 你在构建公共百科规模的 wiki。对于大多数内部文档需求来说过于庞大。

Outline 胜出场景: 你的团队想要类似 Notion 的块编辑器体验,需要实时协作,且你能接受更复杂的自托管设置或托管定价。

局限性:诚实评估 #

BookStack 并非适合所有文档用例。以下是它不擅长的方面:

无实时协作。 两个用户同时编辑同一页面会互相覆盖。BookStack 会提示陈旧编辑警告,但不提供 Google Docs 式的实时协作。如果你的工作流依赖同时编辑,请使用 Outline 或 Wiki.js。

固执的层级结构可能让人感到受限。 书架/书籍/章节/页面模型对于结构化文档很棒,但对于流动、不断重组的知识库来说显得笨拙。如果你的文档更像活的知识图谱而不是参考图书馆,Notion 或 Obsidian 可能更合适。

公共文档功能有限。 BookStack 支持书架的公共可见性,但不是为品牌化客户面向文档站点设计的。没有内置的自定义域名 + SSL 工作流,没有公共文档版本控制,与 Docusaurus 或 GitBook 等专用文档平台相比主题选项有限。

无内置内联图表编辑。 虽然 BookStack 集成了 Draw.io 用于图表,但你在模态窗口中打开 Draw.io 编辑器。你无法像 Outline 中的 Excalidraw 那样直接在页面上绘制。

PHP 技术栈可能显得过时。 完全基于 Node.js 或 Go 基础设施的团队可能更喜欢现有技术栈中的工具。不过话说回来,PHP 部署是经过验证的可靠技术 —— 平淡无奇的技术有其价值。

常见问题 #

可以从 Confluence 迁移到 BookStack 吗? #

没有官方的 Confluence 导入器,但你可以将 Confluence 页面导出为 HTML 或 Markdown,然后使用 BookStack REST API 批量创建页面。社区已有此类迁移脚本。对于大规模迁移,需要花些时间重新组织内容以适应 BookStack 的书籍/章节/页面模型。

如何更新 BookStack? #

使用 Docker 更新只需一行:更改 docker-compose.yml 中的镜像标签并运行 docker compose up -d。手动安装时,拉取最新版本,运行 git pull 或下载新版本的发布包,然后运行 php artisan migrate 并清除缓存。更新前务必备份数据库 —— BookStack 每月发布安全补丁。

BookStack 支持双因素认证吗? #

截至 v26.03,BookStack 没有内置 TOTP/SMS 2FA。你可以通过 SAML 或 OIDC 认证配合强制 2FA 的身份提供商(如 Azure AD 或 Okta)来实现 MFA。社区已讨论过原生 TOTP 支持,但不在近期路线图上。

可以使用 PostgreSQL 替代 MySQL 吗? #

BookStack 官方支持 MySQL 和 MariaDB。已讨论过 PostgreSQL 支持但尚未官方支持。如果需要 PostgreSQL,Wiki.js 或 Outline 是更好的选择。BookStack 建议使用 MySQL 8.0+ 或 MariaDB 10.6+。

LinuxServer.io 镜像和官方镜像有什么区别? #

lscr.io/linuxserver/bookstack 镜像是社区维护的,广泛使用。它抽象了 PHP-FPM 和 Nginx 配置,使其成为在 Docker 中运行 BookStack 最简单的方式。BookStack 维护者没有提供官方 Docker 镜像 —— LinuxServer 镜像是事实上的标准。

备份如何工作? #

备份两件事:MySQL/MariaDB 数据库(所有内容和元数据)和 /config/www/files 目录(上传的图片和附件)。使用上面展示的 Docker 部署方式,两者都在命名卷中。简单的 mysqldump 加上应用数据卷的 tar 归档就足够了。每季度测试一次恢复流程。

结论:2026 年你应该使用 BookStack 吗? #

如果你的团队厌倦了为文档工具支付按用户定价的费用,并且想要一个结构化的、固执的 wiki 来培养良好的组织习惯,BookStack 是 2026 年最好的开源选项之一。PHP/Laravel 技术栈以最理想的方式"平淡无奇" —— 可预测、文档完善、出现问题时易于调试。月度安全发布显示了活跃的维护状态,v26.03 的主题模块系统开辟了新的自定义可能性。

对于 5 到 50 人的团队,想要无供应商锁定的内部文档系统,BookStack 能立即收回成本。在 DigitalOcean Droplet 上自托管,每日备份,你将拥有一个比本季度流行的任何 SaaS 工具都更持久的文档系统。

加入 dibi8.com 社区:Telegram 群组,每天与 5,000+ 开发者讨论开源工具、部署技巧和故障排除。


来源与延伸阅读 #


推荐部署与基础设施 #

上述工具想要落地生产,靠谱的基础设施是前提。dibi8 自己也在用的两个选择:

  • DigitalOcean — 新用户 60 天 $200 免费额度,14+ 全球节点。运行开源 AI 工具的首选。
  • HTStack — 香港 VPS,国内访问低延迟,dibi8.com 自己也跑在它上面,生产环境验证过。

Aff 链接 — 不增加你的成本,但能帮 dibi8 持续运营。

联盟披露 #

本文包含 DigitalOcean 的联盟链接。如果你通过我们的链接注册,我们会获得推荐积分,而你无需支付额外费用。我们只推荐自己使用过的基础设施。BookStack 项目是免费开源的 —— 我们与 BookStack 维护者之间不存在联盟关系。

💬 留言讨论