版本：4.x

产品运维

本文列出 TapData Enterprise 运维相关的常见问题。

如何进行 TapData 健康检查？

此检查清单用于验证 TapData 服务是否处于健康运行状态。

登录 TapData 平台。
在左侧导航栏，选择系统管理 > 集群管理，查看各组件的运行状态，主要检查：
- TapData 服务相关进程：Tapdata管理器、Tapdata引擎、Tapdata API服务器是否运行正常。
- 检查 CPU 和内存使用率是否处于健康水平（低于70%）
单击左侧导航栏的数据复制或数据转换，查看任务列表，主要检查各任务的状态是否均为运行中。此外，您还可以单击任务名称，查看任务详细监控信息，确认任务运行正常，同步延迟是否在可接受范围内，任务 QPS 是否大于0。如果任务出现异常，请跟随下述步骤排查：
- 检查任务报错信息：如果遇到任务异常，您可以通过任务的监控页面的底部查看相关日志信息，根据日志提示进行故障排除。更多介绍，见任务故障排查。
- 检查任务关联的数据库连接：单击左侧的连接管理，找到对应的数据源连接，单击其测试连接按钮以验证连通性，如遇异常，请根据提示进行故障排除（如密码错误）。
- 检查任务增量延迟：如果 QPS 突增持续 30 分钟以上，可能是源端批量操作或业务高峰引起，请评估任务是否需扩容；如果目标库无增量写入或写入耗时异常，请检查 CDC 的前提准备是否正确设置，以 MySQL 数据库为例，需确认是否开启了 binlog 并设置为 ROW 模式，具体设置可参考对应的创建连接文档。此外，任务日志中如出现主键冲突，需确认是否有配置改动。

如经过上述流程排查，任务仍异常，请联系 Tapdata 支持。

如何启停服务？

启停服务

除本方法外，您也可以通过内置 tapdata 命令工具来执行启停操作，该工具的在 TapData 安装目录中，可通过 ./tapdata help 查看命令帮助信息，输出示例如下：

./tapdata help
 _______       _____  _____       _______
|__   __|/\   |  __ \|  __ \   /\|__   __|/\    
   | |  /  \  | |__) | |  | | /  \  | |  /  \   
   | | / /\ \ |  ___/| |  | |/ /\ \ | | / /\ \  
   | |/ ____ \| |    | |__| / ____ \| |/ ____ \ 
   |_/_/    \_\_|    |_____/_/    \_\_/_/    \_\ 

WORK DIR:/root/tapdata
usage: tapdata [option] [subsystem]
Option:
  start            Start Tapdata
  stop             Stop Tapdata
  restart          Restart Tapdata
  status           Check the running status
  init             Initialize Tapdata Configuration
  resetpassword    Reset MongoDB password or certificate key file password
  --version        Tapdata version
  help             Show this usage information
  
Subsystem:
  frontend         Tapdata management portal
  backend          Data Processing Node
  apiserver        API Server Node

如何备份/恢复 TapData？

TapData 运行期间，所有任务配置、共享缓存等关键数据均保存在 MongoDB 中。为保证升级或迁移安全，请通过 MongoDB 备份工具按下列流程对元数据库及工作目录进行备份，并在需要时快速恢复。

备份流程

备份前准备。

登录 TapData 所在服务器，进入安装目录，停止服务，高可用部署时，请在每台节点上依次执行。
```
./tapdata stop -f
```
执行下述格式的命令备份元数据库。
```
mongodump --uri "mongodb://<username>:<password>@<mongodb_host>:<mongodb_port>/<database_name>?authSource=admin" --gzip --excludeCollection="collection_name"  -o /backup/tapdata_db_$(date +%F)
```
- <username>、<password>：MongoDB 实例的用户名及密码。
- <mongodb_host>、<mongodb_port>：MongoDB 实例地址及端口（默认 27017）。
- <database_name>：数据库名（默认 tapdata，如自定义请以实际为准）。
- --gzip：压缩备份文件，可有效减少备份文件大小。
- --excludeCollection="collection_name"：指定无需备份的集合（如系统日志），从而进一步节约备份耗时和所需的存储空间，可重复指定多个，推荐设置为 --excludeCollection="AgentMeasurementV2" --excludeCollection="AlarmInfo" --excludeCollection="ApiCall" --excludeCollection="fs.files" --excludeCollection="fs.chunks" --excludeCollection="Message" --excludeCollection="monitoringLogs" --excludeCollection="InspectDetails" --excludeCollection="DDlTaskHistories" --excludeCollection="Logs"
（可选）如需完整备份，例如用于整机迁移场景，可额外备份 TapData 工作目录，示例命令如下：
```
# 替换 <tapdata_work_dir> 为实际工作目录
tar -czf /backup/tapdata_work_$(date +%F).tar.gz <tapdata_work_dir>
```

