免密图片下载
接口描述
针对采用MQTT消息服务上传的识别结果，其图片被推送到云服务器上。常规的下载图片接口需要AccessKey签名鉴权，但在以下场景中不便使用：
- 网页嵌入：第三方网页（如车场大屏、客户后台）直接通过
<img>标签引用图片，浏览器请求无法携带AccessKey签名。 - 服务端拉取：后端服务批量下载图片，不希望为每次请求生成签名。
免密图片下载接口通过白名单实现鉴权：公司在控制台「系统配置 → 图片免密读」中配置信任的域名白名单（Referer校验）和IP白名单（来源IP校验），并开启总开关后，来自白名单内的请求即可免签名、免AccessKey获取图片。
前提条件：
- 在控制台「系统配置 → 图片免密读」中开启总开关。
- 添加至少一条白名单规则（域名或IP）。
- 白名单规则变更后最长 10 秒生效（服务端缓存刷新周期）。
鉴权机制
中间件采用双通道策略，任一命中即放行：
| 通道 | 适用场景 | 校验方式 |
|---|---|---|
| IP 白名单 | 服务端程序拉取（无 Referer 头） | 按请求来源 IP 匹配，支持精确 IP 与 CIDR 网段（仅 IPv4） |
| 域名白名单 | 网页嵌入（浏览器自动带 Referer） | 按请求 Referer 头的 host 匹配，支持精确域名与 *.example.com 后缀通配 |
两个通道均未命中时返回 400（错误码 1003）。
与「下载图片」接口的区别
| 项目 | 下载图片 | 免密图片下载 |
|---|---|---|
| 鉴权 | AccessKey + HMAC-SHA1 签名 | 白名单（Referer / IP）+ 总开关 |
| 路径 | /openapi/v1/imgs/... |
/openapi/v1/public/imgs/... |
| 适用场景 | 服务端有 AK 的程序化调用 | 网页嵌入、无 AK 的服务端拉取 |
请求说明
| 接口ID | 协议 | 方法 | PATH |
|---|---|---|---|
| 1501 | HTTPS | GET | /openapi/v1/public/${image_path} |
PATH参数
| 参数 | 类型 | 说明 |
|---|---|---|
| image_path | string | 图片路径（在MQTT推送的消息中会携带图片路径，注意需要base64解码） |
请求头
| 头 | 必填 | 说明 |
|---|---|---|
Referer |
否 | 浏览器自动携带。网页嵌入场景由此头匹配域名白名单；缺失时走 IP 白名单通道。两个通道都不命中返回 400 |
请求示例
GET https://open.vzicloud.com/openapi/v1/public/imgs/0c067893-556f140f/20240101/1600914068_167485218_3_0_full.jpg HTTP/1.1
Host: open.vzicloud.com
Referer: https://admin.example.com/dashboard/parking
返回说明
白名单校验通过后，返回一个 302 重定向，重定向地址为图片真正的下载地址（具备有效期，超过有效期不可访问）。
| 场景 | HTTP | 响应 |
|---|---|---|
| 白名单命中且图片存在 | 302 | Location: <图片下载地址> |
| 总开关未开启 | 400 | { "code": 1003, "message": "图片免密读未开启" } |
| IP/Referer 均未命中白名单 | 400 | { "code": 1003, "message": "IP/Referer 未授权" } |
| 设备不属于白名单命中公司 | 400 | { "code": 1003, "message": "无权访问该设备" } |
| 命中公司流量不足 | 400 | { "code": 1010, "message": "流量耗尽，请购买流量" } |
流量计费：免密下载的流量计入白名单命中的公司账户，与「下载图片」接口一致。若设备已开通云备份且公司流量耗尽，返回 1010 错误。
白名单配置
白名单通过控制台「系统管理 → 系统配置 → 图片免密读」页面配置，包含：
- 总开关：功能级开关。关闭后即使存在白名单规则，所有免密下载请求均被拒绝。
- 域名白名单：用于网页嵌入场景（Referer 校验）。
- 精确匹配：如
admin.example.com - 后缀通配：如
*.example.com（匹配任意子域名）
- 精确匹配：如
- IP 白名单：用于服务端拉取场景（来源 IP 校验，仅 IPv4）。
- 精确 IP：如
8.8.8.8 - CIDR 网段：如
192.168.1.0/24
- 精确 IP：如
匹配规则
- 同 host/IP 多公司命中时，取最先创建（id 最小）的规则所属公司。
- 白名单变更后最长 10 秒生效（服务端缓存刷新周期）。
- 命中公司的设备归属于校验：白名单命中公司 A，只能访问公司 A 名下的设备图片，不可跨公司访问。