维护与参考

故障排查

按安装、登录与凭证、证书发现、更新、服务重载和日志位置分类的常见问题检查项。

最后检查: 2026-08-09语言: 简体中文

本页按部署阶段整理通用检查项。错误文案和退出码可能随版本变化，请记录实际命令、完整时间点和脱敏日志，不要用其他版本的报错文本代替现场信息。

安装阶段

二进制无法执行：

  • 确认下载的平台与架构和服务器一致（uname -m 查看架构）；
  • Linux/macOS 确认已执行 chmod 755 添加执行权限；
  • 对照下载页校验 SHA256，排除下载损坏；
  • Windows 如提示文件被阻止，检查文件属性中的“解除锁定”。

--help 无输出或报错： 文件可能不完整或平台不匹配，重新下载并校验后再试。

登录与凭证（CaaS 上游）

login 初始化失败：

  • 确认接入地址（Endpoint）填写正确且服务器可访问该地址（注意出站防火墙和代理）；
  • 确认 AccessKey / AccessSecret 输入无误（注意复制时的首尾空格）；
  • 确认凭证在上游后台仍然有效、未被吊销。

登录成功但节点不可用： 检查是否已在 CaaS 后台管理面板完成节点激活（见配置）。

私有 CLM 或其他证书服务的认证和连接检查取决于对应适配器。请同时核对该适配器说明、上游接口日志和网络访问策略。

证书发现阶段

discover-certificate 找不到证书或缺少部分证书：

  • 确认 clmbot 运行账号对证书路径有读取权限（见最小权限）；
  • 扫描范围会受到版本、系统和权限影响；未被发现的证书先检查路径与权限，再按同版本生成的配置结构补充（见证书发现）。

config.yaml 未生成： 确认扫描结果出现后输入了 Y 确认，并确认 clmbot 对运行目录有写入权限。

更新阶段

update-certificate 执行后证书未更新：

  • 先确认上游确实已签发新证书（以 CaaS 为上游时检查后台重签状态与周期设置）；
  • 检查 config.yaml 中 servers[] 的证书路径和 format 是否正确；
  • 确认 clmbot 账号对证书文件及其目录有写权限，且允许创建 .bak 备份；
  • 查看运行目录 update.log 中本次执行的输出。

定时任务未生效：

  • Linux：确认 crontab 配置在 clmbot 运行账号下、时间表达式正确、命令中已 cd 到运行目录；
  • Windows：在任务计划程序中查看上次运行结果，确认工作目录、运行账号和“不管用户是否登录都要运行”设置。

服务重载阶段

证书已替换但服务仍使用旧证书：

  • 确认 after_script 已配置且内容正确（如 nginx -t && nginx -s reload）；
  • 手动以 clmbot 账号执行 after_script 中的命令，检查是否因 sudoers 未精确授权而失败（见最小权限）；
  • Tomcat 场景确认操作的是目标实例的 shutdown.sh / startup.sh；
  • 重载失败时可用 .bak 备份手动回滚（见自动更新与服务重载）。

日志位置

  • 更新日志：运行目录下的 update.log（定时任务示例通过 >> update.log 追加写入）；
  • 定期检查日志确认每次更新操作是否正常；
  • Server 模式由进程管理器托管时，同时检查 systemd、Windows 服务或容器平台收集的标准输出与错误输出。

仍未解决？

  • 在 GitHub Discussions 提问（使用问答）或在 GitHub Issues 提交可复现 Bug，入口见获取帮助；
  • 提交前务必脱敏：删除 AccessKey/AccessSecret、私钥、内网 IP、主机名与完整证书内容，对照安全页的脱敏清单逐项检查；
  • 安全漏洞请勿公开提交，走安全页的私密报告渠道。

相关页面