Ajenti check_certificates 插件实战：批量监控 SSL/TLS 证书有效期与到期预警

后端运维【免费下载链接】ajentiAjenti Core and stock plugins项目地址https://gitcode.com/gh_mirrors/aj/ajenti点击查看免费下载导读本文围绕 Ajenti 内置的check_certificates插件展开讲解如何在一个管理面板中集中监控大量主机、服务端口上的 SSL/TLS 证书是否仍然有效。读完本文你将掌握该插件的安装配置、Web 界面操作添加/删除域名、查看到期状态、默认端口与 STARTTLS 探测逻辑并能深入到源码层面理解证书抓取、剩余天数分级danger/warning/info/success与仪表盘小部件的工作原理可直接用于部署证书续期监控体系。插件是什么一个轻量的证书有效性巡检工具check_certificates 插件 README 对它的定位只有一句话Test if some certificates are still valid. Usefull when you have to monitor a lot of certificates renew.检测某些证书是否仍然有效当你需要监控大量证书续期时非常有用。这是 Ajenti 面板中的一款实用工具插件它的核心价值在于当你的环境中散落着多个域名的 HTTPS 证书、邮件服务器证书STARTTLS时无需逐个使用openssl s_client手工探测而是把域名统一登记到一个列表里Ajenti 周期性批量检查并以红/黄/蓝/绿四级状态直观呈现剩余有效期从而在证书过期前及时续期避免服务因证书失效而中断。从 plugin.yml 可以看到该插件的基本元信息字段值说明namecheck_certificates插件内部标识名version0.9插件版本titleCheck certificates界面显示标题iconcertificate侧边栏图标dependenciescore!PluginDependency { plugin_name: core }依赖 Ajenti 核心插件resources前端模块、路由、控制器、模板等resources/js/*与resources/partial/*插件依赖列表requirements.txt仅有aj与ajenti.plugin.core说明它是一个纯粹的面板内工具自身不依赖额外的系统服务。注README 中 Usefull 为原文档拼写引用时保持原文。安装与启用check_certificates属于 Ajenti 的官方内置插件随发行包一起提供。启用方式与其他 Ajenti 插件一致通过 Web 界面的Plugins插件管理页面找到Check certificates并启用或在配置文件中把插件加入启用列表。启用后插件通过 main.py 中的SidebarItemProvider向 Ajenti 侧边栏注册入口from jadi import component from aj.plugins.core.api.sidebar import SidebarItemProvider component(SidebarItemProvider) class ItemProvider(SidebarItemProvider): def __init__(self, context): self.context context def provide(self): return [ { attach: category:tools, id: check_cert, name: _(Check certificates), icon: fas fa-certificate, url: /view/check_cert/certificates, children: [], } ]该代码将菜单项挂载到侧边栏的Tools工具分类下点击后跳转到/view/check_cert/certificates页面。url的路径形如/view/check_cert/certificates其中check_cert是路由命名空间certificates是对应的视图名前端路由由 plugin.yml 中声明的resources/js/routing.es负责解析。界面操作从列表总览到添加新主机官方文档 check_certificates.rst 对界面的描述如下列表视图一眼即可看出你的 SSL 证书是否仍然有效列表展示每个条目的hostname主机名、port端口、issuer证书签发者、证书到期时间End、连接状态Status添加或移除主机非常容易默认对443 端口HTTPS 标准端口进行测试你也可以指定其他端口如 8000 或 587当指定端口为587时Ajenti 会尝试建立STARTTLS连接典型场景邮件服务器 SMTP 的证书检查。证书列表视图如上图所示列表表格共 5 列从左到右依次为Domain域名/主机名已登记待检查的域名Port端口对应服务的探测端口Issuer签发者证书签发机构例如图中显示的Lets EncryptEnd到期时间证书的过期时间若检查异常该列会显示具体错误信息而非时间例如Can not handle SSL on this port !该端口无法处理 SSL、Host refuse the connection !主机拒绝连接Status状态证书有效性状态使用徽章样式标识——正常证书显示绿色对勾✔️异常证书显示红色骷髅。每行最右侧带有删除图标可一键移除条目表格底部有Add host添加主机按钮用于登记新的待检查域名。添加新主机点击Add host后弹出New hostname新主机名模态表单包含两个字段URL待检查的域名可直接带端口详见下文 API 解析Port (default is 443 if empty)服务端口留空时默认使用 443上图中示例填写为587邮件服务器 STARTTLS 场景。确认后点击ADD提交CANCEL取消。所有登记的主机 URL 都保存在用户配置中见 views.py 中handle_api_check_cert的注释All urls are stored in the user config。端口约定443 的 HTTPS 探测与 587 的 STARTTLS 探测这是本插件最值得注意的行为设计端口不同探测协议不同。默认端口443走标准 HTTPS/TLS 直连探测端口587走STARTTLS探测适用于 SMTP 邮件服务器邮件服务常用 587 端口先明文握手再升级为 TLS其他任意端口如 8000按普通 TLS 直连处理。该逻辑在 api.py 的checkOnDom中体现try: if port 587: cert CertLimitSTARTTLS(hostname) else: cert CertLimitSSL(hostname, port)也就是说你在添加主机时把端口填成 587插件就会自动切换为 STARTTLS 握手方式去拉取证书无需任何额外配置。源码级实现原理1. 证书抓取CertLimitSSL 与 CertLimitSTARTTLSapi.py 提供了两个底层的证书获取函数CertLimitSSL(hostname, port)—— 建立 TLSv1.2 直连会话抓取对端证书ctx ssl.SSLContext(ssl.PROTOCOL_TLSv1_2) s ctx.wrap_socket(socket.socket(), server_hostnamehostname) s.settimeout(10) s.connect((hostname, port)) cert crypto.load_certificate(crypto.FILETYPE_ASN1, s.getpeercert(binary_formTrue)) s.close() return cert要点使用ssl.PROTOCOL_TLSv1_2上下文并通过server_hostnamehostname启用 SNIServer Name Indication确保对端返回与域名匹配的证书s.settimeout(10)设定 10 秒超时防止不可达主机长时间阻塞s.getpeercert(binary_formTrue)拿到 DER 二进制证书再用 OpenSSL 的crypto.load_certificate(crypto.FILETYPE_ASN1, ...)解析为OpenSSL.crypto.X509对象。CertLimitSTARTTLS(hostname)—— 通过 SMTP 587 端口以 STARTTLS 方式抓取证书connection smtplib.SMTP(hostname, 587) connection.starttls() cert crypto.load_certificate(crypto.FILETYPE_ASN1, connection.sock.getpeercert(binary_formTrue)) connection.quit() return cert这里借助 Python 标准库smtplib.SMTP建立连接后调用starttls()升级为加密通道再从底层 socket 上取出对端证书最后quit()优雅关闭。2. 状态分级checkOnDom 的剩余天数阈值checkOnDom(hostname, port443)是核心入口它把证书的各类信息收拢进一个字典并根据距离到期还剩多少天附加 Bootstrap 状态类。源码注释与实现明确给出了四级阈值剩余天数status值restTime含义 7天danger默认值 7即将过期红色告警 14天warning 14临近过期黄色预警 28天info 28需要关注蓝色提示 28天success空状态健康绿色对应实现if remainingDays 7: certDetails[restTime] 7 elif remainingDays 14: certDetails[status] warning certDetails[restTime] 14 elif remainingDays 28: certDetails[status] info certDetails[restTime] 28 else: certDetails[status] success注意danger是字典的初始默认值因此任何证书一旦进入 7 天倒计时或探测失败都会呈现红色告警状态。剩余天数通过证书的notAfter字段与当前时间差计算remainingDays (datetime.strptime(cert.get_notAfter().decode(), %Y%m%d%H%M%SZ) - now).days证书的notAfter是 ASN.1 格式的 UTC 时间字符串如20260926000000Z用%Y%m%d%H%M%SZ解析后与模块加载时的now datetime.now()相减取天数。返回的certDetails字典包含以下字段字段类型/说明statusdanger/warning/info/successhostname被检查的主机名port探测端口字符串转 inturl原始主机名用于前端展示/回调notAfter证书过期时间探测失败时则为错误提示文本restTime剩余天数档位文本如 14issuer签发者组织名O 字段subject证书主体Subject 组件字典notBefore证书生效时间签发者信息在源码中是从证书组件里按组织名O提取的issuer cert.get_issuer().get_components() # Issuer be like [(bC, bUS), (bO, bLets Encrypt), (bCN, bR3)] # Extract Organization name certDetails[issuer] [e[1] for e in issuer if e[0]bO][0].decode() certDetails[subject] dict(cert.get_subject().get_components())这也是界面列表里Issuer列能直接显示Lets Encrypt这类机构名的原因。3. 异常处理探测失败的六大场景探测网络服务时错误在所难免api.py 为常见失败场景准备了明确的中文友好提示源码中通过_()国际化标记并把错误文本填入notAfter字段前端据此显示红色异常状态异常类型提示文本TimeoutError/socket.timeoutTimeout from host !主机超时socket.gaierrorCould not resolve hostname !无法解析主机名ssl.CertificateErrorCertificate is not valid !证书无效ssl.SSLErrorCan not handle SSL on this port !该端口无法处理 SSLConnectionRefusedErrorHost refuse the connection !主机拒绝连接从代码结构看任何异常路径都会立即返回certDetails此时status保持默认的danger从而在界面中以红色徽章醒目提示问题主机。4. HTTP 端点前端与后端之间的桥梁views.py 通过 Ajenti 的 HTTP 插件机制暴露了唯一的 API 接口component(HttpPlugin) class Handler(HttpPlugin): def __init__(self, context): self.context context post(r/api/check_cert) endpoint(apiTrue) def handle_api_check_cert(self, http_context): url http_context.json_body()[url] return json.loads(json.dumps(checkOnDom(*url.split(:))))调用方式是POST/api/check_cert请求体 JSON 中包含url字段格式为www.domain.com:999这种域名:端口形式。服务端用url.split(:)拆出主机名与端口然后作为位置参数传给checkOnDom若不携带端口checkOnDom会采用默认值port443。返回结果即上文所述的证书详情字典JSON 序列化后。这解释了界面表单里URL Port留空默认 443的设计来源前端把两个字段组合成hostname:port字符串提交端口留空时后端自动回落 443。5. 仪表盘小部件每小时自动刷新插件还提供了仪表盘Dashboard小部件由 widget.py 实现component(Widget) class CertWidget(Widget): id cert name _(Certificates) template /check_certificates:resources/partial/widget.html def __init__(self, context): Widget.__init__(self, context) self.last_update None def get_value(self, config): now datetime.now() if self.last_update is None: self.last_update now return True # One update per hour is sufficient for certificates if (now-self.last_update).seconds 3600: self.last_update now return True return False小部件 ID 为cert名称为 Certificates渲染模板指向插件资源目录下的resources/partial/widget.html。get_value采用每小时最多刷新一次的频率控制注释明确写道 One update per hour is sufficient for certificates因为证书有效期以天计频繁探测既无必要也会给被检主机带来无谓连接这是典型的按业务特性设计轮询节奏的做法。典型使用场景与配置建议结合上述实现可以总结出该插件的典型用法Web 服务证书巡检登记所有对外 HTTPS 服务的域名默认 443 端口在面板内集中查看每个域名的签发者与到期时间邮件服务器证书巡检对 SMTP 服务器登记端口 587插件自动以 STARTTLS 方式抓取证书并评估剩余天数非标端口服务对运行在 8000、8443 等端口的服务显式填写端口即可异常快速定位当某主机出现Could not resolve hostname !DNS 问题、Host refuse the connection !服务宕机/防火墙拦截、Can not handle SSL on this port !端口被非 TLS 服务占用等提示时可第一时间排查面板总览把 Certificates 小部件添加到仪表盘首页配合每小时自动刷新实现证书健康度的一屏监控。配置层面的注意点主机条目以hostname:port形式保存在用户配置中见 views.py 注释无需额外修改服务器级配置文件探测超时固定为 10 秒s.settimeout(10)对于延迟较高的主机可能提示Timeout from host !属预期行为证书解析依赖 PyOpenSSLfrom OpenSSL import crypto插件在aj与ajenti.plugin.core依赖之外实际运行环境需要具备pyOpenSSL支持。小结check_certificates是 Ajenti 中一个麻雀虽小、五脏俱全的实用插件Web 层面提供列表总览、一键增删、状态徽章与仪表盘小部件后端则由 api.py 中的CertLimitSSL/CertLimitSTARTTLS/checkOnDom三个函数完成证书抓取、解析与四级状态分级配合 views.py 的/api/check_cert端点实现前后端联动。理解其 7/14/28 天三级预警阈值与587 端口自动切 STARTTLS的设计可以帮助你在实际部署中准确解读状态颜色、规划证书续期节奏构建一套低成本、可视化的证书有效期监控体系。如需进一步探索可继续阅读 插件源码目录、插件元信息 与 官方插件文档。赞分享后端运维【免费下载链接】ajentiAjenti Core and stock plugins项目地址https://gitcode.com/gh_mirrors/aj/ajenti点击查看免费下载相关推荐Pyroscope 配置指南YAML 配置文件、CLI 参数与多组件部署实践Pyroscope 配置指南YAML 配置文件、CLI 参数与多组件部署实践 本文围绕 Grafana Pyroscope 的配置机制展开系统讲解 YAML后端运维OneUptime SSL 证书监控完整指南有效期监测、过期告警与状态判定OneUptime SSL 证书监控完整指南有效期监测、过期告警与状态判定 SSL/TLS 证书过期是导致线上服务中断的最常见隐性故障之一证书在某个深夜悄然可观测性后端运维前端云原生微服务AI AgentOneUptime SSL 证书监控完整指南证书有效期、自签名与有效性验证实战OneUptime SSL 证书监控完整指南证书有效期、自签名与有效性验证实战 SSL/TLS 证书过期是导致生产服务中断的最常见原因之一。OneUptime可观测性后端运维前端云原生微服务AI Agent上一篇Formbricks性能优化指南PostgreSQL数据库架构与调优策略下一篇智能网页自动化革命5步打造你的AI数字员工创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考