BookStack

用于存储和组织信息和文档的平台。BookStack 的详细信息可以在官方网站https://www.bookstackapp.com/上找到。

• 安装说明
• 文档
• 演示实例
  • 管理员登录
• 截图
• BookStack 博客
• 问题清单
• 不和谐聊天

📚项目定义

BookStack 是一个自以为是的 wiki 系统，它提供了一种愉快而简单的开箱即用体验。实例的新用户应该会发现体验直观，并且只需要基本的文字处理技能就可以参与在 BookStack 上创建内容。该平台应为需要的人提供高级电源功能，但不应干扰核心的简单用户体验。

BookStack 并非设计为可用于与上述声明不同的目的的可扩展平台。

在开发理念上，BookStack 采用轻松、开放、积极的方式。归根结底，这是由人们贡献自己的空闲时间开发和维护的免费软件。

🌟项目赞助商

下面显示的是我们的铜牌、银牌和金牌项目赞助商。非常感谢这些公司对项目的支持。注意：所列服务未经官方 BookStack 项目以任何方式进行测试、审查或支持。 查看所有赞助商。

银牌赞助商

铜牌赞助商

🛣️路线图

下面是 BookStack 的高级路线图视图，用于提供项目发展方向的方向感。这可能随时发生变化，并且不会反映许多功能和改进，这些功能和改进也将包含在此路线图的旅程中。有关即将发布的版本中包含的更详细的内容，您可以查看下面“发布过程”部分中定义的项目里程碑。

• 平台 REST API - （大多数操作已实现，正在成熟）
  • 一个 REST API，至少涵盖对核心内容模型（书籍、章节、页面）的控制，以实现自动化和平台扩展。
• 编辑对齐和审查 - （完成）
  • 审查页面编辑器，以实现更高的互操作性和功能对等性，同时考虑协作编辑的潜力。
• 权限系统审查 - （进行中）
  • 改进权限的应用方式以及审查权限和角色系统的效率。
• 安装和部署流程改造
  • 为用户创建一个简化且安全的流程，以减少开发要求（无 git 或作曲家要求）部署和更新 BookStack。

🚀发布版本控制和流程

每个 BookStack 版本都分配了一个基于日期的版本号，格式为 v<year>.<month>[.<optional_patch_number>]. 例如：

• v20.12- 2020 年 12 月发布的新功能。
• v21.06.2- 2021 年 6 月功能发布后的第二个补丁发布。

补丁版本通常相当小，主要用于修复，因此不太可能在更新时造成损坏。功能版本通常更大，除了修复和增强之外，还带来了新功能。这些版本更有可能在更新时引入重大更改，因此值得检查更新指南中的任何注释。

每个 BookStack 版本都会创建一个里程碑，并分配给它的问题和拉取请求，以定义该版本中的内容。里程碑被建立，然后一直工作直到完成，在一些测试和文档更新之后，将部署该版本。

功能发布和一些补丁发布将附有BookStack 博客上的帖子，其中将提供有关功能、更改和更新的更多详细信息，否则GitHub 发布页面将显示更改列表。您可以在此链接上注册以收到新 BookStack 博客文章的提醒（最多每周一次）。

🛠️开发与测试

BookStack 上的所有开发目前都在 development分支上完成。当需要发布时，development分支会合并到带有内置和缩小的 CSS 和 JS 的发布中，然后在其版本上标记。以下是当前的开发要求：

• Node.js v14.0+

这个项目使用 SASS 进行 CSS 开发，它是与 JavaScript 一起使用一系列 npm 脚本构建的。以下 npm 命令可用于安装依赖项并运行构建任务：

# Install NPM Dependencies
npm install

# Build assets for development
npm run build

# Build and minify assets for production
npm run production

# Build for dev (With sourcemaps) and watch for changes
npm run dev

BookStack 有许多使用 Laravel 内置测试功能的集成测试，这些功能使用 PHPUnit。在应用程序配置中定义了一个 mysql_testing数据库，这是 PHPUnit 使用的。该数据库设置的数据库名称、用户名和密码均定义为 bookstack-test. 在测试之前，您必须创建该数据库和该组凭据。

测试数据库也需要事先迁移和播种。这可以通过以下命令完成：

php artisan migrate --database=mysql_testing
php artisan db:seed --class=DummyContentSeeder --database=mysql_testing

完成后，您可以 composer test在应用程序根目录中运行以运行所有测试。

📜代码标准

PHP 代码标准使用 PHP_CodeSniffer进行管理。使用PHPStan和Larastan进行静态分析。以下命令可用于利用这些工具：

# Run code linting using PHP_CodeSniffer
composer lint

# As above, but show rule names in output
composer lint -- -s

# Auto-fix formatting & lint issues via PHP_CodeSniffer phpcbf
composer format

