适用对象与排查准备
本文用于第一次接入服务器或安装商城时遇到失败的用户。已经上线后的系统或插件版本更新，请看商城更新失败排查。
先准备任务编号、失败时间、错误码和错误详情。不要先重装服务器、删除站点或连续点击重试。任务进度 100% 也可能表示失败，判断结果必须同时看状态。
入口与处理步骤
- 登录官网客户控制台，进入“交易与交付 → 安装任务”。
- 如果失败在“自动部署记录”，点击“查看过程”。这里负责 SSH 连接、Agent 接入、DNS 检查和创建安装任务。
- 如果自动部署已成功，但商城或插件没有装好，在下方安装实例中找到对应系统或插件任务，点击“查看日志”。
- 按本文对应错误修复原因；平台发布、凭据异常、回滚失败等问题交给技术支持。
- 使用与失败阶段对应的入口，再检查真实结果。
| 情况 | 应使用的入口与限制 |
|---|---|
| 自动部署记录失败 | 修复后点“重新尝试”；需要原 SSH 资料仍有效，或原服务器 Agent 已就绪。继续创建安装仍要求 Agent 在线 |
| 首次系统安装失败、实例显示失败 | Agent 在线且授权可用时点“重试安装”，只将失败安装任务重新排队 |
| 系统成功，只有插件失败 | 先看该插件日志；实例可能仍显示正常，没有“重试安装”按钮。交支持核对，或按商城“插件中心”实际提供的操作处理 |
| 已结束的商城更新任务失败 | 不适用这里的两个重试按钮，转到更新排查文档 |
自动部署只对 SSH 暂时不可达、Agent 下载失败、启动失败、握手超时等指定故障自动再试。每轮最多执行 3 次，含首次执行；两次自动等待分别约为 1 分钟、2 分钟。密码、域名、环境或额度错误要先处理原因。
表单、授权和额度
| 错误或现象 | 原因与处理 |
|---|---|
deployment_consent_required | 没有勾选授权确认。确认自己有服务器管理权限后再提交 |
invalid_license、license_not_found | 未选授权、记录不存在或不属于当前账户。到“系统授权”核对，不要改接口参数绕过 |
license_inactive | 授权未生效、到期或状态不可用。核对支付、续费、退款和暂停状态，先恢复合法可用的授权 |
server_limit | 已有 10 台未撤销服务器。由支持核对实际用途和记录，不要撤销正在使用的服务器 |
deployment_concurrency_limit | 已有 2 个自动部署任务在排队或执行。等待原任务结束 |
server_exists | 当前账户已接入相同 IP。检查原记录；Agent 在线时使用“在已有服务器上安装” |
invalid_credential_retention | SSH 保存时间不在允许范围。选择页面提供的 1 天或 3 天 |
domain_in_use | 域名已绑定其他授权。先到“授权域名”查清归属，不要重复部署 |
domain_limit_reached | 主站域名额度不足。核对实际额度及换绑权益；换绑是否收费以当前授权和确认页面为准，并非所有授权一律收费 |
installation_limit_reached | 安装实例额度不足。域名无限或分站无限不代表安装实例无限；联系支持核对已有实例和可选权益 |
domain_not_bound | 在已有服务器安装时，域名尚未绑定到所选授权。先到“授权域名”绑定 |
agent_offline、server_not_found | 所选服务器离线、已撤销或不属于当前账户。核对原服务器状态，不要重新购买授权解决 |
失败实例也可能占用实例额度。“删除 SSH 资料”不会释放额度；“撤销服务器”也不是自动注销安装实例。
SSH 地址与登录
invalid_server_ip / invalid_ssh_port
公网 IP 格只填写云服务商提供的真实公网 IPv4 或 IPv6。不能填域名、宝塔网址、内网地址、localhost 或“IP:端口”。SSH 端口另填 1 至 65535 的数字，通常为 22。
不要照抄页面或文档中的示例 IP。后端会给未指定或为 0 的端口补默认 22，但这不代表其他无效值可以使用；按表单填写实际端口即可。
unsupported_ssh_user / ssh_root_required
固定部署流程需要 root 权限。自动 SSH 表单只支持 root 密码登录。只有密钥登录权限的用户，可由具备 root 权限的管理员按部署教程的命令接入步骤操作，不要为此随意降低服务器登录安全设置。
invalid_ssh_password / ssh_auth_failed
invalid_ssh_password 是密码长度等输入不符合要求；官网表单要求 8 至 256 个字符。ssh_auth_failed 则是连接时认证失败，可能密码错误，也可能服务器禁止 root 或密码认证。
先确认用的是服务器 SSH 密码，不是宝塔、官网或数据库密码。通过云服务商认可的方式确认登录策略，不能仅凭“云控制台终端能打开”就判断 SSH 密码认证一定可用。
“重新尝试”会继续使用原来保存的密码。 改了服务器 root 密码后，点击该按钮不会自动更新平台保存的资料。当前页面没有编辑旧任务 SSH 密码的入口，应先让支持核对原记录及后续接入方式。
ssh_unreachable / ssh_unavailable
ssh_unreachable：检查服务器是否开机、公网 IP 和 SSH 端口是否正确，以及云安全组、宝塔和系统防火墙是否允许部署服务访问。ssh_unavailable：可能是平台 SSH 执行服务不可用，不一定是你的服务器问题。由支持确认，必要时采用命令接入。
如果只允许 VPN、内网或跳板机访问，不能直接使用平台自动 SSH。不要把服务器所有端口对全网开放来排查。
host_key_changed
表示 SSH 主机指纹与该记录保存的指纹不一致。可能刚重装服务器、IP 已重新分配，也可能连到了非预期服务器。
先停止尝试，通过云服务商核实实例和 IP 的归属，再由支持核对旧接入记录。不要忽略指纹校验，也不要直接撤销仍承载业务的服务器。
Linux、宝塔与数据库环境
| 错误 | 处理方式 |
|---|---|
unsupported_os | 当前自动部署需要 Linux，Windows 不适用 |
unsupported_arch | 需要 x86_64/amd64，ARM64 不适用 |
systemd_missing | 缺少 systemctl/systemd。使用具备完整服务管理能力的受支持服务器环境 |
baota_nginx_missing | 宝塔 Nginx 未安装或目录不符。系统自带 Nginx、Apache 不能替代本流程的宝塔 Nginx |
mysql_client_missing | 缺少可执行的 mysql 或 mysqldump。在宝塔核对数据库及配套工具 |
baota_mysql_credential_unavailable | 宝塔本机数据库环境不完整，或本机读不到管理凭据。确认 MySQL、宝塔 Python、Socket 和运行用户，交管理员检查 |
disk_space_insufficient | 接入脚本检查到 /usr/local 可用空间不足 100 MB。扩容或由管理员处理已确认可清理的文件；商城和备份实际需要更多空间 |
baota_mysql_credential_unavailable 可能在安装 Agent 前出现。不要把 MySQL root 密码发到官网表单或工单，也不要因为一条报错就重装整套宝塔。
如果 Agent 已接入，但系统任务报 provision instance database failed，还要核对 MySQL 版本和宝塔保存的管理凭据是否可实际登录。当前自动建库语法不支持 MySQL 5.6；不要在旧业务库上直接升级或手工补建半套账户。
Agent 下载、验证与接入
| 错误 | 原因与下一步 |
|---|---|
agent_download_failed | 可能缺少 curl、DNS/出站 HTTPS 不通，或官方下载源异常。核对网络和系统时间，再让支持核对发布文件 |
agent_checksum_failed | 可能缺少 sha256sum，或下载文件与校验值不一致。停止使用该文件，交支持核对；不要跳过校验 |
agent_source_invalid | 平台或下载地址配置不符合 HTTPS 要求。由平台处理，不要改为 HTTP |
package_key_invalid | 公钥参数或相关工具不完整。由平台核对接入命令及受信任公钥，不要随意替换 |
enrollment_token_invalid | 接入令牌参数无效。让支持核对任务或备用命令；不要从别的服务器复制 Token |
agent_already_enrolled | 本机已有 Agent Token。先查原服务器是否已在线，不要删除 Token 伪造新接入 |
agent_start_failed | Agent 服务启动或接入后重启失败。让管理员查看服务状态和近期日志 |
agent_handshake_timeout | 脚本未在约 30 秒内确认握手完成。核对 Agent 服务、出站 HTTPS、时间和令牌状态 |
Agent 已在线时，修复域名等后续问题通常不需要重新安装 Agent。若仍失败，查看本次的新错误，不要重复执行一次性接入命令。
域名解析
invalid_domain
按页面要求只填完整主机名，例如 shop.example.com。不要填 IP、下划线、中文标点、协议、端口或后台路径。示例域名必须换成自己的实际域名。
domain_dns_unresolved / domain_dns_mismatch / domain_dns_error
domain_dns_unresolved：平台没有取得有效 A/AAAA 结果，也可能是 DNS 查询失败。核对主机记录并等待解析传播。domain_dns_mismatch：返回的 IP 中没有表单填写的服务器 IP。检查旧记录、CDN 代理和实际公网 IP。domain_dns_error：检查服务暂时不可用或输入状态异常，稍后再查，持续出现交支持处理。
DNS 检查只要求结果中至少有一个 IP 匹配。即使这一关通过，错误的其他 A/AAAA 记录仍可能让部分用户或证书机构访问旧服务器。应核对全部相关记录，不要只保留一张“解析成功”的截图。
系统包、插件包与真正的安装失败
system_package_unavailable / plugin_package_unavailable
表示创建安装任务时，系统包或某个待安装的授权插件包缺少有效发布资料。平台需要检查下载地址、校验值和包描述文件。
这不是要求客户自己上传包或删掉插件授权。插件已下架、不兼容、无授权等也会影响其他环节，但不能把此错误码一律解释成“插件下架”。请把原错误和授权版本交给平台确认。
自动部署成功，但系统任务失败
自动部署只完成服务器接入和任务创建，后续还可能在下载商城包、建库、数据库迁移、服务启动或证书检查时失败。
打开系统任务“查看日志”，按具体错误处理。环境问题修复后，实例显示失败时才使用“重试安装”。该按钮沿用原任务的安装包快照，不能用来自动换取平台新发布的另一个包。
系统成功，插件等待或失败
系统任务未成功时，插件等待属于正常顺序。系统已成功后仍有插件失败，则需单独排查插件包、现有系统环境和插件健康检查。
不要因插件失败删除商城数据库或重装主系统。实例“正常”只表明主系统安装状态，不保证所有插件完成。
nginx server name is already configured
目标域名已出现在另一份 Nginx 站点配置中。让管理员定位那一个站点并确认是否仍承载业务，协调域名和站点配置。不要删除整个 Nginx 配置目录。
initial installation rollback failed / automatic rollback failed
表示首次安装失败后的撤销或恢复动作也未完成。停止反复安装，保留任务、文件和数据库现场，联系支持。
首次安装不具备“恢复到安装前完整数据库”的保证。即使服务被撤销，也不代表数据库和配置已完全回到原状。
HTTPS 与证书
| 错误详情 | 排查重点 |
|---|---|
Baota ACME request failed | 域名解析、外网 80 端口、CDN 代理、宝塔 Python/ACME 模块、证书机构限制 |
managed certificate is expired or does not match domain | 证书域名、系统时间、剩余有效期和证书文件；激活检查要求至少覆盖未来约 7 天 |
HTTPS health endpoint did not become ready | 本机 443、Nginx 配置、证书信任链、商城服务和健康接口 |
先核对域名、80/443 与服务器时间。证书相关问题不会通过重复更换 root 密码解决。不要使用忽略 TLS 验证的选项来判定部署成功，也不要上传证书私钥给支持。
修复后按原失败阶段处理。首次安装失败可能撤销本次服务；已有商城的更新失败则走更新回滚流程，两者不能混用。
SSH 资料到期或无法解密
credential_missing、credential_expired 表示原 SSH 资料已不存在或过期。credential_encrypt_failed、credential_decrypt_failed 则需要平台核查加密服务。
- 先到“服务器”查看原 Agent 是否就绪且在线。
- Agent 在线时，通常可以继续原任务的域名检查或已有实例的安装，不需要再次提交 SSH 密码。
- Agent 未接入或离线时，让支持核对原记录和可行的接入方式。当前页面没有给旧自动部署任务补填密码的编辑入口。
不要直接新建同 IP 任务，它可能返回 server_exists；也不要删除 Token、恢复平台已清理的密码，或用“撤销服务器”替代凭据修复。
修复后的成功结果
- 自动部署记录为成功，显示安装任务已创建。
- 官网“服务器”显示就绪且在线。
- 系统任务及所需插件各自成功；有失败项继续单独处理。
- 公网 HTTPS 首页和商城后台均可访问，首位管理员已经创建或原管理员能登录。
任务成功但外网无法访问时，继续检查公共 DNS、安全组和 HTTPS。Agent 的本机健康检查不代表外部网络也已放行。
技术诊断：供管理员使用
以下命令只读取状态；不会重启服务或修改业务数据。不了解命令时，交给服务器管理员执行。
uname -s
uname -m
date -Is
df -h /usr/local /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可在本机另行核对宝塔 Nginx 目录、mysql/mysqldump、/tmp/mysql.sock、宝塔 Python 和 www 用户是否存在。不要直接打印环境文件、Token 文件或数据库密码。
工单提供任务编号、时间、原错误、Linux/CPU/MySQL 版本、是否使用 CDN，以及必要的脱敏日志。先删去日志中的密码、令牌、连接串、带签名下载参数和客户业务信息；不提交整份配置或数据库备份。