实操教程约 5 分钟阅读

CertbotX Agent 一键安装教程：内网服务器也能自动部署证书

从创建 Agent、执行一次性安装命令，到选择部署目标、宝塔自动启用 HTTPS、卸载和离线排查，一步步完成服务器证书自动部署。

本文目录

很多人听到“服务器 Agent”，第一反应是要开放一个管理端口，再准备防火墙规则。CertbotX Agent 恰好相反：它不监听端口，只从服务器主动通过 HTTPS 连接 CertbotX，领取属于本组织、已经签名的证书部署任务。服务器在内网、家里或办公网都可以使用，只要能正常访问公网 HTTPS。

安装前准备

Linux 正式版当前要求：

  • x86_64 架构；
  • 使用 systemd 的 Linux，例如 Debian、Ubuntu、CentOS、RHEL 或 AlmaLinux；
  • 能以 root 或 sudo 权限安装系统服务；
  • 允许出站访问 https://www.certbotx.cn 的 443 端口；
  • 不需要开放 22、80、443 或任何 Agent 入站端口。

Windows Server 2019/2022 x64 在控制台也可以选择，但当前仍是未签名测试版，只负责把证书写入受控目录，不会自动操作 IIS 或 Windows Nginx。生产服务器优先使用 Linux 正式版。

生成一键安装命令

  1. 登录 CertbotX 客户控制台。
  2. 打开“接入点”，选择“服务器 Agent”。
  3. 点击“添加 Agent”，填写容易识别的节点名称，例如“上海生产宝塔”或“内网 API 网关”。
  4. 运行平台选择“Linux x86_64”，点击“生成安装命令”。
  5. 复制弹窗里的短命令，在目标服务器以管理员权限执行。

短命令类似下面这样，但每次生成的 12 位短码都不同：

curl -fsS https://www.certbotx.cn/i/一次性短码|sh

短码有效期为 30 分钟，并且包含一次性安装凭据。不要把真实命令发到群聊、工单正文或截图里。过期后回到控制台重新创建即可，不要试图手工拼接参数。

安装器会先下载固定版本文件，校验 SHA-256 和控制面 TLS 公钥指纹，再安装 systemd 服务。安装成功后终端会打印程序、配置、状态、证书目录和卸载命令。正常情况下，控制台会在几十秒内把节点状态更新为“在线”。

把证书部署到 Agent

Agent 在线后，给域名开启自动托管或创建部署位置：

创建 Agent：1 填写节点名称，2 选择运行平台，3 生成一次性安装命令
创建 Agent：1 填写节点名称，2 选择运行平台，3 生成一次性安装命令查看原图
  1. 在域名管理中选择已经完成 CNAME 委托验证的域名。
  2. 进入部署向导，选择“服务器 Agent”。
  3. 选择刚才上线的节点。
  4. 普通 Nginx 或自定义服务保持“宝塔环境执行配置检测并重载 Nginx”关闭。
  5. 标准宝塔 Nginx 站点可以勾选该选项。Agent 会定位精确域名的宝塔站点配置，先备份，再补齐固定 HTTPS 配置，执行 nginx -t 后 reload；检查失败会恢复证书和站点配置。

证书与私钥由平台写入 Agent 的受控目录，不需要在网页里填写服务器绝对路径。Agent 不接受任务传入 Shell、服务名、任意配置路径或任意 reload 命令。

部署完成不等于工作结束。CertbotX 还会从公网使用 SNI 读取实际返回的叶子证书，只有指纹与本次证书一致，部署运行才会进入成功状态。CDN、反向代理或旧进程仍返回旧证书时，页面会继续显示验证中，而不是礼貌性地点个“成功”。

Agent 离线怎么查

先在服务器执行三条只读或可恢复命令：

systemctl status certbotx-agent --no-pager
journalctl -u certbotx-agent -n 100 --no-pager
curl -I https://www.certbotx.cn/api/health

常见原因包括服务器不能访问公网 HTTPS、系统时间偏差太大、代理拦截 TLS、设备身份被管理员撤销，或者本地配置/状态文件被人工删除。普通断网、进程退出和升级失败会由 Agent、systemd 与本地回退脚本自动恢复，不需要重新安装。

如果只是临时网络问题，可以先执行：

systemctl restart certbotx-agent

不要删除 /var/lib/certbotx-agent 或 /etc/certbotx-agent 来“试试运气”。那里保存设备身份和信任材料，删掉以后平台会把它视为一台陌生机器。

卸载和删除

在“接入点”列表点击“卸载命令”可以随时查看当前节点适用的命令。在线且支持自卸载的 Linux Agent，点击删除后会主动领取固定卸载任务并移除程序；离线、旧版或 Windows 节点会显示手工命令。

卸载默认保留已经部署的证书文件，避免正在运行的网站突然找不到证书。平台记录删除后，关联的自动部署目标会停用，历史部署和审计记录仍会保留。

证书自动化最省心的部分不是“安装成功”那一刻，而是半年以后服务器重启、网络抖动、证书重新申请时仍然自己恢复。安装完成后建议做一次重启和真实部署演练，再把它交给时间。

← 返回资讯中心