市场集成
市场让您将外部服务连接到 Archyl，并将其数据作为实时组件显示在架构仪表盘上。监控部署、跟踪代码质量、观察指标和审查安全告警——所有这些都直接在您的 C4 模型旁边。
概述
市场集成分三层工作：
- 产品 — 可供集成的外部服务（Datadog、GitHub、SonarQube 等）
- 连接 — 用于通过产品 API 进行身份认证的组织级凭据
- 组件 — 放置在项目仪表盘上显示来自连接的实时数据的可视卡片
一个连接可以为不同项目的多个组件提供数据。组件每 30 秒自动刷新。
支持的产品
Datadog
监控基础设施和应用健康状况。
| 组件 | 类型 | 描述 |
|---|---|---|
| 监控状态 | 状态 | 按标签过滤的 Datadog 监控健康状态 |
| 指标查询 | 计数器 | Datadog 指标查询的当前值 |
| 活跃告警 | 列表 | 当前触发的监控列表 |
| 嵌入仪表盘 | 嵌入 | 嵌入的 Datadog 仪表盘或笔记本 |
GitHub
跟踪仓库、工作流和安全发现。
| 组件 | 类型 | 描述 |
|---|---|---|
| 工作流状态 | 状态 | 最新 CI 工作流运行状态 |
| 开放 Pull Request | 列表 | 带状态标签的活跃 PR |
| 仓库统计 | 计数器 | 星标、分支、问题或 PR 数量 |
| Dependabot 告警 | 列表 | 开放的依赖漏洞告警 |
| Dependabot 状态 | 状态 | 总体 Dependabot 告警严重程度 |
| 密钥扫描告警 | 列表 | 仓库中检测到的密钥 |
| 代码扫描告警 | 列表 | CodeQL 或第三方代码扫描发现 |
| 代码扫描状态 | 状态 | 总体代码扫描健康状况 |
GitLab
监控流水线、合并请求和安全扫描器。
| 组件 | 类型 | 描述 |
|---|---|---|
| 流水线状态 | 状态 | 最新流水线运行状态 |
| 开放合并请求 | 列表 | 带状态的活跃 MR |
| 项目统计 | 计数器 | 星标、分支、问题或 MR 数量 |
| 漏洞告警 | 列表 | 依赖扫描发现 |
| 漏洞状态 | 状态 | 总体漏洞严重程度 |
| SAST 告警 | 列表 | 静态分析发现 |
| 密钥检测告警 | 列表 | 检测到的密钥 |
| DAST 告警 | 列表 | 动态分析发现 |
Prometheus
查询指标和监控目标。
| 组件 | 类型 | 描述 |
|---|---|---|
| 即时查询 | 计数器 | PromQL 查询的当前值 |
| 范围查询 | 图表 | 可配置范围内的时间序列折线图 |
| 目标可用状态 | 状态 | 按作业名称的抓取目标健康状况 |
SonarQube
跟踪代码质量和安全分析。
| 组件 | 类型 | 描述 |
|---|---|---|
| 质量门状态 | 状态 | 项目质量门的通过/失败状态 |
| 项目度量 | 计数器 | 覆盖率、缺陷、漏洞、代码异味、技术债务等 |
| 问题 | 列表 | 按严重程度的缺陷、漏洞和代码异味 |
| 安全热点 | 列表 | 需要安全审查的代码位置 |
| 安全评级 | 状态 | 项目的总体安全评级 |
ArgoCD
监控 Kubernetes 应用部署。
| 组件 | 类型 | 描述 |
|---|---|---|
| 应用状态 | 状态 | 单个应用的健康和同步状态 |
| 应用列表 | 列表 | 所有应用及其健康和同步指标 |
| 应用资源 | 列表 | 特定应用的 Kubernetes 资源 |
| 应用计数 | 计数器 | 应用总数，支持可选过滤 |
PagerDuty
监控事件、值班计划和服务健康状况。
| 组件 | 类型 | 描述 |
|---|---|---|
| 事件状态 | 状态 | 触发和确认事件的概览 |
| 活跃事件 | 列表 | 当前活跃事件及其紧急程度和服务 |
| 当前值班 | 列表 | 当前值班的团队成员 |
| 服务状态 | 状态 | PagerDuty 服务的健康概览 |
| 事件计数 | 计数器 | 开放事件总数 |
设置连接
连接在组织级别管理。只有组织管理员可以创建或修改连接。
1. 导航到市场
前往 组织设置 并选择 市场 选项卡。所有可用产品按类别列出。
2. 添加连接
- 找到要连接的产品
- 点击 连接
- 输入连接名称（如"生产环境 Datadog"或"GitHub - 后端仓库"）
- 填写所需凭据
每个产品需要不同的配置字段：
| 产品 | 必填字段 |
|---|---|
| Datadog | API 密钥、应用密钥、站点 URL |
| GitHub | 个人访问令牌 |
| GitLab | 个人访问令牌、GitLab URL |
| Prometheus | 服务器 URL |
| SonarQube | 令牌、服务器 URL |
| ArgoCD | 令牌、服务器 URL |
| PagerDuty | API 密钥 |
3. 测试连接
保存前点击 测试连接。Archyl 将验证凭据并显示成功或错误消息。如果测试失败，请检查：
- API 密钥或令牌是否具有所需权限
- 服务器 URL 是否可从互联网访问
- 凭据是否已过期
4. 保存
测试通过后，点击 保存。连接现在可在组织中的所有项目中使用。
管理连接
- 编辑：更新现有连接的名称或凭据
- 删除：移除连接。使用它的组件将停止工作并显示错误状态
- 状态指示器：绿色（活跃）、红色（错误）、灰色（已断开）
您可以为同一产品创建多个连接——例如，为预发布和生产 Datadog 账户创建不同的连接。
添加组件
组件在项目仪表盘上显示来自连接的实时数据。
1. 打开集成选项卡
在您的项目中，导航到 集成 视图。点击 自定义 进入编辑模式。
2. 添加组件
- 点击 添加组件 按钮
- 步骤 1 — 选择连接：选择要使用的连接。连接按产品分组。
- 步骤 2 — 选择组件类型：选择组件类型（状态、计数器、列表、图表或嵌入）。可用类型取决于产品。
- 步骤 3 — 配置：设置组件标题和产品特定选项
3. 配置组件选项
每种组件类型都有特定的配置字段：
GitHub 组件需要：
- Owner：GitHub 组织或用户名
- Repository：仓库名称
- Severity（安全组件）：按告警严重程度过滤
Datadog 组件需要：
- Monitor Tags（监控/告警）：逗号分隔的标签过滤
- Query（指标）：Datadog 指标查询字符串
- Timeframe（指标）：1h、4h、1d 或 1w
- Embed URL（仪表盘）：共享仪表盘 URL
Prometheus 组件需要：
- Query：PromQL 表达式
- Timeframe（图表）：15m、1h、4h、1d 或 1w
- Y-axis Label 和 Unit（图表）：可选显示格式
- Job Filter（目标状态）：抓取作业名称
SonarQube 组件需要：
- Project Key：SonarQube 项目标识符
- Metric（度量）：coverage、bugs、vulnerabilities、code_smells 等
- Severity 和 Issue Type（问题）：可选过滤
ArgoCD 组件需要：
- Application Name（状态/资源）：单个应用名称
- Application Filter（列表/计数）：正则匹配应用名称
- Project（列表）：ArgoCD 项目过滤
- Health Filter（计数）：Healthy、Degraded、Progressing 等
PagerDuty 组件需要：
- Service ID（事件/状态）：可选按 PagerDuty 服务过滤
- Escalation Policy ID（值班）：可选按升级策略过滤
组件类型
计数器
突出显示单个数值。用于 CPU 使用率、请求计数、覆盖率百分比或星标数量等指标。
- 带可选单位的大号格式化数字
- 值下方的可选标签
- 根据组件尺寸自适应文本大小
状态
带颜色编码的健康指示器。用于 CI 状态、质量门、监控健康或部署同步状态。
- 颜色编码标签：绿色（正常）、琥珀色（警告）、红色（严重）
- 可选分类计数（正常、警告、告警）
- 可用时的上下文消息
列表
可滚动的项目列表。用于 Pull Request、告警、问题或应用清单。
- 每个项目显示标题、可选副标题和状态标签
- 可点击项目链接到外部服务
- 颜色编码状态标签（成功、警告、错误、严重、待处理）
图表
渲染时间序列折线图。用于 Prometheus 范围查询或任何随时间变化的指标。
- 多系列支持，带彩色线条
- 自适应时间轴格式
- 悬停工具提示显示格式化值
- 可选 Y 轴标签和单位
嵌入
在 iframe 中显示外部页面。用于 Datadog 仪表盘、Grafana 面板或任何可嵌入的 URL。
- 完整 iframe 渲染
- 沙箱化以确保安全
- 响应组件大小
组织组件
分区
组件按命名分区组织。默认分区为 通用。
- 创建分区：在编辑模式下，使用分区输入框添加新分区
- 重命名：点击分区标题上的铅笔图标
- 删除：点击垃圾桶图标。已删除分区中的组件移至通用
- 折叠/展开：点击箭头切换分区可见性
重新排序
在编辑模式下：
- 拖动组件 在分区内重新定位或移动到不同分区
- 拖动分区标题 重新排序整个分区
- 调整组件大小 从右下角手柄
组件位置和分区分配自动保存。
组件网格
网格使用 12 列布局。组件可以从 1 列宽调整到完整的 12 列，从 3 行高调整到任意高度。网格垂直压缩——组件向上堆叠以填充间隙。
作用域
组件可以在三个级别设定作用域：
| 作用域 | 可见性 | 使用场景 |
|---|---|---|
| 组织 | 所有项目可见 | 公司级仪表盘 |
| 项目 | 仅特定项目可见 | 项目特定指标 |
| 元素 | 附加到 C4 元素 | 按服务监控 |
组织级组件从顶级集成页面配置。项目和元素级组件在项目的集成选项卡中配置。
故障排除
组件显示"凭据无效"
连接凭据已过期或被撤销。前往 组织设置 > 市场，找到连接并更新凭据。点击 测试连接 验证。
组件显示"无法加载数据"
外部服务可能不可达或查询可能无效。检查：
- 服务是否可用和可访问
- 查询或过滤配置是否正确
- 连接的 API 密钥是否有权限访问请求的资源
添加组件时没有可用连接
连接在组织级别创建。如果您不是管理员，请让组织管理员在 组织设置 > 市场 中设置连接。
最佳实践
清晰命名连接
使用描述性名称，表明环境和用途：
- "Datadog — 生产环境"
- "GitHub — 后端团队"
- "SonarQube — 主项目"
使用分区组织
将相关组件分组到分区中：
- "监控" 用于 Datadog 和 Prometheus 组件
- "安全" 用于 SonarQube 和 GitHub 安全扫描组件
- "CI/CD" 用于工作流状态和部署组件
- "事件响应" 用于 PagerDuty 事件和值班组件
从状态组件开始
状态组件为您提供快速的健康概览。在确定关键指标后，再添加计数器和列表组件以获取更多详情。
使用元素级组件
将组件直接附加到 C4 元素，使架构图显示实时运营上下文。例如，将 GitHub 工作流状态组件附加到代表 API 服务的容器。