9.1 KiB
9.1 KiB
通知中心新项目开通操作手册
使用对象：由壹点统一通知中心维护人。
本文不交给业务项目作为开发教程。业务项目请阅读统一通知中心接入操作手册。
一、开通结果是什么
新项目开通完成后，应同时满足：
- 通知中心生产配置中存在唯一项目代码、项目名称、独立密钥和跳转域名白名单。
- 通知中心服务已重新加载配置并通过健康检查。
- 业务项目已通过安全渠道取得 URL、项目代码和项目密钥。
- 业务项目使用一名真实员工完成首次通知和状态查询。
- 项目密钥没有进入 Git、群聊、工单、共享文档、截图或普通日志。
仅把接入文档发给对方，不代表项目已经开通。
二、收到申请后先审核
业务项目应提交：
- 项目中文名称；
- 建议
projectCode； - 业务负责人和技术负责人；
- 通知场景和触发条件；
- 收件人规则以及钉钉
userId的数据来源； - 只能提供花名时，需要使用的准确花名清单；
- 日常和峰值通知量；
- 生产及测试跳转域名；
- 是否需要钉钉 H5 免登；
- 计划联调和上线日期。
审核门槛：
projectCode使用 2～40 位小写字母、数字、下划线或短横线，创建后不随中文名称改变。- 项目名称简短并适合出现在
【项目名称】业务标题中。 - 跳转域名为业务项目真实控制的 HTTPS 域名，不使用通配符，不包含协议、端口或路径。
- 收件人规则明确；业务项目只能提供花名时，必须提交有限、准确的花名清单。
- 预计发送量在当前串行投递能力可承受范围内；峰值明显较大时先做容量评估。
- 普通通知默认不启用免登；只有点击后必须自动建立登录态时才审核免登配置。
信息不完整时退回补充，不先生成密钥。
三、确认项目身份没有冲突
修改生产配置前只读核对：
- 当前
YYD_NOTIFICATION_PROJECTS_JSON能正常解析为数组。 - 数组中不存在相同
code。 - 申请的域名没有误写为协议、路径或非标准端口。
- 同一项目的花名归一化后没有重复，每个花名只对应一个已确认的在职员工
userId。 - 项目名称不会与已有项目造成用户无法分辨的通知来源。
- 如启用免登，回调地址属于该项目的
allowedHosts，回跳路径前缀采用最小范围。
不要删除、重排或重新生成已有项目的密钥。新增项目时必须完整保留所有既有项目配置。
生产项目配置结构：
{
"code": "product_development",
"name": "产品开发",
"secret": "由通知中心维护人生成的独立随机密钥",
"allowedHosts": ["product.example.com"],
"recipients": [
{"alias": "海棠", "userId": "经过确认的钉钉userId"},
{"alias": "无邪", "userId": "经过确认的钉钉userId"}
]
}
recipients 是可选配置。业务项目能够直接提供 recipientUserId 时可以省略；只能提供花名时才登记。维护人必须从权威通讯录或已确认的账号绑定取得 userId，不能按姓名猜测。
启用免登时才增加：
{
"login": {
"enabled": true,
"callbackUrl": "https://product.example.com/api/dingtalk/broker-login",
"allowedRedirectPathPrefixes": ["/tasks", "/dashboard"]
}
}
四、生成和保管项目密钥
每个项目必须使用独立的高强度随机密钥，长度至少 24 个字符。推荐在受控服务器或受控工作站生成 32 字节以上的随机值。
要求：
- 不复用其他项目密钥；
- 不使用项目名、日期、手机号或人工编写的口令；
- 生成过程不进入共享终端日志；
- 只写入通知中心生产
.env和业务项目后端的密钥配置； - 临时交接文件必须放在已确认不受 Git 跟踪的位置，并限制读取权限；
- 业务项目确认保存后删除不再需要的临时明文副本。
业务项目不需要知道钉钉 AppKey、AppSecret、RobotCode，不得将这些凭证与项目密钥一起交付。
五、变更生产配置
这是生产写入操作，必须获得上线授权后执行。
执行顺序：
- 确认目标服务器和目录是通知中心，而不是其他业务项目。
- 备份通知中心
.env，备份文件包含密钥，权限必须限制为仅维护人可读。 - 备份通知中心 SQLite 数据目录，确保现有通知记录可恢复。
- 在
YYD_NOTIFICATION_PROJECTS_JSON数组末尾新增项目，完整保留所有已有项目和已有recipients。 - 再次解析 JSON，确认项目代码唯一、密钥长度合格、域名格式正确、花名映射无重复。
- 使用当前正式发布方式重新加载通知中心配置。
- 验证本机
/health与公网/notification-center/health。 - 验证现有项目仍可鉴权，新项目能够通过签名请求进入通知队列。
重要限制：
- 日常发布使用仓库当前的
scripts/git-build-deploy.ps1流程。 - 当前
scripts/deploy-material-host.sh已具备“保留生产.env中未列出的已登记项目”逻辑；使用前仍需确认部署的是包含该保护逻辑的最新版本，并在发布后核对项目列表，不能使用更早的脚本副本。 - 不能为了新增项目而更换其他项目密钥。
- 不能把生产
.env、密钥或完整docker compose config输出保存到共享日志。
健康检查只证明服务和数据库可用，不证明新项目已经能够发送通知。仍需完成下一节的真实业务验收。
六、安全交付三项配置
向业务项目技术负责人交付：
YYD_NOTIFICATION_CENTER_URL=https://sc.jiansun.vip/notification-center
YYD_NOTIFICATION_PROJECT_CODE=实际项目代码
YYD_NOTIFICATION_PROJECT_SECRET=实际项目独立密钥
交付方式：
- URL 和项目代码可以写入接入记录；
- 项目密钥只通过双方认可的一对一安全渠道或密钥管理服务交付；
- 密钥与普通接入说明分开发送；
- 要求接收人在业务后端保存后确认，不在群内回复或引用密钥；
- 不替业务项目长期保存收件人名单。
可直接发送给业务项目负责人的非敏感说明：
你的项目已在由壹点统一通知中心完成登记。
公共地址：https://sc.jiansun.vip/notification-center
项目代码：<实际项目代码>
项目密钥：将通过单独的安全渠道发送
请把三项配置只放在业务后端。收件人不是接入密钥：能够提供钉钉 userId 时传 recipientUserId；
只能提供花名时传已登记的 recipientAlias，未登记花名不会发送。
接入步骤请按《由壹点统一通知中心接入操作手册》执行。
七、首次联调怎么做
业务项目准备：
- 一名真实测试员工的钉钉
userId，或已经登记的准确花名； - 一个只在该员工和业务负责人之间可见的低风险测试场景；
- 一个属于项目白名单域名的 HTTPS 跳转地址；
- 稳定且不会与生产业务事件冲突的测试幂等键。
维护人与业务项目共同确认：
- 创建接口返回
202或同幂等请求返回200。 - 返回体包含投递
id。 - 查询接口只能由当前项目查询该投递记录。
- 最终状态进入
sent、unread、read或给出明确failed原因。 - 测试员工实际收到“由壹点”机器人单聊。
- 标题包含正确项目名称。
- 按钮只进入登记的项目域名和正确页面。
- 相同幂等键重复请求不产生第二条消息。
- 如使用花名，已登记花名能解析，未登记花名明确返回
RECIPIENT_ALIAS_NOT_FOUND。
首次真实发送只做能证明链路的一次必要调用；未获得真实发送授权时使用客户端示例测试，不向员工发送消息。
八、生产验收和交接记录
正式上线至少由两名真实员工完成通知与跳转验证。记录中不保存密钥，只保存：
项目名称：
projectCode：
allowedHosts：
业务负责人：
技术负责人：
通知中心维护人：
业务项目版本或 Git 提交：
通知中心版本或 Git 提交：
生产验证时间：
测试业务事件 ID：
通知中心投递 ID：
最终投递状态：
按钮跳转结果：
遗留问题：
完成后把统一通知中心接入操作手册、消息规范和错误与状态规范交给项目后续维护人。
九、密钥轮换或停用
密钥泄露、负责人变更或项目停用时，不要直接覆盖后结束：
- 确认受影响的唯一项目代码和环境。
- 说明轮换或停用窗口及对发送通知的影响。
- 备份当前配置并准备恢复原密钥的回滚路径。
- 新密钥只交付给该项目，不影响其他项目。
- 协调通知中心与业务后端在约定窗口切换。
- 使用一条有上限的真实通知验证新密钥。
- 确认旧密钥失效，并删除不再需要的明文副本。
项目停用前保留必要的历史投递记录，不因停用项目直接删除数据库数据。