启动服务，高可用部署时，请在每台节点上依次执行。

# 替换 <tapdata_work_dir> 为实际工作目录
./tapdata start --workDir <tapdata_work_dir>

恢复/回滚流程

停止服务，高可用部署时，请在每台节点上依次执行。
```
./tapdata stop -f
```
使用 mongorestore 导入元数据，如目标库已存在数据，建议先手动清理或重命名，避免与导入数据冲突。
```
mongorestore --uri "mongodb://<username>:<password>@<mongodb_host>:<mongodb_port>/<database_name>?authSource=admin" <backup_dir>/<database_name>
```
- <username>、<password>：MongoDB 实例的用户名及密码。
- <mongodb_host>、<mongodb_port>：MongoDB 实例地址及端口（默认 27017）。
- <database_name>：数据库名（默认 tapdata，如自定义请以实际为准）。
- <backup_dir>：备份文件存放的目录（即 mongodump -o 指定的输出目录）。

启动服务，高可用部署时，请在每台节点上依次执行。

# 替换 <tapdata_work_dir> 为实际工作目录
./tapdata start --workDir <tapdata_work_dir>

提示

如果是整机迁移进行数据恢复的场景，需要在启动服务前，恢复 TapData 工作目录至新服务器上。

如何执行滚动升级？

从 3.3.0 版本开始，TapData 支持滚动升级功能，相较于普通的停机升级方式，可帮助您缩短升级时间窗口，进一步降低业务影响，具体步骤如下：

提示

升级前后两个版本相兼容，同时推荐任务进入增量阶段或在业务低峰期执行。
升级 TapData 服务前，推荐通过 mongodump 命令或其他方式，对 TapData 依赖的元数据库进行备份。

登录 TapData 所属的服务器，保持原版本的 TapData 服务处于运行中。
下载并解压 3.3.0 版本安装包，然后进入安装包目录中。
执行下述格式的命令，完成滚动升级流程，升级完成后将提示： Update finished. All Task are running.。
```
./tapdata upgrade --source <old_version_path>
```
old_version_path：老版本 TapData 所安装的目录，示例如下：
```
./tapdata upgrade --source /root/320/tapdata/
```
提示
如果升级过程中遇到错误后，再次执行升级命令，可以接续上次升级过程，如需重置升级状态命令，可执行./tapdata upgrade reset。
升级完毕后，登录 TapData 平台，单击右上角的用户名并选择系统版本确认已升级成功。
在 TapData 平台左侧导航栏，选择系统管理 > 集群管理，确认服务都已正常运行。

如何扩容 TapData 集群？

当现有集群面临性能瓶颈、资源使用接近上限或需要提高系统容错能力和高可用性时，可对集群进行扩容操作，具体操作流程如下：

完成新机器的环境初始化。

登录至服务器，依次执行下述命令完成文件访问数、防火墙等系统参数设置。

ulimit -n 1024000 
echo "* soft nofile 1024000" >> /etc/security/limits.conf 
echo "* hard nofile 1024000" >> /etc/security/limits.conf 
systemctl disable firewalld.service 
systemctl stop firewalld.service 
setenforce 0 
sed -i "s/enforcing/disabled/g" /etc/selinux/config 

安装 Java 17 版本。
```
yum -y install java-17-openjdk
```

设置系统时间。

# 方式一：use ntpdate
# nptdate -u cn.ntp.org.cn
crontab -e 
# 最后一行添加
* */1 * * * ntpdate -u ntp1.aliyun.com

# 方式二：date -s 指定
date -s '10:34:06'

# 系统时间同步到硬件，防止系统重启后时间被还原
hwclock -w

