知识库

MySQL

以 Markdown 格式查看

MySQL 连接器用于把已批准的关系型数据行转成可检索文档。它支持两种索引模式：

  • 自动发现：读取所选数据库中可访问的基础表，由管理员选择表和列，再映射为文档。
  • 自定义 SQL：执行受控的 SELECT 或 WITH 查询，把返回列映射为文档 ID、标题、可检索正文、元数据和更新时间。

请使用专用只读账号，并只暴露经过整理的表或视图。不要把拥有广泛权限的生产账号连接到包含未审批个人数据、凭据、令牌或运营密钥的数据库。

需要准备什么

项目要求
网络路径AIvis worker 必须能访问 MySQL 主机和端口。使用私有网络、数据库代理或已加入白名单的出站 IP。
凭据专用 MySQL 账号，仅对已批准表或视图具备 SELECT 权限。
数据范围对敏感表、join、聚合或字段重命名，优先使用脱敏视图。
稳定身份使用主键、非空唯一键，或在自定义 SQL 中返回稳定的 id_column。
更新时间字段优先使用 datetime 或 timestamp 字段，例如 updated_at，用于增量同步。
传输安全当前 MySQL 凭据表单只暴露 host、port、database、username 和 password。如果数据库要求客户端 TLS 选项，请先通过已批准的私有端点或代理承接连接，再对该连接器强制该策略。

创建只读 MySQL 账号

请用数据库管理员账号执行授权，并按实际环境调整 host pattern、数据库、表和视图名称。

1CREATE USER 'aivis_reader'@'10.0.%'
2  IDENTIFIED BY '<generated-password>'
3  WITH MAX_USER_CONNECTIONS 3;
4
5GRANT SELECT ON knowledge.product_catalog_view TO 'aivis_reader'@'10.0.%';
6GRANT SELECT ON knowledge.faq_article_view TO 'aivis_reader'@'10.0.%';
7
8SHOW GRANTS FOR 'aivis_reader'@'10.0.%';

MySQL 支持 REQUIRE SSL 等账号级 TLS 要求。只有当 AIvis 部署路径已经提供兼容的 MySQL TLS 处理能力时，才为该账号启用这类要求，例如通过已批准的私有数据库代理。

当源表包含敏感列时，请先创建视图：

1CREATE VIEW knowledge.product_catalog_view AS
2SELECT
3  id,
4  name,
5  status,
6  public_summary,
7  category,
8  updated_at
9FROM product_catalog
10WHERE searchable = 1;
11
12GRANT SELECT ON knowledge.product_catalog_view TO 'aivis_reader'@'10.0.%';

只有当某个数据库已专门整理用于 AIvis 索引时，才使用数据库级授权：

1GRANT SELECT ON aivis_public.* TO 'aivis_reader'@'10.0.%';

创建凭据

AIvis 字段推荐填写说明
HostMySQL 主机名或私有端点。不要包含 mysql:// 这类协议前缀。
Port除非部署使用自定义端口，否则填 3306。UI 默认值是 3306。
Database包含已批准表或视图的数据库。自动发现会读取此数据库中的基础表。
Username专用只读账号，例如 aivis_reader。避免使用 root、owner、migration 或应用写入账号。
Password只读账号的生成密码。通过常规凭据流程轮换。

连接器读取 MySQL 行时使用 utf8mb4，并设置 10 秒连接超时。

选择索引模式

模式适用场景边界
自动发现希望 AIvis 发现单个数据库中的可访问基础表，并让管理员选择表和字段。自动发现读取基础表，不处理任意 join 或视图。视图、join、聚合或字段重命名请使用自定义 SQL。
自定义 SQL需要受控视图、join、筛选、投影或稳定行结构。查询必须是单条 SELECT 或 WITH，并且每一行对应一个文档。

自动发现

自动发现会读取所选数据库中可访问的基础表，并忽略 information_schema、mysql、performance_schema、sys 等 MySQL 系统 schema。

在 schema 树中：

  • 只选择已批准索引的表和字段。
  • 二进制、geometry 和 blob 类列不会被索引。
  • AIvis 优先使用主键，其次使用非空唯一索引；没有稳定键时使用行哈希。
  • 没有稳定键的表在选中值变化后可能生成新的文档 ID；建议添加主键，或使用自定义 SQL 返回显式 ID。
  • 标题字段会优先从 title、name、subject、label 等列推断；可在表设置中覆盖。
  • 更新时间字段会从 updated_at、updated、modified_at、modified、last_modified 等 datetime 列推断；没有更新时间字段意味着该表需要全表扫描。

