1. 概述
为满足客户的新需求以及完善之前版本某些功能的不足之处，FineDataLink在不断地更新迭代。
若需要体验新产品功能或者修复之前版本中存在的一些问题，客户需要将 FDL 升级到当前最新版本。
我们提供升级工具，帮助客户快速升级到指定版本。
| 分类 | 说明 |
|---|---|
| 使用环境 | Windows 或 Linux 操作系统中的独立部署工程/集群工程 |
| 适用版本 | 限制：目标版本需要高于当前版本 |
| 升级包 | 需要联系技术支持获取 |
2. 准备工作
2.1 获取升级包
联系技术支持获取（技术支持联系方式：前往「服务」，选择「在线支持」、电话「400-811-8890」）。
告知技术支持目前工程版本号、将要升级到的工程版本号。
2.2 升级前确认
| 检查项目 | 说明 |
|---|---|
| 是否可停止 Tomcat | 当前节点可以停止 Tomcat 服务 |
| 停机窗口 | 升级期间 Tomcat 会停止，相关业务暂时不可用。未安排停机窗口时不得执行 |
| 磁盘空间 | 机器磁盘空间足够保存工具救援（建议零件 5 GB 以上） |
| 权限 | 当前用户对 FDL 工程目录（如webapps/webroot）具有读写权限 |
| 集群策略 | 集群环境先升级一个节点，验收通过后再处理其他节点 |
| 回退准备 | 不能提前删除下面文件夹：
否则将影响升级失败的回滚 |
3. 上传并解压升级包
3.1 上传文件
把升级包上传到 FDL 服务器的任意目录，比如 tomcat/webapps/webroot 下或 /opt/fdl 下。
3.2 解压文件
3.2.1 解压步骤
macOS / Linux：
unzip 后的文件名需要根据实际情况替换。
unzip fdl-upgrade-delivery-0.1.0_4.2.4.3_to_4.2.18.3.zip
cd fdl-upgrade-orchestrator
3.2.2 核对目录
解压后的目录内容如下：
关键检查项目：
bin/upgrade.sh和bin/upgrade.bat 同时存在。
lib/fdl-upgrade-orchestrator-0.1.0.jar 存在。
manifest/checksums.txt 存在。
packages/<目标版本>/lib/ 目录下有 30 个左右的 jar（fdl-*.jar）。
注：如果缺 packages、manifest/checksums.txt 或 lib/*.jar，不要继续，联系技术支持重新提供升级包。
4. 进行升级
4.1 启动工具
4.1.1 macOS / Linux
1）首次执行前需赋予用户 bin/upgrade.sh 的执行权限（chmod 755）。
chmod 755 bin/upgrade.sh
2）再执行bin/upgrade.sh语句。
现场升级通常选择1；2 用于在多个工程场景下单独确认哪一个是 FDL 工程；3 用于查看本次升级会跑几个版本节点。
4.1.2 Windows
1）建议优先使用 Windows Terminal / Windows PowerShell 工具。
2）进入 fdl-upgrade-orchestrator 目录，执行bin\upgrade.bat语句。
现场升级通常选择1；2 用于在多个工程场景下单独确认哪一个是 FDL 工程；3 用于查看本次升级会跑几个版本节点。
4.2 执行完整升级并填写输入项
4.2.1 完整升级
| 输入项 | 默认值/回车即可 | 特别说明 |
|---|---|---|
| 升级交付包根目录 | 当前工具所在目录 | 几乎不用改 |
| FDL工程目录 | 回车自动向上识别 | 放置了非常规路径、或工具识别错误时手动指定/path/to/tomcat/webapps/webroot（或WEB-INF、WEB-INF/lib） |
| 目标版本 | 从manifest/versions.json自动粘贴 | 不要手改；不一致会立即报错 |
| Tomcat 根目录 | 从工程目录向上查找bin/conf/webapps | 自动识别失败时手动指定，比如 /opt/fdl/tomcat |
| 可达性访问地址 | 根据conf/server.xml和应用路径生成 | 端口、context path、代理、servlet 路径被客户改过 |
| 产品日志路径 | tomcat/logs下的fanruan.log | 客户修改了fanruan.log输出位置时指定文件路径或所在目录 |
4.2.2 升级前预检
工具会依次校验：交付包 checksum、工程识别、FineDB 检查、Tomcat 识别、版本包检查、备份目录磁盘空间。
磁盘空间检查会估算 WEB-INF、WEB-INF/lib 和内置 FineDB 备份所需空间；备份目录所在磁盘不足时会直接阻断升级。
全部通过后让你二次确认：
升级前检查已完成，确认开始执行完整升级？ 请输入 y 开始，输入 n 取消：
输入 y 才会开始真正修改文件。输入 n 或直接关闭工具，等价放弃本次升级。
4.3 执行升级
4.3.1 强制结束 Tomcat
如果检测到 Tomcat Java 进程仍在运行，工具会先打印 PID，让你输入 kill 确认后才会执行：
macOS / Linux：kill -9 <PID>
视窗：taskkill /PID <PID> /T /F
4.3.2 备份+替换JAR
工具会依次：
创建工具应急备份（emergency-backups/<时间戳>）。
备份WEB-INF。
备份WEB-INF/lib。
备份 / 登记 FineDB 备份信息。
删除旧fdl-*.jar、、fine-*.jar。fineapp-dp-jar-with-dependencies*.jar
从交付包复制当前节点版本jar到WEB-INF/lib。
启动Tomcat。
4.3.3 查看升级进度
会显示升级进度和最近 10 条的 fanruan.log。
如果当前终端支持 ANSI 动态刷新，工具会原地刷新。终端不支持时（比如某些IDE的运行窗口）会自动降级为静态日志模式，并提示查看 fanruan.log 的命令。
根据实际情况修改语句中的路径地址。
1）Linux 系统查看日志：
tail -n 10 -f /opt/fdl/tomcat/logs/fanruan.log
2）Windows PowerShell 查看日志：
Get-Content -Path "C:\fdl\tomcat\logs\fanruan.log" -Tail 10 -Wait
3）Windows CMD
powershell -NoProfile -Command "Get-Content -Path 'C:\fdl\tomcat\logs\fanruan.log' -Tail 10 -Wait"
4.3.4 处理等待超时
工具默认在等待约 3 分钟后提供人工选择。按以下标准处理：
| 情况 | 建议选项 |
|---|---|
| FineDB版本已匹配或可信日志命中FDL start success!，且人工访问确认任务/连接/调度正常 | 1 确认成功并继续 |
| fanruan.log接下来持续输出升级日志 | 2 继续等待一个等待窗口 |
| HTTP 已可访问但内置 HSQL 运行中无法读取库，需要确认 FineDB 版本 | 3 停止Tomcat并读取FineDB版本 |
| 出现异常堆栈、多次失败或不确定 | 4 中断结束，联系升级专家 |
| FineDB版本无法判断或长期未匹配，但人工检查日志和工程密封性确认正常 | 谨慎选 1 |
4.3.5 中间节点 VS 目标节点
多版本节点升级完后工具会按PID检测并要求kill确认，进入下一个节点；最后一个节点（目标版本）升级完后，工具保持Tomcat运行并结束流程，由您登录产品验收。
5. 登录产品
工具提示完成后，按顺序查看：
登录产品，确认能正常进入首页/注册管理/任务列表。
检查任务、连接、调度、数据服务等关键功能。
检查fanruan.log是否还有启动或升级异常（关键字速查见本文 6.2 节内容）。
集群场景：当前节点采集通过后，再按客户集群发布流程处理其他集群。
确认工具日志logs/upgrade.log中没有失败记录。
6. 内容扩展
6.1 失败处理
工具失败时会打印：失败原因、工具日志文件路径、工具救援备份目录。处理顺序：
先停止Tomcat。
确认没有占用Java进程占用当前工程（ps -ef | grep java/ 任务管理器）。
查看工具日志logs/upgrade.log和tomcat/logs/fanruan.log。
不要继续升级，也不要自行处理工具事故备份目录。
优先按产品功能备份或客户现场备份方案恢复。
保留工具日志、产品日志、，emergency-backups联系升级专家处理。
6.1.1 HSQL锁文件提示
使用内置 FineDB 时可能跳出 *.lck / *.lock / sql.lock 锁文件提示。处理原则：
先停止 Tomcat。
确认没有 Java 进程占用当前工程。
确认已通过产品功能或客户现场方案完成备份。
只有确认锁文件是异常退出残留时，才允许人工删除锁文件。
删除后回到工具按回车重试。
注：不要在 Tomcat 仍在运行时删除锁文件。
6.1.2 交付包完整性失败
如果提示 交付包完整性校验失败，禁止继续升级：
不要继续升级。
确认交付包是否被修改、解压是否完整。
联系技术支持重新提供交付包。
6.1.3 当前版本已无需升级
出现当前版本：4.2.18.3 / 目标版本：4.2.18.3 / 升级路径：无需升级时说明工程 jar 已经是目标版本，不需要继续。如果只是自测要回到旧版本，应重新部署旧工程或按产品备份方案恢复，不要继续走完整升级。
6.2 常见错误关键字速查表
| 关键字/现象 | 含义 | 建议动作 |
|---|---|---|
| 交付包完整性校验失败 | checksum 不一致，交付包被破坏 | 停止升级，联系专家重新提供 |
| 不支持降级 | 目标版本 ≤ 当前版本 | 改用产品备份方案回退 |
| 未找到目标版本 ... 的升级包 | OSS 缺该目标版本的代表来源文件 | 把错误消息截图发回 caster |
| FineDB 连接失败 | 内置 HSQL 启动失败 / 锁文件残留 | 先停 Tomcat，按 §9.1 处理锁文件 |
| 等待产品启动超时 | 10 分钟未命中 FDL start success!，且 FineDB 版本不可读 | 保留 logs/upgrade.log、fanruan.log、emergency-backups，联系专家 |
| FDL start success! 仍未出现 | 当前节点 jar 替换不完整或 Tomcat 未真正起来 | 检查 fanruan.log 异常堆栈 |
| checksum / 版本包缺失 | 交付包内文件损坏或不全 | 联系专家重做交付包 |
已停止业务写入后输入其他内容 | 取消本次升级 | 可重新执行 1 重来 |
6.3 什么时候必须联系技术支持
交付包 checksum 失败。
版本包缺失（OSS 找不到对应代表来源文件）。
自动识别出的当前版本和客户记录不一致。
多个候选工程无法判断。
FineDB 连接失败且原因不清晰。
HSQL 锁文件无法判断是否残留。
Tomcat 启动失败且 fanruan.log 有异常堆栈。
需要升级非 Tomcat 容器。
需要集群分发但客户现场方案不明确。
上一篇：多产品连接工具插件
