shiftinv/bookstack

BookStack 镜像文档

概述

BookStack是一个 opinionated 的wiki系统，旨在提供直观、简单的开箱即用体验，用于存储和组织信息及文档。新用户可轻松上手，仅需基本文字处理技能即可参与内容创建，同时为需要的用户提供高级功能，而不影响核心的简单用户体验。

核心功能与特性

• 直观用户体验：简洁界面设计，降低使用门槛，适合各类用户快速上手
• 内容组织结构：通过书籍（Books）、章节（Chapters）、页面（Pages）三级结构有序管理文档
• 多编辑模式支持：集成富文本编辑器和Markdown编辑器，满足不同用户习惯
• 权限管理系统：灵活的角色与权限配置，精确控制内容访问范围
• 多语言支持：通过Crowdin平台提供多语言翻译，支持国际化使用
• REST API：基础API已实现，支持Books、Chapters、Pages等核心内容模型的自动化操作
• 集成测试框架：基于Laravel测试框架，确保功能稳定性与可靠性

使用场景

• 团队知识库：集中存储团队文档、流程规范、最佳实践，促进信息共享
• 项目文档管理：管理项目需求、设计文档、开发指南、测试报告等全生命周期文档
• 个人知识管理：组织学习笔记、研究资料、技术文档，构建个人知识体系
• 企业内部文档：搭建企业内部知识库，整合产品文档、培训材料、规章制度

使用方法与配置说明

Docker Compose 开发环境部署

BookStack提供Docker Compose配置用于开发环境，步骤如下：

环境准备

• 安装Docker和Docker Compose
• 将当前用户添加到docker用户组（避免权限问题）

配置环境变量

bash
# 复制环境变量示例文件
cp .env.example .env

# 编辑.env文件，设置关键参数
# APP_KEY: 生成随机32字符字符串（可通过`openssl rand -hex 16`生成）
# APP_ENV: 设置为local（开发环境）
# DEV_PORT: 主机访问端口（默认8080，如被占用可修改为其他空闲端口）
# DEV_MAIL_PORT: MailHog邮件预览端口（可选，默认8025）

设置存储目录权限

bash
# 确保容器内www-data用户可写入storage目录
chgrp -R docker storage

启动服务

bash
docker-compose up

等待镜像构建、依赖安装及数据库迁移完成后，通过http://localhost:8080访问应用。默认管理员凭据：admin@admin.com / password

常用操作

运行Artisan命令

通过Docker Compose执行Laravel Artisan命令：

bash
docker-compose run app php artisan [命令]
# 示例：查看命令列表
docker-compose run app php artisan list

邮件测试

Docker Compose配置集成MailHog服务，用于捕获应用发送的邮件。访问http://localhost:8025即可查看邮件内容。

运行测试

1. 准备测试数据库

bash
# 迁移测试数据库结构
docker-compose run app php artisan migrate --database=mysql_testing

# 填充测试数据
docker-compose run app php artisan db:seed --class=DummyContentSeeder --database=mysql_testing

2. 执行测试套件

bash
docker-compose run app php vendor/bin/phpunit

版本与更新

BookStack采用语义化版本控制，格式为v<phase>.<feature>.<patch>：

• Patch版本（如v0.25.2）：仅包含bug修复，更新风险极低
• Feature版本（如v0.26.0）：包含新功能及改进，可能存在少量不兼容变更，建议更新前查看官方更新指南
• Phase版本：重大架构变更，可能需要手动干预以完成升级

更新信息可通过BookStack博客或https://github.com/BookStackApp/BookStack/releases获取。

安全与贡献

• 安全管理：管理员安全配置指南参见官方文档
• 贡献方式：通过GitHub提交issues或pull requests，代码需遵循PSR-2标准；CSS/JS修改需编辑resources/目录下源文件，而非public/目录下构建文件
• 翻译贡献：通过Crowdin平台提交翻译，支持新语言可通过GitHub issue申请

许可协议

BookStack基于MIT许可证开源，源代码可自由使用、修改和分发。第三方依赖库遵循各自许可协议。