网站Logo
    首页 / 详情
Site icon

BookStack

基本信息

知识库
访问
BookStack 网站截图预览

工具详情

BookStack 全解指南

一、平台介绍

1.1 基本定位

  • 性质：MIT 开源免费、自托管式 Web 知识库/维基文档系统。
  • 对标产品：Confluence、GitBook。
  • 技术栈：基于 PHP+Laravel 框架开发，使用 MySQL/MariaDB 存储数据。
  • 源码托管：已从 GitHub 迁移至 Codeberg 托管。
  • 核心架构：采用三层经典架构逻辑，即 书架 (Shelves) → 书籍 (Books) → 章节 (Chapters) → 页面 (Pages)，完全贴合图书式内容管理。

1.2 相关链接

  • 官网地址：https://www.bookstackapp.com
  • 在线演示站：https://demo.bookstackapp.com注：演示站数据每 30 分钟自动重置，限制删除用户及修改系统配置。
  • 定位总结：轻量化私有化部署知识库，适用于企业内网文档、个人知识库、产品手册、团队 Wiki 首选。

二、核心主要功能

2.1 双编辑器写作

  1. WYSIWYG 富文本编辑器：所见即所得，支持标题、表格、代码块、折叠区块、图片插入。
  2. Markdown 编辑器：支持实时预览，原生支持 MD 语法，可一键切换编辑模式。
  • 亮点：内置 draw.io（diagrams.net）在线绘图，页面内直接画流程图、架构图，无需跳转第三方工具。

2.2 内容管理能力

  • 全文全域检索：支持全书/全站搜索，可进行标签筛选、时间筛选、创建人筛选及内容类型过滤（页/章/书/书架）。
  • 版本历史：每页自动保存修订记录，可回溯历史、对比修改、回滚内容。
  • 多格式导出：支持单页/整书导出 PDF、Markdown、Word、纯文本、HTML。
  • 图片集中管理：内置图库，支持分类上传、批量选择图片；可开启图片防盗随机 URL 加密。
  • 跨书排序/内容移动：页面可在书籍、章节间自由拖拽移动，支持批量排序。

2.3 权限与安全（企业级）

  • 基于角色 RBAC 权限：提供全局/单本书籍/单页面三级权限，精细化控制「查看/编辑/创建/删除」。
  • 多登录认证：支持默认账号密码 + LDAP/OIDC/SAML2 单点登录 + 第三方社交登录。
  • MFA 多因素认证：支持 TOTP（谷歌/微软验证器）+ 静态备用验证码，可按角色强制开启。
  • 全局开关：支持整站公开访问开关、全局评论启停、高安全图片上传加密。

2.4 基础配套

  • 多语言支持：内置中、英、日、德、法、俄、西等十余国语言，用户可自定义界面语种。
  • 主题设置：提供深浅双主题，用户可独立设置浅色或暗黑模式。
  • 自定义站点：支持自定义网站名称、Logo、注册开关、首页展示内容。

三、适用人群

3.1 企业与技术团队（主力用户）

  • 研发团队：用于管理接口文档、技术架构手册、运维 SOP。
  • 行政人事：用于管理制度手册、员工培训文档。
  • 产品团队：用于管理需求文档、产品使用手册，可替代高价 Confluence。

3.2 个人用户

  • 程序员：建立个人知识库、读书笔记、项目笔记。
  • 站长/开发者：建站私有化笔记，替代 Notion 付费空间。

3.3 小组织/社团/培训机构

  • 用途：管理社团规章制度、课程讲义、培训资料归档。
  • 优势：低成本搭建内部文档站。
  • 局限性（不适合）：
  • 不适用于重度实时多人在线协同文档（无在线协同编辑，偏静态知识库）。
  • 不适用于超大附件在线预览（附件仅支持下载）。

四、免费与付费情况

4.1 软件本体

  • 永久免费开源：遵循 MIT 协议，源码完全免费。
  • 无功能阉割：无用户数上限、无文档数量限制。
  • 无官方 SaaS：BookStack 不提供官方云托管订阅服务，仅能自建部署。
  • 授权费：下载部署无任何授权费，自建实例永久免费使用全部官方功能。

4.2 潜在自费项（按需自选）

  1. 服务器成本：自建需要 VPS/云服务器，最低 2.5 英镑低配 VPS 即可流畅运行（唯一硬性花费）。
  2. 商业技术支持：官方无付费客服，如需定制二开、部署代装，需找第三方服务商付费。
  3. 域名与 SSL 证书：对外公网访问需自行购买域名，证书可免费申请 Let’s Encrypt。

4.3 特别区分

  • 注意：国内「书栈网 bookstack.cn」是同名独立项目，非本官网 BookStack，收费规则不通用。

五、详细使用指南

5.1 阶段一：快速部署（3 种方案）

新手建议首选 Docker 方案

方案 1：Docker Compose 一键部署

  1. 环境准备：服务器装好 Docker+Docker-Compose。
  2. 配置 Docker Compose：新建 docker-compose.yml 配置（最简模板如下）。
  3. yaml
