ZStack文档DevOps平台建设实践

(一) 前言

对于软件产品而言,文档是不可或缺的一环。文档能帮助用户快速了解并使用软件,包括不限于特性概览、用户手册、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

  1. 内容重用

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

  • DITAMAP重用:将一个DITAMAP A嵌套到另一个DITAMAP B。这样,DITAMAP B可以重用DITAMAP A的全部内容。

  • TOPIC重用:一个TOPIC可以拖动到多个DITAMAP中。这样,多本文档可以重用相同的章节内容。

  • LABEL:一个LABLE可以引用到多个TOPIC中。这样,多个章节可以重用相同的句子、表格或图片。

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

图3. TOPIC重用

  1. 过滤与定制*

在文档发布阶段,配置文件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奠定了又一个坚实基础。

(四) Z S tack文档D evO ps平台整体设计思路

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

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

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

图6. 整体设计框架

  1. 安全机制
  • 内外网反向代理

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

  1. A PI 层
  • Flask代理服务器

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

  • 可视化编译管理界面

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

  1. 基础设施层
  • DevOps集群

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

  • Jenkins K8s集群

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

  • 数据库

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

  1. 任务执行层
  • 请求参数处理

* 请求参数标准化

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

  • 工作区分配

* 文档代码隔离

通过工作区(Workspace),管控代码分支,同时实现代码隔离。

  • 文档参数处理

* DITA参数修改

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

  • 文档构建

* 日志整理及输出

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

* 文档交付件构建

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

(五) Z S tack文档D evO ps平台实际建设难题与攻克

  1. 批量构建的配置冲突

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

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

  1. 配置文件的动态维护

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

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

  1. 文档构建的日志分析

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

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

(六) Z S tack文档D evO ps平台价值
  1. 统一管理、直观便捷

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

图7. 集中管理文档映射

图8. 集中管理编译任务

图9. 可视化日志

  1. 性能强劲、提效显著

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

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

(七) 结束语

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

相关推荐
考虑考虑33 分钟前
zookeeper认证
后端·zookeeper
掘金者阿豪1 小时前
数据库选型到底应该看什么?从业务需求到技术架构的实践分析
前端·后端
苍何2 小时前
豆包终于想通了...
后端
AAA修煤气灶刘哥2 小时前
Agent 都能干活了,软件还需要那么多按钮吗?
人工智能·后端·架构
未秃头的程序猿2 小时前
给新模块加了个 @MapperScan,启动崩了,最后发现跟 MapperScan 没关系
java·后端·mybatis
苍何2 小时前
不用 Opus5.5 ,即梦也能出爆款 vibe 视频了
后端
SimonKing2 小时前
WorkBuddy又推出新的限免模型(Hy4 flash)了,羊毛可以薅起来了
java·后端·程序员
Rain的Java大神之路2 小时前
别再死背"三级缓存"了!拿 Spring 7.0.8 源码,把 IoC、AOP、事务、循环依赖四大深水区一次蹚平
java·后端·面试
wno7042 小时前
springboot整合FastDFS
java·spring boot·后端
程序猿DD9 小时前
OctaFuse 2.20.0:MCP 用业务账号直接登录授权,请求日志合并工具调用
后端