[Brave]

Brave

在当今的信息时代，我们经常需要收集、整理和分享各种知识和信息，比如学习笔记、工作文档、个人日记、在线书籍等。有时候，我们也需要和其他人协作和交流，比如家人、朋友、同事等。

为了实现这些功能，我们通常会使用一些云服务或应用程序，比如 Evernote、OneNote、Google Docs 等。这些服务或应用程序虽然方便，但也有一些缺点，比如：

• 📤 需要上传数据到云端，占用网络带宽和存储空间，可能产生费用。
• 🔒 需要信任第三方服务提供商，可能存在隐私泄露、数据丢失、安全风险等问题。
• 📜 需要遵守第三方服务提供商的规则，可能受到限制或封禁。
• 🌐 需要依赖互联网连接，可能受到网络不稳定、速度慢、断网等影响。

那么，有没有一种方法，可以让我们在自己的设备上创建和组织知识和信息，而不需要依赖任何第三方服务呢？答案是有的，那就是 BookStack。你可以把 BookStack 理解为一个功能更强大且自托管的 GitBook。

---

BookStack 的特点和功能

BookStack 是一个开源的个人知识管理系统，它可以让你在你自己的设备上创建和组织文档、笔记、书籍等，支持 Markdown 和 WYSIWYG 两种编辑模式，支持多语言和多主题，支持搜索和标签，支持导入和导出，支持权限和角色，支持社交登录和 LDAP 认证，支持二次开发和扩展。

BookStack 由英国开发者 Dan Brown 于 2015 年 7 月创建，至今已走过十年历程。项目基于 PHP 语言和 Laravel 框架构建，使用 MySQL 作为数据存储。截至 2025 年底，BookStack 已发布超过 5 个功能版本和 18 个补丁版本，最新稳定版本为 v25.12.3。项目在 GitHub 上持续活跃，社区赞助收入从 2024 年的约 4.65 万英镑增长至 2025 年的约 5.88 万英镑，显示出强劲的社区支持力度。

🟢 开源免费

BookStack 是完全免费和开源的，遵循 MIT 协议。源代码都在 GitHub 上，你可以查看、修改和贡献。

与 Confluence、Notion 等商业产品不同，BookStack 不存在订阅费用或用户数限制。对于中小企业和个人用户而言，这意味着可以零成本构建专业级的文档管理系统。MIT 协议的宽松性也允许企业根据自身需求进行深度定制，甚至将其整合到商业产品中。

🟢 简单直观

BookStack 的设计和操作都非常简单和直观，即使是新手也可以轻松上手。所有的内容都按照书籍、章节和页面的层级结构来组织，你可以随时创建、编辑和删除。你也可以使用 Markdown 或 WYSIWYG 两种编辑模式来编写你的内容，支持实时预览和历史版本。

BookStack 采用四层内容组织架构，模拟真实书籍的阅读体验：

层级	名称	说明	是否必需
📚 第一层	书架（Shelves）	用于归类和管理多本书籍，一本书可同时放置在多个书架上	可选
📖 第二层	书籍（Books）	知识内容的主要容器，是组织文档的基本单位	✅ 必需
📑 第三层	章节（Chapters）	用于在书籍内部进一步分类页面，便于大型文档的管理	可选
📄 第四层	页面（Pages）	实际承载内容的最小单位，支持富文本编辑	✅ 必需

这种”书籍隐喻”设计使得用户无需学习复杂的标签系统或文件夹嵌套规则，即可快速理解内容的组织方式。相比 Notion 的自由度过高可能导致的”结构混乱”，BookStack 的规范化层级更适合需要标准化文档管理的团队场景。

🟢 功能丰富

BookStack 支持多种类型的内容，比如文本、图片、视频、音频、代码、表格、公式等。你可以根据自己的需求和喜好，选择不同的主题和语言，创建不同的书籍和页面。你也可以使用搜索和标签来快速找到你想要的内容，或者使用导入和导出来备份和迁移你的内容。

BookStack 的核心功能可归纳为以下几个模块：

📝 编辑器功能

• 双模式编辑：WYSIWYG（所见即所得）编辑器适合非技术人员，Markdown 编辑器则满足开发者偏好。v25.07 版本新增了纯文本 Markdown 页面编辑器输入选项，进一步扩展了编辑灵活性。
• 内置绘图：集成 diagrams.net 绘图功能，可直接在文档中创建流程图、架构图等专业图表
• 代码高亮：支持多种编程语言的语法高亮显示
• 实时预览：Markdown 编辑时提供实时渲染预览
• 版本历史：自动保存页面的历史版本，支持版本对比和回滚

