适用对象与开始前准备
本文面向已经部署商城、通过商城后台更新系统或插件的管理员。这里的 Agent 是在服务器上执行任务的程序，本文不是 Agent 自身升级教程。
第一次接入服务器或首次安装失败，请先看自动部署错误原因与处理。不要用首次安装去覆盖一个正在运行的商城。
更新前准备好：
- 可登录的商城管理员账号及相应更新权限。
- 仍有效且包含更新权益的系统授权；更新插件还需要对应插件权益和安装状态满足条件。
- 在线的服务器 Agent、正常的 DNS/出站 HTTPS，以及足够容纳程序包和数据库备份的磁盘。
- 可用的独立数据库和文件备份，以及低业务量的维护时段。
更新可能重启服务；失败后的数据库恢复也可能覆盖备份之后的新数据。请安排维护并减少新增订单等写入，不要把自动回滚当作“业务零影响”的承诺。
从哪里看任务
| 要处理的内容 | 入口 |
|---|---|
| 商城系统程序更新 | 自己的商城后台 /admin/ → “系统维护 → 更新中心” → “更新历史” |
| 插件版本更新 | 自己的商城后台 → “插件中心” → “更新记录”中的“版本更新记录” |
| 插件首次安装或启停等操作 | “插件中心 → 更新记录”中的“安装与操作记录”，不要混同于版本更新 |
| Agent 是否接入 | 官网客户控制台 → “交易与交付 → 服务器” |
系统更新历史可点“查看详情”；进行中的任务可点“刷新”。官网“安装任务”里的“重试安装”不是商城更新重试入口。
先按这五步处理
- 找到发生问题的那条任务，记录任务编号、源版本、目标版本、时间、状态、错误详情。页面没显示错误码时，提供原文和任务编号即可。
- 若任务仍在更新或回滚，先等待并刷新，不要同时重启、再次更新或手工切换文件。
- 若尚未创建任务，检查授权、Agent 和“可用更新”；按下一节处理提示。
- 若已失败，按失败阶段查原因。能自行确认的是网络、域名、时间和磁盘；包签名、数据库迁移、版本基线及回滚问题交给支持。
- 根据最终状态验收。需要再次执行时，让平台确认可用的后续任务或修订版本，不要反复点同一版本期待重跑。
重复点击同一目标版本，会恢复原任务的进度跟踪，包括已经失败或已回滚的任务，不会自动新建一次更新。 当前更新历史没有通用的“重新执行失败任务”按钮。
没有可用更新，或还没开始就被拦截
| 提示或现象 | 如何理解与处理 |
|---|---|
| 没有可用更新、显示“已是最新” | 表示当前实例没有可获取的更新，不等于平台没有更新版本。还会受套餐兼容、源版本范围、灰度范围和发布暂停状态影响 |
agent_offline | Agent 最近未在线。先查官网服务器状态和实际服务，不要新建授权 |
license_inactive、license_expired、updates_not_allowed | 授权状态、期限或更新权益不满足要求。到官网核对授权及续费 |
product_version_disabled | 对应版本的运行开关被停用，联系平台。单纯停止新销售不应等同于停用已有授权 |
update_already_running | 同一实例存在安装、更新或尚未解除的人工处理任务，先处理原任务 |
instance_version_mismatch | 本机版本和平台记录不一致。先刷新状态；持续出现交支持核对，不要手工改版本号 |
instance_unauthorized | 实例身份、授权凭据、绑定域名或实例状态不匹配，交支持核对原安装记录 |
update_center_unconfigured | 商城尚未完成更新中心所需的实例配置，不是要求你购买第二份系统 |
update_service_unavailable | 商城暂时无法连接控制中心。检查出站 HTTPS、DNS 和时间，持续出现交支持 |
| 插件不能更新 | 核对插件授权、安装状态、适用商城版本、依赖和冲突。不能只看系统授权是否正常 |
| 夜间没有自动更新 | 开启夜间策略也只执行平台允许自动更新、且当前实例符合条件的版本；需要手动确认的版本不会因此被强制安装 |
读懂状态和阶段
| 状态或阶段 | 正在做什么 | 你应该做什么 |
|---|---|---|
queued 等待执行 | 等 Agent 领取 | 确认在线，等待；长时间不动则反馈任务编号 |
prechecking 环境检查 | 检查包描述、版本格式、磁盘和实例环境文件等 | 根据具体错误修复，不要改版本记录 |
downloading 下载安装包 | 下载任务固定的程序包 | 检查 DNS、HTTPS、时间和下载源 |
verifying 校验安装包 | 核对大小、哈希、签名，准备目标版本目录 | 校验异常交平台，不能跳过 |
backing_up 备份中 | 确认当前版本指针并备份实例数据库 | 等待；失败时不会进入后续迁移 |
migrating 数据迁移 | 执行安装包声明的数据库迁移 | 不要手工补 SQL；失败后观察回滚 |
switching 切换版本 | 切换程序指针；系统更新还会处理服务、Nginx 和 HTTPS | 可能短暂中断，等待结果 |
health_checking 健康检查 | 检查系统或插件健康接口 | 等待结果，不要只凭首页能打开判断 |
rollbacking 正在回滚 | 尝试恢复数据库和上一版本运行状态 | 不要干预文件或服务 |
succeeded 更新成功 | 本次任务执行成功 | 刷新版本并验证业务 |
failed 更新失败 | 任务在进入迁移前失败 | 查原因；并不自动重跑，也不代表没有下载或生成文件 |
rolled_back 已自动回滚 | 更新未成功，回滚流程完成 | 核对原版本、登录和业务数据，反馈原错误 |
manual_intervention 需要人工处理 | 自动回滚没有完成 | 停止进一步变更，立即联系支持 |
失败、已回滚、需要人工处理也可能显示 100%。判断依据是状态和实际访问结果，不是百分比。
按错误阶段排查
update_prechecking_failed：环境或包参数不符合要求
常见详情包括版本格式不正确、包地址或大小异常、公钥配置无效、环境文件缺失、数据库连接串字段缺失或重复、磁盘不足。
先确认目标是平台提供的正式更新，并检查服务器磁盘。环境文件和发布公钥交管理员核对，不要把文件内容发到工单。
技术边界：此阶段读取数据库配置不等于已经成功连接数据库；旧版本 current 指针等问题通常还会在“备份中”暴露。旧式目录布局需经支持评估迁移，不能自行改一个文件夹名字冒充新布局。
update_downloading_failed：下载未完成或文件大小不符
核对服务器 DNS、出站 HTTPS、系统时间。HTTP 404/5xx 或下载字节数与任务快照不符时，由平台核对下载源和发布文件。
不要关闭 TLS 校验，也不要自行下载其他版本替换缓存。更新任务固定了包的快照，平台改了商品资料不代表原任务会自动使用新文件。
update_verifying_failed：完整性或目录验证失败
可能是 SHA-256、Ed25519 签名、包大小不匹配，或解包后的目录结构、入口文件不符合要求。
由平台核对正式构建产物、签名和发布快照。包描述格式、身份不符也可能在更早的环境检查阶段失败，因此应看错误详情，不要只按错误码猜原因。不要修改校验值或让 Agent 信任来源不明的公钥。
update_backing_up_failed：当前版本或数据库备份异常
可能是 current 未指向任务记录的原版本、目标版本未准备好、mysqldump 不可用、数据库无法连接或无备份权限，以及空间不足或备份为空。
先由管理员核对当前实际版本、数据库服务、工具和权限。备份没有完成时，流程不会继续执行本次迁移。不要删除旧版本、备份目录或直接修改平台版本号来跳过这一关。
update_migrating_failed：数据库迁移失败
可能是迁移文件异常、SQL 与数据库版本或现有结构不兼容，或账户没有所需权限。任务会尝试自动回滚，等待最终结果。
由平台在隔离环境复现并处理后续发布。不要在生产库执行网上找到的修表语句，也不要手工补半段 SQL 后继续原任务。
update_switching_failed：切换或启动失败
系统更新可能遇到服务模板、目录权限、Nginx 冲突、程序启动或证书问题。插件更新主要切换对应插件目录，不能把所有切换错误都当成 Nginx 故障。
| 常见详情 | 核对内容 |
|---|---|
systemd template does not use managed current link and environment file | 平台核对包内服务模板，不由客户改发布包 |
nginx server name is already configured | 管理员核对同域名的另一份站点配置，不删除整个配置目录 |
Baota ACME request failed | 公共 DNS、外网 80、CDN 代理、宝塔 ACME 模块和证书机构限制 |
managed certificate is expired or does not match domain | 系统时间、证书域名及剩余有效期，激活检查要求至少覆盖未来约 7 天 |
HTTPS health endpoint did not become ready | 本机 443、可信证书链、Nginx 与商城服务 |
等待回滚结果，保留原错误。不要在任务切换或回滚时手工替换证书、修改受管配置或重启整台服务器。
update_health_checking_failed：服务未通过健康检查
系统更新通过本机 Socket 检查商城健康接口；插件更新检查该插件声明的健康接口。需要 HTTP 200 且响应状态为 ok。
可能是进程没有正常启动、没有监听预期 Socket、数据库异常或插件健康接口异常。由管理员核查该任务对应的服务日志，等待自动回滚；浏览器首页能打开也不能替代这项检查。
update_rollback_failed：自动恢复没有完成
任务会进入 manual_intervention。可能数据库恢复失败、旧版本标记或文件不完整、旧服务无法启动，或 Nginx 无法恢复。
立即停止继续安装、更新和手工改文件，联系支持保全现场并评估恢复。不要删除 current、版本目录、备份或数据库，也不要将任务强行标记成功。
此时不能因为首页偶尔能打开就认定安全恢复。由支持核对任务与实例、备份和版本的一致性后，再安排恢复及验收。
更新成功或回滚后的验收
更新成功时：
- 等待页面重新加载，或重新登录商城后台，确认当前系统版本已变为目标版本。
- 插件更新则在“插件中心”核对对应插件版本和状态，不能只看商城系统版本。
- 从外网检查 HTTPS 首页、后台登录、关键页面和已有订单读取；核对所需插件功能。
- 检查更新历史没有新的失败或人工处理任务，并继续观察日志和业务情况。
已回滚时，目标版本没有安装成功。核对原版本能运行、关键数据无异常，将更新失败原因交给支持。备份之后产生的订单或其他写入需要专门核对，不能只检查页面。
技术说明与只读诊断
以下内容给服务器管理员，普通用户提供任务编号即可。
- 更新包要求
format: 2、layout: versioned，版本号为三个数字段，如1.2.3。套餐编号和商城程序版本不是同一个字段。 - 新版本首次安装已支持相同的分版本布局；不能再把所有首次安装都描述成旧式直铺目录。
- 预检查要求程序目录和工作目录所在文件系统各有至少“包大小 × 3 + 512 MiB”的可用空间。这是门槛，不含对大数据库备份容量的充分估算。
- 默认实例环境文件为
/etc/kasuteng-mall/<实例ID>.env，含敏感连接信息。只核对存在性和权限，不公开内容。 - 实例可能使用域名目录，也可能位于域名下的
instances/<实例ID>；插件有自己的组件目录和版本指针。实际位置以任务和服务配置为准，不要机械套用一个路径。 - 备份涵盖实例数据库，并记录原版本位置，不是整台服务器的文件备份。迁移之后失败会尝试恢复数据库、原版本及对应运行配置；文件备份仍须另行安排。
- 商城程序启动时还会应用内嵌的未执行迁移，相关错误可能表现为切换或健康检查失败，并不一定都出现在
migrating阶段。 - 系统激活会检查证书并在需要时申请，本机 HTTPS 检查连接的是
127.0.0.1:443，使用实际域名验证证书。它不验证外部安全组已放行，也不能当作持续自动续签保证。
可先执行这些只读检查：
date -Is
df -h /www /var/lib
systemctl is-active kasuteng-agent.service
systemctl status kasuteng-agent.service --no-pager
journalctl -u kasuteng-agent.service -n 100 --no-pager
/www/server/nginx/sbin/nginx -t商城服务名和实例目录由管理员按具体任务确认，再查看对应日志。不要批量停止服务、输出整份环境配置，或把 SQL 备份上传公开位置。
提交工单时附任务编号、实例编号、源/目标版本、错误时间、状态及必要的脱敏日志。不要附 root 密码、Token、一次性接入命令、授权密钥、数据库连接串、证书私钥、支付密钥或带签名参数的下载地址。