企业官网建设流程全解析

• 可观测性
• 后端
• 前端
• 运维

导读

SSL 监控（SSL Monitor）是 Kener 内置的十余种监控类型之一，它不探测 HTTP 可达性，而是直接与目标主机建立 TLS 连接、读取对端证书的过期时间，将"距离证书过期还剩多少小时"映射为 UP / DEGRADED / DOWN 三种监控状态，从而在证书真正失效之前就提前告警。本文以官方文档 SSL Monitor/docs/content/v4/monitors/ssl.md) 为骨架，结合仓库源码（sslCall.ts、类型定义、管理界面表单/manage/app/monitors/[tag]/types/monitor-ssl.svelte>) 等）完整讲解配置字段、状态判定逻辑、校验规则与底层执行链路，读完你可以在 Kener 中独立创建、调优并排障一个证书过期监控。

SSL 监控的核心理念

与 API/PING 等"现在是否可用"的监控不同，SSL 监控关注的是未来的风险：TLS 证书总有到期日，而证书过期通常是静默发生的——服务本身一切正常，直到某天突然出现浏览器安全警告甚至握手失败。Kener 的 SSL 监控通过以下三步完成检查：

1. 与目标主机建立一次 TLS 连接（默认端口443）；
2. 读取对端服务器返回的证书valid_to（到期时间）字段；
3. 用"到期时间 − 当前时间"得到剩余有效时长，再按配置的两个阈值映射为监控状态。

整个检查由 sslCall.ts 中的getSSLExpiry实现：它使用 Node 内置的tls.connect建立套接字，在连接建立后的回调中调用socket.getPeerCertificate()读取证书，并利用performance.now()记录握手耗时作为本次检查的 latency。从源码结构看，SSL 监控与其它类型一样产出status + latency采样，因此它能无缝进入 Kener 的时序图表、事件流和告警体系。

最小配置：四个关键字段

创建 SSL 监控只需设置以下字段（对应源码中的SslMonitorTypeData类型，见 monitor.ts）：

其中有一条硬性约束：degradedRemainingHours必须大于downRemainingHours。该约束同时存在于管理界面的表单校验（MonitorTypeCard.svelte/manage/app/monitors/[tag]/components/MonitorTypeCard.svelte#L204-L212>) 中if (data.degradedRemainingHours <= data.downRemainingHours) return false;）与服务端保存链路中，如果违反则配置无法通过校验。

状态判定逻辑

令hours为"距离证书过期的剩余小时数"（源码中用timeTillExpiryMs / 1000 / 60 / 60计算），状态判定如下：

hours > degradedRemainingHours → UP downRemainingHours < hours ≤ degraded → DEGRADED hours ≤ downRemainingHours → DOWN

• UP：证书还很充裕，高于降级阈值；
• DEGRADED：证书即将到期（剩余时间已落入降级窗口），检查本身成功，但按你的业务逻辑判定为不健康；
• DOWN：证书已经过期或即将过期（剩余不足downRemainingHours小时）。

此外，连接失败或证书读取失败同样返回 DOWN——比如目标端口无 TLS 服务、主机不可达、或拿不到证书的valid_to字段。此时type标记为ERROR（区别于正常检查的REALTIME），并且error_message会带上失败原因（源码中超过 200 字符的错误消息会被截断）。

完整配置示例

将以下 JSON 作为监控的type_data即可创建标准的证书过期监控：

{ "monitor_type": "SSL", "type_data": { "host": "example.com", "port": "443", "degradedRemainingHours": 168, "downRemainingHours": 24 } }

说明：这是 Kener v4 文档给出的最小编成配置。实际保存监控时，type_data通常与tag（唯一标识）、cron（调度表达式，如* * * * *每分钟执行）等监控通用字段一起写入。调度机制见 monitorSchedulers.ts 与 cron-minute.ts，它们按 cron 将监控推入 BullMQ 队列。

源码级实现原理：一次 SSL 检查如何完成

sslCall.ts 是 SSL 监控的核心实现，其执行逻辑可以拆解为四个环节：

1. 参数解析execute()从type_data中取出host、port、degradedRemainingHours、downRemainingHours，其中端口经parseInt转为数字，两个阈值经Number()转为数值——这也解释了文档中"port 接受数字字符串"的约定。

2. TLS 握手与证书读取getSSLExpiry通过tls.connect(port, domain, { servername: domain })发起连接。servername字段即 SNI（Server Name Indication），它告诉服务器客户端想要哪个虚拟主机的证书——这正是多域名/多证书场景下能否取对证书的关键。连接建立后调用socket.getPeerCertificate()读取valid_to；若拿不到该字段（例如对端未提供有效证书），会以No certificate found.拒绝。

3. 剩余时间与延迟计算

const latency = Math.round(performance.now() - startTime); const timeTillExpiryMs = new Date(valid_to).getTime() - new Date().getTime();

