QUICK START

快速开始

一分钟上手，零门槛配置 —— 单个 jar 启动，不需要任何外部组件。文本教程 + 视频教程

环境要求

JDK 17 或以上 · Maven 3.6+（仅构建时需要） · 内存 ≥ 512MB · 端口 8080

构建

bash
git clone https://github.com/vfaner/synctool.git
cd synctool
mvn clean package -DskipTests

产物：target/synctool.jar（可执行 fat jar）

启动

bash
java -jar target/synctool.jar

访问 http://localhost:8080 即可。

首次启动会自动创建 ./data（元数据）、./logs（运行日志）、./snapshots（快照）目录。

生产配置（重要）

在 jar 同级目录创建 application.yml：

yaml
server:
  port: 8080

sync:
  poll-interval: 2000              # 轮询间隔（毫秒）
  batch-size: 500
  fetch-size: 1000
  safety-lag-ms: 1000
  lock-ttl-ms: 300000
  crypto-password: 请改成你自己的强口令    # ← 必须修改
  crypto-salt: 请改成你自己的16位十六进制盐  # ← 必须修改
🔐 安全提示：crypto-password 与 crypto-salt 用于加密存储的数据库连接密码，发行包带有默认值，生产环境必须修改。

后台常驻

方式 A：systemd（推荐）

ini
[Unit]
Description=SyncTool Database Sync
After=network.target

[Service]
Type=simple
User=synctool
WorkingDirectory=/opt/synctool
ExecStart=/usr/bin/java -Xms512m -Xmx1g -jar /opt/synctool/synctool.jar \
  --spring.config.location=file:/opt/synctool/application.yml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
bash
sudo systemctl daemon-reload
sudo systemctl enable --now synctool
sudo systemctl status synctool

方式 B：nohup（快速验证）

bash
cd /opt/synctool
nohup java -jar synctool.jar > /dev/null 2>&1 &

使用流程

① 数据库连接 → 新建源库和目标库连接 → 点击「测试连接」确认可用
② 项目 → 新建项目 → 选择源库与目标库
③ 进入项目详情 → 勾选要同步的表/视图/存储过程 → 配置同步选项 → 保存
④ 点击「立即同步」验证一次，或点击「启动同步」开始持续轮询
⑤ 在「变更日志」查看每次同步的明细

VIDEO TUTORIAL

视频教程

不想读文档就跟着视频走一遍，从下载到第一条链路跑通

EP.01

5 分钟跑起来

下载 jar、启动、登录，顺手把初始密码改掉
EP.02

配好第一条同步链路

建两个连接 → 建项目 → 勾选要同步的表 → 启动
EP.03

接国产数据库

达梦 / 金仓的驱动 jar 怎么放、怎么填、怎么验
EP.04

上生产

systemd 常驻、加密密钥、批量与轮询参数怎么调
🎬 视频还在录，先占个位。 录好后会挂到 B 站，届时这里的卡片就能直接点开 —— 也欢迎在 Issue 里说你最想先看哪一集。
CONFIGURATION

配置项

application.yml 中的 sync.*

键默认说明
poll-interval2000轮询间隔（毫秒）
snapshot-dir./snapshots元数据快照目录
batch-size500每个 JDBC 批次行数
fetch-size1000源库结果集读取批量
max-retries3连续失败多少次后标记任务为 ERROR
safety-lag-ms1000时间戳水位线回退量，避免晚提交的事务被跳过
row-count-audit-interval-ms60000行数审计间隔（毫秒）
full-compare-max-rows20000全表比对的行数上限
lock-ttl-ms300000同步锁租约时长（毫秒）
crypto-password(默认值)密码加密密钥，生产环境必须修改
crypto-salt(默认值)加密盐值（十六进制），生产环境必须修改
ai.enabledtrue是否允许配置 AI 辅助转换。置 false 则菜单与接口一并下线

连接密码使用 Spring Security Crypto 的 AES-256 加密后存储， 带 enc: 前缀标记以避免重复加密，并兼容加密启用前写入的明文。

AUTH

登录与权限

所有页面和接口都必须登录后才能访问，没有任何匿名可达的入口

用户名角色初始密码权限
admin管理员123456全部操作
view访客123456只读
⚠️ 请在第一次登录后立刻改掉这两个密码。 jar 是公开可下载的，初始密码不是秘密。仍在使用初始密码的账号，登录后页面顶部会一直显示一条黄色警告横幅。

权限按 HTTP 方法判定 设计要点

权限不是按页面枚举的，而是按 HTTP 方法判定：本工具所有的写操作都是 POST， 没有任何 GET 会改动状态，所以规则只有一条 —— POST 一律要求管理员。 这样以后新增接口不会漏配。

管理员

新建/编辑/删除数据库连接、项目、AI 供应商；勾选同步对象、启停同步、立即同步、重置进度；起草和保存存储过程转换、清理变更日志。

访客

能看到全部页面和全部数据（看板、连接列表、项目详情的勾选状态、变更日志都能看、能选、能复制），但界面上不会出现任何写操作按钮，直接构造请求打接口也会被拒。

🔑 忘记密码无法找回。登录密码用 BCrypt 单向哈希存储，和数据库配置里那些必须能还原出明文交给驱动的凭据不同。 真忘了就直接删掉 app_user 表里对应那行，重启后会重新种回初始密码。
UPGRADE

升级

元数据库使用 ddl-auto: update，表结构会自动演进

bash
sudo systemctl stop synctool
cp target/synctool.jar /opt/synctool/synctool.jar
sudo systemctl start synctool
升级前请备份 ./data 目录。 停机期间源库产生的变更会在重启后由游标机制自动补齐，不会丢失。