生成可部署程序与通用目标写入器

Generate deployables 可从目录和/或已保存的 Output Target 定义生成可移植运行器。运行器可以保留 CSV/Excel 审计输出，也可以把多个逻辑目标路由到一个物理目标。

DSE 现在使用 Universal Destination Writer Framework（通用目标写入器框架）。当前目录中的每个 Output Target 预设都有可执行的写入路径。DSE 会根据目标技术选择 Native、ODBC、REST/OData、对象存储 SDK、文件或 Gateway 适配器。

“Runtime writer” 表示生成的运行器具备执行该路由的代码，但仍可能依赖外部前提，例如厂商 ODBC 驱动、API 凭据、云权限，或 VSAM/IMS/CICS 所需的已批准网关。

推荐流程

1. 发现/配置数据源并检查目录。
2. 在 Compose targets 中创建或检查映射。
3. 打开 Generate deployables，加入一个或多个已保存目标。
4. 在激活写入之前先配置物理目标。
5. 检查 writer technology、目标对象名称和写入模式。
6. 只有真正需要外部写入时才勾选 Route selected targets to one destination。
7. 测试连接，选择平台/RID，然后生成。
8. 运行后使用 View results，并独立核对目标端记录数量。

逻辑目标与物理目标

Output Target 是逻辑数据契约，不要求与运行时的物理目标使用同一种技术。

例如：

MongoDB + Couchbase + InfluxDB -> PostgreSQL

Oracle + MongoDB + DynamoDB -> Redis

DSE 会保留每个路由行的来源信息和字段映射，避免把不同逻辑目标的数据盲目混合。

先配置，再激活

即使未勾选 routing，目标 preset、写入模式、目标对象名称和类型也应保持可编辑。复选框只控制外部执行，不应锁定路由编辑器。

写入器技术

Destination object routing

Destination object 可直接编辑。名称必须非空、唯一并符合目标平台规则。Object type 会由所选写入器限制，例如 Table、Collection、Hash、Index、Label、Measurement、Bucket 等。

Append 与 Replace

• Append 保留现有数据并加入当前记录。
• Replace 只清理本路由拥有的对象/前缀一次，然后写入当前数据。

出于安全原因，Salesforce、Dynamics 365 CRM、SharePoint、ServiceNow、Workday 和 SAP OData 的直接 API writer 只提供 Append。如果需要破坏性的全对象替换，应通过经过审核、包含业务规则的自定义 gateway 实现。

目标连接

生产环境建议通过运行时注入：

DSX_DESTINATION_CONNECTION_STRING

ODBC 必须明确提供 Driver= 或 DSN=，并在实际运行 deployable 的主机上安装对应驱动。

REST/OData 通常支持 Url=/Endpoint=、Token/AccessToken、Username/Password 或 ApiKey。

VSAM/IMS/CICS/Generic 可使用 Endpoint=https://... 网关或经过批准的 ODBC 路径。

规范化记录模型

运行器会先把源行/文档转换成中立的 DSE canonical record，其中包含稳定 id、来源信息和映射字段；然后目标 adapter 再转换为实际目标格式。因此不需要为每一种“源技术 -> 目标技术”组合单独开发代码。

AI Advisor

在 目标 中使用单选按钮选择一个 AI 推荐项。在 Deployables 中使用所选目标 会将该目标传递给下一次 Generate Deployables。创建目标草稿 现在只创建或刷新所选目标，避免重复累积 AI 草稿。

AI Advisor 可以推荐目标并把路由发送到 Generate Deployables，但不会静默执行外部写入。用户仍需审核 writer technology、目标对象、写入模式、连接和生成包后才能执行。

由于当前所有 preset 都有 writer path，AI 推荐可以保留原始目标技术，只需满足对应的运行时前提。

故障排除

