Snowflake 对接说明
面向对象：客户 DBA/云管理员、平台管理员、实施顾问 说明范围：Snowflake 作为 Analytics 数据源 的对接逻辑与配置要点 定位说明：本文仅覆盖"数据源对接"场景，不涉及 Knowledge 向量存储连接
适 用范围与版本边界
支持什么：
- 平台连接 Snowflake，浏览/同步表结构、预览数据、供分析报表使用。
- 支持 密码认证 与 RSA Key-Pair 认证 两种方式。
- 支持在数据源配置中指定 Warehouse、Role、Schema 等关键连接参数。
不支持什么：
- 本文不涉及 Snowflake 作为 Knowledge 向量存储的配置与运维。
- 本文不包含 Snowflake 外部 OAuth/SSO 的高级集成说明。
- 平台不负责 Snowflake 账户开通、Warehouse/Role 的创建与授权，这些需由 Snowflake 管理员完成。
角色分工
| 角色 | 职责 |
|---|---|
| ** Snowflake 账户管理员/DBA** | 创建/指定 Warehouse、Database、Schema；创建对接用户与角色并授权（USAGE/SELECT 等）；如使用 Key-Pair 认证需生成 RSA 密钥对并将公钥绑定到 Snowflake 用户。 |
| 平台管理员 | 在平台侧创建 Snowflake 数据源，录入连接信息并执行测试连接、同步元数据。 |
| 实施顾问 | 准备连接信息与密钥，验证测试连接、对象发现和数据预览结果，完成验收。 |
前置条件清单
| 类别 | 前置条件 |
|---|---|
| 权限 | 用户对目标 Warehouse 具备 USAGE；对目标 Database/Schema 具备 USAGE；对待同步表/视图具备 SELECT |
| 账号 | Snowflake 用户名 + 密码，或 Snowflake 用户名 + RSA Key-Pair |
| 网络 | 平台可访问 Snowflake Account 对应的区域端点（注意 .com 与 .cn 区域后缀差异） |
| 资源准备 | Account 标识符、Database、Warehouse、Role、Schema（默认为 PUBLIC） |
| ⚠️ 需与 DBA 确认 | 角色权限粒度（是否用 ACCOUNTADMIN 或自定义 Role）、Network Policy/IP 白名单、密钥轮换策略 |
平台侧录入要点
Snowflake Analytics 数据源
| 字段名 | 必填 | 说明 |
|---|---|---|
| 主机地址（Host） | ✅ | Snowflake Account 标识符，如 xx20138.cn-northwest-1.aws |
| 数据库名称（Database） | ✅ | 数据库名（大小写敏感） |
| 用户名 | ✅ | Snowflake 用户名 |
| 计算仓库（Warehouse） | ✅ | Warehouse 名称 |
| 角色（Role） | ✅ | 角色名称，决定可访问的数据范围 |
| 架构（Schema） | 可选 | 指定访问的 Schema，留空则使用默认权限范围 |
| 认证方式 | 可选 | 密码认证（默认）或 密钥对认证 |
| 密码 | 密码认证下必填 | Snowflake 用户密码，平台 RSA 加密存储 |
| 私钥（Private Key Data） | 密钥对认证下必填 | RSA 私钥（PEM 格式），Base64 编码后加密存储 |
| 私钥密码（Private Key Password） | 可选 | 若私钥设置了口令保护则需填写 |
录入与授权流程：
- 在数据源配置页录入连接信息（Host、Database、Warehouse、Role、User、Schema）。
- 根据认证方式填写密码或私钥相关字段。
- 点击"测试连接"验证可用性。
- 测试通过后点击"保存"完成数据源创建。
具体操作指南
进入数据源创建页面
- 进入 Data > 数据源 页面。
- 点击 新建数据源。
- 在数据源类型中选择 Snowflake。
填写基本连接信息
在表单中填写以下信息：
- Host（主机地址）：Snowflake Account 标识符（例如
xxx.snowflakecomputing.com） - Database（数据库名称）：目标数据库名称（大小写敏感）
- Warehouse（计算仓库）：执行查询的仓库名称
- Role（角色）：决定可访问对象范围的角色
- User（用户名）：Snowflake 用户名
- Schema（架构）：可选，留空按默认权限范围
填写身份验证信息
按所选认证方式填写：
- 密码认证：填写用户密码
- 密钥对认证：填写
Private Key Data（PEM，Base64）和可选的Private Key Password
验证连接
- 确认必填字段均已填写。
- 点击 测试连接。
- 若测试通过，点击 保存 完成数据源创建。
常见问题与排查路径
| 问题分类 | 现象 | 可能原因 | 排查建议 |
|---|---|---|---|
| 认证失败 | 测试连接报认证失败 | 密码错误；Key-Pair 认证时公钥未正确绑定用户，或私钥格式错误（需 PEM，必要时转 PKCS8） | 核对用户名/密码；确认 ALTER USER ... SET RSA_PUBLIC_KEY 已在 Snowflake 侧执行且与私钥匹配 |
| 主机未找到 | 报 Host not found | Account 标识符填写错误，或区域后缀（.com/.cn）不匹配 | 核对 Snowflake 账户的完整 Account 标识符 |
| 连接超时 | 测试连接长时间无响应后超时 | 网络策略限制、Warehouse 处于挂起状态启动较慢 | 检查 Network Policy/IP 白名单；确认 Warehouse 可正常自动恢复 |
| SSL 错误 | 报 SSL/TLS 相关异常 | 网络代理/证书拦截导致握手失败 | 检查网络出口是否存在 TLS 拦截设备 |
| 权限不足 | 测试连接成功但同步表结构/预览数据失败 | 用户对目标 Schema/表缺少 SELECT 权限 | 请 DBA 补充对应表/视图的 SELECT 授权 |