LibreKB 介绍与选型指南

LibreKB v2.3.3（michaelstaake/LibreKB，PHP 8.4+MySQL，GPL-3.0）介绍与选型：定位、版本演进、MVC 架构、功能清单、官方六步安装、适用场景与风险，及与 BookStack/DokuWiki/osTicket 的量化对比（2026-11-01 溯源）。

LibreKBLibreKB文档管理WikiDocs2026/11/01

LibreKB 介绍与选型指南

目标：为内网自建知识库/帮助台选型提供 LibreKB（michaelstaake/LibreKB）的完整认知地图——定位、架构、功能、上手路径与量化竞品对比。本文全部结论来自官方仓库与 GitHub 公开数据联网溯源（查询日期 2026-11-01），实测细节见本专栏其余三篇。

一、环境信息

  • 软件名称：LibreKB（仓库 michaelstaake/LibreKB）
  • 最新稳定版：v2.3.3（GitHub Releases atom，条目标注 2026-10-30 更新；查询日期 2026-11-01）
  • 许可证：GPL-3.0（仓库 LICENSE 文件）
  • 运行要求：PHP 8.4 或更新、MySQL 或 MariaDB、支持 .htaccess 重写的 Web 服务器（Apache、LiteSpeed、OpenLiteSpeed、Lighttpd）
  • 必需 PHP 扩展：pdo_mysql、curl、mbstring、fileinfo
  • 官方容器形态：Dockerfile 基于 php:8.4-apache，官方 docker-compose.yml 搭配 mysql:8.0
  • 社区热度：GitHub stars 62（shields.io 徽章数据，查询日期 2026-11-01）
  • 技术栈：PHP 原生 MVC + MySQL，前端 Bootstrap + TinyMCE，邮件走 PHPMailer

二、软件概述

2.1 定位与一句话价值

LibreKB 官方 README 自述为 "Knowledge Base Web App - Free, Open Source, Self Hosted, PHP/MySQL"——一个用任意 LAMP 主机就能跑起来的开源知识库 Web 应用。它面向的典型场景是：项目/产品/团队对外或内部的常见问题文档站（帮助台知识库），支持分类嵌套、文章富文本编辑、附件下载、站内搜索、活动日志，以及自 v2.2.0 起的只读 JSON API。

💡 技术拓展：「帮助台（Helpdesk）」指面向用户的问题自助与工单体系；LibreKB 只做其中的知识库/自助文档层，不含工单流转（同类需求可对比 osTicket，见第七章）。

2.2 版本演进（GitHub Releases atom 实查，2026-11-01）

