连接对象（Connection）

Connection 是 Lakehouse 中存储第三方服务认证信息的对象，使 Lakehouse 能够安全访问外部数据源（对象存储、Kafka、HDFS、AI 模型等），无需在 SQL 中暴露明文密码或密钥。

类比：Connection 像 Lakehouse 的"密码保险箱"——你把云存储的密钥、Kafka 的地址等信息存进去，之后访问外部数据时只需引用 Connection 名称，系统自动使用保存的凭据。

Connection 类型

类型	用途	适用场景
Storage Connection	连接对象存储（OSS/COS/S3）、Kafka、HDFS	挂载外部存储创建 External Volume，或接入 Kafka 数据
API Connection	连接外部 API 服务（AI 模型等）	创建外部函数调用 LLM、图像识别等服务
Catalog Connection	连接外部数据目录（Hive 等）	创建 External Catalog 实现联邦查询

选型建议

场景	推荐	原因
已有 OSS/S3 数据，不想迁移	Storage Connection + External Volume	直接挂载，零复制
从 Kafka 实时消费数据	Storage Connection + Pipe	持续导入 Kafka 流数据
调用 AI 模型（文本生成/向量化）	API Connection + External Function	在 SQL 中直接调用 AI 服务
查询 Hive 数据仓库	Catalog Connection + External Catalog	联邦查询，数据不迁入

核心机制

凭据安全：Connection 存储的密钥信息加密保存，SQL 中只引用 Connection 名称，不会暴露明文。

跨云限制：Storage Connection 不支持跨云厂商创建。例如运行在阿里云上的 Lakehouse 实例，无法创建腾讯云 COS 的 Connection。

角色授权（RoleARN）：相比 AK 密钥方式，RoleARN 更安全——Lakehouse 通过扮演客户云账号中的角色来访问数据，客户可随时撤销角色权限，且支持 External ID 双重验证。

快速示例

创建 Storage Connection（AK 方式）

-- 创建阿里云 OSS 连接（AK 密钥方式） CREATE STORAGE CONNECTION IF NOT EXISTS my_oss_conn TYPE oss ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com' ACCESS_ID = 'LTAI5tMmbq1Ty1xxxxxxxxx' ACCESS_KEY = '0d7Ap1VBuFTzNg7gxxxxxxxxxxxx'; -- 查看 Connection 信息 DESC CONNECTION my_oss_conn; -- 结果： -- +--------------------+------------------+ -- | info_name | info_value | -- +--------------------+------------------+ -- | name | my_oss_conn | -- | type | OSS | -- | enabled | ENABLED | -- | ACCESS_ID | LTAI5tMm... | -- | ENDPOINT | ... | -- +--------------------+------------------+

创建 Storage Connection（RoleARN 方式）

-- 创建阿里云 OSS 连接（角色授权方式） CREATE STORAGE CONNECTION my_oss_conn_role TYPE oss REGION = 'cn-hangzhou' ROLE_ARN = 'acs:ram::1222808864xxxxxxx:role/czudfrole' ENDPOINT = 'oss-cn-hangzhou-internal.aliyuncs.com'; -- 查看 External ID（用于配置云端的信任策略） DESC CONNECTION my_oss_conn_role; -- 结果中包含 external_id，需在阿里云 RAM 角色的信任策略中配置

⚠️ 注意：使用 RoleARN 方式时，

DESC CONNECTION

DESC CONNECTION

返回的

external_id

external_id

需要配置到云端的角色信任策略中，作为额外的验证层。即使第三方获取了 RoleARN，没有正确的 External ID 也无法访问。

创建 API Connection

-- 创建阿里云函数计算 API 连接 CREATE API CONNECTION my_fc_conn TYPE aliyun_fc REGION = 'cn-hangzhou' ACCESS_ID = 'LTAI5tMmbq1Ty1xxxxxxxxx' ACCESS_KEY = '0d7Ap1VBuFTzNg7gxxxxxxxxxxxx';

常见问题

常见问题 1：跨云创建 Connection 失败

问题：在阿里云上的 Lakehouse 实例尝试创建腾讯云 COS 的 Connection。

症状：报错

cross-cloud connection not supported

cross-cloud connection not supported

。

解决：

Storage Connection 不支持跨云厂商
阿里云 Lakehouse 只能连接阿里云 OSS
如需访问多云数据，先在目标云存储中导出数据，再导入到 Lakehouse 所在云的对象存储

常见问题 2：RoleARN 方式缺少 External ID 配置

问题：使用 RoleARN 创建 Connection 后，访问外部存储报权限错误。

症状：

AccessDenied

AccessDenied

或

STS token expired

STS token expired

。

解决：

创建 Connection 后，用
```
DESC CONNECTION
```
DESC CONNECTION
获取 External ID
在云端的角色信任策略中，将 External ID 添加到
```
sts:ExternalId
```
sts:ExternalId
条件中
确认 Lakehouse 实例的账号 ID 已添加到角色的信任主体（Principal）中

常见问题 3：AK 密钥泄露风险

问题：使用 AK 密钥方式创建 Connection，但 AccessKey 被意外泄露。

症状：外部存储被未授权访问。

解决：

优先使用 RoleARN 方式，而非 AK 密钥
RoleARN 可随时在云端撤销角色权限，无需轮换密钥
定期轮换 AccessKey，并限制密钥的权限范围（最小权限原则）

成本影响

存储成本

Connection 本身只存储元数据（认证信息），几乎零存储成本

计算成本

Connection 本身不产生计算费用
通过 Connection 访问外部数据时，数据传输可能产生云厂商的流量费用
External Volume 读取外部存储文件消耗 VCluster CRU

💡 详细计费规则请参考计费文档

生命周期管理

创建 Connection → 关联使用（Volume/Pipe/External Function）→ 轮换密钥 → 删除 Connection ↓ ↓ ↓ ↓ 保存凭据外部数据访问更新 AccessKey DROP CONNECTION

创建和删除

-- 创建 Connection CREATE STORAGE CONNECTION my_conn TYPE oss ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com' ACCESS_ID = '...' ACCESS_KEY = '...'; -- 查看 Connection 列表 SHOW CONNECTIONS; -- 查看 Connection 详情 DESC CONNECTION my_conn; -- 删除 Connection DROP CONNECTION my_conn;