WuYongJie/YouYiDianNotificationCenter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
YouYiDianNotificationCenter/docs/通知中心新项目开通操作手册.md

11 KiB
Raw Blame History

通知中心新项目开通操作手册

使用对象：由壹点统一通知中心维护人。

本文不交给业务项目作为开发教程。业务项目请阅读统一通知中心接入操作手册。

一、开通结果是什么

新项目开通完成后，应同时满足：

  1. 通知中心生产配置中存在唯一项目代码、项目名称、独立密钥和跳转域名白名单。
  2. 通知中心服务已重新加载配置并通过健康检查。
  3. 业务项目已通过安全渠道取得 URL、项目代码和项目密钥。
  4. 业务项目使用一名真实员工完成首次通知和状态查询。
  5. 项目密钥没有进入 Git、群聊、工单、共享文档、截图或普通日志。

仅把接入文档发给对方，不代表项目已经开通。

二、收到申请后先审核

业务项目应提交：

  • 项目中文名称；
  • 建议 projectCode；
  • 业务负责人和技术负责人；
  • 通知场景和触发条件；
  • 收件人规则以及钉钉 userId 的数据来源；
  • 只能提供花名时，需要使用的准确花名清单；
  • 日常和峰值通知量；
  • 生产及测试跳转域名；
  • 是否需要钉钉 H5 免登；
  • 计划联调和上线日期。

审核门槛：

  • projectCode 使用 2～40 位小写字母、数字、下划线或短横线，创建后不随中文名称改变。
  • 项目名称简短并适合出现在 【项目名称】业务标题 中。
  • 跳转域名为业务项目真实控制的 HTTPS 域名，不使用通配符，不包含协议、端口或路径。
  • 收件人规则明确；业务项目只能提供花名时，必须提交有限、准确的花名清单。
  • 预计发送量在当前串行投递能力可承受范围内；峰值明显较大时先做容量评估。
  • 普通通知默认不启用免登；只有点击后必须自动建立登录态时才审核免登配置。

信息不完整时退回补充，不先生成密钥。

三、确认项目身份没有冲突

修改生产配置前只读核对：

  1. 当前 YYD_NOTIFICATION_PROJECTS_JSON 能正常解析为数组。
  2. 数组中不存在相同 code。
  3. 申请的域名没有误写为协议、路径或非标准端口。
  4. 同一项目的花名归一化后没有重复，每个花名只对应一个已确认的在职员工 userId。
  5. 项目名称不会与已有项目造成用户无法分辨的通知来源。
  6. 如启用免登，回调地址属于该项目的 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，不得将这些凭证与项目密钥一起交付。

五、变更生产配置

这是生产写入操作，必须获得上线授权后执行。

当管理员密钥与加密密钥都已配置时，通知项目配置的真实来源改为通知中心数据库；YYD_NOTIFICATION_PROJECTS_JSON 只用于把“数据库里还没有的项目”首次或补录导入，不能再把它当成每次发布都全量覆盖的真源。

执行顺序：

  1. 确认目标服务器和目录是通知中心，而不是其他业务项目。
  2. 备份通知中心 .env，备份文件包含密钥，权限必须限制为仅维护人可读。
  3. 备份通知中心 SQLite 数据目录，确保现有通知记录可恢复。
  4. 如需用环境变量补录，在 YYD_NOTIFICATION_PROJECTS_JSON 数组末尾新增项目；该数组中的既有项目只作为参考，不会覆盖数据库里已存在项目。
  5. 再次解析 JSON，确认项目代码唯一、密钥长度合格、域名格式正确、花名映射无重复。
  6. 使用当前正式发布方式重新加载通知中心配置，或在管理员 API 调用 POST /admin/runtime/import-env 导入缺失项目后执行 POST /admin/runtime/refresh。
  7. 验证本机 /health 与公网 /notification-center/health。
  8. 验证现有项目仍可鉴权，新项目能够通过签名请求进入通知队列。