• 无法更改 preset：使用包含 destination dropdown 修复的版本；routing 关闭时不应锁定编辑器。
• ODBC 提示 Driver/DSN：在 deployable 运行主机安装厂商驱动并配置连接串。
• REST 返回 401/403：检查 endpoint、token、tenant/site 和写权限。
• SaaS 没有 Replace：这是有意的安全限制。
• VSAM/IMS/CICS 要求 gateway：配置站点写网关或允许的 ODBC 路径。
• 要求 connection string：设置 DSX_DESTINATION_CONNECTION_STRING。

生产建议

先用较小行数验证，初期优先 Append，把秘密信息放在生成包之外，使用最小权限，采用专用对象/前缀，并在 cutover 前保留审计输出和核对关键计数。

企业级可靠性、数据血缘与安全恢复

生成的 deployable 现在可以在 CSV/Excel 和物理目标路由之外启用企业级可靠性层。

每次运行都会获得唯一的 Run ID，启用后会在 output/audit/<run-id>/ 下生成：

• lineage.jsonl：结构化血缘事件，包含源系统、选择字段、目标路由、目标对象、行数、写入器技术、写入模式、状态和映射指纹；
• run-summary.json：保存在审计目录中的每次运行独立摘要副本，后续运行不会覆盖历史治理记录；
• run-manifest.json：运行级治理摘要，包含源/目标统计、重试、恢复信息和生成文件的 SHA-256；
• integrity.sha256：当前运行摘要、血缘流、manifest 和生成文件的完整性哈希。

血缘工件不会记录连接字符串或凭据。

运行租约与心跳

启用 运行租约和心跳 后，运行器会在状态目录中创建按 schema 隔离的 lease 和 heartbeat。使用相同 schema 和 DSX_STATE_DIR 的第二个运行器，在当前租约释放或超时前不能启动。要实现 active/passive 调度，请让两个节点使用同一个持久化共享状态目录。

常用覆盖参数：DSX_RUN_ID/--run-id、DSX_STATE_DIR/--state-dir、--lease-timeout-seconds、--heartbeat-seconds。

瞬时故障重试

源读取发生瞬时错误时使用有上限的指数退避。只有当目标 writer 声明事务或 Upsert 语义、能够较安全地重放时，DSE 才会自动重试目标写入，从而避免盲目重复非幂等的 Append 请求。

恢复检查点

恢复已完成的目标写入 会记录成功的目标 selection checkpoint。运行失败后再次启动时，可以跳过已经完成的目标写入，同时仍重新生成 CSV/Excel 审计输出。

对于 Replace 路由，恢复功能会被有意禁用，因为新进程可能在重放部分任务之前先清空目标对象。

与生产级 CDC 的区别

这些检查点提高的是重启和重放安全性，并不是基于事务日志的 Change Data Capture（CDC）。当前源读取模式仍然是 Snapshot。生产级 CDC 需要为不同数据源实现专用的日志/变更流读取器和持久化游标，例如 SQL Server CDC LSN、PostgreSQL WAL/逻辑复制、MongoDB resume token、Cosmos Change Feed continuation 和 DynamoDB Streams shard position。

完整路线图请参阅 Docs/Enterprise-Reliability-CDC-Governance-HA-Plan.md。

<!-- DSE_DEPLOYABLE_CERTIFICATION_HELP_V1 -->

20. 生成的 Windows 和 Linux 可部署包认证运行

请在 Generate deployables 完成后使用本节。本节记录生成的 win-x64 和原生 linux-x64 包的认证/运行流程。这些是 DSE 生成的集成运行器，不是 DSE 商业 Windows/Container 安装 SKU。

20.1 Windows 可部署包 (windows/win-x64)

将生成的 Windows 文件夹复制到认证机器（或解压传输的压缩包），然后从 windows\win-x64 目录操作。

首次运行前请确认以下生成文件存在：

• DataSourceExplorer.Runner.exe
• manager.cmd
• run.cmd
• schema-catalog.json
• source-connections.json
• destination-route.json — 启用目标路由时

启动本地 Runtime Manager：

cd /d C:\Path\To\deployables\windows\win-x64
manager.cmd

