数据源集成

功能解释

数据源集成用来管理当前租户可用的数据源，决定 Agent 在对话、指标查询、明细查询、数据回写和归因分析时能访问哪些库，以及哪些库允许写入结果表。

当前页面主要管理数据库连接类数据源。系统内置数据源由 Aloudata CAN 提供连接参数，用户在 Agent 页面中只调整本地访问策略；用户自建数据源的新增入口当前未开放，页面以同步和维护系统内置数据源为主。换句话说，这里更像“把可用数据源接进来并管好权限”，而不是从零建库。

使用场景

• 需要把新的业务库、主题库或分析库接进来时。
• 出现查不到数据、指标不对或拆分维度缺失时。
• 指标平台底层库地址、账号或引擎类型在 Aloudata CAN 侧变更后，需要重新同步到 Agent 时。
• 需要限制 Agent 只能读库，或只允许写入指定 Schema 前缀下的表时。

这类配置通常由租户管理员维护，因为它直接影响后续查询、明细访问和写回权限。普通成员如果看不到数据源，通常不是没数据，而是没有对应范围的访问权。

操作入口

进入数据源集成页面后，先看当前租户已经同步了哪些库，再决定是同步系统数据源、测试连接还是编辑访问策略。这个页面最先要确认的，是库本身是否存在以及状态是否正常。

使用步骤

1. 进入页面

进入页面后先看现有数据源卡片和状态，再决定是同步、测试还是编辑。页面上最重要的不是“有没有按钮”，而是“当前租户已经接了哪些库、这些库是否正常”。

2. 同步系统数据源

功能说明：拉取当前租户的系统内置指标平台数据源，并在本页面生成或更新系统内置数据源卡片。同步成功后会提示“系统数据源已同步：{alias}”。

使用限制：

• 仅租户管理员可操作。
• 依赖 Aloudata CAN 配置。若 Aloudata CAN 地址、鉴权或用户权限异常，会提示系统数据源同步失败。
• 该按钮只同步系统内置指标平台数据源，不会创建普通用户自建数据源。
• 该操作可重复执行。已有系统内置数据源时，不会新增重复卡片，而是刷新方言、连接地址、用户名、密码等由 Aloudata CAN 管理的连接参数。

操作后影响：

• 首次同步会新增一个系统内置数据源，通常别名为 __metric_backend__。
• 重复同步会用 Aloudata CAN 最新信息覆盖系统内置数据源的连接参数，并刷新后端连接池缓存。
• 新连接参数会在后续查询、明细访问和数据回写时生效。
• 已在 Agent 页面配置的本地访问策略不会因为同步而全部重置，系统内置数据源仍可在编辑弹窗中维护可读、可写、写入 Schema 前缀和描述。

一般在这些时候需要同步：

• 指标平台侧的连接参数变了
• 新环境刚接入，需要把系统内置数据源拉下来
• 发现当前环境里数据源状态和平台侧不一致

同步成功后，页面会出现或刷新系统内置数据源卡片。卡片右上角“更多操作”可以继续编辑连接信息或测试连接。

功能说明：展开当前数据源的操作菜单。系统内置数据源菜单包含“测试连接”和“编辑”；用户自建数据源还会额外显示“删除”。

• 系统内置数据源不可删除，所以截图中的系统内置卡片不会出现删除入口。
• 菜单里的实际保存、删除、测试动作需要租户管理员权限。

3. 测试连接

功能说明：使用当前保存的数据源连接参数发起连接测试。后端会连接数据库并执行对应方言的轻量探活 SQL，成功后在卡片右上角显示绿色“正常”，失败后显示失败状态并记录错误信息。

使用限制：

• 仅租户管理员可操作。
• 测试的是已经保存的数据源配置，不是编辑弹窗中尚未保存的临时输入。
• 依赖数据库网络、账号密码、连接地址、方言和数据库自身可用性。
• 测试连接只验证连通性，不代表每张业务表、每个 Schema 或写回权限都一定可用。

操作后影响：

• 成功时会提示连接成功和耗时，并把该数据源的最近测试状态更新为“正常”。

• 失败时会提示失败原因，并把最近测试状态更新为失败。

• 不会修改数据源的 alias、方言、URL、账号、密码、描述或访问权限。

测试连接适合在同步后、改配置后、或者怀疑数据库网络和账号有问题时先做一次。它只是看“能不能连上”，不负责证明所有表都能用。

4. 编辑数据源

功能说明：打开“编辑数据源”弹窗，维护当前数据源的说明和访问策略。对系统内置数据源，连接参数由 Aloudata CAN 同步管理，页面只允许调整描述、可读、可写和写入 Schema 前缀。

页面字段说明：

编辑弹窗里最关键的是别名、方言、连接地址、用户名、密码、描述和访问权限。别名是数据源在 Agent 工具调用中的唯一标识，例如系统内置指标平台库 __metric_backend__；方言决定这条连接按哪种 SQL 引擎去解析，目前支持 mysql、postgresql、starrocks、doris、presto、spark、databricks；连接地址、用户名和密码则决定能不能真正连上库。

描述字段是给维护者看的，主要用来说明这个库是做什么的、属于哪个范围。可读控制 Agent 是否允许读取和查询这个数据源，可写控制 Agent 是否允许往这个数据源写结果。如果勾选可写，还必须补一个写入 Schema 前缀，用来限制写回范围，避免把结果写到太宽的区域里。

使用限制：

• 仅租户管理员可操作。
• 系统内置数据源的别名、方言、连接地址、用户名、密码不可在此修改；这些字段会通过“同步系统数据源”从 Aloudata CAN 拉取。
• 数据源别名在编辑时不可修改。
• 勾选“可写”时必须填写非空的写入 Schema 前缀，否则保存会失败。

操作后影响：

• 保存成功后会提示“数据源已更新”，列表刷新。
• 后端会发布数据源配置变更事件，并让后续使用重新读取最新配置。
• 修改可读、可写或写入前缀后，会影响 Agent 后续能否读取该数据源、能否向该数据源写表，以及写表时允许的目标 Schema 范围。

常见操作

• 同步系统数据源。
• 测试连接。
• 编辑描述和访问策略。
• 调整可读、可写和写入前缀。

操作后影响

• 同步系统数据源后，后续查询会读取最新连接参数。
• 测试连接成功只说明连通性正常，不代表所有表都可访问。
• 修改可读、可写或写入前缀后，会影响后续读取和写回范围。