WuYongJie/YouYiDianNotificationCenter

Fork 0

WuYongJie 3fb60314a2 fix: 标准化钉钉限流重试策略

2026-08-29 14:35:03 +08:00

10 KiB

Raw Blame History

由壹点通知中心

由壹点内部项目统一钉钉机器人单聊出口。只有本服务保存钉钉应用密钥和 RobotCode；素材库、固定资产、产品开发平台等业务系统使用各自的项目密钥调用本服务。

业务项目接入

新项目不要从本 README 中零散复制接口代码，请按以下规范接入：

统一通知中心接入操作手册：可直接交给其他项目负责人的完整接入流程、代码入口与验收标准。
通知中心新项目开通操作手册：仅供通知中心维护人登记项目、生成密钥、安全交付和验收使用。
接入指南：项目登记、环境变量、签名、发送、多人通知和上线验证。
消息规范：标题、正文、状态和按钮的统一写法。
错误与状态规范：HTTP 返回、投递状态、错误码和重试边界。
新项目接入清单：从申请到生产验证的逐项门禁。
Node.js 客户端示例：可以直接复制到业务后端的无依赖实现。

接入的核心边界：业务项目只保存自己的项目代码和 HMAC 密钥；钉钉 AppKey、AppSecret、RobotCode 始终只由通知中心持有。

收件人支持两种方式：业务项目可以直接提交钉钉 userId，也可以提交当前项目已由通知中心登记的准确花名。花名会在中心解析为 userId；未登记或冲突时拒绝发送，不做模糊猜测。

安全边界

每个项目使用独立 HMAC 密钥。
请求签名包含时间、nonce、HTTP 方法、路径和正文摘要。
nonce 五分钟内只能使用一次。
每个项目只能跳转到配置的 HTTPS 域名。
projectCode + idempotencyKey 唯一，防止业务重试造成重复通知。
项目无法读取其它项目的投递记录。
钉钉 AppSecret 只保存在通知中心；业务系统只用自己的项目 HMAC 密钥兑换登录票据。
登录票据随机生成、只存 SHA-256 摘要、最长 60 秒、绑定项目和回跳域名并且只能原子消费一次。
免登码和登录票据都只通过 POST 传递，不进入 URL；服务日志不记录二者和任何密钥。

本地启动

复制 .env.example 为 .env 并填写真实配置；不要提交 .env。 Windows 下项目目录包含空格，DATABASE_URL 请保留为完整绝对路径。 YYD_NOTIFICATION_ADMIN_API_SECRET（兼容旧变量 YYD_NOTIFICATION_ADMIN_TOKEN）和 YYD_NOTIFICATION_CONFIG_ENCRYPTION_KEY 只保存在通知中心服务端。
执行 npm install。
执行 npm run prisma:generate。
执行 npm run prisma:migrate。
执行 npm run dev。

健康检查：GET /health。

npm test 不读取本地 .env：测试入口会创建唯一临时 SQLite，先执行正式 Prisma 迁移，再串行运行测试，并在成功或失败后清理数据库、journal、WAL 和 SHM 文件。

项目配置来源与管理 API

当 YYD_NOTIFICATION_ADMIN_API_SECRET（或兼容旧变量 YYD_NOTIFICATION_ADMIN_TOKEN）与 YYD_NOTIFICATION_CONFIG_ENCRYPTION_KEY 都已配置时，通知项目配置以数据库为准；YYD_NOTIFICATION_PROJECTS_JSON 只承担“首次/补录导入缺失项目”的 bootstrap 角色：

