数据库信创改造工具

English | 中文

数据库信创改造工具是一个基于 Spring Boot 3 的 Web 应用，用于将标准 SQL 智能转换为国产信创数据库的兼容语法。支持手工逐条转换和批量自动扫描替换两种模式，并提供 AI 深度优化能力。

• 视频演示（B 站）：https://www.bilibili.com/video/BV15wbA66EP1

• 🔄 智能 SQL 转换：基于 JSqlParser 解析 AST，进行函数替换、类型映射、语法改写
• 🤖 AI 深度优化：集成阿里云百炼（通义千问），对转换后的 SQL 进行深度优化
• 🖼️ 图片 OCR 识别：上传包含 SQL 的图片，通过多模态视觉模型自动识别 SQL 语句
• 📂 批量扫描：自动扫描项目目录，精准识别需要改造的 SQL（支持 Java / MyBatis XML / SQL / 配置文件）
• 📁 文件夹选择器：可视化浏览和选择项目目录，无需手动输入路径
• 🚀 一键改造：自动生成备份并执行批量替换

构建机器

• JDK 17+
• Maven 3.6+

运行机器

• JRE 17+（打包产物为自包含 jar，无需 Maven 与联网，详见 离线 / 内网部署）
• 任意 AI 模型服务（可选，用于 OCR 和 AI 优化功能）：支持云端厂商或内网私有化部署

git clone <repository-url>
cd db-converter-tool

无需修改任何配置文件。启动服务后打开浏览器，进入左侧菜单 「AI配置」 即可可视化维护：

• 多厂商：可添加任意数量的厂商配置，一键切换当前启用项
• 协议选择：OpenAI 兼容 或 Anthropic 原生
• 完全自定义：API 地址、文本模型、视觉模型、API Key、最大 Token、温度、超时均可自定义
• 快速模板：内置阿里云百炼 / DeepSeek / 智谱 / Kimi / Claude / Ollama / vLLM 等模板，填充后可任意修改
• 连接测试：保存前即可点击「测试连接」验证地址、Key 与模型是否可用

配置持久化在 config/ai-config.json（与 jar 分离，重新部署不丢失，文件权限自动收紧为 600）。 不配置 AI 也可以正常使用基础的 SQL 转换和批量扫描功能。

前端资源（Vue、Element Plus、axios）已全部本地化，不请求任何外网 CDN。 AI 侧只需把 API 地址指向内网服务即可，例如：

API 地址支持填写根地址或含 /v1 的地址，系统会自动补全接口路径，并在页面上实时预览最终请求地址。

mvn clean package

java -jar target/db-converter-tool-1.0.1.jar

或使用 Maven 直接运行：

mvn spring-boot:run

打开浏览器访问：http://localhost:8080

1. 访问首页，默认进入「手工处理」页面
2. 上传图片（需配置 API Key）：点击上传区域选择图片，系统自动通过 AI 识别 SQL
3. 输入 SQL：在文本框中输入或粘贴 SQL 语句
4. 选择目标数据库：从下拉框选择目标数据库
5. AI 优化（可选，需配置 API Key）：开启「启用 AI 深度优化」开关
6. 转换：点击「转换」按钮，查看转换结果
7. 复制结果：点击「复制」按钮复制转换后的 SQL

1. 点击左侧菜单「自动处理」
2. 选择项目路径：
   • 手动输入目录路径，或
   • 点击「📁 选择文件夹」按钮，在弹窗中浏览并选择目录
3. 选择目标数据库：选择目标数据库
4. （可选）启用 AI 自动优化：打开「启用 AI 自动优化」开关， 在规则转换的基础上再让 AI 针对目标数据库优化一轮（需先在「AI 配置」中配置可用模型）
5. 扫描：点击「开始扫描」按钮，等待扫描完成
6. 查看清单：扫描完成后查看改造清单，确认每项改造内容。 「来源」列会标出该条是 规则 转换还是 🤖 AI 优化； AI 优化的条目在悬浮预览里可同时看到规则转换结果与 AI 优化结果的对比
7. 执行改造：点击「立即改造」按钮，确认后执行批量替换（自动创建 .bak 备份）