下载 TapData 安装包（可联系我们获取），将其上传至待部署的设备中。
在待部署的设备上，执行下述格式的命令，解压安装包并进入解压后的路径。
```
tar -zxvf 安装包名&&cd tapdata
```
例如：tar -zxvf tapdata-release-v2.14.tar.gz&&cd tapdata
在待部署的设备上，完成扩容操作。
1. 复制集群已有节点中，TapData 工作目录下的 application.yml 文件至待部署设备中的 TapData 工作目录，然后注释或删除该文件中的 uuid 所在行。
2. 上传 License 文件至 TapData 工作目录。
3. 启动并扩容所需的服务。
```
# 扩容 TapData 管理服务
./tapdata start frontend

# 扩容 TapData API 服务
./tapdata start apiserver

# 扩容 TapData 引擎服务
./tapdata start backend
```
启动成功后，可登录 TapData 平台，在系统管理 > 集群管理中查看各服务的状态。

TapData 依赖的 MongoDB 数据库如何保障高可用？

避免使用单节点架构，可采用副本集部署架构来保障高可用，例如采用三节点的副本集架构时，其中一个节点作为 Primary 节点，其他节点作为 Secondary 节点。

提示

如果已采用单节点架构，您可以将其转换为副本集架构。

在副本集中，写入 Primary 节点的数据会自动同步至 Secondary 节点上，当 Primary 节点故障或不可用时，副本集会自动选举一个新的 Primary 节点，从而保证数据库的可用性和数据的完整性，最大程度地减少数据库出现故障的时间和影响。

您可以登录 MongoDB 数据库，通过 rs.status() 命令查看副本集状态和各节点的状态信息。更多介绍，见 Replication。

如何查看运行日志？

在 2.15 之前版本，日志分散存放在 TapData 安装目录中的各文件夹中，从 2.15 版本开始，日志信息集中存放在安装目录下的 logs 目录中。

TapData 配置文件存放位置？

TapData 配置文件：application.yml 存放在 TapData 的按照目录中，它保存了关键配置信息，例如可用内存配置、服务端口、MongoDB 数据库连接信息等。

如何调整 Java 可用的内存大小？

默认情况下，可用的内存为 4 GB，如需调整，可前往 TapData 安装目录下的配置文件 application.yml，编辑该文件，根据服务器的可用内存和任务负载调整内存配置信息，例如配置为 tapdataJavaOpts: "-Xms8G -Xmx16G"，即表示初始内存 8G，最大内存 16G，示例如下：

tapdata:
    cloud:
        accessCode: ""
        retryTime: '3'
        baseURLs: ""
    mode: cluster
    conf:
        tapdataPort: '3030'
        backendUrl: 'http://127.0.0.1:3030/api/'
        apiServerPort: '3080'
        apiServerErrorCode: 'true'
        tapdataJavaOpts: ""
        SCRIPT_DIR: etc
        reportInterval: 20000
        uuid: 093288a0-9ab9-4752-bd1c-7163aea4a7ba
        Decimal128ToNumber: 'false'
        tapdataTMJavaOpts: '-Xmx8G -Xms16G'

提示

如果内存分配较小，但任务负载较多，Java 程序可能因可用内存不足而不停地执行垃圾回收操作，引起 CPU 使用率激增。

管理端子进程不停重启，如何排查？

检查作为 TapData 存储引擎的 MongoDB 是否可以正常连接，且版本需为 4.0 及以上。
执行 ./tapdata restart frontend，随后可以在 logs 目录中找到 frontendDebug.log 文件并查看，通过日志的报错信息分析具体原因。

任务调度的规则是什么？

TapData 提供多层次的任务调度机制，包括默认的基于任务数量的调度策略、灵活的 Flow Engine（流引擎）分组调度，以及基于标签的启动优先级控制。这些机制确保任务高效、均衡地运行在合适的 Flow Engine 上，避免资源浪费和单点过载。

使用建议：日常场景优先使用基础调度机制，简单高效；对性能或隔离有要求的任务，推荐启用 Flow Engine 分组调度；大批量启动任务时，利用标签控制顺序，避免重要任务被阻塞。

基础调度机制（默认）

系统默认采用基于任务数量的均衡策略，自动将任务分配到最优 Flow Engine：

启动调度：任务启动时，系统查询所有存活 Flow Engine 的当前运行任务数量，优先调度到任务数量最少的 Flow Engine。
故障转移：Flow Engine 心跳超时或任务接管失败时，立即触发重新调度，将受影响任务转移到当前任务数量最少的存活 Flow Engine。

