54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
# 由壹点通知中心
|
||
|
||
由壹点内部项目统一钉钉机器人单聊出口。只有本服务保存钉钉应用密钥和 `RobotCode`;素材库、固定资产、产品开发平台等业务系统使用各自的项目密钥调用本服务。
|
||
|
||
## 安全边界
|
||
|
||
- 每个项目使用独立 HMAC 密钥。
|
||
- 请求签名包含时间、nonce、HTTP 方法、路径和正文摘要。
|
||
- nonce 五分钟内只能使用一次。
|
||
- 每个项目只能跳转到配置的 HTTPS 域名。
|
||
- `projectCode + idempotencyKey` 唯一,防止业务重试造成重复通知。
|
||
- 项目无法读取其它项目的投递记录。
|
||
|
||
## 本地启动
|
||
|
||
1. 复制 `.env.example` 为 `.env` 并填写真实配置;不要提交 `.env`。
|
||
Windows 下项目目录包含空格,`DATABASE_URL` 请保留为完整绝对路径。
|
||
2. 执行 `npm install`。
|
||
3. 执行 `npm run prisma:generate`。
|
||
4. 执行 `npm run prisma:migrate`。
|
||
5. 执行 `npm run dev`。
|
||
|
||
健康检查:`GET /health`。
|
||
|
||
生产环境建议只把容器端口绑定到 `127.0.0.1`,再由 Nginx 提供独立 HTTPS 域名。素材库和固定资产可能位于不同主机,因此不能把业务项目配置成通知中心的容器内网地址。
|
||
|
||
当前生产部署脚本位于:
|
||
|
||
- `scripts/deploy-material-host.sh`:只管理通知中心独立容器、配置和独立 FRP 服务;
|
||
- `scripts/deploy-public-nginx.sh`:备份并扩展素材库专用 FRP 端口白名单,然后为素材库公网域名增加 `/notification-center/` 反向代理;脚本会验证主站、S3 和通知中心,失败时回滚。
|
||
|
||
脚本不包含任何密钥。统一机器人凭证从素材库生产环境安全复制到通知中心独立 `.env`,项目 HMAC 密钥在服务器生成并以 `0600` 权限保存。
|
||
|
||
素材库生产 NAS 无法稳定访问 Docker Hub。正式发布应先在构建机或维护工作站构建 `youyidian-notification-center:latest`,将镜像安全传入生产机,再执行部署脚本;脚本检测到预载镜像后会使用 `--no-build` 启动。
|
||
|
||
## 签名算法
|
||
|
||
请求头:
|
||
|
||
- `x-yyd-project-code`
|
||
- `x-yyd-timestamp`:Unix 秒
|
||
- `x-yyd-nonce`:每次请求生成新的随机字符串
|
||
- `x-yyd-signature`:HMAC-SHA256 十六进制字符串
|
||
|
||
待签名文本:
|
||
|
||
```text
|
||
timestamp\nnonce\nHTTP_METHOD\nPATH\nSHA256(rawBody)
|
||
```
|
||
|
||
发送接口:`POST /v1/notifications`。查询接口:`GET /v1/notifications/:id`。
|
||
|
||
通知中心只接受任务并异步发送,业务系统通过查询接口获取 `pending / sending / sent / unread / read / retrying / failed` 状态。
|