PowerJob历史版本升级指南：从4.x到5.x平滑迁移方案

1. 升级前准备工作

1.1 环境检查清单

检查项	最低要求	推荐配置
JDK版本	8+	11+
MySQL版本	5.7+	8.0+
MongoDB版本	4.0+	5.0+
内存	2GB+	4GB+
磁盘空间	10GB+	50GB+

1.2 备份策略

# 数据库备份示例
mysqldump -u root -p powerjob > powerjob_backup_$(date +%Y%m%d).sql

# 配置文件备份
cp -r /path/to/powerjob/conf /path/to/powerjob/conf_backup_$(date +%Y%m%d)

2. 版本升级路径规划

2.1 升级路线图

timeline
    title PowerJob版本升级时间线
    2022-01 : v4.0.x发布
    2022-06 : v4.1.x发布
    2022-12 : v4.2.x发布
    2023-06 : v4.3.x发布
    2023-12 : v5.0.x发布

2.2 推荐升级路径

flowchart LR
    A[v4.0.x] -->|执行v4.0.x-v4.1.x.sql| B[v4.1.x]
    B -->|执行v4.1.x-v4.2.x.sql| C[v4.2.x]
    C -->|执行v4.3.7-v4.3.8.sql| D[v4.3.8]
    D -->|执行v4.3.x-v5.0.x.sql| E[v5.0.x]

3. 数据库升级步骤

3.1 自动升级方案

# 5.x版本Server自动建表功能
java -jar powerjob-server.jar --spring.datasource.url=jdbc:mysql://localhost:3306/powerjob_test \
--spring.datasource.username=root --spring.datasource.password=123456

3.2 手动升级方案（以v4.3.x到v5.0.x为例）

1. 执行官方提供的SQL脚本

-- 执行v4.3.x到v5.0.x的升级SQL
source others/sql/upgrade/v4.3.x-v5.0.x.sql

2. 主要表结构变更说明

-- app_info表新增字段
ALTER TABLE `app_info` ADD COLUMN `creator` bigint NULL DEFAULT NULL;
ALTER TABLE `app_info` ADD COLUMN `extra` varchar(255) NULL DEFAULT NULL;
ALTER TABLE `app_info` ADD COLUMN `modifier` bigint NULL DEFAULT NULL;
ALTER TABLE `app_info` ADD COLUMN `namespace_id` bigint NULL DEFAULT NULL;
ALTER TABLE `app_info` ADD COLUMN `tags` varchar(255)  NULL DEFAULT NULL;
ALTER TABLE `app_info` ADD COLUMN `title` varchar(255)  NULL DEFAULT NULL;

-- 新增命名空间表
CREATE TABLE `namespace`  (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `code` varchar(255)  NULL DEFAULT NULL,
  `creator` bigint NULL DEFAULT NULL,
  `dept` varchar(255)  NULL DEFAULT NULL,
  `extra` varchar(255)  NULL DEFAULT NULL,
  `gmt_create` datetime(6) NULL DEFAULT NULL,
  `gmt_modified` datetime(6) NULL DEFAULT NULL,
  `modifier` bigint NULL DEFAULT NULL,
  `name` varchar(255)  NULL DEFAULT NULL,
  `status` int NULL DEFAULT NULL,
  `tags` varchar(255)  NULL DEFAULT NULL,
  `token` varchar(255)  NULL DEFAULT NULL,
  PRIMARY KEY (`id`) USING BTREE,
  UNIQUE INDEX `uidx01_namespace`(`code` ASC) USING BTREE
) ENGINE = InnoDB AUTO_INCREMENT = 2 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_0900_ai_ci ROW_FORMAT = Dynamic;

3.3 数据迁移注意事项

1. 命名空间（Namespace）概念引入

   • v5.x新增多租户隔离机制
   • 需为现有应用分配默认命名空间

2. 用户权限系统变更

   • 新增pwjb_user_info和user_role表
   • 原用户数据需迁移至新表结构

4. 应用程序升级指南

4.1 依赖更新

<!-- Maven依赖更新 -->
<dependency>
    <groupId>tech.powerjob</groupId>
    <artifactId>powerjob-worker-spring-boot-starter</artifactId>
    <version>5.0.0</version>
</dependency>

4.2 配置变更

旧配置项	新配置项	说明
powerjob.appName	powerjob.worker.app-name	应用名称配置
powerjob.port	powerjob.worker.akka-port	通信端口配置
powerjob.serverAddress	powerjob.worker.server-address	服务端地址配置

4.3 代码变更

4.3.1 已废弃API替换

// 旧版代码
PowerJobWorker worker = new PowerJobWorker();
worker.setAppName("demo-app");
worker.setServerAddress("127.0.0.1:7700");
worker.start();

// 新版代码
PowerJobWorkerConfig config = new PowerJobWorkerConfig();
config.setAppName("demo-app");
config.setServerAddress(Arrays.asList("127.0.0.1:7700"));
PowerJobWorker worker = new PowerJobWorker(config);
worker.init();

4.3.2 处理器类型变更

// 旧版处理器类型
@Deprecated
ProcessorType.JAVA

// 新版处理器类型
ProcessorType.BUILT_IN

4.4 启动类变更

// 初始化代码示例
PowerJobWorkerConfig config = new PowerJobWorkerConfig();
config.setAppName("your-app-name");
config.setServerAddress(Arrays.asList("server1:7700", "server2:7700"));
config.setPort(27777);

PowerJobWorker worker = new PowerJobWorker(config);
worker.init();

5. 升级后验证

5.1 服务验证

# 检查服务日志
tail -f logs/powerjob-server.log | grep "PowerJobWorker initialized successfully"

5.2 功能验证清单

1. 登录管理控制台，确认基础数据显示正常
2. 创建测试定时任务，验证任务调度功能
3. 执行工作流任务，验证依赖关系处理
4. 检查监控指标，确认数据采集正常

5.3 常见问题排查

1. 数据库连接失败

   • 检查JDBC连接串是否正确
   • 确认数据库用户权限是否足够

2. 服务端启动失败

   • 检查端口是否被占用
   • 验证数据库表结构是否完整

3. 任务执行异常

   • 检查处理器类是否正确加载
   • 确认worker与server网络连通性

6. 高级升级场景

6.1 多版本并存方案

flowchart TD
    Client[客户端请求] -->|路由策略| NGINX[负载均衡]
    NGINX -->|部分流量| V4[4.x集群]
    NGINX -->|部分流量| V5[5.x集群]
    V4 --> DB[(共享数据库)]
    V5 --> DB

6.2 数据迁移工具

# 使用官方提供的数据迁移工具
java -cp powerjob-server.jar tech.powerjob.server.migrate.DataMigrationTool \
--from 4.3.8 --to 5.0.0 --jdbc-url jdbc:mysql://localhost:3306/powerjob \
--username root --password 123456

7. 回滚方案

# 数据库回滚
mysql -u root -p powerjob < backup_before_upgrade.sql

# 应用回滚
cd /path/to/old_version
./bin/start.sh

8. 总结与注意事项

8.1 升级关键点

1. 数据库备份必须完整
2. 按顺序执行升级脚本
3. 配置文件需同步更新
4. 代码中已废弃API需替换

8.2 最佳实践

1. 先在测试环境验证升级流程
2. 生产环境建议灰度升级
3. 升级窗口预留足够时间
4. 准备完整回滚方案

8.3 后续版本规划

1. 关注官方发布的升级公告
2. 定期检查已废弃API使用情况
3. 参与社区讨论获取升级经验