YunJiaDB：MySQL 数据传输工具的设计与交付实践

产品与工程实践

从内部需求出发，做一款可交付的数据工具

在开发、测试与运维环境之间复制数据库，是软件交付中常见的一步。真正需要解决的，不只是把数据搬过去，还包括目标对象如何处理、依赖能否保留、失败后哪些操作已经生效，以及凭据如何保存。

YunJiaDB 是云佳创想为自身工作场景研发的 macOS MySQL 8+ 数据传输工具。它将 Schema 复制、压缩备份和数据恢复放在统一界面中，先检查操作范围，再展示执行预览，最后运行任务并记录结果。

技术架构：界面与数据处理各司其职

应用使用 Go 1.26、Wails v2 与 Vue 3 + TypeScript。Go 后端负责连接、SSH 隧道、任务调度、SQL 解析与范围检查，界面负责连接编辑、参数设置、预览和进度展示。MySQL Shell 承担高速分块传输；SQL 路径由应用执行，语句顺序与存储程序边界保持不变。

边界比“全自动”更重要

不锁源库默认开启，但并行读取不承诺全库同一时点快照；失败批次可以回滚，但不承诺整库回滚。遇到无法可靠处理的动态 SQL、跨库引用或对象依赖冲突，先阻止执行并说明原因。产品把这些约束带到操作预览与使用文档中，让执行者能够判断实际影响。

验证与交付

研发能力，落在可核对的结果上

0.1.12 的验证覆盖 Go 竞态检查、前端类型检查和正式构建，以及隔离 MySQL 8.4 环境中的集成测试。集成场景包含导入导出、目录与兼容复制、SSH、排除对象、回滚和取消；正式签名后的内置引擎也再次完成验证。

macOS 分发采用公司 Developer ID 签名，应用启用 Hardened Runtime。安装包通过 Apple 公证并附加票据，本机 Gatekeeper 接受安装包。最终包发布到 OSS 后，通过公开 HTTPS 下载地址完整读取文件，再与本地 SHA-256 比对。

01 / INSTALL

安装与升级

• 使用 Apple 芯片 Mac（M 系列），系统为 macOS 15 或更新版本。
• 数据库服务端为 MySQL 8+。不同版本之间仍受 MySQL 兼容性约束，不支持高主版本向低主版本迁移。
• 安装包内置数据引擎，无需单独安装 Go、Node.js 或 MySQL Shell。

1. 下载 YunJiaDB-0.1.12-macOS-arm64.pkg，建议同时下载校验文件，按文末步骤核对。
2. 升级前确认没有正在运行的传输任务，然后退出 YunJiaDB。
3. 双击 pkg，按 macOS 安装器提示完成安装。系统可能要求管理员验证。
4. 在“应用程序”中打开 YunJiaDB。安装位置为 /Applications/YunJiaDB.app。

本版本使用公司 Developer ID 签名并通过 Apple 公证。安装器的管理员验证用于安装系统应用；应用运行及数据库连接不访问钥匙串。当前未提供 Intel 版本。

02 / QUICK START

首次使用：四步开始

1. 添加数据源：进入“数据源”，填写 MySQL 连接信息；需要时启用 SSH 隧道。
2. 测试并保存：测试连接，确认地址、凭据和 SSH 主机指纹无误，然后保存。
3. 选择操作：“Schema 复制”用于库之间传输；“导出备份”生成本地备份；“导入数据”恢复文件或目录。
4. 预览后执行：点击“检查并预览”，核对对象、覆盖范围和路径，再点击“确认并开始”。在“任务记录”查看进度与日志。

03 / CONNECTIONS

数据源与 SSH

直接连接 MySQL

在“数据源”添加连接，填写名称、主机、端口、用户名和数据库密码。使用“测试连接”检查可达性和认证，再保存。可浏览连接下的 Schema、表与视图；显示的行数为数据库估算值。

通过 SSH 隧道连接

1. 启用 SSH，填写 SSH 主机、端口和用户名。
2. 选择密码认证或私钥认证。私钥可选择本机文件，也可粘贴多行私钥内容；加密私钥需提供正确口令。
3. 首次遇到未知主机时，核对界面显示的主机指纹，并按提示填写确认。已有 known_hosts 记录会参与验证。
4. 填写从 SSH 服务端可访问的 MySQL 地址和端口，测试后保存。

未加密私钥可以不填口令。编辑既有连接时，已保存凭据留空会保持原值；若需移除旧私钥口令，使用“清除已保存口令”。粘贴的私钥加密保存在本机，不会在编辑界面回显。

04 / SCHEMA COPY

复制一个 Schema

1. 进入“Schema 复制”，选择源数据源与源 Schema。
2. 选择目标数据源与目标 Schema；也可点击“新建 schema”输入新名称。源、目标名称可以不同。
3. 按需勾选要排除的表或视图，并调整并发数、读取限速等选项。
4. 点击“检查并预览”，核对“将覆盖”“将保留”和已排除对象，查看依赖提示。
5. 确认后点击“确认并开始”，在任务记录中查看结果。

复制时如何处理目标对象

完整复制支持表、索引、外键、视图、触发器、存储过程、函数和事件；不复制账户与权限。显式 DEFINER 调整为目标连接用户。无法可靠处理的动态 SQL 或跨库引用会报错。

排除与依赖

