# 元数据采集与同步问题排查指南

# 排查指南详细说明

通用前置检查：

确认部署模式：首先明确元数据是独立安装还是集成安装模式。
- 独立模式：单独安装元数据7.5GA完整介质，采集器在元数据平台配置，DAMP通过接口调用元数据服务。
- 集成模式：元数据与DAMP集成安装，采集器需要在资产平台配置，元数据功能嵌入DAMP中。
确认版本：DAMP版本（7.3 GA/7.3.1）、元数据版本（7.5 GA）。
查阅补丁列表：在寻求复杂解决方案前，强烈建议先检索是否有官方发布的补丁。您可以通过以下链接访问官方补丁列表：
- DAMP 7.3.1 补丁列表: DAMP7.3.1补丁列表 (opens new window)
- DAMP 7.3 GA 补丁列表: DAMP7.3GA补丁列表 (opens new window)
- 元数据补丁列表: 元数据补丁列表 (opens new window)

# 场景一：采集任务执行失败

问题现象：
1. 手动执行采集任务时，任务一直处于“执行中”状态。
2. 定时采集任务未按计划执行。
3. 采集任务执行后，状态显示“失败”。
4. 点击“立即执行”无反应。
排查步骤：
1. 第一步：排除产品BUG。
  - 操作：在官方补丁列表中，使用 Ctrl+F 搜索关键词 采集、任务、extractor。
  - 相关补丁：
    - DAMP 7.3.1: METACUBE_7.5.1_SERVER_20250724_P1 (解决元数据采集后物理模型空指针)
    - DAMP 7.3.1: DAMP_7.3.1_SERVER_20250610_P1 (解决海量数据库适配问题)
  - 解决方案：若找到描述匹配的补丁，则申请并应用。
2. 第二步：检查采集器配置（集成模式）。
  - 操作：进入“元数据管理” -> “采集器管理”。
  - 排查项：
    - 采集器IP和端口是否正确配置。
    - 采集器后端配置文件中的IP要与添加时写的IP一致。
    - 采集器服务是否正常启动。
  - 解决方案：
    - 如果采集器IP配置错误，删除后重新添加。
    - 确保采集器后端配置的IP与DAMP添加时填写的一致。
    - 知识点：采集器报错 io.grpc.StatusRuntimeException: INTERNAL: http2 exception 通常是IP不一致导致。
3. 第三步：检查数据源配置。
  - 操作：在“系统管理”中找到对应的数据源，点击“连接测试”。
  - 排查项：
    - 数据源URL、用户名、密码是否正确。
    - 对于达梦数据库，注意大小写敏感配置。
    - 对于Oracle数据库，注意用户是否有权限。
  - 解决方案：
    - 修正数据源配置后重新测试连通性。
    - 确保数据源连接成功后，重新执行采集任务。
4. 第四步：查看采集日志。
  - 操作：进入“元数据管理” -> “采集日志”，查看失败任务的日志详情。
  - 排查项：根据日志具体错误信息判断问题原因。
  - 解决方案：根据日志错误类型，参考场景三的对应解决方案。

# 场景二：采集不到表/字段

问题现象：
1. 采集任务执行成功，但采集到的表数量为0。
2. 只采集到部分表，缺少预期中的表。
3. 采集到表但没有字段信息。
4. 表名/字段名大小写异常。
排查步骤：
1. 第一步：排除产品BUG。
  - 操作：在官方补丁列表中，搜索关键词 采集不到、表、字段。
  - 相关补丁：
    - DAMP 7.3.1: METACUBE_7.5.1_SERVER_20250724_P1 (解决元数据显示问题)
  - 解决方案：若找到描述匹配的补丁，则申请并应用。
2. 第二步：检查数据库类型适配。
  
  达梦数据库
  - 排查项：大小写敏感配置（CASE_SENSITIVE=1）。
  - 解决方案：
```
-- 查询大小写敏感配置
SELECT * FROM V$DM_INI WHERE PARA_NAME = 'CASE_SENSITIVE';

-- 方案1：JDBC URL添加参数
-- jdbc:dm://127.0.0.1:5236/数据库名?columnNameUpperCase=false

-- 方案2：统一使用大写表名
-- 创建表和查询时都使用大写

-- 方案3：申请补丁 DAMP_7.3.1_SERVER_20240731_P2
```
  Oracle数据库
  - 排查项：用户是否有权限访问目标Schema的表。
  - 解决方案：
