# data-scheduling-platform

**Repository Path**: hwxus/data-scheduling-platform

## Basic Information

- **Project Name**: data-scheduling-platform
- **Description**: 基于 Apache SeaTunnel 2.3.13 的表级全量/增量同步图形化调度平台（本地单机部署），支持 PostgreSQL / MySQL / Oracle / MongoDB 四库任意组合互同步，提供任务配置、调度、监控、对账的完整工作流。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 2
- **Created**: 2026-08-12
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: WorkBuddy, Python, FastAPI, Postgresql, seatunnel

## README

# 数据库同步 GUI 调度平台

基于 **Apache SeaTunnel 2.3.13** 的表级全量/增量同步图形化调度平台（本地单机部署），支持 PostgreSQL / MySQL / MariaDB / 达梦 DM8 / MongoDB / Redis / Easysearch（Elasticsearch 兼容）以及 **Oracle（待适配）** 八库组合同步，提供任务配置、调度、监控、对账的完整工作流。

## 功能特性

- **八库互通**：PG / MySQL / MariaDB / Oracle / 达梦 DM8 / MongoDB / Redis / Easysearch 之间的表级同步，全量 + 增量（CDC）全覆盖（Oracle 待适配，Easysearch / 达梦 仅全量）
- **整库同步（v0.15，范围 v0.25 收窄为「同库型」）**：单任务一键同步源库全部表（支持表名关键字过滤），运行时动态发现表清单、单作业多表并行抽取写入，目标表由引擎按源结构自动创建（达梦目标由平台逐表预建）；**仅支持同库型之间**（source.type == target.type，如 PG→PG、达梦→达梦，不区分版本），支持 PG/MySQL/MariaDB/达梦 关系型同库型库对库（全量 + insert/overwrite；Oracle 待适配）
- **增量 CDC**：PostgreSQL 逻辑复制、MySQL/MariaDB Debezium、MongoDB ChangeStream，含断点续传（Savepoint）；Oracle 待适配；Redis / Easysearch / 达梦 仅全量（达梦 2.3.13 无 CDC 源连接器，增量仅 timestamp 轮询降级）
- **CDC 管理**：作业暂停（保留位点）→ 恢复（无丢失无重复续跑）→ 终止，以及 DDL 变更流程；列表新增「位点」列——源库实时位点由后端后台循环（`position_fetcher.position_refresh_loop`，v0.51）周期性采集写库，列表直读元数据，**该列在 v0.51 之前恒为空**；**资源回收语义（v0.51 T68）**：硬终止/删除时统一清理 PG 复制槽与 SeaTunnel savepoint，优雅暂停（paused）则两者全保留以便恢复
- **可视化编排**：四步向导创建任务（源/目标/字段映射/模式参数），字段同名自动匹配；MongoDB 嵌套结构展平预览；源表 WHERE 条件过滤；任务名称根据源/目标类型简称自动生成；字段映射表新增「目标类型」列（v0.57），仅时间类源列（`timestamp`/`datetime`/`date`/`time`）可显式指定原生 `TIMESTAMP`/`DATE`/`TIME` 类型，消除 MySQL 源时间列默认落 TEXT 且带 `+08` 时区后缀的残留
- **自动建表**：内置类型映射矩阵，目标表不存在时按字段映射自动生成 DDL 建表（与数据同步解耦，幂等）；`overwrite` 重跑结果不叠加；**v0.49 结构同步完善**：字段注释/默认值可随结构同步（`sync_comments` / `sync_defaults` 开关）、二级索引默认不建（运行弹窗勾选才建）、源表主键继承为目标主键（跨库主键/索引列名按库规则折叠大小写）、跨库默认值安全透传（时间函数默认值仅落原生时间列，规避 MySQL 1067）
- **任务管理**（已完成 v0.42，将原「同步任务」与「调度管理」合并）：四步向导创建任务；**调度下沉为任务属性**——行操作「配置调度」直接配 Cron 定时（支持秒级）、失败重试次数/间隔、超时、启用开关，弹窗内实时显示 Cron 中文释义；列表默认展示「任务名称 / 源 / 目标 / 模式 / 写入 / 状态 / 执行状态 / 更新时间」等 11 列（默认列可整体经「列设置」调整；「调度类型 / Cron 表达式 / 下次执行 / 调度状态」四列**默认隐藏**，避免手动任务场景空列占宽）与调度筛选；列表「最新执行」按 `start_time DESC` 精确取最新（v0.51 修复原 `max(id)` 非时间序取错的问题），累计写入经 30s TTL 缓存并依托 `idx_exec_task_start` 复合索引；任务列表**批量运行限并发提交（并发 4、单次上限 10 个，v0.21）**，防止大批量同步写库误操作
- **实时监控**：执行状态与指标由前端轮询实时刷新（HTTP REST，无 WebSocket 长连接）；运行中任务的实时写入行数由引擎指标提供——v0.51 修复读取端点（`job-metrics` 对流式作业恒返回 204 空 → 改用 `job-info` 顶层 `metrics`），此前 running 行的进度长期取不到值
- **执行历史**：指标、增量位点、对账结果，成功/失败均可查看引擎执行日志（UTF-8/GBK 容错解码，**v0.51 起默认全量返回**，不再默认只取尾部 800 行，「复制日志」复制全部内容）；日志无 jobId 匹配时按执行时间窗口回退；列表显示源→目标数据源名称；**按筛选条件导出 CSV/Markdown 报告（含指标与对账，2026-08-22 T7）**
- **数据对账**：全量同步完成后自动源/目标行数校验（PG/MySQL/MongoDB，按 WHERE 口径）
- **数据质量（v0.53 落地，v0.54 Phase 3 闭环）**：新增「**质量体检**」独立模块——SQL 直查采样 + 元库阈值规则 + 复用既有通知渠道，覆盖**表级体检 / 字段级规则 / 项目级跨表一致性**，内置 **12 条只读校验规则**（行存在性/行数下限/空值率/主键空值/主键重复/唯一性/数值区间/枚举集中度/时效新鲜度/跨表外键一致性/长度合规/枚举白名单），按**完整性 / 准确性 / 一致性 / 及时性四维加权（30/30/20/20）**输出综合分与分级（PASS≥90 / WARN 80–89 / FAIL<80），前端「质量看板」含四维条形图与趋势折线；独立 `/quality/*` API 与 `etl.tb_quality_*` 六表，不占引擎资源池、不侵入既有同步链路（方案见本地 `docs/in/数据质量模块设计方案.md`）；**v0.54 Phase 3 闭环**：质量告警按实例**聚合成一条**经 Webhook（企业微信 / 钉钉 / 飞书）外发（新增「质量体检告警」开关）、质量任务 Cron **定时调度真正生效**（新增前端配置入口）、单实例**报告导出**（CSV 明细平表 / Markdown 报告，前端两处入口），并修订评分语义——**执行异常（ERROR）不再与不达标（FAIL）同记 0 分**（现与「跳过」等价、不参与评分，避免瞬时故障误判）；**仪表盘已集成质量体检核心指标**（v0.55，主仪表盘右栏「质量体检」卡片：最新体检的综合分/分级、四维分值、通过/警告/不达标/执行异常计数与 ⚠ 执行异常维度提示，独立取数、失败静默降级）；**v0.55 支持自定义规则**——管理员可创建自定义 SQL 模板的质检规则（SQL 安全校验：禁止危险关键字/分号/注释，仅允许 SELECT），内置规则不可修改/删除
- **数据源管理**：八库 CRUD（含 Easysearch/Elasticsearch/达梦 DM8），新建必须先通过连接测试（v0.3），密码 AES-GCM 加密存储；新建时名称自动生成（类型_主机_端口/库名，MongoDB 从 uri 提取主机、Oracle 用 service_name、达梦用用户/schema 名）；列表显示类型色点、连接信息（MongoDB 展示脱敏 uri）、连通性状态；多选筛选
- **文件导入导出**：Excel 导入（解析/类型推断/自动建表/写入）与导出（v0.5），支持 PG/MySQL/MariaDB/MongoDB/Redis/达梦 DM8（Easysearch 暂不支持）
- **通知告警**：**Webhook 告警**（企业微信/钉钉/飞书/自定义）单通道（邮件 SMTP 通道已于 v0.18 下线），任务失败 / 对账 diff / CDC 异常 / 质量体检不达标触发；失败任务的**桌面/Windows 通知**由前端轮询执行状态触发浏览器 Notification（需在设置页授权）；**告警抑制（v0.61）**——按「事件类型 + 任务」指纹冷却（默认 1800s 可配）去重，失败执行标记「已处理 / 忽略」后对该任务**持续静默直到恢复**，恢复时发「已恢复」通知并自动解除；**任务级失败自动暂停（v0.61，默认关闭）**——按调度周期统计连续失败，达阈值自动停用任务并记录原因（手动运行不计入、CDC 排除）
- **用户管理**：管理员专属，批量录入/重置密码/启停/角色（保护规则：不能删自己、至少保留一名管理员）
- **列表体验增强（v0.17）**：所有列表表格**表头居中**；时间字段**全局支持排序**，整表默认按「更新时间倒序」排列（无更新时间则取结束时间 > 创建时间兜底），后端经通用 `apply_sort` 辅助 + `sort_by`/`order` 参数实现；执行历史 / CDC / 调度 / 同步任务 / 数据源 五个重表新增「**列设置**」面板，可勾选显隐字段（localStorage 按表持久化），默认展示精简字段集、序号/选择/任务（执行ID）/操作 等关键列锁定常显
- **性能**：并行分片 + 批量读写，100 万行全量同步约 33s（3 万行/s）；PG→MySQL 约 4 万行/s，PG→MariaDB 约 4.1~4.8 万行/s（2026-08-22），MariaDB→PG CDC 增量约 9.3 千行/s；MongoDB sink 调优后（`bulk.size=2000`）约 1.3 万行/s（2026-08-22，较调优前 +75%）；**页面/列表加载（v0.51 T67）**：任务管理列表累计写入聚合 108ms→30.5ms（30s TTL 缓存 + `idx_exec_task_start` 复合索引）、仪表盘统计 15s 进程内 TTL 缓存、执行历史引擎指标缓存 5s→10s 与前端轮询节奏对齐、全屏遮罩收敛为内容区局部 loading（含 8s 超时兜底）；**列表关键字模糊搜索（v0.52）**：`tasks` / `datasources` / `users` / `files` 的 `ILIKE '%kw%'` 改走 pg_trgm GIN 索引（共 5 条），避免全表扫描
- **元数据缓存（v0.21）**：表浏览/取字段接口进程内 60s TTL 缓存，降低向导与运行预处理重复查询成本；数据源更新/删除、建表、补列等 DDL 后主动失效；MongoDB 字段采样与整库动态发现不走缓存（详见本地 `docs/in/T5-元数据缓存方案.md`）
- **已实测链路**：PG→PG/PG→MongoDB/PG→MySQL 全量、MySQL→PG CDC（含 Savepoint 暂停恢复）、MongoDB→PG/MariaDB 全量（754 条幂等重跑）、Redis→MariaDB 全量、MongoDB→Redis（754 条含中文，2026-08-17 引擎 UTF-8 修复后）、**PG→PG 整库同步（whole-db，跨库自动建 schema + 20 万行 2 表幂等重跑，2026-08-21）**、**达梦 DM8 全量双向（PG↔DM insert/upsert/overwrite，2026-09-02 端到端 5/5）**、**PG→MariaDB 全量三档（100 万行，41k~48k 行/s，2026-08-22）+ MariaDB→PG CDC 增量（binlog ROW，50 万行 9.3k 行/s，2026-08-22）**、**Easysearch→PG 全量（HTTPS+basic auth，3 文档端到端，2026-08-23）**、**DM→PG 全量（2026-09-08，v0.49：修复源列探查误传密文、PG 目标列名小写归一、目标表主键同步后打通）**、**DM→DM 整库 overwrite（v0.50.1：修复 sink 缺 query 缺陷，N3b 达梦侧实跑幂等，3 表 3/2/2 全对账）**、**MySQL→MySQL 整库 overwrite（v0.50.1：二阶幂等验证，引擎 DROP_DATA 正常生效，7 行不叠加）**、**完整四库矩阵（PG→DM / PG→MySQL / PG→Mongo / PG→PG）全绿（2026-09-09 v0.50.1 回归）**