自动处理的 AI 优化与手工处理共用「AI 配置」中当前启用的模型，行为如下：

⚠️ AI 优化结果会被写回源文件，请务必在「立即改造」前逐条核对目标 SQL。

为避免 AI 输出破坏源码，AI 结果在写回前会经过安全校验， 以下情况一律拒绝并保留规则转换结果：

• 输出带 Markdown 代码围栏（ sql ... ）或残留反引号
• 在 .java/.xml/.properties/.yml 中出现裸双引号或反斜杠（会破坏字符串字面量）
• 夹带原文中不存在的中文等解释性文字
• 输出长度相比规则结果暴增
• 输出不再是一条合法 SQL

此外，非 .sql 文件中的多行输出会被压成单行，结尾分号会与被替换的原文保持一致。

需要强调的是：安全校验保证的是语法安全（不破坏文件）， 无法保证语义正确——模型完全可能返回一条语法合法但业务语义有偏差的 SQL， 因此人工核对不可省略。改造前的 .bak 备份是最后一道防线。

mysql 是唯一一个反方向的目标库，用于国产库回迁或者两套库并行维护：NVL→IFNULL、SYSDATE→NOW()、TO_CHAR→DATE_FORMAT（格式串一并翻回 %Y-%m-%d）、VARCHAR2→VARCHAR、CLOB→LONGTEXT、NUMBER→DECIMAL、WHERE ROWNUM <= n→LIMIT n、FETCH FIRST n ROWS ONLY→LIMIT n、IDENTITY(1,1)→AUTO_INCREMENT。源本来就是 MySQL 时输出与输入完全一致，不会被改坏。

其中 WHERE ROWNUM <= n 会连同 WHERE 一起换成 LIMIT n；但 AND ROWNUM <= n（同层已有其他条件）故意不动 —— LIMIT 必须挪到句尾才合法，就地替换会产出 status = 1 AND LIMIT 10 这种半对半错的结果，这种情况留给人工判断。

自动处理模式下的扫描器支持从多种文件类型中精准提取 SQL：

扫描器内置 7 层过滤器，有效排除 FUNCTION() 占位符、控制流片段、Java 代码片段等假阳性结果。

# 服务端口与监听地址
server:
  port: 8080
  # 本工具可浏览目录并就地改写文件，且无鉴权，默认只监听本机回环地址。
  # 确需从其他机器访问时才覆盖为 0.0.0.0，并自行做好网络隔离。
  address: ${SERVER_ADDRESS:127.0.0.1}

# 文件上传限制
spring:
  servlet:
    multipart:
      max-file-size: 10MB

# AI 配置持久化文件（AI 厂商/模型/Key 均在网页「AI配置」菜单维护）
app:
  ai:
    config-file: ${AI_CONFIG_FILE:config/ai-config.json}