剩余毫秒数换算成小时后再与两个阈值比较，得到状态；同时把 TLS 握手耗时作为本次采样的latency返回，因此 SSL 监控的图表同样能看到延迟曲线。

4. 错误兜底socket.on("error")会捕获握手失败、超时等异常，统一返回DOWN + ERROR，并附上error_message。这意味着证书监控在目标完全不可达时也会如实告警，而不是静默。

从调度链路看，SSL 监控和其它类型共享同一套执行管线：cron 调度器触发 → monitorExecuteQueue.ts 的 worker 中new Service(monitor)按monitor_type === "SSL"实例化SSLCall（见 service.ts）→ 执行结果与维护/事件叠加层合并后写入采样。监控的状态优先级遵循 Monitors Overview/docs/content/v4/monitors/overview.md) 中的MAINTENANCE > INCIDENT > REALTIME > DEFAULT，即证书检查的实时状态不会覆盖正在进行的维护窗口或人工事件。

管理界面配置

在 Kener 管理后台新建/编辑 SSL 监控时，表单由 monitor-ssl.svelte/manage/app/monitors/[tag]/types/monitor-ssl.svelte>) 渲染，界面提供：

• Host（必填）：目标主机名，占位符示例example.com；
• Port：默认443；
• Degraded 阈值：数字输入框，单位小时，默认168，界面提示"Certificate expiring within this many hours will be marked as DEGRADED"；
• Down 阈值：数字输入框，单位小时，默认24，界面提示"Certificate expiring within this many hours will be marked as DOWN"。

表单在加载时会对未设置的字段填充默认值（443 / 168 / 24），与文档默认值完全一致。保存时 MonitorTypeCard.svelte/manage/app/monitors/[tag]/components/MonitorTypeCard.svelte#L204-L212>) 会执行前端校验：host必须为合法主机名、port必须合法、两个阈值必须非负、且degradedRemainingHours严格大于downRemainingHours。

阈值调优建议

默认的168 / 24（7 天 / 1 天）适合大多数站点。可按业务场景调整：

• 证书签发周期较长（如年付证书），可放宽 DEGRADED 阈值到 14～30 天（336～720小时），给自己留出足够的续期缓冲；
• 使用自动续期（如 ACME/Let's Encrypt）且续期可靠，可收紧阈值、减少噪音；
• 对公网用户影响敏感的服务，DOWN 阈值建议保持 24 小时以上，确保有告警和人工介入的时间窗口。

阈值只影响状态判定，不影响检查本身；配合 Alert Configurations 可在状态翻转为 DEGRADED/DOWN 时触发通知。

排障指南

文档给出了三类常见问题的处置方向，这里结合源码补充排查要点：

• 状态立即为 DOWN：优先怀疑host/port填错，或目标端口上根本没有 TLS 服务（例如误填了 HTTP 明文端口）。此时可在服务器上用openssl s_client -connect host:port -servername host手工验证是否能拿到证书。若握手本身报错，error_message会带上底层错误信息（注意超过 200 字符会被截断）。
• 配置校验失败：检查degradedRemainingHours是否严格大于downRemainingHours，且两者均为非负数；host必须是有效主机名（不能是 URL 或路径）。
• 过期时间结果与预期不符：由于连接时携带了 SNI（servername: domain），返回的是该主机名下服务器实际下发的证书。如果目标服务器存在多证书/CDN 分发，请确认 SNI 指向的证书正是你要监控的那张；某些边缘节点或中间层（如负载均衡、CDN）可能颁发自己的证书，导致valid_to与源站证书不一致。

与其它监控类型的配合

SSL 监控关注"证书什么时候会出问题"，适合与 API 监控（关注"服务现在是否可用"）叠加使用，二者分别覆盖可用性与证书生命周期风险。这类"阈值驱动的状态监控"在 Kener 中并非孤例——Prometheus Monitor/docs/content/v4/monitors/prometheus.md?utm_source=gitcode_repo_files) 用 PromQL 查询结果与阈值比较、Heartbeat Monitor/docs/content/v4/monitors/heartbeat.md?utm_source=gitcode_repo_files) 用信号新鲜度判定状态，理解 SSL 监控的"剩余时间 → 状态"映射后，也能帮助你更快上手同类的阈值类监控。

相关文档

• Monitors Overview/docs/content/v4/monitors/overview.md) —— 状态值、状态优先级与调度机制总览
• API Monitor/docs/content/v4/monitors/api.md) —— HTTP/HTTPS 可用性检查
• Alert Configurations/docs/content/v4/alerting/alert-configurations) —— 为状态翻转配置告警
• Grace Period/docs/content/v4/monitors/grace-period.md) —— 连续 N 次确认后才变更状态的防抖动机制

• 可观测性
• 后端
• 前端
• 运维