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_URL 为 https://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 的图库

# 图片库可从编辑器工具栏访问
# 所有上传的图片存储在 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
高级用法:生产环境加固 #
启用仅 HTTPS Cookie #
# .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 与替代方案 #
| 特性 | BookStack | Wiki.js | DokuWiki | MediaWiki | Outline |
|---|---|---|---|---|---|
| 许可证 | MIT | AGPL-3.0 | GPL-2.0 | GPL-2.0+ | BSL 1.1 |
| 技术栈 | PHP / Laravel | Node.js | PHP (无 DB) | PHP | Node.js |
| 编辑器 | WYSIWYG + Markdown | Markdown + 可视化 | Wiki 语法 | Wikitext | 块编辑器 |
| 实时协作 | 否 | 是 | 否 | 否 | 是 |
| 内容层级 | 书架→书籍→章节→页面 | 灵活 | 扁平 | 分类→页面 | 集合→文档 |
| 自托管成本 | 免费(仅服务器) | 免费(仅服务器) | 免费(仅服务器) | 免费(仅服务器) | $10/用户/月 托管 |
| 数据库要求 | MySQL/MariaDB | PostgreSQL/MySQL/SQLite | 无(基于文件) | MySQL/PostgreSQL | PostgreSQL |
| LDAP/SSO | 是 (LDAP, SAML, OIDC) | 是(广泛) | 通过插件 | 通过插件 | SAML, OIDC |
| 搜索 | MySQL FULLTEXT | Elasticsearch/DB | 内置 | Elasticsearch | PostgreSQL FTS |
| API | REST | GraphQL + REST | XML-RPC | REST | REST |
| 活跃维护 | 月度发布 | 定期 | 稳定 | 定期 | 定期 |
| GitHub stars | 18,700 | 24,500 | 1,800 | 4,200 | 14,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+ 开发者讨论开源工具、部署技巧和故障排除。
来源与延伸阅读 #
- BookStack 官方文档
- BookStack GitHub 镜像
- BookStack Codeberg 仓库
- BookStack v26.03 发布说明
- LinuxServer.io BookStack Docker 镜像
- BookStack vs Wiki.js 对比
推荐部署与基础设施 #
上述工具想要落地生产,靠谱的基础设施是前提。dibi8 自己也在用的两个选择:
- DigitalOcean — 新用户 60 天 $200 免费额度,14+ 全球节点。运行开源 AI 工具的首选。
- HTStack — 香港 VPS,国内访问低延迟,dibi8.com 自己也跑在它上面,生产环境验证过。
Aff 链接 — 不增加你的成本,但能帮 dibi8 持续运营。
联盟披露 #
本文包含 DigitalOcean 的联盟链接。如果你通过我们的链接注册,我们会获得推荐积分,而你无需支付额外费用。我们只推荐自己使用过的基础设施。BookStack 项目是免费开源的 —— 我们与 BookStack 维护者之间不存在联盟关系。
💬 留言讨论