## 已知限制与能力校验（SeaTunnel 2.3.13 实测，2026-08-18 / 2026-08-22 / 2026-09-12 更新）

平台在**任务创建/编辑/运行前**统一拦截并给出明确提示（`validate_sync_capabilities`），避免同步运行时才报错：

| 限制 | 引擎原因 | 平台行为 |
|------|----------|----------|
| MariaDB 目标 `upsert` | ~~2.3.13 无 MariaDB 方言~~ **已解决（2026-08-22）**：job_builder 对 MariaDB 改用 MySQL 官方驱动 + `jdbc:mysql://` URL 走 MySQLDialect（MariaDB 协议兼容），`ON DUPLICATE KEY` 实测可用 | **拦截已解除（T15-①）**，向导可选 upsert（需指定主键）；实测 1000 行重跑幂等 + 更新生效 |
| MariaDB 目标 `overwrite` | MySQL 方言 SaveMode 版本解析拒绝 MariaDB 版本串（DROP_DATA 失败） | 提交前平台主动清空目标表（TRUNCATE，失败回退 DELETE）+ sink 走 APPEND_DATA，保证幂等 |
| MariaDB 目标自动建表（平台 DDL 方言） | 无（引擎无关）——平台自身 `generate_ddl` 方言分支漏判 mariadb，误发 PG 专属 `COMMENT ON TABLE` 语法 | **已修复（v0.42）**：方言分支统一 `in ("mysql","mariadb")` + 预览/实建共用 `build_target_ddl_for_task` + `_assert_dialect_safe` fail-fast 拦截错方言语法（案例 `pg2mariadb_tb_api_access_log`） |
| MariaDB 源 CDC | MySQL-CDC 初始化解析 GTID 时，MariaDB `0-1-N` 格式 `GtidSet` 解析必炸 | 前置：`RESET MASTER` 清空 GTID 后启动任务（**任务启动后不得重启**）；binlog 需开启 ROW 格式（配置须置于 my.ini `[mysqld]` 段） |
| MySQL 源/目标（非标准版本串，如 26.7.0） | 2.3.13 `MySqlVersion.parse` 仅识别已知版本号，MySqlCatalog 对未知版本抛 `UnsupportedOperationException` 后**自动回退 V_5_7 方言**（作业 INFO 日志含堆栈，非阻断；2026-08-26 实测 MySQL 26.7.0） | 无需处理：自动建表 DDL、upsert（ON DUPLICATE KEY）、全量（100 万行）、CDC I/U/D（GTID=ON）均实测正常；MySQL/MariaDB 源 CDC 运行前 binlog 预检（T42）会在配置不合规时给出修正 SQL |
| PG 源 CDC（2026-08-25 实测打通 PG→PG 跨库） | ① 源表须 `REPLICA IDENTITY FULL` 否则 UPDATE/DELETE 无法捕获；② 引擎不支持 `timestamptz` 反序列化（TIMESTAMP_TZ Unsupported） | `REPLICA IDENTITY` 不合规：平台运行前预检（T38）**直接拦截**并给修正 SQL；`timestamptz` 列：平台运行前预检（T38/T44）改为**软告警兜底（不阻断提交）**，任务仍可运行，运行期若引擎报 TIMESTAMP_TZ Unsupported 再提示，建议表结构改用 `timestamp`；CDC 停止后平台自动清理 `seatunnel_<task>` 复制槽与 `dbz_publication`（T39，防 WAL 涨盘），无需手动清理 |
| Oracle 源/目标（全量 + CDC，**待适配**） | SeaTunnel Oracle-CDC 基于 Debezium+LogMiner，需 DBA 前置（`ARCHIVELOG` 归档 + 最小补充日志 + LogMiner 权限账号） | 平台侧适配代码与运行前预检（T43）保留，实例级验证待本机 Oracle + `ojdbc8.jar` 就绪后执行（恢复清单 D1/D3/D4）；受限时可降级 timestamp 轮询 |
| MongoDB 源 CDC（ChangeStream，2026-08-25 实测打通 Mongo→PG） | ① standalone 不支持 ChangeStream，需单节点 replica set；② 非 `_id` 数值字段经 sink 序列化为 BSON 包装串（如 `{"_value":{"$numberInt":"1"}}`），与 `_id` 包裹同根因 | 前置：mongod 启用 `replication.replSetName: rs0` 并 `rs.initiate()`；数值字段落关系型目标此前建议存字符串——平台现已自动 CAST 兜底（T40），无需存字符串 |
| 嵌套字段展平映射（`a.b`→`a_b`） | MongoDB 源将嵌套文档读为 row 类型，需 `sql` transform 以 `address.city` 取子字段展平 | **已解决（T16-①）**：MongoDB 源 + 关系型目标（全量）经 `sql` transform 展平并重命名，本机实测可用（2026-08-22）；关系型源 / Mongo→Mongo 等组合仍运行前拦截 |
| 字段重命名（target≠source） | generate_sink_sql 按目标列名生成 INSERT，源字段名不匹配 | **已解决（T16-②）**：全量 + 关系型目标（非 Redis）经 FieldMapper transform 改写列名，本机实测可用（2026-08-22） |
| 目标表缺列（旧表结构不匹配） | INSERT 引用不存在列 | **已解决（T16-③）**：运行前/上报前平台主动 `ALTER ADD COLUMN` 补齐，本机实测可用（2026-08-22） |
| Redis / Easysearch 源或目标增量/CDC | Redis 无日志/时间戳能力，Easysearch 无 binlog/changeStream | 创建/编辑时拦截，仅支持全量 |
| 达梦 DM8（全量 + 关系型目标） | ① 引擎 2.3.13 无 Dameng-CDC 源连接器，增量仅 timestamp 轮询降级；② overwrite 时引擎 DROP_DATA 为空操作（catalog 查不到表→跳过清空）；③ 引擎 catalog 无自动建表能力，整库目标需平台逐表预建；④ catalog 建表不可用，表名须归一大写（`database` 字段 = schema）；⑤ **generate_sink_sql=True 时引擎生成 `MERGE INTO USING (SELECT ? "col"...`，达梦 JDBC 不支持 `? "column"` 语法（报错 -2007）；⑥ generate_sink_sql=False 时引擎 catalog 发现表走 JDBC DatabaseMetaData，Dameng 驱动该 API 有缺陷（直接 SQL 查 ALL_TABLES 正常，但 DatabaseMetaData 返回空）；⑦ **generate_sink_sql=False + query 后，SinkWriteCount>0 / SinkCommittedCount=0，真因：平台 query 列名随源小写，但达梦 CASE_SENSITIVE=1 目标表大写列 NOT NULL，小写列可空，导致大写列落空触约束**；⑧ Dameng 表存在大小写重复列（历史遗留问题，导致 getTable 返回列数翻倍）** | ① 创建/编辑期拦截 cdc-initial/cdc-latest，仅 timestamp 放行；② overwrite 提交前平台 TRUNCATE 兜底 + sink APPEND_DATA，重跑幂等；③ 整库（同库型 DM→DM）目标由平台逐表 `generate_ddl` 预建 + TRUNCATE；④ 达梦目标统一 `schema_save_mode=IGNORE`，由平台 dmAsync 预建大写表；⑤ **平台侧对 dameng 强制设置 generate_sink_sql=False**；⑥ **源码修改 `DamengCatalog.getTable()`（JOIN USER_INDEXES 修复），JAR 已部署（2026-09-07）**；⑦ **已修复（2026-09-07）**：平台 query 列名统一大写 `f'"{c.upper()}"'`；⑧ **已修复（2026-09-07）**：`SELECT_COLUMNS_SQL` 去重子查询过滤小写重复列；⑨ **DM 作为 source 时（v0.49）**：SeaTunnel 2.3.13 `JdbcSource` 初始化会经 `DamengCatalog.open()` 额外开 JDBC 会话探测表结构，该会话报「登录失败次数超过限制」触发 API-06 `Unable to create a source for identifier 'Jdbc'`——平台改为走 `_dameng_source_select_exprs` 直接构建 SELECT 表达式绕过 catalog 探测（与源列类型探查改用 `DataSourceConn.password` 明文配套修复） |
| 跨库时间列默认值（v0.49） | 平台 type_mapper 默认把各源时间列统一折叠为 **TEXT**（存 ISO 字符串规避精度丢失），若把源列时间函数默认值（`now()` / `CURRENT_TIMESTAMP`）原样拼进 TEXT 目标列，MySQL 会报 1067 `Invalid default value` | **已修复（v0.49）**：`_safe_default_expr()` 仅在目标列为**原生时间类型**时才透传时间函数默认值并按目标方言归一（MySQL/MariaDB→`CURRENT_TIMESTAMP`；PG/Oracle/达梦保留），落在非时间目标列一律丢弃；PG cast 语法字面量（`'x'::type`）仅 PG 目标保留 |
| 目标表 `upsert` 的前置条件 | 引擎 JDBC sink 的 upsert 依赖目标表**唯一约束/主键**；无主键表只能 overwrite | 平台建表时同步源表主键（T56）；创建/编辑期对无主键源表 + upsert 组合给出提示 |
| PG 目标 JSON/JSONB/UUID 列（v0.43） | 引擎 2.3.13 JDBC connector 以 varchar 绑定写入，PG 不接受 varchar→jsonb/uuid 隐式转换 | 平台自动将 **PG 目标**的 JSON/JSONB/UUID 列降级为 **TEXT**（与源库型无关，MySQL/MariaDB/MongoDB 源同步到 PG 目标同样生效）；TEXT 存 JSON 字符串，`SELECT`/`json` 访问完全兼容。MySQL/MariaDB 目标暂不降级（驱动行为不同） |
| 整库同步仅限关系型**同库型**（source.type == target.type） | 跨库型（如 PG→MySQL）与 MongoDB/Redis 需逐集合采样字段定义、无统一表清单语义 | 创建/编辑时拦截，提示改用单表模式；整库仅支持全量 + insert/overwrite（无字段映射、无 upsert、对账标记 skipped） |
| 列表关键字模糊搜索依赖 pg_trgm 扩展（v0.52） | 各列表页关键字走 `col ILIKE '%kw%'`（前导通配），B-tree 索引无法命中；改用 trigram GIN 索引提速 | 存量库执行 `backend/sql/migrate_v0.52_pg_trgm_search_indexes.sql`（内含 `CREATE EXTENSION IF NOT EXISTS pg_trgm`，**需 PostgreSQL superuser**）；未安装时功能不受影响、仅退化为全表扫描。新库用 `full.sql` 已自动包含 |
| CDC 资源回收依赖 `SEATUNNEL_HOME` 与状态存储类型（v0.51 T68） | 硬终止/删除 CDC 作业时会清理 PG 复制槽与 SeaTunnel savepoint 目录；savepoint 清理仅对 localfile 状态存储有效 | 需正确配置 `SEATUNNEL_HOME`（默认 Hazelcast IMap 无本地文件，自动跳过并记 WARNING，不影响停止/删除结果）；复制槽清理仅 PG CDC 生效，其它源自动跳过 |

