将Forest应用从DERBY数据库迁移到MySQL
在开发和部署 AI 驱动的 Web 应用时，我们常常会遇到一个看似微小却影响深远的问题：数据库选型。许多示例项目为了简化部署，默认使用嵌入式数据库（如 DERBY），这在本地调试阶段确实方便——无需额外配置、一键启动。但一旦进入生产环境，尤其是面对多用户并发访问、实时图像识别与交互等高负载场景时，这些“轻量级”数据库很快就会暴露出性能瓶颈。
比如 Forest 这个典型的应用，它作为 GLM-4.6V-Flash-WEB 多模态模型服务的前端载体，承担着用户管理、订单处理、商品展示等核心功能。默认基于 DERBY 的存储方案虽然能“跑起来”，但在真实请求压力下，连接池耗尽、事务阻塞、远程访问受限等问题接踵而至。更别提数据备份困难、扩展性差这些运维噩梦了。
于是，迁移至 MySQL 成为必然选择。这不是简单的“换个数据库”，而是一次系统稳定性和可维护性的跃迁。本文将带你完整走一遍从 DERBY 到 MySQL 的迁移流程，涵盖配置修改、驱动替换、SQL 脚本重写到最终验证的每一个关键细节。
核心改动清单
整个迁移过程主要围绕三个层面展开：
- 数据源配置更新：让应用知道该连哪个数据库；
- JDBC 驱动切换：替换底层通信协议；
- SQL 脚本适配：确保建表语句符合 MySQL 语法规范。
听起来不复杂，但实际操作中稍有疏忽就可能导致启动失败或运行时异常。接下来我们逐一拆解。
打开项目的WEB-INF/web.xml文件，找到<data-source>配置段。原始 DERBY 配置通常长这样：
<data-source> <name>java:global/ForestDataSource</name> <class-name>org.apache.derby.jdbc.EmbeddedDataSource</class-name> <database-name>derbyDB</database-name> <create-database>true</create-database> </data-source>我们需要将其替换为 MySQL 对应的配置：
<data-source> <name>java:global/ForestDataSource</name> <class-name>com.mysql.cj.jdbc.MysqlDataSource</class-name> <server-name>localhost</server-name> <port-number>3306</port-number> <database-name>forest</database-name> <user>root</user> <password>your_password_here</password> <property> <name>useSSL</name> <value>false</value> </property> <property> <name>allowPublicKeyRetrieval</name> <value>true</value> </property> <property> <name>serverTimezone</name> <value>UTC</value> </value> </property> </data-source>这里有几个关键点需要注意：
- 使用
com.mysql.cj.jdbc.MysqlDataSource作为新的数据源类名； - 显式指定服务器地址和端口，避免依赖默认值；
- 添加
useSSL=false和allowPublicKeyRetrieval=true是为了防止因 SSL 认证导致的连接拒绝，尤其在测试环境中非常实用； serverTimezone=UTC解决了常见的时区偏移问题，否则可能报错 “The server time zone value ‘XXX’ is unrecognized”。
如果你的应用部署在容器或远程服务器上，请将localhost改为实际的数据库主机 IP，并确保防火墙开放 3306 端口。
仅仅改了配置还不够，JVM 必须能加载对应的 JDBC 驱动。对于传统 WAR 包部署方式，你需要手动把 MySQL Connector JAR 包放入应用服务器的共享库目录。
以 GlassFish 或 TomEE 为例，路径通常是：
domains/domain/lib/推荐使用稳定版本：
mysql-connector-java-8.0.33.jar你可以通过 Maven Central 下载，或者执行 Maven 命令自动获取：
mvn dependency:get -Dartifact=mysql:mysql-connector-java:8.0.33如果你使用的是 Maven 构建项目，那就更简单了，在pom.xml中添加依赖即可：
<dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>8.0.33</version> </dependency>构建时会自动打包进 WAR 文件，省去手动拷贝的麻烦。
⚠️ 提醒：不要遗漏这一步！否则你会看到熟悉的
ClassNotFoundException: com.mysql.cj.jdbc.MysqlDataSource错误，应用根本无法启动。
大多数基于 JPA 的项目都有一个persistence.xml文件，用于定义持久化单元。好消息是，这个文件通常不需要大改——ORM 框架（如 Hibernate 或 EclipseLink）会根据当前数据源自动识别方言。
但为了提升兼容性和稳定性，建议显式声明 MySQL 方言：
<property name="hibernate.dialect" value="org.hibernate.dialect.MySQL8Dialect"/>这样可以确保生成的 SQL 语句充分利用 MySQL 8.x 的特性，比如窗口函数、JSON 支持、更高效的索引策略等。同时也能避免某些隐式转换带来的性能损耗。
如果你用的是较老版本的 MySQL（5.7 及以下），请改为MySQL57Dialect或MySQL5Dialect，否则可能会出现语法不支持的问题。
原始 DERBY 初始化脚本不能直接用于 MySQL，因为两者在自增字段、数据类型、约束命名等方面存在差异。我们必须重写三类脚本：drop.sql、create.sql和data.sql。
先看drop.sql，它的作用是清理旧表结构：
SET FOREIGN_KEY_CHECKS = 0; DROP TABLE IF EXISTS PERSON_GROUPS; DROP TABLE IF EXISTS PERSON; DROP TABLE IF EXISTS GROUPS; DROP TABLE IF EXISTS ORDER_DETAIL; DROP TABLE IF EXISTS CUSTOMER_ORDER; DROP TABLE IF EXISTS ORDER_STATUS; DROP TABLE IF EXISTS PRODUCT; DROP TABLE IF EXISTS CATEGORY; SET FOREIGN_KEY_CHECKS = 1;注意这里用了SET FOREIGN_KEY_CHECKS = 0;来临时关闭外键检查，防止删除顺序引发冲突。操作完成后记得恢复。
再来看最关键的create.sql：
CREATE DATABASE IF NOT EXISTS forest CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE forest; SET autocommit=0; START TRANSACTION; CREATE TABLE CATEGORY ( ID INT NOT NULL AUTO_INCREMENT PRIMARY KEY, NAME VARCHAR(45) NOT NULL, TAGS VARCHAR(45) ); CREATE UNIQUE INDEX SQL_CATEGORY_ID_INDEX ON CATEGORY(ID); CREATE TABLE PERSON ( ID INT NOT NULL AUTO_INCREMENT PRIMARY KEY, FIRSTNAME VARCHAR(50) NOT NULL, LASTNAME VARCHAR(100) NOT NULL, EMAIL VARCHAR(45) NOT NULL UNIQUE, ADDRESS VARCHAR(45) NOT NULL, CITY VARCHAR(45) NOT NULL, PASSWORD VARCHAR(100), DTYPE VARCHAR(31) ); CREATE UNIQUE INDEX SQL_PERSON_EMAIL_INDEX ON PERSON(EMAIL); CREATE UNIQUE INDEX SQL_PERSON_ID_INDEX ON PERSON(ID); CREATE TABLE GROUPS ( ID INT NOT NULL AUTO_INCREMENT PRIMARY KEY, NAME VARCHAR(50) NOT NULL, DESCRIPTION VARCHAR(300) ); CREATE TABLE PERSON_GROUPS ( GROUPS_ID INT NOT NULL, EMAIL VARCHAR(45) NOT NULL, CONSTRAINT PK_PERSON_GROUPS PRIMARY KEY (GROUPS_ID, EMAIL) ); ALTER TABLE PERSON_GROUPS ADD CONSTRAINT FK_PERSON_GROUPS_PERSON FOREIGN KEY (EMAIL) REFERENCES PERSON(EMAIL); ALTER TABLE PERSON_GROUPS ADD CONSTRAINT FK_PERSON_GROUPS_GROUPS FOREIGN KEY (GROUPS_ID) REFERENCES GROUPS(ID); CREATE INDEX SQL_PERSONGROUPS_EMAIL_INDEX ON PERSON_GROUPS(EMAIL); CREATE INDEX SQL_PERSONGROUPS_ID_INDEX ON PERSON_GROUPS(GROUPS_ID); CREATE TABLE ORDER_STATUS ( ID INT NOT NULL PRIMARY KEY, STATUS VARCHAR(45) NOT NULL, DESCRIPTION VARCHAR(200) ); CREATE UNIQUE INDEX SQL_ORDERSTATUS_ID_INDEX ON ORDER_STATUS(ID); CREATE TABLE CUSTOMER_ORDER ( ID INT NOT NULL AUTO_INCREMENT PRIMARY KEY, AMOUNT FLOAT(52) NOT NULL, DATE_CREATED TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL, CUSTOMER_ID INT NOT NULL, STATUS_ID INT NOT NULL ); ALTER TABLE CUSTOMER_ORDER ADD CONSTRAINT FK_CUSTOMER_ORDER_ORDER_STATUS1 FOREIGN KEY (STATUS_ID) REFERENCES ORDER_STATUS(ID); ALTER TABLE CUSTOMER_ORDER ADD CONSTRAINT FK_CUSTOMER_ORDER_CUSTOMER1 FOREIGN KEY (CUSTOMER_ID) REFERENCES PERSON(ID); CREATE INDEX SQL_ORDER_STATUS_ID_INDEX ON CUSTOMER_ORDER(STATUS_ID); CREATE INDEX SQL_ORDER_CUSTOMER_ID_INDEX ON CUSTOMER_ORDER(CUSTOMER_ID); CREATE UNIQUE INDEX SQL_ORDER_ID_INDEX ON CUSTOMER_ORDER(ID); CREATE TABLE PRODUCT ( ID INT NOT NULL AUTO_INCREMENT PRIMARY KEY, NAME VARCHAR(45) NOT NULL, PRICE DECIMAL(10,2) NOT NULL, DESCRIPTION VARCHAR(145) NOT NULL, IMG VARCHAR(45), CATEGORY_ID INT NOT NULL, IMG_SRC LONGBLOB ); ALTER TABLE PRODUCT ADD CONSTRAINT FK_PRODUCT_CATEGORY FOREIGN KEY (CATEGORY_ID) REFERENCES CATEGORY(ID); CREATE UNIQUE INDEX SQL_PRODUCT_ID_INDEX ON PRODUCT(ID); CREATE TABLE ORDER_DETAIL ( ORDER_ID INT NOT NULL, PRODUCT_ID INT NOT NULL, QTY INT NOT NULL, CONSTRAINT SQL_ORDER_PRODUCT_PK PRIMARY KEY (ORDER_ID, PRODUCT_ID) ); ALTER TABLE ORDER_DETAIL ADD CONSTRAINT FK_ORDER_DETAIL_PRODUCT FOREIGN KEY (PRODUCT_ID) REFERENCES PRODUCT(ID); ALTER TABLE ORDER_DETAIL ADD CONSTRAINT FK_ORDER_DETAIL_ORDER FOREIGN KEY (ORDER_ID) REFERENCES CUSTOMER_ORDER(ID); CREATE INDEX SQL_ORDER_PRODUCT_ID_INDEX ON ORDER_DETAIL(PRODUCT_ID); CREATE INDEX SQL_ORDER_DETAIL_ID_INDEX ON ORDER_DETAIL(ORDER_ID); COMMIT;几个重点说明：
- 所有主键都使用
AUTO_INCREMENT替代 DERBY 的GENERATED BY DEFAULT AS IDENTITY； - 图片字段
IMG_SRC使用LONGBLOB类型，能够存储最大约 4GB 的二进制数据，远超原BLOB(1073741823)在 MySQL 中的实际限制； - 表名和字段名统一采用大写字母，避免大小写敏感问题；
- 外键约束命名清晰且带前缀，便于后期排查问题。
至于data.sql，内容基本不变，只需确认字符串长度未超过定义上限即可。例如：
INSERT INTO CATEGORY (NAME, TAGS) VALUES ('Plants', 'Seeds, trees, flowers ...'); INSERT INTO PERSON (FIRSTNAME,LASTNAME,EMAIL,ADDRESS,CITY,PASSWORD,DTYPE) VALUES ('Robert','Exampler','robert@example.com','Example street','San Francisco','81dc9bdb52d04dc20036dbd8313ed055','Customer'); -- 其他插入略密码字段使用的是 MD5 加密示例，生产环境建议升级为 BCrypt。
完成代码和脚本修改后，进入最后的部署与验证阶段。
登录 MySQL，创建目标数据库：
sql CREATE DATABASE forest CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;执行初始化脚本：
bash mysql -u root -p forest < drop.sql mysql -u root -p forest < create.sql mysql -u root -p forest < data.sql启动应用服务器（如 GlassFish、Tomcat 等）。观察日志输出是否出现数据库连接成功信息。
访问前端页面或调用 API 接口，尝试登录、浏览商品、下单等操作，确认所有功能正常。
查看服务器日志，重点关注是否有以下错误：
-SQLException: SQL 语法或约束冲突
-Connection refused: 数据库未启动或网络不通
-Table doesn't exist: 脚本未正确执行
如果一切顺利，你应该能看到熟悉的 Forest 商城界面，而背后支撑它的已是稳健的 MySQL 数据库。
尽管步骤清晰，但在实际迁移中仍可能踩坑。以下是常见问题及解决方案汇总：
| 问题 | 可能原因 | 解决方法 |
|---|---|---|
ClassNotFoundException: com.mysql.cj.jdbc.MysqlDataSource | 缺少 JDBC 驱动 | 检查lib目录是否包含mysql-connector-java-x.x.xx.jar |
Access denied for user 'root'@'localhost' | 用户权限不足或密码错误 | 使用GRANT ALL PRIVILEGES ON forest.* TO 'root'@'%' IDENTIFIED BY 'your_password'; FLUSH PRIVILEGES;授权 |
| 表创建失败 / 语法错误 | 使用了 MySQL 关键字作为表名（如order） | 用反引号包裹关键字，如`order` |
| 图片无法显示 | BLOB 字段类型不匹配或编码错误 | 改为LONGBLOB，并确保插入时使用setBinaryStream或setBytes方法 |
| 时间字段报错 | 时区设置缺失 | 在 JDBC 配置中添加serverTimezone=UTC |
还有一个容易被忽视的问题：字符集。务必使用utf8mb4而非utf8，因为后者在 MySQL 中实际上只支持 3 字节 UTF-8，无法存储 emoji 等 4 字节字符。这也是为什么我们在建库时明确指定了CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci。
当 Forest 应用成功运行在 MySQL 之上时，它不再只是一个“能跑”的演示项目，而是具备了真正投入生产的潜力。这种底层架构的升级，为集成像GLM-4.6V-Flash-WEB这样的高性能多模态模型提供了坚实基础。
想象一下这样的场景：用户上传一张花园照片，系统不仅调用视觉模型识别植物种类，还能结合历史订单推荐相关商品，同时记录完整的审计日志供管理员审查。这一切的背后，都需要一个可靠、高效、可扩展的数据存储引擎来支撑。
一次数据库迁移，看似只是技术栈的调整，实则是系统从“玩具”迈向“工具”的关键一步。它让我们离构建真正智能、可用、可持续演进的 AI 应用又近了一分。
