red-future/cid
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

yidun送检功能

Browse Source
This commit is contained in:
李明康
2026-05-15 10:28:17 +08:00
parent 51d26aeee7
commit c8cc19e8e7
29 changed files with 5133 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
YIDUN_API_DOCUMENTATION.md
View File

@@ -4,11 +4,14 @@
- [概述](#概述)
- [配置说明](#配置说明)
- [模式切换](#模式切换)
- [API接口列表](#api接口列表)
- [文本检测](#1-文本检测)
- [图片检测](#2-图片检测)
- [视频检测](#3-视频检测)
- [回调与轮询接口](#回调与轮询接口)
- [错误码说明](#错误码说明)
- [常见问题](#常见问题)
---
@@ -27,7 +30,7 @@
### 服务地址
```
http://localhost:3002
http://localhost:3001
```
---
@@ -38,38 +41,100 @@ http://localhost:3002
```yaml
yidun:
# 音视频检测配置
# 回调模式开关: true=使用回调模式（需要公网地址）, false=使用轮询模式
callback_mode: false
# 视频检测配置
video:
business_id: "YOUR_VIDEO_BUSINESS_ID"
secret_id: "f58a38341ca6227014df7c3bf0e6f16f"
secret_key: "526aa631ba5d518aedeb70b5a3b67371"
callback_url: "http://your-domain.com:3001/yidun/callback/receiveVideo"
# 图片检测配置
image:
business_id: "YOUR_IMAGE_BUSINESS_ID"
business_id: "your_image_business_id"
secret_id: "9a82f90bfec61eb40d1c95605b894817"
secret_key: "f73a78954417a3713c36ec2d14eb2b5f"
callback_url: "http://your-domain.com:3001/yidun/callback/receiveImage"
# 文本检测配置
text:
business_id: "YOUR_TEXT_BUSINESS_ID"
secret_id: "YOUR_TEXT_SECRET_ID"
secret_key: "YOUR_TEXT_SECRET_KEY"
# 内容送检定时任务配置
content_check:
batch_size: 10 # 每批处理数量
image_enabled: true # 是否启用图片检测
video_enabled: true # 是否启用视频检测
interval_seconds: 30 # 定时任务执行间隔（秒）
```
---
## 模式切换
### 轮询模式（无公网地址）
适用于开发测试环境或没有公网地址的场景。
```yaml
yidun:
callback_mode: false # 使用轮询模式
```
**工作流程**：
```
定时任务 → 提交检测 → 保存taskId → 手动轮询 → 获取结果 → 更新状态
```
### 回调模式（有公网地址）
适用于生产环境，需要配置公网可访问的回调地址。
```yaml
yidun:
callback_mode: true # 使用回调模式
image:
callback_url: "http://your-public-domain.com:3001/yidun/callback/receiveImage"
video:
callback_url: "http://your-public-domain.com:3001/yidun/callback/receiveVideo"
```
**工作流程**：
```
定时任务 → 提交检测 → 易盾检测完成 → 易盾推送结果 → 自动更新状态
```
---
## API接口列表
### 送检接口
| 接口名称 | 请求方法 | 路径 | 说明 |
|---------|---------|------|------|
| 文本检测提交 | POST | `/yidun/detect-text` | 提交文本进行异步检测 |
| 图片检测提交 | POST | `/yidun/detect-image` | 提交图片进行异步检测 |
| 视频检测提交 | POST | `/yidun/detect-video` | 提交视频进行检测 |
| 图片结果查询 | POST | `/yidun/GetImageResult` | 查询图片检测结果（轮询模式） |
| 图片检测回调 | POST | `/yidun/receive-image-callback` | 接收图片检测结果推送（推送模式） |
| 视频结果查询 | POST | `/yidun/GetVideoResult` | 查询视频检测结果（轮询模式） |
| 视频检测回调 | POST | `/yidun/receive-video-callback` | 接收视频检测结果推送（推送模式） |
### 回调模式接口
| 接口名称 | 请求方法 | 路径 | 说明 |
|---------|---------|------|------|
| 接收图片回调 | POST | `/yidun/callback/receiveImage` | 接收易盾图片检测结果推送 |
| 接收视频回调 | POST | `/yidun/callback/receiveVideo` | 接收易盾视频检测结果推送 |
### 轮询模式接口
| 接口名称 | 请求方法 | 路径 | 说明 |
|---------|---------|------|------|
| 轮询所有结果 | POST | `/yidun/callback/poll` | 轮询所有待处理结果（图片+视频） |
| 轮询图片结果 | POST | `/yidun/callback/pollImage` | 仅轮询图片待处理结果 |
| 轮询视频结果 | POST | `/yidun/callback/pollVideo` | 仅轮询视频待处理结果 |
| 查询单个结果 | POST | `/yidun/callback/pollTask` | 根据taskId查询单个结果 |
| 获取待处理数量 | GET | `/yidun/callback/pendingCount` | 查看待处理结果数量 |
**注意**：检测结果是异步的，提交接口只返回 `task_id`，需要通过回调或轮询获取结果。
@@ -814,6 +879,197 @@ callbackData={"antispam":{...}}&signature=xxx&secretId=xxx
---
## 回调与轮询接口
### 轮询模式接口详解
#### 轮询所有待处理结果
```
POST /yidun/callback/poll
```
**说明**：轮询所有图片和视频的待处理检测结果
**响应示例**：
```json
{
"code": 200,
"msg": "轮询完成，成功处理 5 条，失败 1 条",
"data": {
"success_count": 5,
"fail_count": 1,
"pending_count": 10
}
}
```
#### 获取待处理数量
```
GET /yidun/callback/pendingCount
```
**响应示例**：
```json
{
"code": 200,
"data": {
"pending_count": 15,
"description": "待查询结果的日志数量（状态为pending且有taskID）"
}
}
```
#### 查询单个结果
```
POST /yidun/callback/pollTask?taskId=xxx&type=image
```
**参数说明**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskId | string | 是 | 易盾任务ID |
| type | string | 否 | 类型：`image`/`video`，不填则自动识别 |
**响应示例**：
```json
{
"code": 200,
"msg": "查询并处理成功"
}
```
---
## 使用示例
### 轮询模式使用流程
```bash
# 1. 查看待处理数量
curl http://localhost:3001/yidun/callback/pendingCount
# 2. 执行轮询（所有）
curl -X POST http://localhost:3001/yidun/callback/poll
# 3. 或分别轮询
curl -X POST http://localhost:3001/yidun/callback/pollImage
curl -X POST http://localhost:3001/yidun/callback/pollVideo
# 4. 查询单个结果
curl -X POST "http://localhost:3001/yidun/callback/pollTask?taskId=abc123&type=image"
```
### 配置定时轮询
```bash
# 每分钟轮询一次
*/1 * * * * curl -X POST http://localhost:3001/yidun/callback/poll
# 或更保守的频率（每5分钟）
*/5 * * * * curl -X POST http://localhost:3001/yidun/callback/poll
```
---
## 状态说明
### 检测状态转换
```
┌─────────────────────────────────────────────────────────────┐
│ 送检前 │
│ tencent_image/tencent_video: status = "pending" │
└─────────────────────────────────────────────────────────────┘
↓
↓ 定时任务/手动送检
↓
┌─────────────────────────────────────────────────────────────┐
│ 提交检测 │
│ material_verify_log: verify_status = "PENDING" │
│ material_verify_log: task_id = "易盾任务ID" │
│ tencent_xxx: status = "submitting" │
└─────────────────────────────────────────────────────────────┘
↓
↓ 等待检测完成
↓ (回调模式)或(轮询查询)
↓
┌─────────────────────────────────────────────────────────────┐
│ 检测完成 │
│ material_verify_log: verify_status = "VERIFIED" (通过) │
│ 或 "REJECTED" (不通过) │
│ 或 "PENDING" (嫌疑，需人工审核) │
│ tencent_xxx: status = "VERIFIED"/"REJECTED"/"PENDING" │
└─────────────────────────────────────────────────────────────┘
```
### 状态值说明
| 状态值 | 说明 | 触发条件 |
|--------|------|----------|
| `pending` / `PENDING` | 待检测 | 素材创建时 |
| `submitting` | 送检中 | 提交至易盾检测 |
| `VERIFIED` | 校验通过 | 易盾建议通过（suggestion=0）|
| `REJECTED` | 校验不通过 | 易盾建议不通过（suggestion=2）或检测失败 |
| `PENDING` (人审) | 嫌疑待审 | 易盾建议人工审核（suggestion=1）|
### 易盾处置建议对照
| suggestion值 | 说明 | 系统状态 |
|-------------|------|----------|
| 0 | 通过 | VERIFIED |
| 1 | 嫌疑，需人工审核 | PENDING |
| 2 | 不通过 | REJECTED |
---
## 常见问题
### Q1: 轮询后待处理数量没有减少？
**可能原因**：
1. 检测仍在进行中（易盾尚未返回结果）
2. 上次查询出错，状态已更新为 REJECTED
**排查方法**：
```bash
# 查看日志
grep "检测仍在进行中" resource/log/server/cid.log
# 查看数据库状态
SELECT id, task_id, verify_status FROM material_verify_log WHERE task_id = 'xxx';
```
### Q2: 如何判断是图片还是视频？
```bash
# 方法1：查询日志
SELECT id, material_type, task_id, verify_status FROM material_verify_log WHERE task_id = 'xxx';
# 方法2：调用接口指定类型
curl -X POST "http://localhost:3001/yidun/callback/pollTask?taskId=xxx&type=image"
```
### Q3: 回调模式收不到回调？
**排查步骤**：
1. 确认公网地址可访问：`curl http://your-domain.com:3001/yidun/callback/receiveImage`
2. 确认易盾控制台配置了正确的回调地址
3. 检查服务器防火墙/安全组是否开放端口
4. 查看日志确认请求是否到达：`grep "收到易盾" resource/log/server/cid.log`
### Q4: 状态不一致？
如果 `material_verify_log` 和 `tencent_image/video` 表状态不一致，检查：
1. 代码执行过程中是否有报错
2. 是否有并发更新导致覆盖
3. 日志表和原表更新是否在同一事务中
---
## 错误码说明
| code | 说明 |
@@ -872,4 +1128,4 @@ func detectVideo() (string, error) {
---
**最后更新**: 2026-05-07
**最后更新**: 2026-05-14