来源与分类

• 来源渠道：Veeam对接客户现场问题。
• 分类结论：特定升级路径下的卸载残留问题。
• 确认依据：现场先卸载API Proxy 1.0.3，再安装1.0.4时安装失败；沟通中确认1.0.3卸载后可能残留ovirtadapter相关表和失败的数据库迁移记录，并给出了清理语句。未卸载1.0.3时，1.0.4正常升级路径为直接覆盖安装。
• 内部追踪：暂无关联Jira。

问题元数据

• 问题编号：暂无。
• 组件/产品：Veeam API Proxy。
• 状态：已有现场修复方案，仍需在目标环境完成安装和业务验证。
• 优先级/严重程度：高；安装失败会导致Veeam无法通过API Proxy对接平台。
• 受影响版本：已安装并卸载API Proxy 1.0.3，随后安装1.0.4的环境。
• 已确认环境：现场沟通提及ZSphere 5.1.0 h84r，是否与全部受影响现场一致需进一步确认。
• 问题确认日期：2026-08-26。
• 最后更新时间：2026-09-04。

问题描述

API Proxy 1.0.3升级到1.0.4时，正常方式是保留1.0.3并直接安装1.0.4，由安装程序覆盖旧版本。若在升级前先执行本地卸载或远程卸载，卸载过程可能没有完整清理数据库中的ovirtadapter对象。

再次安装1.0.4时，数据库初始化或版本迁移会遇到旧表以及失败的迁移历史记录，导致安装失败。此时重复卸载、重复安装或再次尝试覆盖安装，通常不能自动清除已经形成的数据库残留。

现场沟通涉及以下残留对象：

• zstack.ovirtadapter_snapshot_proxy_attachment；
• zstack.ovirtadapter_snapshot_session；
• zstack.ovirtadapter_schema_history中版本为8或9且success = 0的失败迁移记录。

现象

• 环境原来安装API Proxy 1.0.3，卸载后安装1.0.4失败。
• 本地卸载、远程卸载以及卸载后的覆盖安装均不能恢复。
• 重试安装时反复出现相同的数据库初始化或迁移错误。
• 数据库中仍可查到ovirtadapter_snapshot_proxy_attachment、ovirtadapter_snapshot_session，或者版本8、9的失败迁移记录。

安装界面的具体报错和安装日志关键字需以现场实际输出为准。仅凭“1.0.4安装失败”不能直接执行本文的数据库清理操作。

现场截图

影响

• API Proxy 1.0.4无法完成安装或启动。
• Veeam无法注册、扫描或保护平台虚拟机。
• 反复重试安装可能增加残留状态和现场判断难度。
• 清理对象属于数据库操作；若作用范围判断错误或未保留备份，可能导致配置丢失或无法回退。

规避方案

未卸载1.0.3时的正确升级方式

1. 不要为了升级到1.0.4而先卸载1.0.3。
2. 保存API Proxy当前配置、安装参数和日志，并按1.0.4发布说明完成升级前检查。
3. 直接运行1.0.4安装程序执行覆盖安装。
4. 安装后验证API Proxy进程、服务端口、平台连接以及Veeam虚拟机扫描。

已经卸载1.0.3且1.0.4安装失败时

以下操作包含删除数据库表和记录，必须由熟悉现场环境的数据库管理员或研发人员在维护窗口内执行。执行前必须确认本问题的版本路径和残留对象，并完成可用的数据库备份。不要把该方案用于其他API Proxy版本或无法确认原因的安装失败。

1. 停止重试并收集信息

1. 停止重复运行1.0.4安装程序，保留首次失败和最近一次失败的完整输出。
2. 收集以下信息：

• 平台版本、API Proxy原版本和目标版本；
• 1.0.3的卸载方式和卸载时间；
• 1.0.4安装失败的完整界面截图或终端输出；
• API Proxy安装日志及/opt/api-proxy/logs/api-proxy.log；
• 数据库迁移报错中涉及的表名、版本号和SQL错误。

3. 确认路径确实为“已安装1.0.3 → 卸载1.0.3 → 安装1.0.4失败”。若不是该路径，停止使用本文方案并按实际错误排查。

2. 备份数据库并确认回退能力

1. 对zstack数据库执行完整备份，或按照现场数据库架构创建可验证、可恢复的备份。
2. 记录备份时间、文件位置、校验结果和恢复命令，并确认备份不为空。
3. 确保维护窗口内没有其他API Proxy安装、升级或数据库迁移任务并发执行。
4. 由数据库管理员确认可在出现异常时使用该备份回退，再继续后续操作。

3. 只读检查残留对象

先连接目标管理数据库，仅执行以下只读语句：

SHOW TABLES FROM zstack LIKE 'ovirtadapter_snapshot_proxy_attachment';
SHOW TABLES FROM zstack LIKE 'ovirtadapter_snapshot_session';
SELECT *
FROM zstack.ovirtadapter_schema_history
WHERE version IN ('8', '9');

确认结果满足以下条件：

• 两张ovirtadapter_snapshot_*表属于已卸载的1.0.3实例残留；
• 版本8或9存在success = 0的失败迁移记录；
• 当前没有仍在使用这些表的API Proxy实例；
• 表名、数据库名和现场报错一致。