> **排查规范**：碰到同步问题，若有目标表参与，**优先比对目标表实际字段与 SeaTunnel databaseTableSchema 返回的列**。差异在哪，问题就在哪。严禁在未确认目标表结构前猜测 JDBC/Dialect 层问题。

> 数据对账（全量后源/目标行数校验）仅 PG/MySQL/MongoDB 支持；Redis/Oracle 目标自动标记「跳过」。
> 完整记录见 `docs/out/遗留任务排期.md`（T15/T16）。

> 上述为平台能力边界（引擎约束）；运行期故障排查与排错步骤见本地 `docs/in/故障排查FAQ.md`。

## 技术栈

| 层 | 技术 | 说明 |
|----|------|------|
| 前端 | Vue 3 + Element Plus + Pinia + Vue Router | 10 个功能页面 |
| 后端 | Python FastAPI + SQLAlchemy 2 async + APScheduler | 任务编排 / 调度 / 监控 |
| 执行引擎 | Apache SeaTunnel 2.3.13（Zeta） | 全量 JDBC/MongoDB/Redis + 增量 CDC |
| 元数据库 | PostgreSQL | 独立 schema `etl`、`tb_` 前缀 |

## 架构

```
Vue3 前端 (5173)
   │ HTTP REST（前端轮询）
FastAPI 后端 (8000) —— 元数据存储：PostgreSQL(etl schema)
   │ SeaTunnel REST API
SeaTunnel Zeta 引擎 (5801) —— 全量/增量同步执行
```

