后端知识库知识管理文档【免费下载链接】BookStackNOW MANAGED ON CODEBERG项目地址https://gitcode.com/gh_mirrors/bo/BookStack点击查看免费下载导读BookStack 提供了一种名为 Portable ZIP便携式 ZIP的导出格式用于在 BookStack 实例之间进行内容的便携传输、存储、导出与导入。本文以仓库文档 dev/docs/portable-zip-file-format.md 为主体结合app/Exports/ZipExports/目录下的导出构建器、读取器、校验器与导入执行器等源码实现完整解析该格式的容器结构、data.json数据模型、[[bsexport:...]]引用语法、稳定性承诺以及导入校验与安全边界。读完本文你将能够读懂并自行生成、解析或移植 BookStack 的便携 ZIP 导出文件也能准确判断哪些内容可以安全地往返于 BookStack 实例之间。概述便携 ZIP 是什么不是什么便携式 ZIP 是 BookStack 提供的导出容器格式其设计目标非常明确让 BookStack 内容能够在不同实例之间便携地传输、存储、导出与导入。官方文档同时强调这不是一种备份格式Not a BookStack backup format因为它缺少恢复一个完整 BookStack 实例所需的大量数据用户、权限、设置、审计日志等备份场景应使用官方推荐的更合适的替代方案。从源码看该格式的完整实现集中在 app/Exports/ZipExports/ 目录导出侧ZipExportBuilder构建 ZIP、ZipExportFiles生成文件引用、ZipExportReferences改写内容中的内部链接为引用标记导入侧ZipExportReader读取 ZIP 与data.json、ZipExportValidator结构校验、ZipImportRunner真正落库导入、ZipImportReferences把引用标记替换回新实例的内部链接。稳定性承诺格式稳定性是便携 ZIP 的核心设计原则官方文档给出了三条明确的规则新功能与属性可以在任何版本中加入在合理范围内尽量避免对既有功能/属性的修改与删除一旦必须做出潜在的破坏性变更将在 BookStack 的发布/更新说明中明确标注。同时文档界定了一个重要边界仅新增功能/属性不视为破坏性变更。破坏性变更的判定基于是否影响文档所描述属性的常规、预期使用方式而不是基于使用方的假设或任何可能的破坏。文档特别举例如果你的应用因为硬编码按属性位置如第三个属性解析而不是按属性名解析导致新增属性后解析错位那么责任在使用方自身。这与 BookStack 一贯追求的前向兼容理念一致。格式总览极简的 ZIP 容器该格式刻意保持简单、可读并基于开放标准构建便于在绝大多数主流编程语言中被轻松读取和处理。其整体结构如下ZIP archive container ├── data.json # 导出数据结构化 JSON └── files/ # 被引用的文件目录 ├── file-a ├── file-b └── ...data.json包含导出的全部结构化数据files/包含导出内容中引用的所有文件封面图、页面图片、附件等。这一结构在源码 ZipExportBuilder.php 中有直接对应实现构建时先用tempnam创建临时 ZIP 文件通过ZipArchive写入data.json$zip-addFromString(data.json, json_encode($this-data))再调用$zip-addEmptyDir(files)创建空目录最后逐个把引用文件以files/fileRef的条目名加入 ZIP。读取侧 ZipExportReader.php 则要求data.json必须存在并对其实施两层防护使用statName(data.json)检查条目是否存在校验其大小不超过app.upload_limit配置max(intval(config()-get(app.upload_limit)), 1) * 1000000字节防止超大 JSON 拖垮内存。引用机制两种引用两个层级文件引用String reference导出数据 JSON 中标注为String reference的属性是直接指向 ZIP 内files/目录下文件名的引用。例如下面的 book 封面直接引用了 ZIP 内应存在的files/4a5m4a.jpg{ book: { cover: 4a5m4a.jpg } }源码 ZipExportFiles.php 揭示了这些随机文件名的生成方式对每个附件与图片用Str::random(20)生成 20 位随机文件名保留原始扩展名图片的扩展名取自其存储路径并在与已有文件名冲突时循环重新生成确保files/内名字唯一。读取侧 ZipExportReader.php 提供了fileExists、fileWithinSizeLimit、streamFile、sniffFileMime等配套方法——其中sniffFileMime会用 WebSafeMimeSniffer 嗅探文件内容而非信任扩展名为导入时的安全校验提供依据。内容内引用[[bsexport:...]]标记在 HTML 与 Markdown 内容中如果需要引用导出内容里的其他对象可以使用如下格式[[bsexport:object:reference]]其中reference指向数据对象的id。官方文档给出五种类型的示例[[bsexport:image:22]] [[bsexport:attachment:55]] [[bsexport:page:40]] [[bsexport:chapter:2]] [[bsexport:book:8]]对应解析正则位于 ZipReferenceParser.php/\[\[bsexport:([a-z]):(\d)]]/类型会被strtolower归一化id被intval转为整数随后调用传入的处理器若处理器返回非空字符串则替换原标记。导出侧如何生成这些标记ZipExportReferences.php 的buildReferences会在打包前遍历所有页面/章节/书籍的内容用 ZipReferenceParser 的parseLinks把指向实例内部 URL 的链接解析成对应的模型再按规则改写为[[bsexport:...]]标记附件若附件也在本次导出范围内则改写为[[bsexport:attachment:id]]图片仅处理gallery图库与drawio两种类型若图片可访问imageService-imageAccessible且属于导出范围会同时把图片对象加入所属页面的images数组并改写为[[bsexport:image:id]]实体书籍/章节/页面仅当目标对象在导出范围内时改写为对应的[[bsexport:book|chapter|page:id]]否则保持原链接不动。导入侧如何还原ZipImportReferences.php 维护了一张以type:old-reference-id为键、新导入模型为值的referenceMap。导入过程中每个新创建的实体/图片/附件都会登记映射最后replaceReferences()遍历全部导入对象用parseReferences把内容里的[[bsexport:...]]替换为实体$model-getUrl()新实例中的真实 URL图库图片$model-thumbs[display] ?? $model-url附件$model-getUrl(false)。此外 ZipImportReferences.php 还处理 draw.io 图的内嵌引用把 HTML 中drawio-diagram旧id的属性值替换为新图片 id。HTML 与 Markdown 内容规范BookStack 的内容以 HTML 为主存储与使用。文档规定提供或期望 HTML 的属性要么名为html要么在属性名中包含html如description_html。需要注意的边界包括BookStack 支持的 HTML 范围尚未正式文档化可参考 WYSIWYG 编辑器实际产出的 HTML 作为基准顶层元素通常应保持常见块级格式p、blockquote、h1、h2等除常见行内元素外不应使用嵌套或自定义结构部分使用 HTML 的区域如书籍与章节的描述会严格按允许列表过滤 HTML 标签与属性——这一点与仓库中的 HtmlContentFilter 等过滤实现相对应Markdown 方面BookStack 以 CommonMark 规范为目标并额外支持表格tables与任务列表task-listsMarkdown 中允许 HTML但同样不保证所有 HTML 都能正常工作。内容安全文档给出明确的消费方安全建议即使内容直接来自某个 BookStack 实例也不要假定导出中的 HTML/Markdown 是安全的应将其视为潜在不安全内容处理。BookStack 默认会做基础过滤移除脚本等危险元素但这并非万无一失BookStack 自身还依赖 CSPContent Security Policy等额外安全机制来抵御多种攻击。仓库中的 CspService 与 HtmlNonceApplicator 正是这一安全体系的一部分。导出数据data.json顶层结构data.json是一个包含导出全部结构化数据的 JSON 文件顶层属性如下属性类型必填说明instanceInstance 对象可选导出源实例的详情exported_atString可选导出创建时的完整 ISO 8601 时间戳bookBook 对象可选书籍导出数据chapterChapter 对象可选章节导出数据pagePage 对象可选页面导出数据根据导出类型book、chapter、page中只会有其中一个存在。消费方应逐个检查这些键以判断导出类型以及自己是否能够处理文档特别提醒未来可能加入其他选项例如面向多本书的books数组因此明智的做法是显式检查自己能够处理的属性无法处理时报错提示不支持而不是假设固定的结构。源码与这一设计严格对应导出侧 ZipExportBuilder.php 分别提供buildForPage、buildForChapter、buildForBook三个入口各自只写入page/chapter/book一个顶层键exported_at使用date(DATE_ATOM)即 ISO 8601生成instance则取自设置项instance-id与 AppVersion 的版本号。导入侧 ZipExportReader.php 的decodeDataToExportModel同样按book→chapter→page的顺序探测三者皆无则抛出ZipExportException。数据对象详解以下对象及其属性构成 Application Data 的完整数据模型对应 app/Exports/ZipExports/Models/ 下的一系列模型类。Instance提供导出来源 BookStack 实例的信息性详情id- String必填BookStack 实例的唯一标识version- String必填导出源实例的 BookStack 版本。对应实现ZipExportBuilder::build()中$this-data[instance] [id setting(instance-id, ), version AppVersion::get()]。Bookid- Number可选导出系统中书籍的原始 IDname- String必填书籍名称/标题description_html- String可选HTML 格式的描述内容cover- String reference可选书籍封面图引用chapters- Chapter 数组可选书籍内的章节pages- Page 数组可选书籍的直接子页面tags- Tag 数组可选书籍的标签。关于pages的重要说明pages并非书籍内的全部页面只是不在任何章节中的直接子页面。要在书内构建如 BookStack 所示的有序混合章节/页面列表需要把chapters与pages合并后按priority值升序排序。这一逻辑在源码中有两处对应导出侧 ZipExportBook::children() 与导入侧 ZipImportRunner::importBook() 都采用usort按($a-priority ?? 0) - ($b-priority ?? 0)排序。此外导出侧 ZipExportBook::fromModel() 明确排除了草稿页面!$child-draft。Chapterid- Number可选导出系统中章节的原始 IDname- String必填章节名称/标题description_html- String可选HTML 格式的描述内容priority- Number可选在书内显示顺序的整数值低到高pages- Page 数组可选章节内的页面tags- Tag 数组可选章节的标签。Pageid- Number可选导出系统中页面的原始 IDname- String必填页面名称/标题html- String可选页面 HTML 内容markdown- String可选页面的用户 Markdown 内容priority- Number可选显示顺序的整数值低到高attachments- Attachment 数组可选页面上传的附件images- Image 数组可选页面使用的图片tags- Tag 数组可选页面的标签。页面内容要么提供markdown要么提供html并应限制在 BookStack 支持的 Markdown/HTML 范围内。页面编辑器类型由提供的内容决定若提供了非空markdown页面会被假定为 Markdown 编辑器页面在权限允许时HTML 由 Markdown 渲染而来否则使用提供的html作为编辑器与展示内容。源码中导出侧 ZipExportPage::fromModel() 仅在模型 markdown 非空时写入markdownHTML 则通过(new PageContent($model))-render()渲染导入侧 ZipImportRunner::importPage() 创建草稿后调用publishDraft提交markdown与html引用还原时 ZipImportReferences::replaceReferences() 也按$exportPage-markdown ? markdown : html决定内容类型。Imageid- Number可选导出系统中页面的原始 IDname- String必填图片名称file- String reference必填图片文件引用type- String必填必须为gallery图库或drawiodraw.io 图。文件必须是 BookStack 接受的图片类型png、jpg、gif、webp。drawio类型的图片预期是内嵌了 draw.io 绘图数据的 png 文件。源码中 ZipExportReferences::handleModelReference() 只对gallery与drawio两种类型的图片生成引用标记与文档约束一致。Attachmentid- Number可选导出系统中附件的原始 IDname- String必填附件名称link- String半可选附件的 URLfile- String reference半可选附件文件引用。link与file必须至少存在一个其存在与否决定附件类型外链附件或文件附件。导入侧 ZipImportRunner::importAttachment() 正是按此分支处理有file时以文件上传方式保存否则以saveNewFromLink保存外链。Tagname- String必填标签名称value- String可选标签值可为空。导入流程与校验从 ZIP 到 BookStack 实体一个完整导入的执行链路见 ZipImportRunner::run()包含以下步骤读取并重新校验以只读方式打开 ZIPZipArchive::RDONLY由 ZipExportValidator 校验data.json结构、字段类型、文件引用存在性、id 唯一性等校验失败抛出ZipImportException并返回聚合的错误信息识别导出模型通过decodeDataToExportModel判断是书籍、章节还是页面校验父级类型书籍导入不允许设置父级章节导入必须有父书籍页面导入必须有父书籍或父章节权限预检ensurePermissionsPermitImport按导入内容逐类检查权限——书籍需要book-create-all章节需要chapter-create(-all)页面需要page-create/page-create-all/page-create-own图片需要image-create-all附件需要attachment-create-all任何一项不满足都会在真正落库前中止见 ZipImportRunner.php逐级导入书籍→章节→页面页面导入时先处理附件与图片再发布草稿替换引用全部实体创建完成后ZipImportReferences::replaceReferences()统一把[[bsexport:...]]标记改写为当前实例可用的真实链接清理关闭 ZIP 读取器并清理全部临时文件。其中图片与附件文件会先被解压为临时文件再以UploadedFile形式交给ImageService/AttachmentService落库fileWithinSizeLimit会在每个文件上复核app.upload_limit大小限制超限即报错见 ZipImportRunner.php。从调用入口看导出与导入分别通过 Web 与 API 两种途径暴露导出BookExportController::zip、ChapterExportController::zip及对应的*ExportApiController::exportZip调用ZipExportBuilder生成以slug.zip命名的下载文件见 BookExportController.php导入ImportController与ImportApiController负责上传、校验ZipValidationException、查询详情、执行导入ZipImportException与删除待导入 ZIP见 ImportApiController.php。结语面向开发者的格式要点速查最后把本格式对开发者最有用的要点浓缩如下容器ZIP 内固定包含data.json与files/目录无其他强制性结构判别类型顶层book/chapter/page三者取其一未来可能扩展务必按能力检查而非假设文件引用JSON 中值为文件名的属性均指向files/下条目文件名由导出方随机生成内容引用[[bsexport:image|attachment|page|chapter|book:id]]用于 HTML/Markdown 内的跨对象引用id 为导出系统原始 id导入后会替换为实例内真实链接稳定性新增属性不视为破坏性变更消费方应基于属性名解析而非位置解析安全导出的 HTML/Markdown 不可视为安全内容消费方需自行做净化处理并参考 BookStack 的 CSP 等机制非备份本格式不含用户、权限、设置等数据不能用于实例恢复。无论是为其他平台编写 BookStack 内容导入器、构建跨实例内容迁移工具还是实现第三方阅读器本文所述的格式规范与源码实现都能为你提供完整、可验证的参考依据。深入阅读仓库中的 dev/docs/portable-zip-file-format.md 及 app/Exports/ZipExports/ 源码可进一步查看每条规则的实际落地实现。赞分享后端知识库知识管理文档【免费下载链接】BookStackNOW MANAGED ON CODEBERG项目地址https://gitcode.com/gh_mirrors/bo/BookStack点击查看免费下载相关推荐Thorium Portable 便携版打包全解从 .deb 与 mini installer 生成 Linux/Windows zip 便携包的完整流程Thorium Portable 便携版打包全解从 .deb 与 mini installer 生成 Linux/Windows zip 便携包的完整流程 本桌面应用跨平台3分钟快速上手DouK-Downloader抖音TikTok视频下载终极指南3分钟快速上手DouK Downloader抖音TikTok视频下载终极指南 你是否经常在抖音或TikTok上看到精彩的短视频想要保存下来却找不到简单的方法网页爬虫.NET runtime 便携式 PDB 元数据格式全解Portable PDB v1.0 规范深度剖析.NET runtime 便携式 PDB 元数据格式全解Portable PDB v1.0 规范深度剖析 Portable PDBPortable Prog语言运行时标准库JIT编译编译器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考