# Run static analysis via larastan/phpstan
composer check-static

如果提交 PR，按照我们的项目标准进行格式化将有助于清晰，但不要太担心使用/理解这些工具，因为我们总是可以在稍后阶段被我们的自动化工具拾取时解决问题。

🐋使用 Docker 进行开发

此存储库附带用于开发目的的 Docker Compose 配置。它将构建一个安装了所有需要的扩展的 PHP 映像，并启动一个 MySQL 服务器和一个节点映像来监视 UI 资产。

要开始使用，请确保您满足以下要求：

• 安装了 Docker 和 Docker Compose
• 您的用户是该 docker组的一部分

如果满足所有条件，您可以继续执行以下步骤：

1. 复制 .env.example到 .env ，更改 APP_KEY为随机 32 字符字符串并设置 APP_ENV为 local.
2. 确保端口 8080 未使用 ，否则更改 DEV_PORT为主机上的空闲端口。
3. 运行 chgrp -R docker storage 。开发容器将 chown storage目录给 www-data容器内的用户，以便 BookStack 可以写入它。您需要在此处将组更改为主 docker机组，以免失去对 storage目录的访问权限。
4. 运行 docker-compose up并等待，直到构建映像并完成所有数据库迁移。
5. 您现在可以使用 admin@admin.com和 password作为密码登录 localhost:8080（或指定的其他端口）。

如果需要，您将能够通过 docker-compose 运行任何工匠命令，如下所示：

docker-compose run app php artisan list

docker -compose 设置运行MailHog的实例并设置环境变量以将任何 BookStack 发送的电子邮件重定向到 MailHog。您可以通过 MailHog Web 界面查看此邮件 localhost:8025。DEV_MAIL_PORT您可以通过设置环境变量来更改可以访问 MailHog 的端口。

运行测试

启动通用开发 Docker 后，迁移和播种测试数据库：

# This only needs to be done once
docker-compose run app php artisan migrate --database=mysql_testing
docker-compose run app php artisan db:seed --class=DummyContentSeeder --database=mysql_testing

迁移和播种数据库后，您可以像这样运行测试：

docker-compose run app php vendor/bin/phpunit

调试

docker-compose 设置附带 Xdebug，您可以在端口 9090 上收听。注意：对于某些编辑器，如 Visual Studio Code，您可能需要将工作区文件夹映射到 docker 容器中的 /app 文件夹才能工作。

🌎翻译

BookStack 中的文本翻译通过Crowdin 上的 BookStack 项目进行管理。一些字符串有冒号前缀的变量，例如 :userName. 保留这些值，因为它们将在运行时被替换。Crowdin 是提供翻译的首选方式，否则可以在 resources/lang路径中找到原始翻译文件。

如果您希望将新语言添加到 Crowdin，以便您能够为其提供翻译，请在此处打开一个新问题。

请注意，BookStack 中的翻译提供给“Crowdin 全球翻译记忆库”，帮助 BookStack 和其他项目查找翻译。如果您对此贡献不满意，则不建议向 BookStack 提供翻译，甚至通过 GitHub 手动提供。

🎁贡献、问题和拉取请求

随意创建问题以请求新功能或报告错误和问题。请按照创建问题时提供的模板进行操作。

欢迎请求请求。除非进行小的调整或语言更新，否则最好尽早打开拉取请求或为您的预期更改创建一个问题，以讨论它将如何适应项目并计划合并。仅仅因为功能请求存在或被标记，并不意味着该功能将被核心项目接受。

拉取请求应该从 development分支创建，因为一旦完成它们将被合并回 development。请不要从分支构建或请求合并到 release分支，因为这仅用于发布版本。如果您希望更改 CSS 或 JavaScript 内容，请编辑 resources/. 其中的任何 CSS 或 JS 文件 public都是从这些源文件构建的，因此不应直接编辑。

该项目的行为准则可以在这里找到。

🔒安全

可以在此处的文档站点上找到管理 BookStack 实例的安全信息。

如果您希望收到有关新的潜在安全问题的通知，您可以注册 BookStack 安全邮件列表。

如果您想报告安全问题，可以在此处找到这样做的详细信息。

♿可访问性

我们希望尽可能多的人可以访问 BookStack。我们的目标是在可能的情况下至少达到 WCAG 2.1 A 级标准，尽管我们不会在每次发布时都严格测试这一点。如果您遇到任何可访问性问题，请随时打开一个问题。

🖥️网站、文档和博客

包含项目文档和博客的网站可以在BookStackApp/website repo 中找到。

⚖️执照

BookStack 源代码是在 MIT 许可下提供的。

BookStack 使用和包含的库是根据它们自己的许可和版权提供的。我们的许多核心依赖项的许可证可以在下面的归属列表中找到，但这并不是 BookStack 中使用的所有项目的详尽列表。