```
-- 授予查询权限
GRANT SELECT ANY TABLE TO 用户名;

-- 如果只需要特定Schema
GRANT SELECT ON schema名.表名 TO 用户名;

-- 查看用户默认Schema
SELECT SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA') FROM DUAL;
```
  MySQL数据库
  - 排查项：URL中是否指定了数据库名。
  - 解决方案：
```
-- 正确URL格式
jdbc:mysql://127.0.0.1:3306/数据库名?characterEncoding=UTF-8

-- 确认用户有权限
GRANT SELECT ON 数据库名.* TO '用户名'@'%';
```
  PostgreSQL数据库
  - 排查项：搜索路径（search_path）设置。
  - 解决方案：
```
-- 设置搜索路径
ALTER USER 用户名 SET search_path TO schema名, public;

-- 或在URL中指定当前Schema
jdbc:postgresql://127.0.0.1:5432/数据库名?currentSchema=schema名
```
  SQLServer数据库
  - 排查项：用户默认Schema和权限。
  - 解决方案：
```
-- 授予db_datareader角色
EXEC sp_addrolemember 'db_datareader', '用户名';

-- 设置默认Schema
ALTER USER 用户名 WITH DEFAULT_SCHEMA = schema名;
```
3. 第三步：检查数据源Schema配置。
  - 操作：在数据源配置中，确认Schema字段是否正确填写。
  - 排查项：
    - 对于达梦，如果用户名不是Schema所有者，必须在URL中指定Schema。
    - 对于Oracle，用户名通常就是Schema名，但也可以不同。
  - 解决方案：
    - 在JDBC URL中添加 ?schema=实际Schema名 参数。
    - 申请补丁 DAMP_7.3.1_SERVER_20250516_P1（解决达梦Schema识别问题）。
4. 第四步：检查表过滤条件。
  - 操作：检查采集任务配置中是否有表名过滤条件。
  - 排查项：可能配置了包含/排除规则，过滤掉了目标表。
  - 解决方案：调整过滤条件，或取消过滤重新采集。

# 场景三：采集日志报错

问题现象：
1. 采集日志中报“连接超时”。
2. 报“权限不足”或“无权限”。
3. 报“驱动类找不到”。
4. 报“表不存在”但表实际存在。
5. 报“密码超长错误”。
排查步骤：
1. 第一步：排除产品BUG。
  - 操作：在官方补丁列表中，搜索关键词 日志、报错、密码。
  - 相关补丁：
    - DAMP 7.3.1: DAMP_7.3.1_SERVER_20250516_P1 (解决密码超长问题)
  - 解决方案：若找到描述匹配的补丁，则申请并应用。
2. 第二步：处理连接超时错误。
  - 现象：Connection timed out 或 connect timed out。
  - 排查项：
    - 网络连通性：DAMP服务器到数据库服务器的网络。
    - 防火墙设置：数据库端口是否开放。
    - 数据库监听状态：数据库服务是否正常。
  - 解决方案：
```
# 测试网络连通性
telnet 数据库IP 数据库端口

# 如果不通，检查防火墙
# 在数据库服务器上
systemctl status firewalld
firewall-cmd --list-ports

# 临时开放端口
firewall-cmd --add-port=5236/tcp --permanent
firewall-cmd --reload
```
3. 第三步：处理权限不足错误。
  - 现象：Access denied、权限不足、ORA-00942: table or view does not exist。
  - 排查项：数据库用户权限不足。
  - 解决方案：
```
-- MySQL
GRANT SELECT ON *.* TO '用户名'@'%';

-- Oracle
GRANT CONNECT, RESOURCE TO 用户名;
GRANT SELECT ANY TABLE TO 用户名;
GRANT SELECT ON DBA_TABLES TO 用户名;
GRANT SELECT ON DBA_TAB_COLUMNS TO 用户名;

-- SQLServer
EXEC sp_addrolemember 'db_datareader', '用户名';

-- PostgreSQL
GRANT SELECT ON ALL TABLES IN SCHEMA public TO 用户名;
```
4. 第四步：处理驱动类找不到错误。
  - 现象：No suitable driver、Driver class not found。
  - 排查项：JDBC驱动文件缺失或版本不匹配。
  - 解决方案：
    - 从数据库官方获取正确版本的JDBC驱动。
    - 将驱动jar包放入DAMP服务的lib目录。
    - 重启DAMP服务后重试。