此机制适用于大多数场景，无需额外配置，即可实现高效资源利用。

Flow Engine 分组调度

为满足不同业务对性能、隔离或专用资源的需求，TapData 支持 Flow Engine 分组调度。

配置步骤：
进入集群管理页面，切换到组件视图，根据机器性能、业务线等维度创建分组（如“高性能组”或“业务A专用组”），并将相应 Flow Engine 加入。

调度规则：

在创建连接或任务时，可选择特定分组进行调度。
系统仅在选定分组内的 Flow Engine 中调度任务。
分组内仍遵循任务数均衡原则（优先选择任务数量最少的 Flow Engine）。
如果分组内所有 Flow Engine 不可用，任务进入等待状态，并触发告警通知，便于管理员及时介入。

任务标签调度

任务标签主要用于分类管理和批量操作场景下的启动顺序控制。

配置步骤：
在任务管理页面，为任务设置标签（优先级范围 P1~P6）。

调度规则：

优先级范围：P1 ~ P6，数字越小，优先级越高，启动顺序越靠前。
批量启动多个任务时：系统按标签优先级从高到低依次执行。
无标签任务：按选中顺序依次启动，如同时多选多个无标签任务，系统会并发启动这些任务。

提示

标签调度仅控制任务的启动顺序，不影响运行时的 Flow Engine 分配。
批量启动时，TapData 在下发启动指令后即视为“已启动”，不会等待任务状态变为“运行中”。

TapData 如何实现高可用？

您可以在多台机器上部署 TapData 以实现高可用，某个节点出现异常时，其余节点可继续提供服务，进入增量的任务会断点续传，任务可自动均衡调度分配。

TapData 所依赖的 MongoDB 库异常，如何排查？

MongoDB 数据库异常可能有多种不同的原因，通常的排查流程如下：

检查硬件资源，例如 CPU、内存、磁盘空间，如果资源不足或者磁盘空间已经用尽，可能会导致数据库异常。
检查 MongoDB 日志文件，尤其是最近几次启动的日志文件。日志文件通常会记录警告、错误、异常等信息，这些信息可以帮助确定问题的来源。

您也可以通过 mongo shell 登录上数据库查看，更多介绍，见 getLog。
登录上 MongoDB 数据，执行 db.serverStatus() 命令查看当前数据库的状态及统计信息，分析是否存在性能等问题。更多介绍，见 serverStatus。
尝试使用 MongoDB 自带的工具进行故障排查，例如使用 mongotop 命令查看各个集合的读写操作情况，使用 mongostat 命令查看服务器的活动状态。

TapData 所依赖的 MongoDB 库中，库名是什么，集合有哪些？

采用的数据库名称为 tapdata，您可以通过 mongo shell 登录上数据库查看具体包含的集合，示例如下：

# 进入 tapdata 数据库
use tapdata;

# 查看当前数据库中有哪些集合
show collections;

# 查看指定集合中的数据
db.ClusterState.find();

主要关注的集合如下，随着版本更新，可能会有所变化：

ClusterState: 集群状态信息
ClusterStateLog: 集群状态日志
Connections: 连接源属性信息
DatabaseTypes: 支持的数据源类型(字典数据)
DataCatalog: 数据目录信息
DataFlows: 任务属性状态信息
DataFlowStage: 任务属性阶段信息
DeleteCaches: 缓存的删除数据
Events: 任务执行的通知事件
Jobs: 任务执行过程信息
LineageGraph: 数据地图
Logs: 日志信息
Message: 消息
MessageQueue: 消息队列
MetadataDefinition: 元数据定义
MetadataInstances: 元数据信息
Modules: 数据发布 - API 发布信息
nodeConfig: 自定义节点配置信息
Permission: 权限信息(字典数据)
Role: 角色
RoleMapping: 角色有那些权限
ScheduleTasks: 任务调度信息
Settings: 系统设置信息
User: 用户信息
UserLogs: 用户操作信息
Workers: 进程信息
License: License 信息
TypeMappings: 类型映射

如何确认告警邮件是否发送成功

TapData 支持通过 SMTP 协议发送告警邮件，帮助用户及时了解运行异常，保障任务的稳定运行。