服务启动时会尝试把 YYD_NOTIFICATION_PROJECTS_JSON 中尚未登记的项目导入数据库；
已存在项目不会被覆盖，已轮换密钥、已手工维护的 recipients 和登录配置保持不变；
运维可用 POST /admin/runtime/import-env 再次补录当前环境变量中的缺失项目；
运维可用 POST /admin/runtime/refresh 让运行时缓存重新读取数据库，不必重启进程。
如果管理员密钥或加密密钥缺失，服务会安全回退到 legacy 内存模式：继续直接使用 YYD_NOTIFICATION_PROJECTS_JSON 提供旧 /v1/* 能力，且不挂载 /admin/*。

管理 API 使用独立管理员 Bearer Secret，与业务项目 HMAC 密钥隔离：

主变量：YYD_NOTIFICATION_ADMIN_API_SECRET
兼容旧变量：YYD_NOTIFICATION_ADMIN_TOKEN
请求头：Authorization: Bearer <YYD_NOTIFICATION_ADMIN_API_SECRET>
可选 x-yyd-admin-actor：写入审计日志的操作人标识

当前管理接口：

GET /admin/projects / GET /admin/projects/:projectCode
POST /admin/projects
PATCH /admin/projects/:projectCode
DELETE /admin/projects/:projectCode
GET|PUT /admin/projects/:projectCode/recipients
POST /admin/projects/:projectCode/rotate-secret
POST /admin/projects/:projectCode/test
GET /admin/deliveries
GET /admin/audits
POST /admin/runtime/import-env
POST /admin/runtime/refresh

稳定响应 contract：

项目列表：{ projects: [...] }，默认包含 projectCode / name / recipientCount / recipients / deliverySummary
创建/轮换密钥：{ project, secret, env }
投递列表：{ deliveries, total }
审计列表：{ audits, total }
管理错误：{ error: { code, message, details? } }

其中 secret 与 env.YYD_NOTIFICATION_CENTER_PROJECT_SECRET 只会在 POST /admin/projects 和 POST /admin/projects/:projectCode/rotate-secret 当次响应里出现一次，后续列表、详情和审计都不会回显明文密钥。

请求体大小限制：

业务 /v1/*：64 KB
管理 /admin/*：256 KB

普通业务接入接口 POST /v1/notifications、GET /v1/notifications/:id、GET /v1/notifications 与原签名协议保持兼容。

生产环境建议只把容器端口绑定到 127.0.0.1，再由 Nginx 提供独立 HTTPS 域名。素材库和固定资产可能位于不同主机，因此不能把业务项目配置成通知中心的容器内网地址。

当前生产部署脚本位于：

scripts/deploy-material-host.sh：只管理通知中心独立容器、配置和独立 FRP 服务；
scripts/deploy-public-nginx.sh：备份并扩展素材库专用 FRP 端口白名单，然后为素材库公网域名增加 /notification-center/ 反向代理；脚本会验证主站、S3 和通知中心，失败时回滚。

脚本不包含任何密钥。统一机器人凭证从素材库生产环境安全复制到通知中心独立 .env，项目 HMAC 密钥在服务器生成并以 0600 权限保存。

发布脚本会先一致性备份通知中心 SQLite、环境配置和源码，再从本次解压的源码强制构建镜像并 force-recreate，不会因为服务器上存在旧 latest 镜像而跳过新代码。素材库生产 NAS 无法稳定访问 Docker Hub，正式发布前应预载 node:22-alpine 基础镜像并确认 npm 依赖源可用；构建失败会在重建容器前终止，旧服务继续运行。

Git 发布入口会在生产机首次生成、后续稳定保留 YYD_NOTIFICATION_ADMIN_API_SECRET 与 YYD_NOTIFICATION_CONFIG_ENCRYPTION_KEY，并只把管理地址和管理员密钥同步到素材库后端 .env；脚本只打印配置完成状态，不输出密钥原文。

签名算法

请求头：

x-yyd-project-code
x-yyd-timestamp：Unix 秒
x-yyd-nonce：每次请求生成新的随机字符串
x-yyd-signature：HMAC-SHA256 十六进制字符串

待签名文本：

timestamp\nnonce\nHTTP_METHOD\nPATH\nSHA256(rawBody)

发送接口：POST /v1/notifications。查询接口：GET /v1/notifications/:id。

通知中心只接受任务并异步发送，业务系统通过查询接口获取 pending / sending / sent / unread / read / retrying / failed 状态。

钉钉 H5 免登中转

项目的 login 配置是可选项；不配置时仍按原方式直接跳转，素材库等现有调用不受影响。启用后，通知中心会把业务传入的项目 HTTPS 地址转换为内部 redirectPath，并把卡片动作包装到统一入口：

GET /v1/auth/h5-entry?projectCode=fixed_asset&redirectPath=%2Fworkflows%2Fdisposals%2F53

入口页面向钉钉 JSAPI 同时传入公开的 clientId（即 AppKey）和 corpId 获取免登码，再以 JSON POST 调用：

POST /v1/auth/h5-code
{"projectCode":"fixed_asset","redirectPath":"/workflows/disposals/53","code":"..."}

中心换取钉钉 userId 后返回 {ticket, formPostUrl, expiresIn}，页面立即通过隐藏表单把 ticket POST 到项目配置的精确 callbackUrl。业务后端收到票据后，使用与通知接口相同的 HMAC 头调用：

POST /v1/auth/tickets/redeem
{"ticket":"..."}

成功响应只包含 {dingtalkUserId, redirectPath}。未知、过期、已消费或跨项目票据统一返回 401 TICKET_INVALID_OR_EXPIRED，不泄露票据是否存在。业务系统必须在创建 Session 前重新核验本地账号、员工绑定和在职状态。

项目配置示例：

{
  "code": "fixed_asset",
  "name": "固定资产",
  "secret": "独立随机项目密钥",
  "allowedHosts": ["asset.jiansun.vip"],
  "login": {
    "enabled": true,
    "callbackUrl": "https://asset.jiansun.vip/api/dingtalk/broker-login",
    "allowedRedirectPathPrefixes": ["/workflows/disposals", "/dashboard", "/inventory"]
  }
}

新增环境变量：

DINGTALK_CORP_ID：统一钉钉应用所属企业 CorpId。
YYD_NOTIFICATION_PUBLIC_BASE_URL：通知中心公网 HTTPS 基地址，生产为反向代理后的 /notification-center 地址。
DINGTALK_LOGIN_TICKET_TTL_SECONDS：30~60 秒，默认 60 秒。

新建任务最多投递 5 次，钉钉 HTTP 429、QpsLimit 和其他明确限流统一归一为 FLOW_CONTROLLED，按 1、5、15、30 分钟退避；接入方只观察统一状态和错误码，不解析钉钉厂商错误码。中心默认将发送请求启动间隔限制为至少 250ms（WORKER_SEND_MIN_INTERVAL_MS 可在 100～5000ms 内调整），避免整点任务集中冲击下游。发送调用若在请求已发出后发生网络断开、超时、非限流 HTTP 408/5xx、钉钉成功响应缺少 processQueryKey，或进程在发送中途崩溃并遗留过期租约，会以 DELIVERY_OUTCOME_UNKNOWN 结束并停止自动重试，避免不确定结果造成重复单聊。历史任务保留创建时的最大尝试次数，不通过迁移篡改。

10 KiB Raw Blame History Unescape Escape