5. 第五步：处理密码超长错误。
  - 现象：密码超长错误，采集失败。
  - 排查项：达梦数据库原始密码太长（验证发现14位密码可能有问题）。
  - 解决方案：
    - 临时方案：将数据库密码控制在14位以内。
    - 补丁方案：申请补丁 DAMP_7.3.1_SERVER_20250516_P1（修复密码加解密问题）。
    - 手动测试：在URL中直接输入明文密码测试，如果能连接则说明是加解密问题。
6. 第六步：处理http2 exception错误。
  - 现象：io.grpc.StatusRuntimeException: INTERNAL: http2 exception。
  - 排查项：采集器IP配置不一致。
  - 解决方案：
    - 检查采集器后端配置文件中的IP地址。
    - 确保与DAMP中添加采集器时填写的IP一致。
    - 修正后重启采集器服务。

# 场景四：资产/模型看不到元数据

问题现象：
1. 资产编目时，选择元数据后无法展现元数据信息。
2. 物理模型管理中，查看元数据报空指针。
3. 模型开发时，选择数据源无子项。
4. 数据服务开发时，选不到表。

排查步骤：

第一步：排除产品BUG。
- 操作：在官方补丁列表中，搜索关键词 元数据、空指针、物理模型。
- 相关补丁：
  - DAMP 7.3.1: METACUBE_7.5.1_SERVER_20250724_P1 (解决物理模型查看元数据空指针)
  - DAMP 7.3.1: DAMP_7.3.1_SERVER_20250610_P1 (解决海量数据库适配问题)
- 解决方案：若找到描述匹配的补丁，则申请并应用。

第二步：检查元数据服务配置。

操作：进入“平台配置” -> “平台参数配置”，检查元数据相关配置。

排查项：

参数	说明	正确值
`metacube.product`	元数据产品类型	`LOCAL`
`metacube.isAlone`	集成模式	`Y`（独立）/`N`（集成）
`metacube.serverUrl`	元数据服务地址	`http://ip:port/dgs`
`metacube.isUse`	是否启用	`Y`

解决方案：
- 确保 metacube.serverUrl 配置正确，能正常访问。
- 如果是集成模式，确保 metacube.isAlone 设为 N。
- 修改配置后，点击“刷新缓存”使配置生效。

第三步：处理物理模型空指针问题。
- 现象：点击物理模型菜单或查看元数据时报空指针。
- 排查项：元数据采集的数据源未正确分配给系统。
- 解决方案：
  - 申请补丁 METACUBE_7.5.1_SERVER_20250724_P1。
  - 打补丁后，在系统管理中删除已选择的数据源，重新选择。
  - 具体操作步骤：
    1. 进入“系统管理”，找到对应系统。
    2. 在“数据存储情况”中，删除已关联的元数据数据源。
    3. 点击“选择元数据数据源”，重新选择。
    4. 保存后，重新进入物理模型查看。
第四步：检查元数据服务状态。
- 操作：确认元数据服务（DGS）是否正常启动。
- 排查项：
  - 访问 http://元数据IP:端口/dgs 是否能打开页面。
  - 查看元数据服务日志是否有错误。
- 解决方案：
  - 如果服务未启动，启动元数据服务。
  - 如果服务异常，重启元数据服务。
第五步：检查nginx配置（如有）。
- 操作：如果通过nginx访问，检查nginx配置。
- 排查项：metacube.serverUrl 配置的地址是否正确转发到元数据服务。
- 解决方案：
  - 修正nginx配置，确保 /dgs 路径正确代理到元数据服务。
  - 例如：proxy_pass http://元数据IP:端口;
第六步：检查系统与数据源关联。
- 操作：确认元数据数据源已正确分配给系统。
- 排查项：
  - 在“系统管理”中，该系统是否关联了元数据数据源。
  - 关联的数据源是否已成功采集元数据。
- 解决方案：
  - 如果未关联，点击“选择元数据数据源”进行关联。
  - 如果已关联但无数据，重新执行采集任务。

# 场景五：采集器状态异常