manager.cmd 会启动 DataSourceExplorer.Runner.exe --manager。管理器只监听 127.0.0.1，通常会自动打开默认浏览器。如果浏览器未打开，请直接运行可执行文件并使用控制台中显示的 Local management URL。

DataSourceExplorer.Runner.exe --manager

1. 确认 Runtime status 为 READY，且没有活动执行。
2. 在 Connections 中确认所有必需源和目标均显示 Configured。若要保留保存/嵌入的值，请将受保护字段留空。
3. 首次认证运行请使用 Manual only，并将输出目录设置为 output。
4. 选择 Run now，等待状态返回 READY。
5. 确认 Last result 和 Run history 显示 Success，然后独立验证预期输出文件/目标数据。

一次性无界面运行：

run.cmd

生成器会先尝试 self-contained 发布。如果回退为 framework-dependent 发布，请在目标机器安装匹配的 .NET 8 和 ASP.NET Core 8 Runtime。

20.2 Linux 可部署包 (linux/linux-x64) — 已验证的 Ubuntu Hyper-V 流程

以下流程遵循提供用于认证的 Ubuntu Server 26.04.1 LTS / Microsoft Hyper-V 已验证指南。它运行原生 Linux 可部署包；此流程不需要 Docker。

从 Windows 浏览器访问的推荐安全方式

与其把管理器暴露到 VM 网络，不如在读取 Linux 日志中的管理器端口后，从 Windows PowerShell 建立本地 SSH 端口转发：

ssh -L 18093:127.0.0.1:<manager-port> <linux-user>@<VM-IP>

然后在 Windows 打开 http://127.0.0.1:18093/。使用管理器期间请保持 SSH 会话打开。下方的 socat 转发仍可用于隔离/可信的认证网络。

目的

本流程创建一个轻量级 Ubuntu Server 虚拟机，并运行由 DSE 生成的原生 Linux 可部署包。它对应 Windows 上的部署流程：复制生成的包、启动 DSE Deployable Runtime Manager、从 Windows 主机打开管理器、执行部署并验证结果。

本文所述包是原生 linux-x64 可部署包。本流程不需要 Docker。

先决条件

• 已启用 Hyper-V 的 Windows 主机
• Ubuntu Server LTS ISO
• DSE 生成的 linux 文件夹，其中包含 linux/linux-x64
• 至少 4 个 vCPU、4 GB RAM 和 40 GB 虚拟磁盘
• 虚拟机可以访问所需的 DSE 源和目标系统

Windows → Hyper-V → Ubuntu → DSE Runtime Manager → Browser

1. 创建 Hyper-V 虚拟机

创建第 2 代虚拟机，并使用以下基准配置：

安装 Ubuntu 时选择 Install OpenSSH server。安装完成后弹出 ISO，并从虚拟硬盘启动。

2. 准备 Ubuntu

登录 Ubuntu 并更新系统，然后检查 CPU、内存、磁盘和 IP 地址。

sudo apt update
sudo apt upgrade -y
hostname -I
nproc
free -h
df -h

如果 40 GB VHDX 已创建，但根逻辑卷只有约 18-19 GB，请扩展 LVM 根卷以使用剩余空间。

sudo vgs
sudo lvextend -l +100%FREE -r /dev/ubuntu-vg/ubuntu-lv
df -h

3. 从 Windows 使用 SSH 连接

使用 hostname -I 显示的当前虚拟机 IP。Hyper-V Default Switch 的地址可能在重启后改变。

ssh <linux-user>@<VM-IP>

4. 复制生成的 Linux 文件夹

请从 Windows PowerShell 运行 ssh/scp，而不是从 Ubuntu shell 运行。DSE 生成的是 linux 文件夹，而不是 linux.zip 文件。将示例路径、用户和 IP 替换为实际值。

ssh <linux-user>@<VM-IP> "rm -rf /home/<linux-user>/dse-deploy/linux && mkdir -p /home/<linux-user>/dse-deploy"
scp -r "C:\Path\To\GeneratedDeployables\...\linux" <linux-user>@<VM-IP>:/home/<linux-user>/dse-deploy/