version: "3.3"
services:
  bookstack:
    image: linuxserver/bookstack
    ports: ["6875:80"]
    environment:
      - APP_URL=http://你的 IP:6875
      - DB_HOST=mysql
      - DB_USER=root
      - DB_PASS=自定义数据库密码
      - DB_DATABASE=bookstack
    volumes: ["./bookdata:/config"]
    depends_on: [mysql]
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: 自定义数据库密码
      MYSQL_DATABASE: bookstack
version: "3.3"
services:
  bookstack:
    image: linuxserver/bookstack
    ports: ["6875:80"]
    environment:
      - APP_URL=http://你的 IP:6875
      - DB_HOST=mysql
      - DB_USER=root
      - DB_PASS=自定义数据库密码
      - DB_DATABASE=bookstack
    volumes: ["./bookdata:/config"]
    depends_on: [mysql]
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: 自定义数据库密码
      MYSQL_DATABASE: bookstack
  1. 启动服务：执行 docker-compose up -d。
  2. 访问登录：访问 http://服务器 IP:6875，默认管理员账号：admin@example.com，密码：password（首次登录立刻改密）。

方案 2：原生 PHP 手动部署

  • 环境：安装 PHP 7.4+、MySQL 5.7~8.0、Nginx/Apache。
  • 步骤：拉取源码配置 .env 数据库参数，配置站点伪静态。

方案 3：先试用演示站

5.2 阶段二：日常基础使用步骤

  1. 建立顶层分类：首页 → Shelves → 新建书架（例：研发文档、行政制度），用于归类多本书籍。
  2. 创建书籍：进入书架 → New Book（新建书籍，对应一套完整手册，如《Java 开发规范》）。
  3. 新建章节：打开书籍 → New Chapter（分大目录，如环境搭建、语法规范）。
  4. 新建页面（正文）：章节内 → New Page，选择富文本或 Markdown 编辑，支持插入图片、draw.io 图表、代码块。
  5. 权限配置：书籍/页面右上角 → Permissions，新增角色并配置读写权限。
  6. 导出分享：页面/书籍 → Export，导出 PDF 分享。
  7. 用户管理：后台 Settings → Users/Roles，新增成员、分配角色权限。

六、部署与使用避坑点（高频踩坑汇总）

6.1 部署避坑

  1. 数据库版本问题：原生兼容 MySQL 5.7~8.0，MySQL 5.6 及以下、MariaDB 新版本易出现连接失败。Docker 优先使用官方配套 mysql:8.0 镜像，不要混用高版本数据库。
  2. APP_URL 配置：.env 或 docker 环境变量 APP_URL 必须填写 最终访问域名/IP（带 http/https）。配置错误会导致图片打不开、附件链接失效、跳转异常。
  3. 端口冲突：默认映射 6875:80，若服务器 80 端口被 Nginx 占用，需更换宿主机端口（如 8080:80）。
  4. PDF 导出乱码：原生 Dompdf 缺少中文字体，导出 PDF 中文会出现方框乱码。
  • 解决：替换 wkhtmltopdf 渲染引擎或手动导入中文字体包。
  1. 数据备份：定期备份 /config 挂载目录 + MySQL 数据库。容器删除易丢失数据，建议配置定时自动备份。

6.2 日常使用避坑

  1. 图片公开泄露：默认上传图片 URL 可被外网遍历，敏感文档务必开启「Higher Security Image Uploads（高安全图片加密）」（后台设置 → Features & Security），自动给图片路径加随机密钥串防爬取。
  2. 注册开关管控：公网部署务必关闭「用户开放注册」，否则爬虫批量注册账号。需要成员加入时由管理员手动创建账号。
  3. 权限层级误区：书架权限≠书籍权限，书籍单独配置权限会覆盖书架继承权限，涉密文档建议单本书独立锁权限。
  4. 编辑器切换：单页面选定富文本/Markdown 后不要反复切换，格式易错乱，建议长期固定一种编辑格式。
  5. 系统升级：版本升级前先全量备份数据库。新版会变更数据表结构，直接升级大概率丢字段报错。
  6. 附件预览限制：不支持 Office 在线预览，Word/Excel/PDF 附件仅支持上传下载，如需预览需额外集成第三方预览服务。

6.3 运维避坑

  1. 内存要求：服务器内存最低 1G，512M 内存易出现 PHP 内存溢出、打开页面超时。
  2. MFA 管理：开启 MFA 后务必妥善保存备用验证码，管理员丢失验证码将无法登录后台。

七、补充拓展

7.1 二次开发

  • 可定制：开源可自定义 LOGO、首页、新增插件。
  • 社区资源：社区有汉化优化版可供参考。

7.2 替代选型建议

  • 想要云端免部署：选 Notion 或石墨。
  • 想要在线实时协同：选 OnlyOffice 知识库。


评论

暂无评论