跳到主要内容

结构采集、复核与维护

采集的目的，是把当前业务实现和真实物理约束放在一起核对，而不是从历史 SQL 重新猜一份数据库。运行于 2026-09-18 的采集已成功取得所列 MySQL、TDengine 和 ES 元数据；旧 SQL 只作历史线索。

输入与连接方式​

输入是 doc/数据库设计管理/nacos/ 中的 datasource.yaml、9 个服务 YAML 和 application-common.yaml。程序支持多 document YAML，解析实际配置对象，避免把注释掉的数据源当作有效绑定。凭据只在本地进程内使用；Java 子进程通过标准输入接收连接信息，不将凭据放入命令参数、日志或文档。

连接实现参考 report/GoView 的实际边界：旧 MySQL/TDengine 查询服务只返回查询结果列，不等于完整结构导出；新的 ReportTdengineResource 使用独立 REST 连接。因此采集器独立执行固定元数据查询，没有调用 GoView 任意业务 SQL 接口，没有启动完整 Spring 服务、定时器或消息消费者。

system 的 SQL 明确访问 monitor.visit_minute，但提供的公共配置缺少 td_api_visit。本次对既有测试 TDengine 实例额外采集 monitor，明确作为代码指定库的结构证据，不反推缺失数据源已经正确配置。

采集了什么​

存储读取范围本次不读取
MySQLinformation_schema 中表/视图、列、逐列索引、约束、键列和外键更新/删除规则；补采有分区名的分区/子分区方法、表达式、顺序与边界定义业务表记录、凭据字段值、数据库全量备份
TDengine服务端版本、SHOW STABLES、DESCRIBE、系统目录普通表及各超级表子表数业务行、标签值、逐设备子表名清单
ES服务端版本、开放索引 _mapping 与 _alias；补采23个业务索引 _settings 中分片、副本、routing、sort和analysis配置_search 文档、closed 索引、运行统计及未列入保留范围的其他settings
Redis / SLS仅源码与配置中的用途、键规则或查询边界在线 key/value、云日志内容及云端索引采集

TDengine 实测版本为 3.3.8.4。用户提供的 3.3.8 SQL 文档入口 在本次浏览工具中不可访问，另核对了官方超级表说明中的 SHOW STABLES、DESCRIBE，并以目标实例实际返回验证兼容性。没有按新版文档推定本实例支持其他新特性。

查询布局补采于 2026-09-18 21:32:38—21:33:23（北京时间） 完成：12个MySQL库均成功，复算37张声明式分区表、27,130项分区定义；ES的23个业务索引settings于21:33:23采集成功。原始结果位于临时快照的 query-layout/。按业务和对象族压缩展示，避免逐项展开数万分区；见 查询路径与优化边界。

复用工具​

  • collect_metadata.py：协调配置解析、MySQL 子进程、TDengine REST 与 ES 元数据请求。
  • MysqlMetadata.java：固定 MySQL 目录查询；连接只读，查询设超时；异常只输出类型和状态码。
  • collect_query_layout.py：复用原快照manifest去重补采MySQL分区及业务ES settings；MySQL调用 MysqlMetadata.java 的 partitions 模式，仅查分区目录，不重复采集完整表结构。
  • render_catalog.py：将采集快照渲染为临时 Markdown 附录，不能直接写回工作区。
  • validate_docs.py：只读检查链接、表格、slug、编码、凭据值及 Python 语法。
  • validate_mdx.mjs：使用站点已有依赖解析 MDX 正文，并调用 Docusaurus 的 URL 解析函数检查链接、自动链接及图片地址；不构建或执行组件。

依赖本地 Python 3、PyYAML、JDK 17+ 与 MySQL Connector/J。实际使用已有 JDK 和 JDBC jar，未运行 Maven 构建、项目测试或业务服务。

python doc_code/docs-develop/database-design/tools/collect_metadata.py `
  --workspace C:/work/ikv2/code/ik_v2_doc `
  --output C:/Users/Lenovo/AppData/Local/Temp/ik-db-metadata-20260918 `
  --java C:/work/env/ocacle17/bin/java.exe `
  --mysql-jar C:/Users/Lenovo/.m2/repository/com/mysql/mysql-connector-j/9.4.0/mysql-connector-j-9.4.0.jar `
  --extra-td monitor

重新采集时使用新的临时目录。已有同名快照会被复用，以免重复访问共享库；复用不是一次新的在线核验。manifest.json 记录服务绑定、去重关系和失败状态。task 与 device 对单体遗留 MySQL nebula_ids 的连接去重；Task 独立库 ik_yudao_task 仍单独采集，连接去重不改变业务归属，也不表示微服务拆分已经完成。

补采布局的复用命令如下，独立运行且只输出到工作区外临时目录：

python doc_code/docs-develop/database-design/tools/collect_query_layout.py `
  --workspace C:/work/ikv2/code/ik_v2_doc `
  --snapshot C:/Users/Lenovo/AppData/Local/Temp/ik-db-metadata-20260918 `
  --output C:/Users/Lenovo/AppData/Local/Temp/ik-db-metadata-20260918/query-layout `
  --java C:/work/env/ocacle17/bin/java.exe `
  --mysql-jar C:/Users/Lenovo/.m2/repository/com/mysql/mysql-connector-j/9.4.0/mysql-connector-j-9.4.0.jar