## 快速开始

**环境要求**：Java 11（SeaTunnel 引擎）、Python 3.12+、Node.js 20+、PostgreSQL 18、SeaTunnel 2.3.13。详细配置见 `docs/out/前置配置指南.md`。

### 首次部署

```bat
:: 1. 初始化元数据库（建库后执行）
psql -U <user> -d <database> -f backend\sql\init.sql

:: 2. 配置后端（复制 .env.example 为 .env，填数据库连接）
copy backend\.env.example backend\.env

:: 3. 安装依赖（使用系统全局 Python / npm，无需虚拟环境）
cd backend && pip install -r requirements.txt
cd ..\frontend && npm install

:: 4. 初始化 SeaTunnel（连接器 / JDBC 驱动 / REST / checkpoint，详见前置配置指南）
```

### 日常启停（一键 bat 脚本）

```bat
:: 一键启动（后端 8000 + 前端 5173，自动打开浏览器；不含 SeaTunnel）
一键启动.bat

:: 一键停止（终止后端与前端两个服务）
一键停止.bat
```

**SeaTunnel 引擎需单独启动**：根目录 `一键启动.bat` 只拉起后端 + 前端；需要连引擎一起拉时用 `scripts\start-all.bat`（按序启动 **引擎 master(5801) → worker(5802) → 后端(8000) → 前端(5173)**）与 `scripts\stop-all.bat`（按同四端口停止）。
> **完整的部署步骤与全部启停脚本说明见 [部署运维手册](docs/out/部署运维手册.md) §二**（含 v0.51 引擎启停脚本固化说明），此处不重复。

