3keycompany/czertainly-email-notification-provider

CZERTAINLY-Email-Notification-Provider 技术文档

镜像概述和主要用途

CZERTAINLY-Email-Notification-Provider 是商业开源项目 CZERTAINLY 的一部分，作为实现特定功能组的连接器（Connector），专注于提供邮件通知能力。该镜像实现以下功能组（Function Group）和类型（Kind）：

其核心用途是通过邮件方式发送通知，集成于 CZERTAINLY 平台中，处理各类事件触发的邮件通知需求（如证书状态变更、到期提醒等）。

核心功能与特性

• 邮件通知发送：支持基于配置的邮件模板和变量替换，发送定制化邮件通知。

使用场景与适用范围

适用于 CZERTAINLY 平台环境中需要通过邮件传递事件通知的场景，例如：

• 证书状态变更通知（如从有效变为即将过期）
• 证书操作结果通知（如证书签发、吊销完成）
• 系统关键事件提醒（如配置变更、异常状态）

部署与配置

前置要求

• 数据库：需 PostgreSQL 数据库存储通知相关数据。

Docker 容器获取

镜像名称格式：czertainly/czertainly-email-notification-provider:tagname
通过以下命令拉取指定版本镜像：

bash
docker pull docker.xuanyuan.run/czertainly/czertainly-email-notification-provider:tagname

环境变量配置

容器通过环境变量进行配置，详细参数如下：

实例配置属性

创建 Email Notification Provider 实例时，需配置以下属性：

变量替换说明

主题（Subject）和内容模板（Content Template）支持变量替换，变量格式为 ${variable}，运行时会被通知请求中的数据替换。

内容模板示例：

html
<h3>证书状态变更通知</h3>
<p>证书信息如下：</p>
<ul>
  <li>主题：${notificationData.subjectDn}</li>
  <li>序列号：${notificationData.serialNumber}</li>
  <li>颁发者：${notificationData.issuerDn}</li>
</ul>
<button onclick="location.href='https://yourdomain.com/certificates/${notificationData.certificateUuid}'" type="button">查看证书</button>

变量替换逻辑：
通知请求数据示例：

json
{
  "recipients": [{"name": "John Doe", "email": "john.doe@example.com"}],
  "eventType": "certificate_status_changed",
  "notificationData": {
    "subjectDn": "CN=test",
    "serialNumber": "4a25c46b33ee052d242023f5dfaaafd3694858a4",
    "issuerDn": "CN=issuer",
    "certificateUuid": "7de49ef9-8244-4e8f-95b8-82205ae0ad48"
  }
}

模板中的 ${notificationData.subjectDn} 等变量会被替换为对应值，生成最终邮件内容。

Docker 部署示例

1. docker run 命令示例

bash
docker run -d \
  --name email-notification-provider \
  -p 8080:8080 \
  -e JDBC_URL="jdbc:postgresql://postgres-host:5432/emailnpdb" \
  -e JDBC_USERNAME="dbuser" \
  -e JDBC_PASSWORD="dbpass" \
  -e SMTP_HOST="smtp.example.com" \
  -e SMTP_PORT="587" \
  -e SMTP_USERNAME="smtpuser@example.com" \
  -e SMTP_PASSWORD="smtppass" \
  docker.xuanyuan.run/czertainly/czertainly-email-notification-provider:tagname

2. docker-compose 配置示例

yaml
version: "3.8"
services:
  email-notification-provider:
    image: docker.xuanyuan.run/czertainly/czertainly-email-notification-provider:tagname
    container_name: email-notification-provider
    ports:
      - "8080:8080"
    environment:
      - JDBC_URL=jdbc:postgresql://postgres-host:5432/emailnpdb
      - JDBC_USERNAME=dbuser
      - JDBC_PASSWORD=dbpass
      - DB_SCHEMA=emailnp
      - SMTP_HOST=smtp.example.com
      - SMTP_PORT=587
      - SMTP_USERNAME=smtpuser@example.com
      - SMTP_PASSWORD=smtppass
      - SMTP_AUTH=true
      - SMTP_TLS=true
    restart: unless-stopped

DEBUG 日志配置

启用应用调试日志

设置环境变量：

bash
LOGGING_LEVEL_COM_CZERTAINLY=DEBUG

启用邮件发送调试日志（SMTP 过程）

设置环境变量：

bash
SPRING_MAIL_PROPERTIES_MAIL_DEBUG=true

接口兼容性

实现 Notification Provider 接口，详细接口定义及端点说明参见 https://github.com/CZERTAINLY/CZERTAINLY-Interfaces%E3%80%82

参考文档

• https://github.com/CZERTAINLY/CZERTAINLY
• https://docs.czertainly.com