如果当前环境尚未配置管理员密钥或加密密钥，通知中心会继续使用 legacy YYD_NOTIFICATION_PROJECTS_JSON 内存模式提供旧 /v1/*；此时 /admin/* 不挂载，也不会做数据库项目导入和运行时刷新。

重要限制：

  • 日常发布使用仓库当前的 scripts/git-build-deploy.ps1 流程。
  • 当前 scripts/deploy-material-host.sh 已具备“保留生产 .env 中未列出的已登记项目”逻辑；使用前仍需确认部署的是包含该保护逻辑的最新版本，并在发布后核对项目列表，不能使用更早的脚本副本。
  • 不能为了新增项目而更换其他项目密钥。
  • 不能把生产 .env、密钥或完整 docker compose config 输出保存到共享日志。

健康检查只证明服务和数据库可用，不证明新项目已经能够发送通知。仍需完成下一节的真实业务验收。

5.1 管理 API 开通与轮换

维护人现在也可以直接通过管理员 API 管理项目，而不是手工编辑环境变量。管理员鉴权与业务项目 HMAC 密钥分离：

  • 主变量：YYD_NOTIFICATION_ADMIN_API_SECRET
  • 兼容旧变量：YYD_NOTIFICATION_ADMIN_TOKEN
  • 请求头：Authorization: Bearer <YYD_NOTIFICATION_ADMIN_API_SECRET>
  • 可选：x-yyd-admin-actor: <操作人标识>，仅用于审计

常用接口：

  • POST /admin/projects：创建项目，并只在本次响应返回新密钥和交付业务方的 env
  • PATCH /admin/projects/:projectCode：修改名称、域名白名单、启停状态、免登配置
  • PUT /admin/projects/:projectCode/recipients：替换当前项目花名清单
  • POST /admin/projects/:projectCode/rotate-secret：轮换项目密钥，并只在本次响应返回新密钥和 env
  • POST /admin/projects/:projectCode/test：发一条测试通知
  • GET /admin/deliveries / GET /admin/audits：查看投递与审计

关键规则：

  • secret 和 env.YYD_NOTIFICATION_CENTER_PROJECT_SECRET 只在创建/轮换响应中展示一次，后续列表、详情、审计都不回显；
  • 审计日志自动脱敏，不记录明文密钥、签名或 Bearer Token；
  • /admin/* 请求体限制为 256 KB，超限返回结构化错误；
  • /v1/notifications 等业务接口保持原有签名协议与返回语义。

六、安全交付三项配置

向业务项目技术负责人交付：

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 跳转地址；
  • 稳定且不会与生产业务事件冲突的测试幂等键。

维护人与业务项目共同确认：

  1. 创建接口返回 202 或同幂等请求返回 200。
  2. 返回体包含投递 id。
  3. 查询接口只能由当前项目查询该投递记录。
  4. 最终状态进入 sent、unread、read 或给出明确 failed 原因。
  5. 测试员工实际收到“由壹点”机器人单聊。
  6. 标题包含正确项目名称。
  7. 按钮只进入登记的项目域名和正确页面。
  8. 相同幂等键重复请求不产生第二条消息。
  9. 如使用花名，已登记花名能解析，未登记花名明确返回 RECIPIENT_ALIAS_NOT_FOUND。

首次真实发送只做能证明链路的一次必要调用；未获得真实发送授权时使用客户端示例测试，不向员工发送消息。

八、生产验收和交接记录

正式上线至少由两名真实员工完成通知与跳转验证。记录中不保存密钥，只保存：

项目名称：
projectCode：
allowedHosts：
业务负责人：
技术负责人：
通知中心维护人：
业务项目版本或 Git 提交：
通知中心版本或 Git 提交：
生产验证时间：
测试业务事件 ID：
通知中心投递 ID：
最终投递状态：
按钮跳转结果：
遗留问题：

完成后把统一通知中心接入操作手册、消息规范和错误与状态规范交给项目后续维护人。

九、密钥轮换或停用

密钥泄露、负责人变更或项目停用时，不要直接覆盖后结束：

  1. 确认受影响的唯一项目代码和环境。
  2. 说明轮换或停用窗口及对发送通知的影响。
  3. 备份当前配置并准备恢复原密钥的回滚路径。
  4. 新密钥只交付给该项目，不影响其他项目。
  5. 协调通知中心与业务后端在约定窗口切换。
  6. 使用一条有上限的真实通知验证新密钥。
  7. 确认旧密钥失效，并删除不再需要的明文副本。

项目停用前保留必要的历史投递记录，不因停用项目直接删除数据库数据。