访问 `http://127.0.0.1:5173`，默认账号 `admin / admin`（首次登录后请修改密码）。

> **注意**：`一键启动.bat` / `一键停止.bat` 与 `scripts\*.bat` 中硬编码了 Python、SeaTunnel 等安装路径，部署到其他机器需修改脚本内路径。
> **存量库升级**：按序执行 `backend/sql/migrate_*.sql`（自 v0.50.1 起新增 `migrate_v0.51_exec_task_start_index.sql` → `migrate_v0.52_pg_trgm_search_indexes.sql` → `migrate_v0.53_quality.sql` → `migrate_v0.54_quality_alert.sql` → `migrate_v0.56_quality_rule_dimension.sql` → `migrate_v0.61_t57_failover_alert_suppress.sql` → `migrate_v0.62_quality_rule_description.sql`）；**v0.52 建 `pg_trgm` 扩展需 PostgreSQL superuser**（其余新增迁移普通权限即可）。新库直接用 `backend/sql/full.sql`（已含全部）。
> 部署前的完整配置（环境变量、元数据库、SeaTunnel 连接器/驱动/REST/checkpoint、CDC 前置）见 `docs/out/前置配置指南.md`。

## 界面预览

| 仪表盘 | 数据源管理 | 任务管理（含调度配置） |
|:-------|:-----------|:---------|
| ![仪表盘](docs/out/screenshots/demo-dashboard.png) | ![数据源管理](docs/out/screenshots/demo-datasources.png) | ![任务管理](docs/out/screenshots/demo-tasks.png) |