“全选排除”“反选”“清空排除”作用于全部表与视图，不受搜索过滤影响。完整已排除清单显示在页面，关联视图的自动排除结果显示在预览中。

依赖排除对象的源视图会自动跳过；源外键跨越排除边界时阻止执行。目标保留对象依赖被覆盖对象时也会检查冲突。存在排除项时不覆盖过程、函数和事件，只复制所选表的触发器。

05 / EXPORT

导出压缩备份

1. 进入“导出备份”，选择源连接与 Schema。
2. 选择导出格式，默认是“单个 SQL 文件”。
3. 选择新的保存路径和压缩方式，按需排除表或视图。
4. 点击“检查并预览”，核对实际导出对象、格式、路径与排除项，再确认开始。
5. 任务完成后点击“打开所在目录”，Finder 会定位到备份。

压缩直接写入磁盘。单文件 SQL 使用单连接、批量 SQL，通常比并行分块目录慢。单文件失败或取消会清理该任务的临时文件，完成并校验后才发布最终文件；已有备份不会被覆盖。

部分导出不包含过程、函数和事件，仅包含所选表的触发器；依赖排除表的视图也会跳过。全部排除时会阻止空导出。

06 / IMPORT

导入到指定 Schema

导入 SQL 文件

1. 进入“导入数据”，切换为“SQL 文件”，选择 .sql、.sql.gz 或 .sql.zst。
2. 选择目标连接与目标 Schema，也可新建目标 Schema。
3. 点击“检查并预览”。应用预扫描语句、验证目标范围与依赖，准备通过校验的语句快照。
4. 核对预览中的覆盖与保留对象，然后确认执行。

SQL 按文件中的语句顺序执行，支持标准 MySQL 单 Schema 转储及 DELIMITER 存储程序边界。CREATE DATABASE / USE 重定向到所选目标；不会执行 DROP DATABASE、账户授权、客户端系统命令或任意全局变量修改。标准转储中的 GTID 与二进制日志元数据会跳过。

只有 INSERT 的数据文件使用目标现有表结构，先清空涉及表的数据再导入，其他表保留。单条 SQL 上限为 64 MiB，目标的 max_allowed_packet 也需满足要求。

导入备份目录

1. 切换为“备份目录”，选择完整的 MySQL Shell 导出目录，无需手动解压数据块。
2. 确认目录含完成标记 @.done.json；不完整备份不能导入。
3. 选择目标连接与 Schema，预览并确认执行。目录导入可使用多线程。

07 / TRANSFER OPTIONS

传输选项与任务记录

• 不锁定源数据库：复制与分块导出默认开启，不主动申请全局读锁、显式表锁或备份锁。并行读取不保证跨表同一时点快照，该模式只接受 InnoDB 表。普通查询仍可能产生元数据锁和资源消耗。
• 一致性模式：关闭“不锁定源数据库”会切换为一致性模式，建立快照时可能短暂阻塞写入；非 InnoDB 表仍无事务快照保证。单文件 SQL 导出固定使用单连接 InnoDB 事务快照读取。
• 并发数：可选择 1、2、4、8、16、32，界面推荐 4。仅适用于高速路径；SQL 文件导入、单文件 SQL 导出和兼容复制使用单连接批量处理。
• 读取限速：0 表示不限速，支持 k、M、G，例如 10M。高速路径显示为每线程读取限速。
• 任务记录：同一时间只运行一个传输任务。可查看阶段、进度、耗时、日志及错误，运行中可取消。保留最近 100 条任务，每条最多 200 行日志。

复制使用本机临时备份或 SQL 快照衔接读写，请保留足够磁盘空间。性能受网络、源库、目标库、磁盘和数据形态影响，不能用线程数推算固定完成时间。

08 / PORTABLE CONNECTIONS

把连接配置迁移到另一台 Mac

1. 原电脑：在“数据源”点击“导出配置”，设置并确认至少 8 个字符的口令，保存 .yunjia-connections 文件。
2. 把文件传到新电脑，并妥善保存口令。
3. 新电脑：点击“导入配置”，选择该文件，输入同一口令。
4. 导入只新增连接；同名连接自动加“导入 2”等后缀，不覆盖已有配置。
5. 使用 SSH 私钥的连接，需在新电脑重新选择本机私钥文件，或重新粘贴私钥正文，再测试连接。

迁移文件使用口令加密，包含连接信息、数据库密码、SSH 密码及私钥口令；不包含本机加密密钥、SSH 私钥文件或粘贴的私钥正文。SSH 主机指纹与私钥来源设置保留。

09 / TROUBLESHOOTING

常见问题

10 / RELEASE

版本信息与文件校验

0.1.12 包含标准 MySQL 转储 GTID / 二进制日志元数据兼容处理，以及目录预检查与正式加载进度状态隔离修复。本次分发使用已经完成 Developer ID 签名、Apple 公证并附加票据的安装包。

最终安装包 SHA-256

请将安装包与 同名 .sha256 文件 放在同一个目录。在“终端”进入该目录后执行：

shasum -a 256 -c YunJiaDB-0.1.12-macOS-arm64.pkg.sha256

输出 YunJiaDB-0.1.12-macOS-arm64.pkg: OK 表示文件与本次分发的校验和一致。

发布验证：安装包签名、公证票据、本机 Gatekeeper 与哈希校验均通过；此版本 Go 竞态检查、前端正式构建及隔离 MySQL 8.4 集成验证已通过。尚未在另一台 Mac 实际安装验证。