外部数据连接

外部数据连接让您可以直接在 ModelMonkey 中查询数据库。无需手动导出数据或编写复杂的导入脚本，您可以让 ModelMonkey 从 PostgreSQL 或 BigQuery 数据库中提取数据，并将其与电子表格数据合并使用。

连接建立后，您可以提出如下问题："将 Google Sheets 中的销售数据与 PostgreSQL 中的客户画像进行对比"，或"查找上个月的所有订单，并与数据库中的用户资料进行关联"。

ModelMonkey 目前支持两种外部数据源：

PostgreSQL
连接任何可通过互联网访问的 PostgreSQL 数据库，包括自托管 PostgreSQL、Amazon RDS、Google Cloud SQL、Azure Database for PostgreSQL 及其他托管 PostgreSQL 服务。

Google BigQuery
使用服务账号连接 Google BigQuery 数据集，非常适合大规模分析工作负载和数据仓库查询。

两种连接类型均仅支持只读查询，以防止生产数据被意外修改。

要创建新的外部数据连接，请按以下步骤操作：

1. 从 ModelMonkey 侧边栏打开"外部数据连接"面板
2. 点击"新建连接"按钮
3. 选择数据源类型（PostgreSQL 或 BigQuery）
4. 输入连接详情
5. 测试连接以验证其是否正常工作
6. 保存连接

设置向导将引导您完成每个步骤，并在保存前验证您的配置。

要连接 PostgreSQL 数据库，您需要提供以下信息：

必填字段

• 连接名称：用于标识此连接的名称（例如："生产分析数据库"）
• 主机：数据库服务器的主机名或 IP 地址
• 端口：PostgreSQL 端口（默认：5432）
• 数据库：要连接的数据库名称
• 用户名：数据库用户名
• 密码：数据库密码

可选字段

• Schema：使用的默认 schema（默认："public"）
• SSL 模式：SSL 连接的处理方式
  • Disable：不使用 SSL（不建议在生产环境中使用）
  • Allow：如果可用则使用 SSL
  • Prefer：优先尝试 SSL，失败后回退至非 SSL（默认）
  • Require：始终使用 SSL

Connection Name: Production Analytics
Host: analytics-db.example.com
Port: 5432
Database: analytics
Schema: public
SSL Mode: Require
Username: readonly_user

要连接 Google BigQuery，您需要一个具有适当权限的服务账号：

必填字段

• 连接名称：用于标识此连接的名称
• Project ID：您的 Google Cloud 项目 ID（可在 Google Cloud Console 中查看）
• 服务账号 JSON：具有 BigQuery 访问权限的服务账号 JSON 密钥文件

可选字段

• Dataset ID：默认查询的数据集
• Location：数据存储位置（US、EU 或特定区域）

所需 IAM 角色
您的服务账号需要以下权限：

• BigQuery Data Viewer：读取表元数据和数据
• BigQuery Job User：创建并执行查询
• BigQuery Read Session User：通过 Storage API 读取数据

要为 BigQuery 访问创建服务账号，请按以下步骤操作：

1. 前往 Google Cloud Console（console.cloud.google.com）
2. 导航至"IAM 和管理" → "服务账号"
3. 点击"创建服务账号"
4. 输入名称，例如"modelmonkey-readonly"
5. 授予以下角色：
   • BigQuery Data Viewer
   • BigQuery Job User
   • BigQuery Read Session User
6. 点击"完成"以创建账号
7. 点击新建的服务账号，然后切换到"密钥"选项卡
8. 点击"添加密钥" → "创建新密钥" → "JSON"
9. 下载 JSON 文件并将其上传至 ModelMonkey

请妥善保管此 JSON 文件，它提供了访问您 BigQuery 数据的权限。

在保存连接之前，ModelMonkey 会验证是否能够成功访问您的数据库：

测试内容

• 与主机的网络连通性
• 使用您的凭据进行身份验证
• 查询数据库的权限

测试结果
测试成功后将显示：