🔍 搜索与发现

• 全文搜索：可在整个实例范围或特定书籍内进行内容搜索
• 标签系统：为页面添加标签，便于跨书籍的内容聚合
• 评论功能：v25.05 版本重点增强了评论功能，支持页面级别的讨论和协作

📦 导入导出

• 支持导出为 PDF、HTML、纯文本、Markdown 等多种格式
• v25.07 版本推出了全新的 ZIP 导出格式，并通过 REST API 提供了完整的 ZIP 导入/导出端点（books、chapters、pages），支持批量数据迁移和自动化备份
• 可从其他平台导入内容

🌍 国际化支持

• 提供 30 多种语言的用户界面
• v25.07 版本新增了尼泊尔语支持
• 支持自定义翻译文本

🎨 主题与定制

• 内置明暗两种主题，用户可自行切换
• 可视化主题系统（Visual Theme System）允许自定义视图、翻译文本和图标
• 逻辑主题系统（Logical Theme System）支持通过 PHP 代码扩展后端功能

🟢 安全可控

BookStack 不会存储或访问你的任何私密信息，你的数据只存储在你自己的设备上，不会上传到任何其他地方。你可以完全控制你的数据和隐私，不用担心任何安全风险或隐私泄露。你也可以设置不同的权限和角色，来控制谁可以查看或编辑你的内容，或者使用社交登录或 LDAP 认证，来方便和安全地登录你的账户。

BookStack 提供企业级的安全与权限管理能力：

🔐 认证方式

认证类型	适用场景
📧 邮箱/密码	个人用户或小型团队的默认登录方式
🔗 LDAP	与企业现有目录服务（如 Active Directory）集成
🎫 SAML2	支持单点登录（SSO），适配 KeyCloak 等身份提供商
🆔 OIDC	OpenID Connect 协议支持，兼容现代身份认证系统
🌐 社交登录	支持 Google、GitHub、Twitter 等第三方账号登录

👥 权限与角色

• 细粒度权限控制：可针对书架、书籍、章节、页面分别设置查看/编辑权限
• 角色管理：预设或自定义角色，批量分配权限
• MFA 多因素认证：支持基于角色强制启用双因素认证
• 审计日志：完整记录系统内所有修改操作，便于合规审查和问题追溯

⚠️ 安全更新

v25.12.3 是一个重要的安全更新版本，修复了页面内容中表单元素可能被用于诱骗高权限用户发起 API 请求的漏洞。如果你的 BookStack 实例允许不受信任的用户创建或编辑页面，强烈建议立即更新。

此外，2026 年欧盟《网络弹性法案》（Cyber Resilience Act, CRA）的主要义务将正式生效，BookStack 项目团队正在积极应对相关合规要求，确保开源项目符合新的安全标准。

---

BookStack 与同类产品对比

在选择知识管理工具时，了解不同产品的定位和特点非常重要。以下是 BookStack 与几款主流产品的对比：

特性	BookStack	Notion	GitBook	Confluence
部署方式	🏠 自托管	☁️ 云服务	☁️ 云服务	☁️ 云服务/自托管
开源协议	✅ MIT	❌ 闭源	❌ 闭源	❌ 闭源
费用	💚 完全免费	💰 $8+/用户/月	💰 付费为主	💰 付费为主
数据主权	✅ 完全自主	❌ 存储在云端	❌ 存储在云端	部分自主
学习曲线	🟢 简单	🟡 中等	🟡 中等	🔴 较陡
适合场景	内部知识库、文档管理	全能工作空间	技术文档、API 文档	企业级协作

选择建议：

• 🏆 选择 BookStack：如果你重视数据主权、需要完全控制自己的数据、有基本的技术能力进行自托管部署，或者希望避免持续的订阅费用
• 📱 选择 Notion：如果你需要一个集笔记、数据库、项目管理于一体的全能工作空间，且团队成员分布广泛需要实时协作
• 💻 选择 GitBook：如果你的主要需求是面向开发者的技术文档，需要与 GitHub/GitLab 深度集成，并发布公开的 API 文档

---

API 与集成能力