如果出现 “Could not resolve hostname c:”，说明 scp 是在 Ubuntu 中运行的。退出到 Windows PowerShell 后重新运行。

5. 准备部署包

如需使用 relay，请安装 socat，然后进入已复制的 linux-x64 目录并添加 Linux 执行权限。当前版本的 DSE 生成无 BOM 的 UTF-8 shell 脚本，因此不需要解压或移除 BOM。

sudo apt update && sudo apt install -y socat
cd ~/dse-deploy/linux/linux-x64
chmod +x DataSourceExplorer.Runner manager.sh run.sh
ls -l DataSourceExplorer.Runner manager.sh run.sh

6. 验证源/目标连接

启动 DSE 前，确认 Ubuntu VM 可以访问所需的主机和端口。下面示例使用 MongoDB 27017 端口。

timeout 5 bash -c '</dev/tcp/<source-host>/<source-port>' \
  && echo 'Port reachable' \
  || echo 'Port NOT reachable'

# MongoDB example
timeout 5 bash -c '</dev/tcp/192.168.50.124/27017' \
  && echo 'MongoDB port reachable' \
  || echo 'MongoDB port NOT reachable'

7. 启动 DSE Deployable Runtime Manager

启动管理器并查看控制台日志。管理器绑定到 127.0.0.1，并选择一个本地端口。

cd ~/dse-deploy/linux/linux-x64
./manager.sh
sleep 2
cat .dse-manager/manager-console.log
curl http://127.0.0.1:<manager-port>/ | head

成功日志会包含类似内容：Local management URL: http://127.0.0.1:51827。重启后端口可能改变。

8. 让 Windows 浏览器访问管理器

在 Ubuntu 中使用 socat，将固定的虚拟机端口 18093 转发到管理器当前的 loopback 端口。下面命令会自动检测虚拟机 IP 和管理器端口。

cd ~/dse-deploy/linux/linux-x64
VM_IP=$(hostname -I | awk '{print $1}')
MANAGER_PORT=$(grep -oE '127\.0\.0\.1:[0-9]+' .dse-manager/manager-console.log | tail -1 | cut -d: -f2)
nohup socat TCP-LISTEN:18093,bind="$VM_IP",reuseaddr,fork TCP:127.0.0.1:"$MANAGER_PORT" > ~/dse-relay.log 2>&1 &
echo "Open: http://$VM_IP:18093/"
ss -ltnp | grep 18093

只在受信任的测试网络中使用此转发。socat 运行期间，管理器可通过虚拟机网络接口访问。

9. 从界面运行部署包

1. 在 Edge 或 Chrome 中打开转发命令显示的 URL。
2. 确认 Runtime status 显示 READY，且没有活动执行。
3. 在 Connections 中确认源和目标显示 Configured。如果要保留嵌入的受保护连接值，请保持相关字段为空。
4. 首次测试时，将 Scheduler configuration 设置为 Manual only，将 Output directory 设置为 output，然后保存。
5. 选择 Run now，并等待状态返回 READY。
6. 确认 Last result 和 Run history 显示 Success，然后验证输出文件和目标数据。

10. 停止、重启与清理

虚拟机重启后，IP 和管理器端口可能变化。再次运行 manager.sh，读取新端口并重新启动 socat。停止转发：

pkill -f 'socat TCP-LISTEN:18093' || true

验证清单

• Ubuntu 从 VHDX 启动且 SSH 登录正常
• 根文件系统有足够可用空间
• 从 Ubuntu 可以访问源/目标端口
• DataSourceExplorer.Runner、manager.sh 和 run.sh 具有执行权限
• manager-console.log 显示本地管理 URL
• Windows 浏览器可以打开 http://<VM-IP>:18093/
• 执行 Run now 后 Runtime status 返回 READY
• Run history 显示 Success，且预期输出/目标数据存在

故障排除

集成到产品帮助时，请使用本包中的本地化 HTML 页面。命令保持不变，只翻译说明文字和界面指导。