| ~~调度管理~~（已并入任务管理） | ~~运行监控~~（已下线，并入执行历史） | 执行历史 |
|:-------|:-----------|:---------|
| （已并入「任务管理」截图） | （已下线） | ![执行历史](docs/out/screenshots/demo-history.png) |

| CDC 管理 | 文件导入导出 | 用户信息 |
|:-------|:-----------|:---------|
| ![CDC 管理](docs/out/screenshots/demo-cdc.png) | ![文件导入导出](docs/out/screenshots/demo-files.png) | ![用户信息](docs/out/screenshots/demo-users.png) |

| 系统设置 |
|:---------|
| ![系统设置](docs/out/screenshots/demo-settings.png) |

> MongoDB → PostgreSQL 全量同步执行历史（754 条照片元数据，重跑多次幂等）：

> ![MongoDB→PG 全量同步执行历史](docs/out/screenshots/demo-mongodb-to-pg.png)

## 目录结构

```
├── backend/                # FastAPI 后端
│   ├── app/
│   │   ├── api/            # 路由（datasources/tasks/schedules/executions/cdc/files/notifications/users/dashboard/system）
│   │   ├── services/       # 业务服务（含 datasource_adapters 适配器策略包、job_builder、table_service 等）
│   │   ├── core/           # 公共能力（utils/identifier/db_factory/event_notifier/errors/security/timefmt）
│   │   ├── models/ schemas/
│   │   ├── config.py database.py main.py
│   │   └── requirements.txt
│   ├── sql/full.sql        # 元数据库权威全量 DDL（init.sql = \ir 兼容入口）
│   └── tests/              # pytest 单元测试（552 passed / 9 skipped）
├── frontend/               # Vue3 前端（views/ + components/task 子组件 + composables）
├── scripts/                # 一键启停脚本（start-all.bat / stop-all.bat）
├── 一键启动.bat             # 一键启动（仅后端 + 前端；不含 SeaTunnel）
├── 一键停止.bat             # 一键停止
├── docs/out/screenshots/   # 界面截图（README 引用）
└── LICENSE                 # Apache-2.0
```