版本条目更新时间关键变化
v1.3.12024-12-06v1 末期维护版
v2.0.02025-07-19重写为 MVC 架构，引入 /install 安装器与 /upgrade 升级器
v2.0.12025-08-05依据社区反馈移除在线更新检查，改为手动查版本
v2.1.02025-12-29新增文章附件（attachments 表与 /attachment/{id} 下载路由）
v2.2.02026-10-19新增只读 JSON API（/api/v1/*，默认关闭）
v2.3.02026-10-192.3 系列起点
v2.3.12026-10-20快速修复
v2.3.22026-10-27快速修复
v2.3.32026-10-30当前最新稳定版

节奏解读：v2.0.0（2025-07）完成架构重写后约一年半只出了 v2.0.1/v2.1.0 两个功能版；2026-10 中旬两周内密集发布 v2.2.0→v2.3.3 共 5 个版本（API 上线后进入活跃修复期）。对选型而言：项目处于「小作者、低星、但近期活跃」的组合状态。

2.3 作者与治理

单一维护者项目（michaelstaake），无独立官网，文档以仓库 README 为主，问题反馈走 GitHub Issues。无商业实体、无付费支持层。

三、核心架构

3.1 前端控制器与路由

所有请求由 index.php 接收，Apache 靠自带 .htaccess 把非真实文件的请求重写进前端控制器（子目录部署需打开 RewriteBase 注释）。路由集中在 routes.php，声明式注册公开路由（首页/分类/文章/搜索/附件/登录/密码重置）、/admin 管理路由组（带 auth 与 role:admin,manager、role:admin 三级中间件）以及 /install、/upgrade 特殊路由。

3.2 MVC 分层

  • controllers/：HomeController、ArticleController、CategoryController、AdminController、ApiController、InstallController、UpgradeController、SearchController、AttachmentController、ProfileController、UserController、PasswordController、LogController 等；
  • models/：Database、Article、Category、Attachment、FileStorage、Setting、User、Search、Email、Log；
  • views/：前台 main 布局与后台 admin 布局模板；
  • vendor/：随包分发 PHPMailer、Bootstrap、TinyMCE 等第三方资源，无需 Composer 联网安装。

3.3 数据模型

安装器建 6 张表：users（含 group 预定义用户组、密码重置字段）、settings（name/value 键值对，站点配置全在此）、articles（number/title/slug/category/content/order/status/featured）、categories（支持 parent 自引用嵌套）、log（谁-做了什么-对什么-何时）、attachments（v2.1.0 引入，original_name/stored_name/extension/mime_type/size）。时间字段均为 VARCHAR 存储的 Y-m-d H:i:s 字符串，是该项目轻量取向的直接体现。

3.4 安全机制

  • 会话：PHP session + HttpOnly; SameSite=Lax Cookie，响应头带 X-Frame-Options: DENY；
  • CSRF：所有后台表单含 csrf_token 隐藏域，POST 校验失败返回 403；
  • 富文本入库与渲染前经 HtmlSanitizer::clean() 清洗；
  • API 密钥比较用 hash_equals(sha256, sha256) 防时序侧信道；
  • 上传目录 storage/uploads/attachments 由程序自动写入 Require all denied 的 .htaccess，文件以 32 位随机十六进制名落盘，不可直接 URL 访问，只能走 /attachment/{id} 受控下载。

3.5 配置模型

双层配置：文件层 config.php（由 config.example.php 复制，数据库连接、systemURL、SMTP 邮件、bypassRequirements）+ 数据库层 settings 表（站点名、可见性、外观、编辑器、API、维护模式，后台可视化修改）。config.php 内置一个 /.dockerenv 探测分支：容器环境自动套用 Docker 默认值（详见《LibreKB 2.3.3 配置参数详解》）。

四、功能特性

官方 README 特性清单（逐条对照源码核实）：

特性说明
100% 自由开源GPL-3.0，无功能阉割
极低部署门槛任意支持 .htaccess 的 PHP 主机/虚拟主机的/LAMP/Docker 均可
分钟级安装/install 向导建表并创建管理员
品牌定制General 设站点名、Appearance 设主色/Logo/自定义 CSS/Google Fonts
后台设置五分区General / Appearance / Editor / API / Maintenance
编辑器工具栏可配Editor 分区勾选 TinyMCE 按钮
预定义用户组users.group（admin/manager 等），后台用户管理仅 admin 可见
TinyMCE 富文本文章正文所见即所得
分类无限嵌套categories.parent 自引用，前台面包屑
附件下载文章可挂多个文件（白名单扩展名、单文件 ≤10 MB、单次 ≤10 个）
邮件密码重置PHPMailer SMTP，配合 /password/reset
Bootstrap 响应式移动端可用
只读 JSON APIv2.2.0 起，默认关闭，X-API-Key 认证，详见《LibreKB 2.3.3 API 使用详解》
维护模式开启后前台与 API 统一 503/维护页
活动日志log 表记录登录/登出/增删改

五、快速开始

以下路径转述自官方 README 与仓库 Dockerfile/docker-compose.yml（2026-11-01 实查），本专栏《LibreKB 2.3.3 Docker Compose 部署指南》有端到端实测版。

5.1 裸机六步（官方 Getting Started）

  1. 准备 PHP 8.4+、MySQL/MariaDB，启用 pdo_mysql、curl、mbstring、fileinfo；
  2. 文件部署到服务器，DocumentRoot 指向含 index.php 的目录；
  3. cp config.example.php config.php，填数据库四要素与 systemURL（含子目录路径，如 https://example.com/kb/）；
  4. 建空库（数据库用户需有建表权限），保证 PHP 对 storage/uploads、storage/cache 可写；
  5. 浏览器打开 /install，输入管理员邮箱与密码，运行安装器（示例可用 admin@kb.example.com / q1w2e3r4）；
  6. /login 登录后台；用户表非空后 /install 自动失效（返回 404）。

5.2 官方 Docker Compose

仓库自带 docker-compose.yml：app 服务由根目录 Dockerfile 构建（php:8.4-apache，装 pdo_mysql/mysqli/zip 扩展、开 mod_rewrite、设 upload_max_filesize=12M/post_max_size=128M），db 服务用 mysql:8.0；端口经 APP_PORT（默认 8080）映射，数据库凭据由 DB_ROOT_PASS/DB_NAME/DB_USER/DB_PASS 环境变量注入，源码目录 bind mount 到 /var/www/html，数据卷 librekb-db-data 持久化。config.php 检测到 /.dockerenv 时套用容器默认值，因此 Compose 起栈后直接访问 /install 即可。

5.3 升级

官方口径：新发布文件覆盖旧文件、保留自己的 config.php，然后访问 /upgrade。

六、适用场景与限制

6.1 适用场景

  • 中小团队/开源项目的产品文档站与帮助台知识库（文章量千级以内）；
  • 已有 LAMP 虚拟主机、没有专职运维的环境（共享主机也能装）；
  • 需要把知识库内容喂给外部应用（聊天机器人、站内搜索组件）的场景——只读 JSON API 是同类轻量方案里少见的原生能力；
  • 内网离线部署：全量依赖随包 vendor/ 分发，安装与运行不需要外网。

6.2 限制与风险

  • 社区极小：62 stars、单维护者，长期维护与响应速度存在不确定性；
  • 无版本历史/草稿流：文章直接覆盖更新，没有内容修订回滚（对比 wiki 类产品的 revision 机制）；
  • API 只读：不能通过 API 创建/修改内容，自动化写入只能走数据库或后台界面；
  • 权限模型粗：预定义用户组粒度有限，无细粒度分类/文章级 ACL；
  • 搜索为基础匹配（标题与内容），无高亮/分词/相关度调优；
  • 无多租户/多知识库，一个实例一套库；
  • 表结构用 VARCHAR 存时间与文本状态值，扩展性一般，属"够用主义"设计。

七、同类选型对比

7.1 量化对比表（GitHub/shields.io 实查，2026-11-01）

维度LibreKB v2.3.3BookStackDokuWikiosTicket
GitHub stars6219k4.7k4k
最新稳定版v2.3.3（2026-10-30）v26.09.2release-2026-07-14c（tag）v1.18.4
技术栈PHP 8.4 + MySQLPHP（Laravel）+ MySQLPHP + 纯文本文件（无数据库）PHP + MySQL
存储形态MySQL 6 表MySQL平面文件MySQL
定位知识库/帮助台文档结构化文档/WikiWiki/笔记工单+帮助台
只读 API原生 JSON API（v2.2.0 起）REST API插件生态无原生 KB API
许可证GPL-3.0MITGPL-2.0GPL-2.0
安装复杂度极低（6 步/向导建表）低-中（artisan 迁移）极低（上传即用）中（含 cron/邮件管道）

⚠️ 注意：DokuWiki 的 GitHub 仓库为官方镜像且不用 GitHub Releases 发版，表中取其最新 tag；BookStack 版本号采用「年月」式发布命名。

7.2 站内同类已交付文档

本平台同组（文档与知识库）已交付多篇实战，选型时可横向阅读：

7.3 怎么选

  • 要工单流转/客服 SLA → osTicket，LibreKB 不含工单；
  • 要大团队结构化文档 + 权限细分 + 成熟生态 → BookStack，星数与功能面全面占优；
  • 要零数据库、纯文件可 git 管理 → DokuWiki；
  • 要PHP/MySQL 基础上的极简知识库 + 原生只读 JSON API + 分钟级安装，且接受小社区风险 → LibreKB；
  • 要Go 单二进制无依赖 → LeafWiki；要深度定制 wiki 引擎 → django-wiki。

LibreKB 的差异化落点是「LAMP 上最省事的知识库 + 自带对外 JSON API」，适合把文档"发出去给程序读"的轻量集成场景。

八、参考链接

LibreKB 介绍与选型指南 - Quzuo