3 篇博文 含有标签「backend-dev」

我第一次出差给用户交付 HAMi 企业版，Helm 安装到一半就撞上了五六个漏打包的镜像，只能 Ctrl+C 停下来排障。

这在普通环境里也许只是补一次下载，在有些传统 HPC 或 IDC 环境里却完全不是一回事：文件要先刻录到光盘，经过可信设备，再从内网传到集群主节点。偏偏那天 MacBook Pro 还认不出 USB 光驱，一下午就这么没了。

当时我们交付的是一份 10 GB 左右的压缩包和一本安装手册。后来我才意识到：我交付的不是代码，也不是 Helm Chart，而是一整套要在没有公网的集群里跑起来、升级和排障的环境。

那也是我第一次负责 air-gap 环境交付。这篇文章最初写于 Zarf v0.76.0。2026 年 8 月，项目升级到了 v0.82.0，旧文里一些绝对判断也被实践推翻了。这一版保留当时的事故和选择过程，再补上后来踩到的 values、CRD、镜像架构和制品校验问题。

2026 年的今天：hermes agent、OpenClaw、各种各样的 CLI、skills、MCP，你方唱罢我登场。潮起潮落，最后剩下些什么？服务端的 API 一定仍然是企业内最重要的“资产”。

在此背景下，我们该如何产出 API 文档？特别地限定一下讨论范围，我们如何在 企业内部 产出 API 文档供其他 技术人员 使用？

本文所说的“文档”不限于形式，Markdown、YAML、JSON，人和 agent 有一方能读就行。 后文的重点将会是 O pen A PI S pecification YAML/JSON 文档（legacy named as Swagger specification）。

抛出这个问题之后，可能会有以下质疑：

• “AI Native” 时代了，还有这种需求吗？
• 这难道不是很成熟的技术吗？
• 人工编写文档怎么了？

接 上文，我想开发一个 CLI 工具，一行命令生成 Gin 等 HTTP/gRPC 框架的 API 文档。