问题现象：
1. 采集器管理页面显示采集器状态为“离线”。
2. 新增采集器时，测试连接失败。
3. 采集器无法注册到DAMP。
4. 采集器日志报错。
排查步骤：
1. 第一步：排除产品BUG。
  - 操作：在官方补丁列表中，搜索关键词 采集器、extractor。
  - 相关补丁：暂无直接相关补丁。
  - 解决方案：按以下步骤排查。
2. 第二步：检查采集器进程。
  - 操作：登录采集器所在服务器，检查进程状态。
  - 命令：
```
# 查看采集器进程
ps -ef | grep extractor

# 查看采集器端口监听
netstat -anp | grep 采集器端口

# 查看采集器日志
tail -f 采集器安装目录/logs/extractor.log
```
  - 解决方案：
    - 如果进程不存在，启动采集器服务。
    - 如果进程存在但状态异常，重启采集器服务。
3. 第三步：检查IP/端口配置。
  - 操作：核对DAMP中配置的采集器IP和端口。
  - 排查项：
    - IP地址是否与采集器服务器实际IP一致。
    - 端口号是否与采集器配置文件中的端口一致。
    - 采集器后端配置文件中的IP要与添加时写的IP一致。
  - 解决方案：
    - 如果IP不一致，删除采集器后重新添加。
    - 修改采集器配置文件中的IP，重启后重试。
4. 第四步：检查网络连通性。
  - 操作：测试DAMP服务器到采集器服务器的网络。
  - 命令：
```
# 测试IP连通性
ping 采集器IP

# 测试端口连通性
telnet 采集器IP 采集器端口
```
  - 解决方案：
    - 如果ping不通，检查网络路由。
    - 如果端口不通，检查防火墙设置。
5. 第五步：检查认证配置（Kerberos场景）。
  - 操作：如果使用Kerberos认证，检查配置。
  - 排查项：
    - keytab文件是否存在且权限正确。
    - krb5.conf配置是否正确。
    - 认证主体（principal）是否正确。
  - 解决方案：
    - 修正认证配置文件。
    - 确保keytab文件可读。
    - 重启采集器服务。

# 场景六：性能/超时问题

问题现象：
1. 查询元数据表接口响应慢（超过4分钟）。
2. 采集大量数据时超时失败。
3. 模型开发时加载表列表缓慢。
4. 资产编目选择元数据时等待时间长。
排查步骤：
1. 第一步：排除产品BUG。
  - 操作：在官方补丁列表中，搜索关键词 慢、超时、性能。
  - 相关补丁：暂无直接相关补丁。
  - 解决方案：按以下步骤排查。
2. 第二步：添加数据库索引（关键优化）。
  - 现象：查询元数据表接口慢，如 queryMetaTablePage 接口。
  - 排查项：元数据数据库缺少必要索引。
  - 解决方案：
```
-- 在元数据数据库中添加索引
-- 该索引优化按classifier_id、namespace、INSTANCE_NAME查询的性能
CREATE INDEX IDX_MD_INSTANCE_OPT ON T_MD_INSTANCE (classifier_id, namespace, INSTANCE_NAME);

-- 添加后重启元数据服务
```
  - 效果：该索引可显著提升元数据查询性能，将4分钟的查询优化到秒级。
3. 第三步：分批采集大数据量。
  - 现象：采集百万级数据量的表时超时。
  - 解决方案：
    - 在采集任务配置中，设置分批采集。
    - 调整采集任务的超时时间。
    - 避开业务高峰期执行采集任务。
4. 第四步：重启元数据服务。
  - 现象：临时性性能问题，重启后恢复。
  - 操作：
```
# 重启元数据服务
cd 元数据安装目录/bin
./shutdown.sh
./startup.sh

# 查看日志确认启动成功
tail -f 元数据安装目录/logs/*.log
```
5. 第五步：检查元数据服务负载。
  - 操作：检查元数据服务的CPU、内存使用情况。
  - 命令：
```
# 查看进程资源使用
top -p 元数据进程PID

# 查看JVM内存使用
jstat -gcutil 元数据进程PID 1000
```
  - 解决方案：
    - 如果内存不足，调整JVM参数增加内存。
    - 如果CPU过高，分析是否存在慢SQL。

← 数据资产部署至达梦数据库环境相关问题资产流程审批相关问题 →