176 lines
5.0 KiB
Markdown
176 lines
5.0 KiB
Markdown
# 回调告警转短信服务
|
||
|
||
本项目是一个 Python 后端服务，用于接收 AI 视频分析平台的 HTTP 回调，并将关键告警信息转为阿里云短信发送给手机号列表。
|
||
|
||
## 启动指令
|
||
pip install -r requirements.txt
|
||
py -m uvicorn app.main:app --host 0.0.0.0 --port 2336
|
||
|
||
核心目标：
|
||
1. 接收并解析上游回调 JSON。
|
||
2. 生成短信模板变量 ACTION。
|
||
3. 查询 SQLite 中已启用手机号并群发。
|
||
4. 记录可追踪日志，返回标准化接口结果。
|
||
|
||
## 1. 功能概览
|
||
|
||
服务提供两个接口：
|
||
1. GET /healthz：健康检查。
|
||
2. POST /callback：接收告警回调并触发短信逻辑。
|
||
|
||
POST /callback 的处理流程：
|
||
1. 解析 JSON（支持常见编码容错）。
|
||
2. 提取事件标识 event_id（优先 snowflake_id，其次 analysis_job_id）。
|
||
3. 脱敏写日志（图片 base64、密钥等敏感字段不落盘）。
|
||
4. 生成短信预览文本：发现有${ACTION}行为，请去摄像头查看。
|
||
5. 查询 SQLite 中 is_enabled=1 的手机号。
|
||
6. 根据 LOG_ONLY_NO_SMS 决定仅预览还是实际调用阿里云接口。
|
||
7. 返回统一结构：code、message、data。
|
||
|
||
## 2. 环境准备
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
推荐 Python 3.11+。
|
||
|
||
## 3. 配置说明
|
||
|
||
项目默认通过 .env 读取配置，主要参数如下：
|
||
|
||
1. ALIBABA_CLOUD_ACCESS_KEY_ID：阿里云 AK。
|
||
2. ALIBABA_CLOUD_ACCESS_KEY_SECRET：阿里云 SK。
|
||
3. ALIBABA_CLOUD_REGION_ID：区域，默认 cn-hangzhou。
|
||
4. ALIYUN_SMS_SIGN_NAME：已审核通过的短信签名。
|
||
5. ALIYUN_SMS_TEMPLATE_CODE：短信模板编码。
|
||
6. SMS_DB_PATH：SQLite 数据库路径，默认 data/sms_receivers.db。
|
||
7. SMS_DB_TABLE：手机号表名，默认 sms_receivers。
|
||
8. LOG_ONLY_NO_SMS：是否仅预览不实发。
|
||
|
||
LOG_ONLY_NO_SMS 取值建议：
|
||
1. true：联调阶段使用，不调用阿里云发送。
|
||
2. false：生产或实发测试使用，会真实发送短信。
|
||
|
||
## 4. 手机号来源与优先级
|
||
|
||
服务启动时会自动创建手机号表（如果不存在）：
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS sms_receivers (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
phone_number TEXT NOT NULL UNIQUE,
|
||
is_enabled INTEGER NOT NULL DEFAULT 1,
|
||
updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
接收方选择规则：
|
||
1. 仅使用 SQLite 中 is_enabled=1 的手机号。
|
||
|
||
这意味着你在服务运行期间修改数据库，下一次 callback 会立即生效，无需重启。
|
||
|
||
常用维护 SQL：
|
||
|
||
```sql
|
||
INSERT INTO sms_receivers (phone_number, is_enabled) VALUES ('17394641215', 1);
|
||
UPDATE sms_receivers SET is_enabled = 0, updated_at = CURRENT_TIMESTAMP WHERE phone_number = '17394641215';
|
||
DELETE FROM sms_receivers WHERE phone_number = '17394641215';
|
||
```
|
||
|
||
## 5. 启动服务
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
py -m uvicorn app.main:app --host 0.0.0.0 --port 2336
|
||
```
|
||
|
||
启动成功后会看到：
|
||
1. sms_db_ready
|
||
2. Uvicorn running on http://0.0.0.0:2336
|
||
|
||
## 6. 如何测试
|
||
|
||
### 6.1 健康检查
|
||
|
||
```bash
|
||
curl http://127.0.0.1:2336/healthz
|
||
```
|
||
|
||
### 6.2 回调测试
|
||
|
||
方式一：使用示例文件 test_callback_payload.json。
|
||
|
||
```bash
|
||
curl -X POST "http://127.0.0.1:2336/callback" \
|
||
-H "Content-Type: application/json; charset=utf-8" \
|
||
--data-binary "@test_callback_payload.json"
|
||
```
|
||
|
||
方式二：直接发最小 JSON。
|
||
|
||
```bash
|
||
curl -X POST "http://127.0.0.1:2336/callback" \
|
||
-H "Content-Type: application/json" \
|
||
-d "{\"algorithm_name\":\"行人闯入\",\"snowflake_id\":\"demo-001\"}"
|
||
```
|
||
|
||
## 7. 返回结构说明
|
||
|
||
接口始终返回统一结构：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": {
|
||
"event_id": "1768287987212271616",
|
||
"sms_preview": "发现有行人闯入行为，请去摄像头查看。",
|
||
"sms_ok": true,
|
||
"sms_skipped": false,
|
||
"receiver_count": 1,
|
||
"sms": {
|
||
"code": "OK",
|
||
"message": "OK",
|
||
"request_id": "...",
|
||
"biz_id": "..."
|
||
},
|
||
"sms_error": ""
|
||
}
|
||
}
|
||
```
|
||
|
||
字段含义：
|
||
1. sms_preview：短信文本语义预览。
|
||
2. sms_skipped：是否因为 LOG_ONLY_NO_SMS=true 而跳过实发。
|
||
3. sms_ok：阿里云返回码是否为 OK。
|
||
4. sms：阿里云网关返回详情。
|
||
5. sms_error：发送失败时的错误信息。
|
||
|
||
## 8. 日志与排障
|
||
|
||
日志位置：logs/callback.log。
|
||
|
||
常见日志事件：
|
||
1. callback_received：收到回调。
|
||
2. sms_preview：短信预览与模板参数。
|
||
3. sms_receivers_loaded：当前收件人数。
|
||
4. sms_sent：已调用阿里云并返回结果。
|
||
5. sms_skipped：当前为仅预览模式。
|
||
6. sms_config_missing：缺少必要配置。
|
||
|
||
常见问题：
|
||
1. 看见中文乱码：多数是终端显示编码问题，先以接口 JSON 返回为准。
|
||
2. 未发送短信：检查 LOG_ONLY_NO_SMS 是否为 true。
|
||
3. receiver_count 为 0：检查 SQLite 是否有 is_enabled=1 的号码。
|
||
4. 阿里云报模板错误：确认签名、模板编码、模板变量 ACTION 与控制台一致。
|
||
|
||
## 9. 安全建议
|
||
|
||
1. 不要把 AK/SK 提交到版本库。
|
||
2. 生产环境建议通过系统环境变量注入密钥。
|
||
3. 定期轮换 AK/SK，并限制 RAM 权限最小化。
|