ES补采对象来自原mapping快照中的 base_device、apk_push_history 和 app_install_device*，不是集群全部索引。仅保留 index.number_of_shards/number_of_replicas 以及 index.routing.*、index.sort.*、index.analysis.*；没有保留 index.max_result_window，因此不能据此确认服务端深分页窗口。

生成待审阅附录：

python doc_code/docs-develop/database-design/tools/render_catalog.py `
  --input C:/Users/Lenovo/AppData/Local/Temp/ik-db-metadata-20260918 `
  --output C:/Users/Lenovo/AppData/Local/Temp/ik-db-catalog-20260918 `
  --workspace C:/work/ikv2/code/ik_v2_doc

程序仅输出工作区外临时结果。审阅后通过 apply_patch 将最终文本纳入文档；不运行会直接覆盖交付文档的生成器。每份附录包含采集时间及原始临时快照 SHA-256，方便本次复核；原始 JSON 不包含认证参数，但仍只保存在本地临时目录，未作为业务数据发布。

跨工具传递生成内容时使用 ASCII 转义 JSON 作为传输格式，解析回 Unicode 后再提交补丁，避免 Windows 终端编码改变中文。交付前逐文件与 UTF-8 临时原稿对照；不能把终端“命令成功”当作文本内容无损的证明。

结果与限制​

  • 本次所选 12 个 MySQL 库、30 个 TDengine 库以及 ES 请求均成功。未解析的 3 个绑定为 td_api_visit、report_prod、td_report；这些是配置资料缺口，不是连接失败证明。
  • 快照按连接与查询顺序采集，没有跨库事务一致性保证。期间发生结构变更时应重新采集相应库。
  • 源码核验基于本次读取的本地工作区，包含已有未提交内容，不等同于某个发布版本。不同代理分批读取，也不构成全工作区原子快照；后续代码变化应同步复核引用和业务说明。
  • MySQL 分区定义已经补采，压缩汇总在查询指南；原字段附录继续按列、索引和约束组织。触发器、存储过程、视图 SQL 或 CHECK 表达式文本仍未采集；不把这些未采集项说成不存在。
  • TDengine 子表用超级表结构及系统目录计数表达，未导出 4,651 个实例名。ES 附录只公开别名名称，未发布别名过滤内容；业务索引的analysis settings已补采，22个索引返回冒号分隔的pattern型 mac_analyzer，app_install_device_s0 未返回该配置。未执行 _analyze 或业务查询，不把配置当成运行效果证明。
  • 实库额外对象可能属于历史版本、测试、其他服务或外部框架；不以名字相似判定可以删除。
  • 只执行独立结构采集与文档静态检查，没有编译项目、运行业务测试、构建或发布文档站点。

文档静态复核​

从工作区根目录执行下列只读检查；它们不会构建站点或启动业务服务：

python doc_code/docs-develop/database-design/tools/validate_docs.py --workspace C:/work/ikv2/code/ik_v2_doc
node doc_code/docs-develop/database-design/tools/validate_mdx.mjs doc_code/docs-develop/database-design
git -C doc_code diff --check -- docs-develop/database-design

新增目录尚未跟踪时，普通 git diff --check 不覆盖其文件，必须同时检查文件文本；本轮另对 60 份 Markdown 和 6 个工具逐文件执行了 git diff --no-index --check。MDX 检查覆盖最终 60 页；修复 BPM 表格中未加代码标记的 Java 泛型后，单独复核该页通过。结构字典与 UTF-8 临时原稿逐文件对照，避免仅凭终端显示判断编码。

九个服务的静态映射检查覆盖了 134 处字面量 @TableName / @IndexName 声明，其对象名均在对应服务文档中出现。这个检查不替代动态命名、XML SQL、继承字段和运行时路由核验；这些另由服务业务页及实测字典说明。设备、任务的关键查询路径另经交叉复核，包括单月 ES、TD 热库/归档库以及 MySQL 显式分区选择。

单纯调用 MDX parse 不覆盖后续链接处理，曾漏检数据库注释里的 https://ip:port 占位地址。检查工具现对 AST 链接调用与 Docusaurus resolveMarkdownLinks 相同的 parseLocalURLPath；字典生成器将注释里的 HTTP 协议冒号编码为字符实体，保持显示文本，同时避免将占位地址变成自动链接。这仍是静态检查，不代表完整 Docusaurus / webpack 构建已经执行。

后续业务变化时怎样维护​

在变更所在服务的业务页补充流程和关联变化，再检查字段默认值、唯一约束、逻辑删除、租户规则、动态对象名与跨库依赖。需要重新核验时只读采集对应环境，明确核验日期，保留无法解释的差异；不要把“过去的设计意图”替换成未经确认的“当前运行事实”。

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答