自定义 SQL 要求

连接器会把你的查询包装为子查询，并校验返回列。SQL 应保持只读、确定性和可复现。

字段要求
SQL Query单条 SELECT 或 WITH 查询。不要包含尾随分号或多语句。
ID Column每行非空唯一值。复合键可转换为文本。
Title Column人类可读标题，用作文档名称。
Content Columns一个或多个列，其值会成为可检索正文。
Metadata Columns可选字段，用于筛选或排障。
Updated At Column可选 datetime 或 timestamp 字段，用于只同步每个窗口内更新的行。
Batch Size每批拉取的行数。UI 默认是 16；只有在测试查询成本后再提高。

示例：

1SELECT
2  CAST(p.id AS CHAR) AS doc_id,
3  p.name AS title,
4  CONCAT_WS(
5    '\n',
6    CONCAT('Status: ', p.status),
7    CONCAT('Category: ', p.category),
8    CONCAT('Summary: ', p.public_summary)
9  ) AS body,
10  p.category,
11  p.updated_at
12FROM knowledge.product_catalog_view AS p
13WHERE p.searchable = 1

对应字段：

AIvis 字段值
ID Columndoc_id
Title Columntitle
Content Columnsbody
Metadata Columnscategory
Updated At Columnupdated_at

生产安全

连接器会在只读事务中读取 MySQL，并在读取时设置 max_execution_time。这能避免 AIvis 写入数据，但不能替代数据库侧权限控制。

上线前：

  • 尽量使用只读副本、分析库或受控视图层。
  • 为自定义 SQL 的筛选条件和更新时间窗口添加索引。
  • 自定义 SQL 避免 SELECT *；只返回已批准列。
  • 避免在高负载 OLTP 表上运行长 join。
  • 在测量查询计划和同步耗时前，保持较小批大小。
  • 把 MySQL 账号 host pattern 限制到 AIvis 网络路径，不要使用 %。
  • 在已部署连接路径支持前，不要对账号强制 MySQL TLS；需要受保护链路时使用私有网络或已批准代理。
  • 确认查询计划不会产生重锁、大表全扫或过多临时表。

验证

  1. 确认凭据能用只读账号连接。
  2. 在自动发现中确认能看到预期数据库表和字段。
  3. 在自定义 SQL 中确认查询返回所有已配置列。
  4. 执行首次同步，检查行数、已索引文档数和失败记录。
  5. 按标题和正文搜索代表性记录。
  6. 确认未选表、字段和敏感列不会出现在搜索中。
  7. 修改一行测试数据，确认配置更新时间字段后会更新同一文档。
  8. 使用连接器受众之外的用户测试，确认受限文档不可见。

常见问题排查

现象可能原因处理方式
认证失败账号、密码、数据库、主机或端口错误。从部署网络用同一账号测试连接，必要时轮换密码。
权限被拒绝对选中表或视图缺少 SELECT。给只读账号补充最小缺失 SELECT 权限。
没有发现表账号看不到任何基础表，或只授权了视图。自动发现请授权选定基础表；视图请使用自定义 SQL。
自定义 SQL 被拒绝查询为空、多语句、包含尾随分号后的额外内容，或不是 SELECT / WITH 开头。使用单条只读查询，并为映射字段返回明确别名。
缺少列查询没有返回已配置的 ID、标题、正文、元数据或更新时间列。添加别名，或更新字段映射。
更新时间字段无效更新时间列不是 MySQL datetime 或 timestamp 值。使用 datetime 兼容字段，或留空并接受全量扫描。
文档重复或 ID 变化没有稳定身份，或配置的 ID 会变化。使用主键、非空唯一键，或稳定的 id_column。
同步超时查询成本超过 max_execution_time，或批大小过高。添加索引、缩小范围、降低批大小，或改用副本/视图。
强制 TLS 连接失败服务器账号或数据库代理要求当前凭据表单未暴露的 TLS 选项。使用能终止或承接所需 TLS 路径的私有端点/代理，或先调整部署支持，再强制账号级 TLS。

相关官方文档