# 仅用于「首次启动」时生成一条默认 AI 配置，之后修改这里不影响已保存的配置
anthropic:
  api:
    key: ${ANTHROPIC_API_KEY:}
    base-url: ${ANTHROPIC_BASE_URL:https://dashscope.aliyuncs.com/compatible-mode}
    model: ${ANTHROPIC_MODEL:qwen-max-latest}
    vision-model: ${ANTHROPIC_VISION_MODEL:qwen-vl-max-latest}

# 日志配置
logging:
  level:
    com.dbconverter: DEBUG
  file:
    name: logs/db-converter.log

mvn package 产出的已经是自包含的可执行 jar（约 27MB），44 个依赖、内嵌 Tomcat、以及 Vue / Element-Plus / axios 等前端资源全部打在包内，页面无任何外网 CDN 引用。目标机器上只需要一个 JRE 17+，不需要 Maven、不需要 ~/.m2、不需要联网。

在有外网的机器上构建，只把 jar 带进内网：

# 外网机器
mvn clean package -DskipTests
# 产物：target/db-converter-tool-1.0.1.jar —— 只需拷贝这一个文件

# 内网机器
mkdir -p /opt/db-converter && cd /opt/db-converter
# 放入 jar 后直接启动
java -jar db-converter-tool-1.0.1.jar

首次启动会在当前工作目录下自动生成两个目录，所以请先 cd 到你希望存放数据的位置再启动：

/opt/db-converter/
├── db-converter-tool-1.0.1.jar
├── config/ai-config.json          # AI 配置持久化，升级换 jar 不会丢
└── logs/db-converter.log          # 日志

ai-config.json 内含 API Key，创建时权限为 600（仅属主可读写），迁移或备份时请注意保持。

如需固定路径而不依赖启动目录：

java -jar db-converter-tool-1.0.1.jar \
     --app.ai.config-file=/etc/db-converter/ai-config.json \
     --logging.file.name=/var/log/db-converter/db-converter.log

出于安全考虑（本工具可浏览任意目录并就地改写文件，且无任何鉴权），默认只监听回环地址 127.0.0.1，即只能从本机访问。

若需让内网其他同事访问，必须显式覆盖：

SERVER_ADDRESS=0.0.0.0 java -jar db-converter-tool-1.0.1.jar
# 或
java -jar db-converter-tool-1.0.1.jar --server.address=0.0.0.0

⚠️ 放开前请务必评估风险：GET /api/directories?path=/ 可遍历服务器上任意目录，/api/replace/* 可就地改写文件。放开监听等同于把该机器的文件系统读写能力开放给同网段所有人。建议仅在可信网段内放开，或叠加反向代理鉴权 / 防火墙白名单。

后两项需要能访问 OpenAI 兼容或 Anthropic 原生接口。内网若有私有化部署的模型服务（vLLM / Ollama / One-API / 各厂商信创一体机等），进入网页 「AI配置」 菜单，把 API 地址改为内网地址即可，例如：

协议：OpenAI 兼容
API 地址：http://192.168.1.10:8000/v1
模型：<你的内网模型名>

内网若没有任何可用模型服务，SQL 转换与批量替换等核心能力不受影响，仅 OCR 与 AI 优化两项功能不可用，请提前告知使用方。

若因流程要求必须在内网执行 mvn package，需先在外网预热本地仓库并整体搬迁：

# 外网机器：把包括父 POM 在内的依赖全部拉到本地仓库
mvn dependency:go-offline -DincludeParent=true
mvn clean package -DskipTests          # 确保插件也已下载
tar czf m2-repo.tar.gz -C ~ .m2/repository

# 内网机器：解压到 ~/.m2/repository 后离线构建
mvn -o clean package -DskipTests

直接搬 jar 比搬仓库可靠得多（Maven 插件的解析很容易漏包），除非有强制要求，优先用前者。

db-converter-tool/
├── src/
│   ├── main/
│   │   ├── java/com/dbconverter/
│   │   │   ├── DbConverterApplication.java      # 启动类
│   │   │   ├── common/                          # 通用类（Result, ConversionItem, ScanTask, AiConfig）
│   │   │   ├── config/                          # 全局异常处理
│   │   │   ├── controller/
│   │   │   │   ├── ManualController.java        # 手工处理 API
│   │   │   │   ├── AutoController.java          # 自动处理 + 目录浏览 API
│   │   │   │   └── AiConfigController.java      # AI 配置管理 API
│   │   │   └── service/
│   │   │       ├── AiService.java               # AI 服务（OpenAI / Anthropic 双协议）
│   │   │       ├── AiConfigService.java         # AI 配置持久化服务
│   │   │       ├── SqlConverter.java            # SQL 方言转换引擎
│   │   │       ├── FileScannerService.java      # 文件扫描服务
│   │   │       └── FileReplacerService.java     # 文件替换服务
│   │   └── resources/
│   │       ├── application.yml                  # 应用配置
│   │       └── static/                          # 前端页面（资源全部本地化）
│   │           ├── index.html                   # 入口（跳转手工处理）
│   │           ├── manual.html                  # 手工处理页面
│   │           ├── auto.html                    # 自动处理页面
│   │           ├── ai-config.html               # AI 配置页面
│   │           ├── support.html                 # 支持与更新页面
│   │           └── libs/                        # Vue / Element Plus / axios 本地资源
│   └── test/                                    # 测试代码
├── pom.xml
├── README.md
└── README_EN.md

mvn test

1. API Key 安全：请勿将 API Key 提交到代码仓库，建议使用环境变量传入
2. 文件备份：自动改造会创建 .bak 备份文件，请在改造前确认备份
3. 大项目扫描：扫描大型项目可能需要一定时间，页面会实时显示进度
4. SQL 解析：部分复杂 SQL 可能无法被 JSqlParser 完全解析，会自动降级为正则处理
5. 目录过滤：扫描时自动跳过 target/、build/、.git/、node_modules/、.idea/ 等非业务目录
6. AI 优化需人工复核：AI 结果的安全校验只保证语法安全（不破坏文件）， 无法保证语义正确，改造前请逐条核对

以下问题会直接产出错误的 SQL 并写回源文件，已修复并补充了回归测试：

字面量保护的覆盖范围：

-- ✅ 字面量内容保持原样，字面量外的转换照常生效
WHERE kind = 'text' AND created > NOW()
WHERE kind = 'text' AND created > CURRENT_TIMESTAMP

-- ✅ 引号标识符、注释、转义引号（''）均受保护
SELECT "text", `text` FROM t WHERE a = 'it''s text'   -- 全部保持不变

TEXT / INT / DATE / DATETIME / DOUBLE 既是类型名，也是极常见的列名。词法掩码只能识别引号和注释，无法判断一个裸词是列名还是类型声明，因此列名会被当成类型替换掉——这是静默的语义破坏，改完的 SQL 引用了不存在的列，运行时才炸：

SELECT text FROM notes            →  SELECT CLOB FROM notes             -- ❌ 列不存在
INSERT INTO t (int) VALUES (1)    →  INSERT INTO t (INTEGER) VALUES (1) -- ❌ 列不存在
CREATE TABLE notes (text TEXT)    →  CREATE TABLE notes (CLOB CLOB)     -- ❌ 列名也被改了
SELECT body AS text FROM notes    →  SELECT body AS CLOB FROM notes     -- ❌ 结果列名错误

修复：把类型替换从"到处都替换，只避开字面量"（黑名单）改成只在类型声明槽位替换（白名单）。已覆盖的槽位：

配套细节：表级约束项（PRIMARY KEY (...)、KEY text (...)、CONSTRAINT text CHECK (...)）不是列定义，整项跳过；CREATE TABLE x AS SELECT ... 的括号里是查询而非列定义，也跳过；列名与类型之间的注释会一并跳过（真实建表语句几乎每列都带 -- 注释，只跳空白会导致类型被漏改）。

CONVERT() 的参数顺序靠内容判别：MySQL 是 CONVERT(expr, TYPE)，SQL Server 是 CONVERT(TYPE, expr)，顺序正好相反；而本工具只收到目标库、从不知道源库方言，所以不能按方言配置去猜。改为看哪一侧「像类型名」（对照一份内置类型词表，允许 DECIMAL(10,2) 这样的精度修饰）：只有一侧像 → 那一侧就是类型；两侧都像 → 一个都不动（CONVERT(text, CHAR) 既可读作 MySQL 形式也可读作 SQL Server 形式，无解）。CONVERT(expr USING charset) 不含类型，整段跳过；Oracle 的 CONVERT(str, 'charset', 'charset') 里字符集是字符串字面量，本身就在掩码内。

DECLARE 的区间边界按写法不同：T-SQL（DECLARE @a INT, @b TEXT;）以逗号分隔、止于分号；PL/SQL 声明块以分号分隔、止于 BEGIN（BEGIN 之后是语句体，里面的 SELECT text 是列名不是声明）。游标声明（DECLARE c CURSOR FOR SELECT ...）后面跟的是完整查询，整段跳过——查询的选择项与「变量名 类型名」同形（SELECT id, label text 里 text 是隐式别名），逐项解析必然误判。

方向性权衡：白名单的失效模式是漏改（少迁移一处，人工可发现），而不是改坏（静默产出错误 SQL）。这是有意选择的方向。目前已知的剩余漏改点：CONVERT() 两侧都像类型名的歧义情形（上文），以及 DECLARE @t TABLE (id INT, body TEXT) 里的内层列定义（识别到第二个词是 TABLE 而非类型名后整项跳过，括号内不再深入）。这两类需人工复核。

为什么不用 JSqlParser AST（README 早前版本曾把 AST 称为"正解"，实测证明行不通）：

1. JSqlParser 4.9 的 ColumnDefinition / ColDataType 没有实现 ASTNodeAccess，Token 也只有行列号、没有绝对字符偏移——无法把类型节点映射回原文位置，而"按偏移写回原文"是保形改造的前提。
2. 含 #{} / 动态标签的 MyBatis 片段根本无法被解析，而这恰好是保形改造的主场景。

所以只能走词法扫描。好处是它对两条转换路径（AST 路径与保形路径）一视同仁，也对解析不了的片段同样有效。

根因是扫描端与替换端的文本"表示层"不一致：扫描端把 SQL 归一化（XML 去标签、#{}→?、Java 反转义、多行压平）之后才交给转换器，而替换端拿归一化后的文本回原文里做 contains 匹配——原文里根本不存在这段文本。因此下列写法（几乎覆盖所有真实项目）扫得出来但改不进去：

• MyBatis XML：只要含 #{} / ${} 参数或动态标签
• Java：多行字符串（含 \n 转义）、字符串拼接、Text Block

修复分两步，缺一不可：

1. 保形转换 —— 新增 SqlConverter.convertPreservingText()，只做局部 token 替换，不经过 JSqlParser 的 toString() 重排。原本的 convertStatement 除了 toString() 之外并未真正用到 AST，所以跳过它不损失任何转换能力，却能完整保留换行、缩进、#{} 占位符和 Java 转义。
2. 偏移量替换 —— 扫描时记录每个片段在原文中的区间 [startOffset, endOffset)（由 Matcher.start(n)/end(n) 得到；注释改为用等长空格抹除以保持下标对齐），替换时按 startOffset 倒序逐个拼接，不再做文本匹配。倒序是必需的，否则前一处改动会让后面所有下标错位。

配套的三道安全闸：

无偏移信息的条目（如手工提交给 /api/replace/custom 的清单）自动退回原来的逐字匹配路径，行为不变。

改造后的效果（缩进、#{id}、字面量、结尾 "; 全部保持原样，diff 只落在真正需要改的 token 上）：

  <update id="touch">
-     UPDATE users SET updated_at = NOW() WHERE id = #{id}
+     UPDATE users SET updated_at = CURRENT_TIMESTAMP WHERE id = #{id}
  </update>

- "SELECT id, name FROM users WHERE created > NOW() AND kind = 'CLOB' LIMIT 10";
+ "SELECT id, name FROM users WHERE created > CURRENT_TIMESTAMP AND kind = 'CLOB' FETCH FIRST 10 ROWS ONLY";

顺带修掉的两处：改造清单的行号此前恒为 0（前端无法定位），现在是真实行号；Java 的三个提取正则会重复命中同一段文本，按偏移替换要求区间互不重叠，因此新增了重叠区间去重。

欢迎提交 Issue 和 Pull Request！

如果这个项目对你有帮助，欢迎请我喝杯咖啡 ☕

个人 / 非商业使用免费，商业使用需获得作者授权。详见 LICENSE。