先查看原任务
错误码以实际任务响应为准。到官网“交易与交付 → 安装任务”查看原请求的状态、阶段、错误码和子任务。失败、需要人工处理或结果不明时，不要另建商城覆盖原目录。
| 现象 / 错误 | 处理 |
|---|---|
| 进度到了 5% 后失败 | 只表示开始连接等前置步骤；以错误码判断，不能认定 SSH 已登录或升级命令已执行 |
invalid_ssh_password | 输入未满足长度要求。本版密码范围为 6～256 个字符；不要自行删改或去除原密码的空格，格式通过后仍需真实 SSH 认证 |
ssh_auth_failed / Permission denied | 服务器拒绝 root SSH 密码认证。核对公网 IP、端口、账号、密码及登录策略；宝塔密码不能替代 SSH 密码 |
ssh_unreachable / ssh_unavailable | 核对服务器状态、端口、来源白名单和网络；平台连接服务异常交支持核对 |
host_key_changed | 服务器指纹发生变化；先核实是否重装或 IP 变更，不能忽略校验 |
agent_signature_invalid | Agent 版本清单、签名或受信任公钥检查失败。保留原任务，由平台核对该版本的完整制品及签名配置；不要关闭验签、修改已发布包或在服务器手工绕过安装 |
agent_upgrade_consent_required | 此版需要先升级 Agent，阅读说明后在更新窗口确认短暂停止旧 Agent |
agent_upgrade_credentials_required | 按更新窗口提示重新填写本次 SSH 凭据；不要通过聊天提供密码 |
agent_upgrade_remote_unknown | 远端执行状态不明；保留恢复副本和服务器占用，由支持核对，不自动重复执行 |
| Agent 版本不足 / 离线 | 先检查原 Agent 和受支持升级路径，不要反复提交新的安装任务 |
正常安装由页面完成连接和认证。只有认证失败需要进一步排查时，才由熟悉终端的用户或技术支持在自己的电脑执行以下命令，替换真实 IP 和端口；不熟悉命令的用户可保留错误码，按云控制台说明核对资料：
ssh -o PubkeyAuthentication=no -o PreferredAuthentications=password root@服务器公网IP -p 22输入密码时不显示字符。若依然 Permission denied，通过云服务器控制台核对或重置 服务器 root SSH 密码，实际登录成功后再回更新窗口填写。不要发送密码。
商城“检测更新”中的重新填写密码，与“自动部署记录”的原任务重试是不同流程。自动部署重试沿用尚有效的保存资料；服务器改密后不要反复重试旧凭据，应先由支持核对原记录和接入方式。
环境与数据保护
| 错误 / 状态 | 处理 |
|---|---|
unsupported_os / unsupported_arch | 核对 Linux 与 amd64 架构。缺少组件时，自动补齐方案另外仅覆盖 Ubuntu 22.04 / Debian 12；CentOS 空环境不能靠重试自动补齐 |
baota_panel_required | 当前任务没有可用的宝塔环境方案。普通 Ubuntu 22.04 / Debian 12 空机请联系平台核对签名方案及任务版本；其他系统先确认支持范围，不要反复重装或自行绕过检查 |
systemd_missing / environment_tools_missing | 核对 systemd，以及 Python 3、curl、sha256sum、flock。先补齐基础工具再重试原任务；进度开始不代表已执行组件安装 |
environment_panel_runtime_missing | 宝塔 Python 运行环境缺失或损坏，由服务器管理员核对 |
environment_path_unsafe | 路径、归属、权限或符号链接不符合保护要求；核对原内容，不能直接清空目录 |
environment_reconcile_required | 检测到原服务异常、已有数据库冲突或未完成的环境变更；保留现场，由支持核对 |
environment_install_failed / environment_verify_failed | 环境步骤失败或未通过复查；保留服务器上的私有执行记录，修复原因再决定重试 |
environment_recipe_incomplete / environment_recipe_invalid | 平台固定环境方案缺少组件或格式错误，由平台修订并验收方案；不要求客户修改签名包 |
environment_checksum_failed / environment_source_invalid | 组件校验或来源检查失败，已停止安装。由平台核对固定制品，不能关闭验签或改用未知下载地址 |
environment_download_failed | 下载服务未能连接、返回错误状态或传输中断。先核对服务器 DNS、出站 HTTPS、网络代理及平台服务状态；保留原任务。已有不完整下载或安装记录时由支持核对后继续，不要另建商城或清空目录 |
environment_tls_verification_failed | HTTPS 证书验证失败。核对服务器时间、可信根证书和 DNS 解析；不要关闭证书验证、忽略证书错误或改用 HTTP 下载 |
deployment_environment_busy | 服务器已有环境操作在执行，等待原操作并核对其结果，避免并行安装 |
existing_environment_conflict | 已有服务或目录与环境方案冲突，先核对归属、业务和备份，不覆盖原服务 |
environment_resources_insufficient | 空机安装需要至少 2GB 内存、系统分区至少 8GiB 可用空间。先扩容或核对可以安全清理的内容，再重试原任务；不要删除数据库、商城目录或已有备份来勉强通过 |
environment_package_state_invalid | 系统存在未完成或异常的软件包操作。保留原任务，由服务器管理员处理软件包状态；不要并行运行另一套安装程序 |
environment_packages_failed | 系统依赖准备失败。先核对软件源、服务器网络和其他软件包操作是否已经结束，再点击原任务的“重新尝试”。系统会核对是否可以安全继续；若随后提示需要人工核对，请保留现场联系支持，不要删除锁文件或安装记录 |
environment_tls_configuration_unsafe | 系统下载工具被配置为跳过 HTTPS 证书验证。由管理员恢复正常验证并检查可信根证书，再重试原任务；不要沿用关闭验证的配置 |
baota_mysql_credential_unavailable | 宝塔本机 MySQL 管理凭据、Socket 或环境不可用；不要把数据库密码填入官网或发送工单 |
disk_space_insufficient | 扩充磁盘并保留商城、数据库、上传文件及备份所需空间；接入的最低检查值不是运营配置建议 |
| 证书申请达到签发限额 | 等待提示的机构限额恢复时间，再重试原商城安装任务。UTC 时间加 8 小时为北京时间；保留已有证书，不要反复重装或删除证书 |
| 证书域名验证失败 | 核对全部 A/AAAA 记录、网站公网 TCP 80、云端与系统防火墙；证书验证地址应能直接到达当前服务器，修正后重试原任务 |
| 证书申请失败，原因不明 | 记录原任务编号与时间，核对 DNS、公网 TCP 80 和服务器出站 HTTPS，由技术支持检查私有证书申请日志；不要关闭证书验证 |
已有 Nginx 或数据库不会为通过安装而被自动重置。新建商城数据库支持 MySQL 5.7/8.0，自动补齐固定 MySQL 8.0.45。
若出现 runtime environment changed after credential delivery; refusing to overwrite，表示当前运行配置与该任务已交付的凭据记录不一致。应保留配置、原始备份和任务检查点，由支持核对变化来源；不要删除或重写检查点来绕过保护。原 Agent 0.3.15 在首装失败后再次清理已经不存在的服务时，可能附带 Unit file ... does not exist 和回滚失败提示；这是已登记的重复清理提示问题，不能只凭这一句认定数据库已损坏，也不能据此认定已安全恢复。须核对前面的主错误、实际服务状态和数据。
域名、授权与任务冲突
核对全部 A/AAAA 解析、公网 TCP 80/443、证书验证和实际域名归属；具体放行方法见安装前放行端口。域名无限、分站额度、安装实例额度不是同一项。
- 授权失效、到期或额度不足：先到“系统授权”处理对应状态。
- 服务器已接入：使用原服务器记录，Agent 在线时从“在已有服务器上安装”继续。
- 任务正在执行：等待原任务，不重复部署。
- 等待设置管理员：由官网原授权账户领取初始化入口，不能直接以访客身份初始化。
- 链接到期或结果不明：回原任务核对并按页面提供的入口继续，不新建第二个管理员。
- 需要人工处理：保留任务编号、版本、错误码和时间，等待核对；不绕过锁、签名或恢复检查。
初始化超时与结果待核对
core_request_timeout 表示当前请求未能及时取得控制中心响应，不证明服务端未提交。保留原入口和原请求，先使用页面的结果核对功能。若接口返回 HTTP202，且显示管理员已创建、提交仍待核对，应继续核对原结果；不要创建新管理员，也不要删除原商城或重新部署。
deployment_revision_conflict 表示领取初始化入口时部署状态已经变化。刷新原任务，再使用它提供的领取入口；不要自行拼接链接或修改版本号。若管理员已经创建而仍显示待核对，由支持核对原商城回执和控制中心记录，不能靠改数据库状态制造交付成功。
宝塔资料领取与补领
| 提示 / 错误码 | 处理方法 |
|---|---|
invalid_current_password | 输入官网当前登录密码，不是商城后台或 root 密码；忘记时先恢复官网账户 |
panel_access_ssh_required | 原 SSH 资料已过期、删除或无法解密；在领取窗口重新填写官网密码和 root 密码，只读补领，不会保存此次 root 密码 |
panel_access_not_ready | 环境尚在准备，等待原任务推进；不重复创建安装 |
panel_access_not_available | 未保存本平台生成的初始资料，或尚无已核验的 SSH 主机指纹；自行安装的宝塔继续使用原账号，必要时从云控制台使用 bt 工具处理 |
panel_access_read_failed | 检查服务器 SSH 端口、root 密码及连接；主机指纹变化时先核对是否重装或更换了服务器，不绕过主机校验 |
panel_access_binding_changed | 服务器绑定或交付记录已变化，刷新原任务后重新领取 |
panel_access_rate_limited | 同一账户 15 分钟内最多领取尝试 10 次，请等候后重试 |
panel_access_delivery_failed / panel_access_unavailable | 加密交付、完整性核验或审计未完成；保留任务编号、错误码与时间联系支持，不发送密码，不覆盖重装 |
能领取资料但打不开宝塔时，放行领取窗口显示的实际面板 TCP 端口，来源建议限自己的管理 IP，并核对完整安全入口。详细步骤见领取自己的宝塔资料。已在宝塔修改的密码、端口或入口不会回写到旧的初始资料，官网不会帮你重置。
授权到期与续费
授权到期后，签名运行许可不提供额外运营宽限。完成续费后还需要取得新的有效许可；网络或平台不可达时不能保证立即恢复。平台主动停用的传播时间受已签发短租约限制，最长剩余 60 秒，与固定授权到期不同。
技术支持需要的是域名、任务编号、错误码、发生时间和源/目标版本。不要提供服务器密码、管理员密码、授权密钥、完整环境文件或数据库备份。