技术文档架构

Basic(开箱即用)

部署 Backstage 时(默认情况下启用 TechDocs)，您将获得基本的开箱即用体验。

注意：请参阅以下我们推荐的部署架构，该架构兼顾了 > 稳定性、可扩展性和速度。 还请参阅 > 如何迁移指南。

在 Backstage 中打开 TechDocs 网站时，"...技术文档阅读器请求techdocs-backend插件的实体 ID 和您正在查看的当前页面的路径。 作为回应，它会接收静态文件(HTML、CSS、JSON 等)，以便在 TechDocs/Backstage 中的页面上渲染。

静态文件包括由 MkDocs 生成的 HTML、CSS 和图片。 出于安全考虑，我们在将它们添加到 Backstage 之前删除了所有 JavaScript。 此外，还有一个额外的techdocs_metadata.json文件，以便 TechDocs 渲染网站。技术文档-客户端或技术文档容器为预期输出生成文档。

然后，TechDocs 阅读器会应用一个 "变形器 "列表(请参见概念) 可修改生成的静态 HTML 文件，以满足多种使用要求，例如删除某些标题、过滤掉某些 HTML 标记等。

目前，我们使用 Backstage 服务器(或 techdocs-backend)的本地文件系统来存储生成的文件。 不过，理想的做法是使用外部存储系统(如 AWS S3、GCS 或 Azure Blob Storage)。 在以下内容中阅读更多内容使用云存储.

建议部署

我们建议在生产环境中这样部署 TechDocs。

推荐部署方法的关键区别在于文档的构建位置。

我们假设每个实体都保存在某个版本库中(GitHub、GitLab 等)。 我们建议使用 CI/CD 管道生成的静态文件将被用于存储在云存储中您所选择的解决方案。

与基本设置中的方法类似，TechDocs 阅读器请求techdocs-backend文档网站的插件。techdocs-backend然后请求您配置的存储解决方案以获取必要的文件，并将其返回给 TechDocs 阅读器。

根据您选择的云存储提供商及其与后端服务器的实际距离，使用这种部署方法加载 TechDocs 网站时可能会出现较高的延迟。 如果遇到这种情况，您可以选择配置techdocs-backend在缓存存储中缓存响应由 Backstage 提供支持.

安全考虑

我们最大的安全顾虑是管理对云存储中文档的访问。 我们还希望为所有不同类型的存储(GCS、AWS、自定义 SFTP 服务器等)提供唯一的安全解决方案。techdocs-backend来获取文件是一个很好的方法。

这样，当访问控制管理 Backstage 准备就绪时，我们也可以使用它。在此跟踪进度。

理论上，您可以直接启用 TechDocs 阅读器从存储中读取文档，但您必须考虑如何在不公开文档的情况下做到这一点，以及如何管理用户组的访问权限。

用于云存储访问令牌、techdocs-backend但在您的 CI/CD 系统中，需要一个具有 "写 "权限的令牌才能发布生成的文档站点文件。

FAQs

**问：为什么要分别采用 "基本 "和 "建议 "部署方法？

答：基本设置或开箱即用设置是指创建新应用程序或进行以下操作时获得的设置git clone我们希望第一次体验能够就这样神奇地工作但是，如果您决定将 TechDocs 部署到生产环境中使用，基本设置是可行的，但随着文档站点数量和规模的增加，会出现一些问题。 因此，您需要确保部署尽可能稳定。 因此，我们推荐一种方法。 TechDocs 还可以有更多的部署方法，我们欢迎社区提出这种 "另类 "想法。

**问：为什么不推荐使用 techdocs 后端本地文件系统来提供静态文件？

答：这会增加扩展Backstage实例的难度。 想想我们有分布式Backstage部署(例如Backstage应用程序的多个 Kubernetes pod)的情况。 为 TechDocs 使用一个单独/集中的文件存储系统是必要的，这样可以确保在服务器/pods 重新启动时站点是持久的，并避免每个实例重复创建站点。 通过使用外部存储，我们可以更轻松地执行一些操作，例如删除文档站点或擦除其内容。

**问：为什么不即时生成文档，即当用户访问页面时，实时生成文档？

答：即时从 Markdown 生成内容并不是最佳选择。 存储解决方案可作为生成的静态内容的缓存。 TechDocs 目前也是基于 MkDocs 构建的，它不允许我们按页面生成文档，因此我们必须在每次请求时为一个实体构建所有文档。

**问：没有技术文档后端插件，能否使用技术文档插件？

A:techdocs和techdocs-backend插件设计为一起使用，就像任何其他 Backstage 插件一样，有一个前端和它的后端(目录、脚手架等)。 如果你将 Backstage 实例设置为在服务器上生成文档、techdocs-backend将负责管理整个构建过程，确保其可扩展性。 它负责与云存储提供商进行安全通信，以获取静态生成的网站并发布更新。 还有其他计划中的功能，如用户身份验证层，以确定他们是否有权限查看特定的文档网站。 如果没有一个紧密集成的后端，要开发一些功能是非常困难的。 因此，支持techdocs不带techdocs-backend开发有限且具有挑战性。