当前位置：首页 > news >正文

ZStack文档DevOps平台建设实践

news 来源：原创 2025/8/19 2:04:31

（一）前言

对于软件产品而言，文档是不可或缺的一环。文档能帮助用户快速了解并使用软件，包括不限于特性概览、用户手册、API手册、安装部署以及场景实践教程等。由于软件与文档紧密耦合，面对业务的瞬息万变以及软件的飞速迭代，如何敏捷高效开发文档，是摆在每个软件公司面前必须攻克的难题。

本文从ZStack文档实践出发，围绕结构化文档开发、结合实际业务的文档版本管理策略、文档DevOps平台设计思路、实际建设难题与攻克等要点，向大家全面深入介绍ZStack文档DevOps平台建设的成功实践。

（二）结构化文档开发是前提

在软件开发领域，“Docs as Code”的文档开发理念已深入人心。该理念的核心思想是将文档作为代码的一种形式，将其纳入到软件开发生命周期中。传统的非结构化写作缺乏模块化和标准化机制，很难满足“Docs as Code”高效编写发布文档的要求。在此背景下，结构化写作应运而生，成为解决以上问题的有效方案。

结构化写作十分重视信息架构设计。DITA作为结构化写作的国际标准之一，已在业内广泛使用。DITA（Darwin Information Typing Architecture）最初由IBM公司开发，并在2005年被开放标准组织OASIS收录为开放标准。作为基于XML的体系结构，DITA通过内容与形式分离、内容重用、过滤与定制等机制，充分实现文档开发的灵活性和标准性。

图1. DITA的特点

1.内容与形式分离

DITA按模块组织文本内容，支持DITAMAP、TOPIC、LABEL等不同层级的模块化。

DITAMAP：DITAMAP是一本文档的框架，定义文档中包含哪些TOPIC以及TOPIC的组织形式。
TOPIC：TOPIC是一个完整的主题或章节。DITA提供了适用于不同场景的多种TOPIC类型，例如：Concept、Task、Troubleshooting、Reference，并通过DTD规定这些TOPIC的基本架构（即规定TOPIC必须或只能包含哪些LABEL），从而保证同类型主题/章节的规范性和风格一致性。
LABEL：LABEL是TOPIC中的标记对，通常是组成一个TOPIC的各种元素，包括段落、句子、短语、表格、列表、图片等。

在文档开发阶段，开发者按照规范，逐级组织DITAMAP和TOPIC架构，并在LABEL层级进行内容编写。这样，既保证了开发者始终在框架规范内进行创作，也使得最终输出的文档层次分明。

图2. TOPIC DTD

2.内容重用

DITA支持以模块为单位进行不同粒度的内容重用。DITAMAP、TOPIC、LABEL均适用重用机制。

DITAMAP重用：将一个DITAMAP A嵌套到另一个DITAMAP B。这样，DITAMAP B可以重用DITAMAP A的全部内容。
TOPIC重用：一个TOPIC可以拖动到多个DITAMAP中。这样，多本文档可以重用相同的章节内容。
LABEL：一个LABLE可以引用到多个TOPIC中。这样，多个章节可以重用相同的句子、表格或图片。

在文档迭代过程中，重用机制既减少了重复劳动也保证了文档内容一致性。一旦重用来源被修改，所有引用均会被更新。在ZStack技术文档中，产品名称、产品版本、术语等均以重用的形式出现在各个文档、各个章节。一旦发生变动，这些被广泛使用的内容可“牵一发而动全身”。

图3. TOPIC重用

3.过滤与定制

在文档发布阶段，配置文件DITAVAL和DITA-OT决定了输出文档的内容和样式。通过调整DITAVAL和DITA-OT，基于同一本DITAMAP可以发布不同内容、不同格式、不同风格的文档，面对多样化的业务需求和发布渠道可实现灵活定制。

DITAVAL：DITAVAL用于对文档内容进行条件过滤。开发者可以在DITAVAL中定义某个标签在输出文档中被剔除/包含，并给需要过滤的TOPIC、LABEL标记对应的标签。在文档输出过程中，DITAVAL自动识别标签，使对应的内容最终被呈现/隐藏，实现不同业务场景下的文档内容定制。
DITA-OT：DITA-OT用于定义文档发布样式，包括文档格式、封面、字体、字号、颜色、页眉、页脚等。灵活配置DITA-OT，可使文档输出为多种格式（PDF、HTML等）以配合不同的发布渠道，或改变文档样式风格，实现多样化定制需求。

ZStack基于DITA构建了庞大的结构化文档库，总文字规模超过千万级。由于高度模块化和标准化，为实现文档DevOps奠定了坚实基础。

图4. 结构化文档库

（三）结合实际业务的文档版本管理策略

ZStack文档库采用GIT仓库托管，通过GIT机制实现文档版本控制。

在软件开发领域，GIT是一种被广泛使用的分布式版本控制系统。开发者在本地完成工作，通过Commit、Push操作提交至远端，并通过Pull操作获取远端更新。GIT提供强大的分支管理功能，开发者可依据业务需要，灵活创建独立分支，每个分支专注于特定任务，互不冲突。必要时，可通过分支合并实现内容汇总。

以ZStack Cloud技术文档开发为例，在新版本开发之初，开发者基于稳定的主分支（Master Branch）开出多个特性分支（Feature Branch），并在特性分支进行独立开发，各特性分支稳定后全部并入主分支。期间，可按需开出Bugfix分支修复问题，还可灵活响应定制项目插队，随时开出定制分支（Customized Branch）进行定制开发。最终，基于主分支评估开出合适的发布分支（Release Branch），用于最终发布。

