你的架构图表展示了存在的事物。现在它们还能展示已发布的内容。Archyl 全新的发布管理功能让你可以跨系统和环境追踪部署，支持从 GitHub Actions、Webhooks 和 REST API 接入数据。

发布管理：追踪架构中的每一次部署

两个月前，我参加了一次事后复盘，其中的核心问题看似简单："当前生产环境中运行的支付服务是什么版本？"

四个人给出了三个不同的答案。一个人查看了 GitHub Releases 页面。另一个人打开了 ArgoCD。第三个人翻看了 Slack 部署频道。第四个——实际执行部署的人——正在休假。

这不是一家初创公司。这是一个拥有成熟 CI/CD 流水线、良好标签实践和在 Archyl 中维护完善的架构图表的团队。图表准确告诉你存在哪些系统、它们如何连接、使用什么协议。只是无法告诉你任何东西实际上在运行什么版本。在任何地方。

这个差距困扰了我很久。架构文档告诉你系统的结构。部署历史告诉你系统的状态。这两件事应该放在一起。今天，它们做到了。

与架构关联的发布

Archyl 的发布管理将部署作为你架构工作区中的一等对象来追踪。一个发布拥有版本号、状态、环境、变更日志，以及——关键的——与其所属 C4 元素的关联。

最后这一点是使其区别于 CI/CD 仪表板的地方。GitHub Actions 运行告诉你 v2.4.0 已经部署了。但在架构的上下文中，部署到了哪里？哪个系统？哪个容器？Archyl 的发布通过将部署事件直接连接到 C4 图表上的系统和容器来回答这个问题。

当你打开一个系统的详情面板时，你会看到它最近的发布和关系、ADR 以及 API 合约并列显示。架构图表成为一张活的地图——不仅展示存在什么，还展示什么时候发布了什么。

三种接入方式

我们不希望发布追踪意味着更多的手动工作。如果你已经通过流水线部署，发布应该自动流入 Archyl。

GitHub Actions —— 我们发布了一个官方 GitHub Action，你可以将其添加到部署工作流中。最简配置只需在 YAML 中写两行。该 Action 在每次成功部署时向 Archyl 发送版本号、提交 SHA、环境和变更日志。它还支持自定义字段——链接到特定系统或容器、设置状态、包含作者信息。

- uses: archyl/release-action@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    version: ${{ github.ref_name }}

就这样。每个打标签的发布现在都会出现在你的架构工作区中。

Webhooks —— 在项目设置中配置一个 webhook 端点，然后将 GitHub 或 GitLab 的发布 webhook 指向它。当新发布发布或标签被推送时，Archyl 接收事件并自动创建发布条目。你可以设置标签模式（例如 v*）来过滤哪些标签创建发布，并指定默认环境，让 webhook 创建的发布进入正确的位置。

REST API —— 对于使用 Jenkins、CircleCI、Bitbucket Pipelines 或任何其他 CI/CD 工具的团队，接入端点接受简单的 JSON 请求。使用 API 密钥认证，发送版本号和元数据，发布就会出现在 Archyl 中。这是通用的方案——如果你的工具能发送 HTTP 请求，它就能报告发布。

所有三种方式都在项目设置的"Releases"选项卡下配置，提供可复制的代码片段和自动填充的 API 密钥。

环境

并非所有部署都是一样的。推送到预发布环境是常规操作。推送到生产环境是一件大事。发布管理分别追踪这两者。

环境由用户定义并带有颜色标记。创建"Development"、"Staging"、"Production"——或你的团队使用的任何名称。每个发布都标记了目标环境，你可以过滤时间线只查看生产部署，或只查看当前预发布环境中的内容。

环境模型是灵活的。运行单个服务的团队可能只有两个环境。管理四十个微服务的平台团队可能有五个。你定义对项目有意义的环境，发布会相应地自我组织。

时间线