BookStack 不仅是一个独立的文档系统，还提供了强大的扩展和集成能力，使其能够融入现有的技术栈和工作流程。

🔌 REST API

BookStack 内置完整的 REST API，支持对核心内容类型（书架、书籍、章节、页面）的 CRUD 操作。API 文档可在你的 BookStack 实例的 /api/docs 路径访问。

主要功能包括：

• 📚 书籍、章节、页面的创建、读取、更新、删除
• 🔢 通过 priority 参数管理页面和章节的排序
• 📦 v25.07 新增：ZIP 格式的导入/导出 API 端点
• 🔑 基于 API Token 的认证机制

使用 API 需要用户具有”访问系统 API”的角色权限。API 访问的内容权限受用户角色限制，确保安全性。

🪝 Webhooks

BookStack 支持 Webhooks，当系统内发生特定事件时（如页面更新、书籍创建等），可自动向指定端点发送 HTTP POST 请求。

配置路径：设置 > Webhooks

可选触发事件包括审计日志中记录的所有操作类型，支持：

• 📨 全部事件触发
• 🎯 特定事件触发

实用场景示例：

场景	实现方式
🔔 页面更新时发送 Slack 通知	Webhook 直接支持 Slack 兼容格式
📧 应用设置变更时邮件通知管理员	配合邮件服务或 Zapier
📝 记录页面变更到 Google 文档	通过 n8n 或 Zapier 中间件
🔄 新用户注册时自动更新指定页面	结合 REST API 实现

对于更复杂的集成需求，可使用 Zapier、n8n 等自动化平台作为中间件，将 BookStack 与其他服务连接起来。

---

典型应用场景

BookStack 的灵活性使其适用于多种组织类型和使用场景：

🏢 企业内部知识库

企业可以使用 BookStack 构建集中化的知识管理平台：

• 新员工入职指南：将公司政策、工具配置、团队介绍等整合到一本”新员工手册”中，新人可按自己的节奏学习，HR 团队只需维护一份文档
• 标准操作流程（SOP）：运营团队可以在不学习 Markdown 的情况下创建 SOP，无需 IT 支持
• 客户资料管理：为每个主要客户创建独立书籍，记录项目历史、联系偏好、历史问题等，账户交接时无需冗长的会议

💻 技术团队文档

开发团队可以使用 BookStack 管理：

• 📘 项目技术文档
• 🏗️ 系统架构设计
• 🔧 开发环境配置指南
• 🐛 故障排查手册

📚 个人知识管理

个人用户可以将 BookStack 作为：

• 📝 学习笔记库
• 📖 读书摘录集
• 💡 创意灵感库
• 📅 个人日志

🎓 教育培训

教育机构可以利用 BookStack：

• 📖 创建在线课程资料
• 📋 管理培训手册
• 💬 支持学员讨论（通过评论功能）

适用组织类型：中小企业、初创公司、自由职业者、非营利组织、政府机构、企业团队

---

如何安装和使用 BookStack

其实，安装和使用 BookStack 非常简单，一种方法是自行安装，但比较繁琐，这里推荐的方法是使用 Umbrel 或 Runtipi 等 Homelab 工具，在应用商店里一键安装。

方法一：使用 Homelab 平台一键安装（推荐）

对于大多数个人用户和家庭实验室爱好者，使用 Homelab 管理平台是最简单的安装方式。

📦 支持 BookStack 的 Homelab 平台

平台	说明	BookStack 支持
Runtipi	轻量级自托管应用管理器，无需刷写系统，可在现有 OS 上运行	✅ 官方应用商店收录
Umbrel	美观的家庭服务器操作系统，支持树莓派和 x86 系统	⚠️ 需通过第三方应用商店或手动 Docker 部署
CasaOS	Umbrel 的开源替代品，界面友好	✅ 应用商店收录
TrueNAS	企业级 NAS 操作系统	✅ 应用市场收录

安装步骤（以 Runtipi 为例）：

1️⃣ 安装 Runtipi：在你的 Linux 服务器（包括树莓派）上安装 Runtipi

2️⃣ 访问应用商店：打开 Runtipi 的 Web 管理界面，进入 App Store 标签页

3️⃣ 安装 BookStack：搜索并点击 BookStack，选择反向代理设置后点击安装

4️⃣ 访问 BookStack：安装完成后点击 Open 按钮，即可在浏览器中访问

方法二：Docker 部署