图5. ZStack Cloud文档分支管理

由上可见，ZStack文档库具备与代码库紧耦合的开发管理能力，同时也为实现文档DevOps奠定了又一个坚实基础。

（四）ZStack文档DevOps平台整体设计思路

由于ZStack文档库已实现结构化和版本控制，因此实现文档CI/CD，建设一体化文档DevOps管理平台顺理成章照进现实。

在软件开发领域，CI/CD是一种通过自动化流程实现代码持续集成、测试和部署的软件开发实践，旨在快速、可靠地交付高质量应用。文档CI/CD则是通过自动化流程对结构化文档库进行批量构建、存储、回传，从而实现文档的快速、可靠、高质量、一体化交付。

ZStack文档DevOps平台基于微服务架构设计，依托ZStack Cloud云平台与Kubernetes（K8s）实现服务的容器化部署与动态编排，并通过微服务间的协同调度，完成从任务发起到构建、存储、回传的全流程自动化闭环。

图6. 整体设计框架

1.安全机制

内外网反向代理

将内网Flask代理服务器端口映射到外部端口上，以供轻流访问。实现网络隔离，确保内部服务仅通过API暴露，外部请求需经反向代理验证。

2.API层

Flask代理服务器

负责初步处理请求、对请求的参数做初步解析、触发CI/CD构建任务、获取构建记录。

可视化编译管理界面

文档发布者可在该界面维护文档映射，按需触发CI/CD构建任务。

3.基础设施层

DevOps集群

内部生产环境管理平台，用于集成CI/CD流水线。

Jenkins K8s集群

负责以任务为单位，执行文档构建。

数据库

保存任务的执行参数，执行记录以及相关Metadata。

4.任务执行层

请求参数处理

请求参数标准化：将轻流传入参数做统一处理和检查，对不合规参数进行修改或过滤，对合规参数做预处理，以供后续操作使用。

工作区分配

文档代码隔离：通过工作区（Workspace），管控代码分支，同时实现代码隔离。

文档参数处理

DITA参数修改：针对不用的文档构建需求，动态修改相关DITAVAL/DITA-OT文件参数。

文档构建

日志整理及输出：根据DITA-OT构建文档时输出的日志，判断构建是否成功。同时结合构建参数和相关DITAVAL/DITA-OT文件，标准化、结构化输出日志。最后对任务的所有日志进行汇总、可视化输出。

文档交付件构建：通过DITA-OT构建文档，将最终交付件输出到MINIO对象存储上。

（五）ZStack文档DevOps平台实际建设难题与攻克

1.批量构建的配置冲突

为确保文档构建效率及规范化，对文档构建申请以任务为单位。一个构建任务支持批量构建多本文档，这也就不可避免会出现多本文档使用同一个DITAVAL/DITA-OT文件，且对文件内参数需求不同。

引入工作区（Workspace）的概念，从文档交付件维度，将不存在配置冲突的文档构建请求放在同一工作区内，同一工作区内使用同一套DITAVAL/DITA-OT文件。在构建文档时，按序构建每一个工作区的文档。

2.配置文件的动态维护

DITAVAL/DITA-OT文件内相关参数由实际业务决定（如产品线名称、文档厂牌等），随着业务变化，参数内容必须是动态变化、易于维护的。平台采用一个独立配置文件集中维护相关参数，这样一来，当业务变化触发参数变化时，能尽可能减少对CI/CD代码的修改。

此外，平台将DITA-OT文件放在一个特殊分支上维护，当构建文档需调用时，只需对工作区内的DITA-OT文件进行替换。同样地，当业务变化触发参数变化时，能尽可能减少对现行分支代码的影响。

3.文档构建的日志分析

一次文档构建任务可能生成大量不同文档，若整体任务失败，或任务中某些文档出现问题，文档工程师面对庞大的文档日志，分析定位问题十分不便。

平台对日志文件进行总结、可视化输出。当文档构建任务完成后，自动将所有日志进行总结，统计所有日志的编译输出，将使用同一套DITAVAL/DITA-OT文件的文档构建进行整合记录，最后输出汇总、可视化的日志报告。

（六）ZStack文档DevOps平台价值

1.统一管理、直观便捷

ZStack文档DevOps平台为文档编译发布提供统一的可视化管理界面，文档发布者可一站式维护文档映射、创建编译任务，跟进编译进程及结果。对于构建失败的任务，可直接查看可视化日志，快速定位问题。

图7. 集中管理文档映射

图8. 集中管理编译任务

图9. 可视化日志

2.性能强劲、提效显著

平台运行在DevOps集群环境上，提供强大的计算支持和灵活的资源调配，大幅缩短文档编译时间，面对大规模批量编译任务，优势尤为明显。以ZStack Cloud全量文档发布为例，相较于本地编译，平台编译耗时缩短50%以上。

此外，针对定制化文档场景，平台直接对接轻流业务接口，业务人员提交定制需求后，系统全程自动完成定制开发、编译和交付，人工仅需关注构建失败的任务，分析失败原因并解决。

(七)结束语

工作流程优化是提升企业效率的重要一环。ZStack文档一直致力于敏捷高效的文档开发管理探索与实践。在科技迅猛发展的今天，如何拥抱新技术，创新构建最适合自身业务的工具链，并策略性运用到工作实践中，提升生产力和效率，是现代企业工作者的重要挑战。我们一起共勉。（联合作者：潘玲、程楚乔、王帧颐）