• 服务器版本信息
• 可用 schema（PostgreSQL）
• 可访问的数据表数量

如果测试失败，您将看到说明问题原因的具体错误信息。常见问题包括：

• 主机名或端口不正确
• 用户名或密码错误
• 防火墙阻止了连接
• 缺少数据库权限

ModelMonkey 采用企业级安全措施保护您的数据库凭据：

信封加密
您的凭据使用为每个连接专门生成的数据加密密钥（DEK）进行加密。DEK 本身在存储前由 Google Cloud KMS 加密。这种双层加密方式确保您的凭据永远不会以明文形式存储。

SSRF 防护
ModelMonkey 会屏蔽对私有 IP 地址段、本地回环地址及云元数据端点的连接请求，即使提供了恶意输入也能有效防范潜在安全漏洞。

安全内存处理
解密后的凭据存储在安全内存缓冲区中，使用完毕后自动清除。

只读访问
BigQuery 连接被明确配置为只读模式。对于 PostgreSQL，我们建议使用仅具有 SELECT 权限的数据库用户。

连接激活后，您只需用自然语言向 ModelMonkey 提问即可进行查询：

请求示例

• "从我们的 PostgreSQL 数据库中显示收入排名前 10 的客户"
• "将 Google Sheets 中的销售数据与外部数据库中的客户画像进行对比"
• "查找上个月的所有订单，并与用户资料进行关联"
• "分析我们 BigQuery 分析数据中的趋势"

ModelMonkey 将自动完成以下操作：

1. 安全连接至您的外部数据库
2. 将您的请求转换为 SQL
3. 执行查询
4. 返回结果并写入您的电子表格

您可以在单个请求中合并来自多个数据源的数据，轻松实现电子表格数据与外部数据库记录的关联查询。

查看连接
所有连接均显示在"外部数据连接"面板中。每个连接显示以下信息：

• 连接名称
• 提供商类型（PostgreSQL 或 BigQuery）
• 主机或项目信息
• 启用/停用状态
• 创建日期

连接状态

• 启用：该连接可用于查询
• 停用：该连接存在但已被禁用

删除连接
要移除某个连接：

1. 点击连接卡片上的菜单图标（三个点）
2. 选择"删除"
3. 确认删除操作

删除连接将永久移除该连接及其加密凭据，此操作不可撤销。

连接测试失败

• 验证主机名是否正确且可公开访问
• 检查防火墙是否已开放数据库端口
• 确认用户名和密码是否正确
• 对于 BigQuery，确保服务账号已具备所需角色

查询返回错误

• 检查数据库用户是否对目标表具有 SELECT 权限
• 确认表名和 schema 名称是否正确
• 对于 BigQuery，确保服务账号可以访问指定的数据集

连接超时

• 您的数据库可能位于防火墙后，阻止了 ModelMonkey 服务器的访问
• 检查云服务提供商是否要求 IP 白名单配置
• 如果无法直接访问，请考虑使用数据库代理或 VPN

"检测到 SSRF 尝试"错误

• 不支持连接到私有 IP 地址或本地回环地址
• 请为数据库使用可公开访问的主机名
• 云托管数据库（RDS、Cloud SQL 等）通常提供公共访问端点

使用专用只读用户
为 ModelMonkey 单独创建一个仅具有 SELECT 权限的数据库用户。这样即使凭据泄露，也能将影响范围降到最低。

启用 SSL/TLS
对于生产环境的 PostgreSQL 连接，始终将 SSL 模式设置为"Require"。BigQuery 连接始终采用加密传输。

限制表访问权限
仅授予 ModelMonkey 需要查询的表和 schema 的访问权限，避免使用超级用户或管理员账号。

使用清晰的连接名称
为连接起一个直观易懂的名称（例如"生产分析数据库"、"预发环境订单库"），便于在请求中准确引用。

定期审查连接
定期检查您的连接列表，删除不再需要的连接。活跃连接越少，安全暴露面越小。