发布时间线是主要视图。发布按月分组，以逆时间顺序显示，带有版本徽章、环境标签和状态指示器。它一目了然地回答了"最近发生了什么？"

每个发布条目显示：

版本 —— 语义化版本标签或标识符（例如 v2.4.0、3.12.0-rc.2）
状态 —— 已部署、进行中、已计划、失败或已回滚
环境 —— 带颜色的徽章（生产、预发布等）
关联元素 —— 该发布所属的系统或容器
来源 —— 发布来自哪里（GitHub Action、webhook、API、手动）
变更日志 —— 更改了什么、谁是作者、签署信息

点击任何发布可打开其详情面板，包含完整的变更日志、日期（创建、发布、更新）、受影响的 C4 元素，以及返回源的链接（提交、GitHub Release 页面等）。

部署矩阵

对于管理多个服务跨多个环境的团队，我们构建了第二个视图：部署矩阵。

这是一个网格，其中行是你的系统和容器，列是你的环境，每个单元格显示部署到该组合的最新发布。一眼就能看到账户 API 在生产环境是 v3.1.0，但在预发布环境是 v3.2.0-beta。或者通知服务已经三周没有部署到生产环境了。

矩阵使环境漂移可见。当预发布和生产版本出现分歧时，你会立即发现。当一个服务落后而其他服务前进时，差距显而易见。

状态生命周期

发布并不总是干净利落的。部署会失败。发布会回滚。我们追踪完整的生命周期：

已计划 —— 发布存在但尚未部署。用于追踪即将到来的版本。
进行中 —— 部署正在进行。在部署步骤中由 CI/CD 集成自动设置。
已部署 —— 发布在目标环境中上线。正常路径。
失败 —— 部署未成功。发布条目保留作为尝试记录。
已回滚 —— 发布已部署但随后被回退。这保留了历史——你可以看到 v2.3.1 被回滚了，何时回滚的，以及原因。

使用 CI/CD 集成时，状态转换是自动的；通过 UI 创建发布时，则需要手动操作。

链接到架构元素

每个发布都可以链接到一个系统、一个容器，或两者都有。这就是赋予发布架构上下文的关键。

在项目设置中，你配置默认的链接目标——发布应附加到的系统和可选的容器。GitHub Actions、webhooks 和 REST API 的代码片段会自动更新以包含正确的元素 ID。

在图表上，关联的元素在详情面板中显示其发布历史。右键点击一个容器，你不仅能看到它的关系和合约，还能看到它的部署时间线。这就是架构文档与运营现实交汇的地方。

为什么这很重要

架构图表一直是时间点的快照。它们展示系统是什么——方框、箭头、协议。但它们不展示系统在做什么。那个服务是最新版本吗？上次部署是什么时候？有人回滚了上周二的发布吗？

这些问题在每次架构评审、每次事件响应、每次入职对话中都会出现。直到现在，答案总是"查看 CI/CD 工具"或"问负责该服务的团队"。

发布管理将部署历史放到了它应该在的地方：架构本身上。当有人问"支付网关运行的是什么版本？"时，答案就在图表上——不在另一个工具里，不在另一个标签页里，不在某人的脑子里。

这与 API 合约和 ADR 背后的理念相同：架构文档应该回答每天出现的真实问题，而不仅仅是抽象地描述结构。

开始使用

导航到项目的设置并打开 Releases 选项卡。选择你的集成方式——GitHub Action、webhooks 或 REST API——并按照设置指南操作。创建环境，链接目标系统或容器，然后发布你的第一个版本。

从那时起，每次部署都会自动流入你的架构工作区。你的 C4 图表不再是静态的蓝图，而是实际运行状况的活记录。

你的架构不仅仅是结构。现在你的工具也反映了这一点。

想了解更多关于将架构连接到现实？看看 API 合约如何将规范链接到图表，或架构变更请求如何将 Pull Request 工作流引入你的 C4 模型。

发布管理：追踪架构中的每一次部署 - Archyl Blog