在实际使用中，如果接收端用户反馈未收到告警邮件，作为管理员可以通过以下步骤排查邮件发送情况：

登录 TapData 所依赖的 MongoDB 数据库。
进入 tapdata 数据库，执行以下命令：
```
db.Events.find().sort({_id: -1})
```
此命令将按时间倒序查看最新的告警事件记录。
分析关键字段：
- 如果记录中包含 successful，表示邮件已发送成功。
- 如果记录中包含 failed，表示邮件发送失败，此时可以查看 fail_message 字段的值，分析具体失败原因。

哪些是高危操作？

通过仔细审查系统高危操作，及时发现和应对潜在威胁，确保系统操作上的数据安全、完整性和可用性。深入理解各项高危操作，有助于建立可靠的平台管理制度、权限管理制度，提高对系统各种安全挑战的识别能力，从而为企业的数据处理流程、平台管理规范奠定基础。

常见的高危操作如下：

连接管理
- 删除数据源连接：如果有任务使用到此数据源，为避免误删除，当执行删除操作会提示该连接被任务引用。
- 编辑数据源连接：如果数据源的参数设置不正确可能导致该连接失效，正在引用该数据源的任务会使用之前的参数而不受影响，但是新任务或将任务重置后可能引发报错。
数据复制/数据转换任务
- 重置任务：该操作会将任务重置为初始状态，清空历史监控数据，后续启动任务时需要重新执行全量数据同步。
- 数据重复处理策略：在目标节点的设置中，设置不同的数据重复策略会影响目标表的结构和数据，例如选中清除目标端原有表结构和数据，在任务启动后，TapData 将清除目标端的表结构和所有数据，同步源端新的表结构和数据。
- 设置数据写入策略：在目标节点高级设置中，如选择为追加写入，Tapdata 将仅处理插入事件，丢弃更新和删除事件，请基于业务需求谨慎选择，避免带来数据不一致的风险。
- 设置同步索引：当数据复制任务用于仅同步增量数据的场景中，即保留目标表数据，如果目标表的数据规模较大，同步索引操作可能会影响目标库的整体性能。
- 设置更新条件字段：如果目标没有索引，会按照更新条件字段创建索引。
- 任务 Agent 设置：在右上角的任务设置中，如果手动指定 Agent ，后续任务如果是复制此任务时此配置项会保持不变，可能造成单个 Agent 的压力过大，推荐设置为平台自动分配。
数据服务
- 删除或者下线 API，将导致该 API 不可用。
系统管理
- 在管理集群时，应仅在服务出现异常时，才对相关服务执行关闭或重启操作。

任务发生异常，如何排查？

当任务发生异常时，可通过以下步骤进行排查：

如果无法登录 TapData 平台，可在其所属机器上执行 ./tapdata status，查看服务是否正常运行。

./tapdata status
 _______       _____  _____       _______
|__   __|/\   |  __ \|  __ \   /\|__   __|/\    
   | |  /  \  | |__) | |  | | /  \  | |  /  \   
   | | / /\ \ |  ___/| |  | |/ /\ \ | | / /\ \  
   | |/ ____ \| |    | |__| / ____ \| |/ ____ \ 
   |_/_/    \_\_|    |_____/_/    \_\_/_/    \_\ 

WORK DIR:/root/tapdata
Tapdata was stopped.
Tapdata Engine PID:
Tapdata Management PID:
API Server Controller PID:
API Server Instances PID:

如上述示例所示，服务处于停止状态，此时可执行 ./tapdata start 启动相关服务。

如何进行 TapData 健康检查？​

如何启停服务？​

如何备份/恢复 TapData？​

如何执行滚动升级？​

如何扩容 TapData 集群？​

TapData 依赖的 MongoDB 数据库如何保障高可用？​

如何查看运行日志？​

TapData 配置文件存放位置？​

如何调整 Java 可用的内存大小？​

管理端子进程不停重启，如何排查？​

任务调度的规则是什么？​

基础调度机制（默认）​

Flow Engine 分组调度​

任务标签调度​

TapData 如何实现高可用？​

TapData 所依赖的 MongoDB 库异常，如何排查？​

TapData 所依赖的 MongoDB 库中，库名是什么，集合有哪些？​

如何确认告警邮件是否发送成功​

哪些是高危操作？​

任务发生异常，如何排查？​