对于有一定技术基础的用户，Docker 部署提供了更大的灵活性。

🐳 推荐镜像

LinuxServer.io 维护的 Docker 镜像是社区最广泛使用的版本：

docker pull lscr.io/linuxserver/bookstack:latest

⚙️ 关键配置项

环境变量	说明	示例值
APP_URL	应用访问地址	http://192.168.1.100:6875 或 https://bookstack.yourdomain.com
APP_KEY	会话加密密钥	使用命令生成（见下方）
DB_HOST	数据库主机地址	mariadb
DB_DATABASE	数据库名称	bookstack
DB_USERNAME	数据库用户名	bookstack
DB_PASSWORD	数据库密码	自定义强密码

生成 APP_KEY：

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

⚠️ 数据库依赖

BookStack 需要 MariaDB 数据库支持。如果你没有现成的数据库实例，可以使用 LinuxServer.io 提供的 MariaDB 镜像一并部署。

🔑 默认登录凭据

• 用户名：admin@admin.com
• 密码：password
• 默认端口：6875

⚠️ 重要安全提示：首次登录后请立即修改默认密码！

方法三：手动安装

如果你需要完全控制安装过程，可以参考 BookStack 官方文档进行手动安装。需要准备：

• PHP 8.1+（含必要扩展）
• MySQL 5.7+ 或 MariaDB 10.2+
• Nginx 或 Apache Web 服务器
• Composer（PHP 依赖管理器）

详细安装指南请访问：https://www.bookstackapp.com/docs/admin/installation/

---

首次配置指南

成功安装 BookStack 后，建议按以下步骤进行初始配置：

1️⃣ 修改管理员密码

访问 设置 > 我的账户，立即更改默认密码

2️⃣ 配置应用设置

访问 设置 > 应用设置：

• 📛 设置应用名称
• 🖼️ 上传 Logo
• 🎨 选择默认主题（明/暗）
• 🔒 配置注册设置（开放/关闭/仅邀请）

3️⃣ 创建角色和用户

访问 设置 > 角色：

• 根据团队结构创建不同角色（如：管理员、编辑、访客）
• 为每个角色分配适当的权限

4️⃣ 开始创建内容

点击”创建书架”或”创建书籍”开始构建你的知识库：

📚 书架：技术文档
   └── 📖 书籍：后端开发指南
       ├── 📑 章节：环境搭建
       │   ├── 📄 页面：本地开发环境配置
       │   └── 📄 页面：测试环境说明
       └── 📑 章节：编码规范
           ├── 📄 页面：命名约定
           └── 📄 页面：代码审查流程

---

进阶技巧

以下是一些帮助你更高效使用 BookStack 的进阶技巧：

⌨️ 快捷键

快捷键	功能
Ctrl + S	保存页面
Ctrl + Enter	保存并关闭编辑器
/	快速搜索

🔗 页面链接

在页面中可以使用以下语法创建内部链接：

[链接文字](/books/书籍slug/page/页面slug)

📊 嵌入内容

BookStack 支持嵌入多种外部内容：

• YouTube 视频
• Diagrams.net 图表
• 代码片段（支持语法高亮）

🔄 自动排序

v25.02 版本引入了自动排序功能，可按名称或创建日期自动整理页面和章节的顺序，大幅减少手动排序的工作量。

---

资源与社区

如果你在使用 BookStack 过程中遇到问题，可以通过以下渠道获取帮助：

资源	链接
📖 官方文档	https://www.bookstackapp.com/docs/
💻 GitHub 仓库	https://github.com/BookStackApp/BookStack
🎨 演示站点	https://demo.bookstackapp.com/
🛠️ 官方 Hacks	https://www.bookstackapp.com/hacks/
📰 版本发布日志	https://www.bookstackapp.com/tags/releases/

---

小结

BookStack 是一款优秀的开源知识管理系统，它以”书籍”为隐喻的直观设计、强大的权限管理、丰富的扩展能力，使其成为个人和团队构建知识库的理想选择。无论你是想要掌控自己数据的隐私保护主义者，还是寻求低成本文档解决方案的中小企业，亦或是热衷于自托管的 Homelab 爱好者，BookStack 都值得一试。

通过 Runtipi、Umbrel 等现代化的 Homelab 工具，即使没有深厚的技术背景，你也可以在几分钟内部署属于自己的知识管理系统，开始构建你的数字图书馆。