如果ovirtadapter_schema_history不存在、字段结构不同、版本8或9已经成功，或无法确认两张表是否仍在使用，不要继续删除，联系研发确认。

4. 清理卸载残留

在完成备份并获得现场变更批准后，由数据库管理员执行：

DROP TABLE IF EXISTS zstack.ovirtadapter_snapshot_proxy_attachment;
DROP TABLE IF EXISTS zstack.ovirtadapter_snapshot_session;

DELETE FROM zstack.ovirtadapter_schema_history
WHERE version IN ('8', '9')
  AND success = 0;

上述语句只删除两张已确认的残留表，以及版本8、9中明确失败的迁移记录。不得删除success = 1的成功记录，不得扩大版本范围，也不得删除整个ovirtadapter_schema_history表。

5. 验证清理结果

再次执行：

SHOW TABLES FROM zstack LIKE 'ovirtadapter_snapshot_proxy_attachment';
SHOW TABLES FROM zstack LIKE 'ovirtadapter_snapshot_session';
SELECT *
FROM zstack.ovirtadapter_schema_history
WHERE version IN ('8', '9');

确认两张残留表已不存在，版本8、9中不存在success = 0的失败记录；若存在成功记录，应保持不变。保存执行前后的查询结果用于审计和问题复盘。

6. 重新安装1.0.4

1. 使用正式发布的API Proxy 1.0.4安装包和对应安装说明重新安装。
2. 使用原环境正确的管理节点地址、账号、端口和证书参数，不要沿用失败尝试中未经确认的临时参数。
3. 观察安装输出，确认数据库初始化和版本迁移成功完成。
4. 若仍出现数据库错误，停止重试，保留新日志并联系研发；不要继续删除其他表或迁移记录。

7. 安装后验证

至少完成以下验证：

• API Proxy服务处于运行状态，进程没有反复退出或重启；
• API Proxy监听端口符合当前安装配置，默认场景可检查16443；
• /opt/api-proxy/logs/api-proxy.log中没有新的数据库迁移、表冲突或启动失败错误；
• Veeam可以正常注册或连接平台；
• Veeam能够扫描并列出虚拟机；
• 选择一台测试虚拟机执行备份，并确认任务成功；
• 如业务涉及恢复，再使用测试恢复点完成一次不影响生产的恢复验证。

回退方案

发生以下任一情况时停止操作并回退：清理对象与预期不一致、安装出现新的数据库错误、API Proxy启动异常，或Veeam业务验证失败。

1. 停止API Proxy及正在运行的安装或迁移任务。
2. 保存清理后的数据库状态、安装输出和日志，便于研发分析。
3. 按现场数据库恢复流程，使用操作前创建并验证过的备份恢复zstack数据库。
4. 恢复后检查平台管理服务和数据库状态，确认没有持续运行的失败迁移任务。
5. 联系研发重新评估残留对象和修复范围，未经确认不要扩大DROP或DELETE范围。

注意事项

• 本文中的SQL来自特定现场沟通，只适用于确认的1.0.3卸载残留导致1.0.4安装失败场景。
• 聊天记录中第二张表的SQL在数据库名后出现了空格；本文已按合法对象名整理为zstack.ovirtadapter_snapshot_session，执行前仍须以现场数据库查询结果为准。
• DROP TABLE和DELETE均为破坏性操作，必须先备份、再核验、后执行，并保留执行记录。
• 不要删除版本8或9中success = 1的成功迁移记录。
• 不要仅依据版本号或安装失败现象执行SQL；必须同时核对安装日志、表名和失败迁移记录。
• 正常升级路径是直接覆盖安装1.0.4，不建议先卸载1.0.3。
• 现场聊天没有保留数据库清理后安装和业务验证全部成功的最终结论，因此修复后必须完成本文列出的验证步骤。

受影响产品

• 产品：Veeam集成。
• 产品线：ZVF。
• 组件：Veeam API Proxy安装程序及ovirtadapter数据库迁移。
• 版本：API Proxy 1.0.3卸载后安装1.0.4。
• 触发条件：卸载1.0.3后遗留快照相关表和版本8、9的失败迁移记录，再次安装1.0.4时发生数据库初始化或迁移冲突。

修复状态

• 当前状态：已有现场清理和重装方案，需在目标环境完成验证。
• 推荐升级方式：未卸载1.0.3时直接覆盖安装1.0.4。
• 已卸载后的处理：备份数据库，确认并清理两张残留表以及版本8、9中success = 0的失败迁移记录，再重新安装1.0.4。
• 修复限制：当前聊天记录未提供通用修复脚本，也未记录清理后完整的最终验证结果；不同版本或不同报错不能直接套用。
• 关联补丁/修复包：暂无。

关联信息

• API Proxy日志：/opt/api-proxy/logs/api-proxy.log。
• 关键数据库表：zstack.ovirtadapter_snapshot_proxy_attachment、zstack.ovirtadapter_snapshot_session、zstack.ovirtadapter_schema_history。
• 建议配图：1.0.4安装失败的完整报错、清理前只读查询结果、重新安装成功界面，以及Veeam虚拟机扫描或测试备份成功结果。