## 文档导航

公开文档随仓库发布，位于 `docs/out/`，按用途索引如下：

| 类别 | 文档 | 说明 |
|------|------|------|
| 使用 | [使用文档](docs/out/使用文档.md) | 功能操作指南与版本变更 |
| 配置 | [前置配置指南](docs/out/前置配置指南.md) | 部署前环境 / 变量 / 元库 / 引擎配置 |
| 配置 | [配置项参考](docs/out/配置项参考.md) | 全部环境变量与配置项清单 |
| 运维 | [部署运维手册](docs/out/部署运维手册.md) | 生产部署、健康检查、安全加固 |
| 运维 | [发版手册](docs/out/发版手册.md) | 发版流程与回滚 |
| 测试 | [测试指南](docs/out/测试指南.md) | 测试体系与运行方式 |
| 对接 | [接口文档 v0.2](docs/out/接口文档-v0.2.md) | REST API 契约 |
| 协作 | [贡献指南与开发规范](docs/out/贡献指南与开发规范.md) | 分支 / 提交 / 高危操作铁律 |
| 规划 | [遗留任务排期](docs/out/遗留任务排期.md) | 版本规划与遗留项 |
| 检索 | [已知缺陷索引](docs/out/已知缺陷索引.md) | 历史缺陷与已知限制的检索指针表（症状→根因→修复版本） |
| 性能 | [性能报告](docs/out/性能报告.md) | T63 量化（v0.43~v0.52）+ 阶段五压测（附录 A 历史快照） |

> 内部文档（含敏感信息或纯本地记录：技术方案 / 开发指南 / 故障排查 FAQ / 字段类型映射 / 达梦适配系列 / 数据库迁移指南等）保留在 **本地 `docs/in/` 目录，不随仓库公开**，不在上述索引内。

## License

[Apache License 2.0](LICENSE) © 2026 hwxus

本项目的执行引擎基于 [Apache SeaTunnel](https://seatunnel.apache.org)（Apache-2.0）二次开发。