云平台系统 产品需求文档
| 字段 | 内容 |
|---|---|
| 文档编号 | SUB-CP-V0.1 |
| 版本 | V0.1 |
| 状态 | 草稿 |
| 作者 | 产品团队 |
| 日期 | 2026-04-16 |
| 审核人 | [待定] |
修订记录
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| V0.1 | 2026-04-16 | 产品团队 | 初稿 |
1. 概述
1.1 目的
本文档定义云平台子系统（Cloud Platform, CP）的产品需求，作为云平台系统设计、开发、部署和运维的依据。云平台是农业无人机系统的远程服务中枢，为设备管理、远程遥测、远程指令、OTA升级、作业数据管理等功能提供后端支撑。
1.2 适用范围
- 适用产品型号：XX 农业无人机
- 适用版本：V1.0 种子用户版（100台规模）
- 未来版本：V1.5/V2.0 扩展至1,000~10,000台规模
1.3 关联文档
| 文档编号 | 文档名称 | 关系 |
|---|---|---|
| PRD-MASTER-V0.1 | 总体产品需求文档 | 上位需求来源 |
| ICD-07-V0.1 | 飞控与App远程接口(4G) | 接口定义（云平台通信架构、API路径、安全机制） |
| SUB-APP-V0.1 | 操控App系统PRD | 协作子系统（App为云平台主要客户端） |
| SUB-FC-V0.1 | 飞控系统PRD | 协作子系统（飞行器为云平台数据源） |
1.4 术语定义
| 术语 | 定义 |
|---|---|
| MAVLink TCP Relay | 云端MAVLink透传中继服务，不解析不转换MAVLink消息，仅做TCP会话级转发 |
| REST API | 基于HTTP的业务接口，用于用户认证、设备管理、OTA、作业记录等非实时业务 |
| mTLS | 双向TLS认证，设备和服务端互相验证证书 |
| JWT | JSON Web Token，用于用户身份认证的令牌机制 |
| HMAC | Hash-based Message Authentication Code，基于哈希的消息认证码 |
| OTA | Over-The-Air，空中固件升级 |
| TSDB | Time Series Database，时序数据库，用于存储遥测数据 |
| RBAC | Role-Based Access Control，基于角色的访问控制 |
| GEO围栏 | 地理围栏，定义禁飞区/限飞区/授权区的地理边界数据 |
| 灰度发布 | 按百分比或设备分组逐步推送固件更新的策略 |
| CA | Certificate Authority，证书颁发机构 |
| PIPL | Personal Information Protection Law，中华人民共和国个人信息保护法 |
2. 系统描述
2.1 子系统职责
云平台系统是农业无人机系统的远程服务中枢，负责设备管理、远程遥测透传与存储、远程指令转发与审计、OTA固件分发、作业数据管理、GEO围栏服务和地图服务，为飞行器和操控App提供完整的云端业务支撑。
2.2 系统边界
飞行器(4G模块) 操控App(Wi-Fi/4G)
│ │
│ MAVLink TCP (mTLS) │ MAVLink TCP (Token)
▼ ▼
┌──────────────────────────────────────────────┐
│ 云平台系统 (CP) │
│ │
│ ┌─────────────┐ ┌───────────────────────┐ │
│ │ MAVLink TCP │ │ REST API 服务 │ │
│ │ Relay 服务 │ │ │ │
│ │ │ │ · 用户认证 (JWT) │ │
│ │ · 透传转发 │ │ · 设备管理 │ │
│ │ · 旁路采集 │ │ · 作业数据 │ │
│ │ · 指令审计 │ │ · 固件/OTA │ │
│ │ · 会话管理 │ │ · GEO围栏 │ │
│ └──────┬──────┘ │ · 地图服务 │ │
│ │ │ · 历史遥测查询 │ │
│ │ 旁路写入 └───────────┬───────────┘ │
│ ▼ │ │
│ ┌──────────────────────────────┴───────────┐ │
│ │ 数据存储层 │ │
│ │ · 时序数据库 (遥测数据, ≥90天) │ │
│ │ · 关系数据库 (用户/设备/作业/权限) │ │
│ │ · 对象存储 (固件包/地图文件/航测图) │ │
│ │ · 审计日志存储 (指令日志, ≥1年) │ │
│ └─────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘上游输入：
- 飞行器：通过4G模块建立TCP连接，发送MAVLink v2二进制流（遥测数据）
- 操控App：通过TCP连接接收/发送MAVLink消息（遥测查看/指令下发）；通过HTTPS调用REST API（业务操作）
下游输出：
- 向App透传飞行器MAVLink数据流
- 向App提供REST API响应（设备列表、历史遥测、作业记录、固件信息、GEO围栏、地图等）
- 向飞行器透传App下发的MAVLink指令
协作子系统：
- SUB-APP（操控App）：云平台的主要客户端，消费所有REST API和MAVLink TCP Relay服务
- SUB-FC（飞控系统）：通过4G模块与云平台建立TCP连接，是遥测数据的源头和指令的执行者
- ICD-07：定义了飞控↔App远程接口的完整规范，云平台PRD需与之完全对齐
2.3 架构决策说明
2.3.1 为什么选择MAVLink TCP透传而非MQTT
决策：4G实时通道采用MAVLink over TCP直连透传，云端做纯TCP Relay；业务功能走独立REST API。
考量因素：
前期开发难度最低
- TCP Relay方案：App已有MAVLink协议栈，4G通道只是换个socket地址，业务代码零修改
- 全MQTT方案：需额外开发MAVLink↔JSON转换层、MQTT客户端、部署Broker，工作量翻倍
代码复用
- 直连链路（AR8131）和4G链路对App完全透明，都是MAVLink over TCP/UDP
- 一套代码两条路径，维护成本最低
生态兼容
- QGroundControl、Mission Planner等开源GCS原生支持MAVLink TCP远程连接
- 调试和测试阶段可直接用开源工具验证
种子用户阶段够用
- 100台设备，不需要Pub/Sub一对多实时订阅
- TCP Relay + REST API完全满足需求
渐进式升级路径
V1.0（种子用户100台）： MAVLink TCP Relay + REST API（最小可行） → 开发量最小，快速上线 V1.5（规模扩大至1,000台）： + WebSocket推送（机队看板实时更新） → 在REST层加WebSocket，不动MAVLink通道 V2.0（万台级别）： TCP Relay → MQTT fanout层（多订阅者） → 仅在云端relay后面加MQTT Broker做消息分发 → App端仍然收MAVLink，由Broker负责协议桥接 → App代码不变，只是云端架构升级每个版本只在云端加层，App代码始终不需要改动。
2.3.2 架构方案对比
| 维度 | 方案A：MAVLink TCP + REST（采用） | 方案B：全MQTT（弃用） |
|---|---|---|
| 前期开发量 | 低——App复用MAVLink协议栈 | 高——需协议转换层+MQTT客户端+Broker |
| 协议栈数量 | App维护1套（MAVLink），云端REST独立 | App维护2套（MAVLink + MQTT） |
| 实时性 | 直接TCP转发，延迟低 | 多一层Broker转发+JSON序列化 |
| 直连/4G代码复用 | 完全复用 | 不可复用 |
| 一对多订阅 | 不擅长（TCP点对点） | 擅长（Pub/Sub） |
| 生态兼容 | QGC/Mission Planner原生支持 | 需定制开发 |
2.4 工作环境
云平台为纯软件系统，部署于云服务器/数据中心环境：
- 部署环境：中国境内机房（数据安全法/PIPL合规要求）
- 运行环境：Linux服务器（Ubuntu/CentOS）
- 网络环境：公网IP + 负载均衡，支持TCP长连接和HTTPS
- 依赖基础设施：时序数据库、关系数据库、对象存储、监控告警系统
3. 功能需求
3.1 设备管理（CP-F-1xx）
| 编号 | 需求描述 | 优先级 | 验证方式 | 来源 |
|---|---|---|---|---|
| CP-F-101 | 云平台应支持设备注册：飞行器出厂时预分配唯一设备ID和激活码，用户通过App扫码或手动输入激活码完成设备绑定（对应API：POST /api/v1/devices/{id}/bindcode） | P0 | 接口测试+端到端流程 | ICD-07-I-040, SYS-C-002 |
| CP-F-102 | 云平台应支持设备身份认证：每台飞行器使用X.509设备证书进行mTLS认证，证书由产品CA签发；云平台维护设备证书的签发、吊销、续期流程 | P0 | 安全测试 | ICD-07-I-040~042 |
| CP-F-103 | 云平台应维护设备在线/离线状态：基于MAVLink TCP Relay连接状态判定——TCP会话建立且收到HEARTBEAT为在线，30秒无HEARTBEAT或TCP断开为离线；状态变更应在5秒内反映至REST API查询结果 | P0 | 接口测试+模拟断连 | ICD-07-R-004 |
| CP-F-104 | 云平台应跟踪每台设备的固件版本信息（飞控/电调/遥控器），设备上线时通过MAVLink AUTOPILOT_VERSION消息旁路采集版本号并更新至设备注册表 | P1 | 接口测试 | CP-F-601 |
| CP-F-105 | 云平台应支持设备分组管理：按用户（归属）、按区域（省/市）、按型号分组，支持一台设备属于多个分组；分组信息用于OTA灰度发布和统计报表 | P1 | 接口测试 | — |
| CP-F-106 | 设备绑定/解绑操作需通过物理确认（飞行器端按键确认或扫码确认），不可纯远程完成 | P0 | 端到端流程测试 | ICD-07-I-052 |
| CP-F-107 | 云平台应提供设备列表查询API（GET /api/v1/devices），返回用户已绑定的所有设备及其在线状态、最新位置、固件版本等摘要信息 | P0 | 接口测试 | ICD-07 §6.2 |
| CP-F-108 | 云平台应支持管理员查看所有设备的注册信息、在线状态、绑定关系，用于运维排障 | P1 | 接口测试 | — |
3.2 用户管理（CP-F-2xx）
| 编号 | 需求描述 | 优先级 | 验证方式 | 来源 |
|---|---|---|---|---|
| CP-F-201 | 云平台应支持用户注册：手机号+密码注册，注册时通过短信验证码验证手机号有效性 | P0 | 接口测试+短信通道 | ICD-07-I-045 |
| CP-F-202 | 云平台应支持用户登录：账号+密码+短信验证码双因素认证（对应API：POST /api/v1/auth/login） | P0 | 接口测试 | ICD-07-I-045 |
| CP-F-203 | 云平台应实现JWT Token管理：Access Token有效期≤2小时，Refresh Token有效期≤7天；支持Token刷新（POST /api/v1/auth/refresh）和主动注销 | P0 | 安全测试 | ICD-07-I-046 |
| CP-F-204 | 云平台应支持基于角色的权限控制（RBAC），预置三个角色：管理员（Admin）、操作员（Operator）、只读观察者（Viewer） | P0 | 权限测试 | — |
| CP-F-205 | 角色权限定义：管理员拥有全部权限（设备管理/用户管理/OTA/系统配置）；操作员可操控设备和下发指令；观察者仅可查看遥测数据和作业记录 | P0 | 权限测试 | — |
| CP-F-206 | 云平台应维护用户-设备绑定关系：一个用户可绑定多台设备，一台设备可被多个用户绑定（需设备所有者授权） | P0 | 接口测试 | CP-F-101 |
| CP-F-207 | 多用户绑定同一设备时，应区分权限等级：设备所有者（Owner，首次绑定者）拥有完整控制权，被授权用户的权限由所有者指定（操作员/观察者） | P1 | 权限测试 | — |
| CP-F-208 | 连续5次登录失败后，账号应锁定30分钟，防止暴力破解 | P0 | 安全测试 | — |
3.3 远程遥测服务（CP-F-3xx）
| 编号 | 需求描述 | 优先级 | 验证方式 | 来源 |
|---|---|---|---|---|
| CP-F-301 | 云平台应部署MAVLink TCP Relay服务：接收飞行器4G模块的TCP连接（mTLS认证），透传MAVLink v2二进制流至对应App的TCP会话，不解析不转换MAVLink消息内容 | P0 | 端到端透传测试 | ICD-07-R-001~003 |
| CP-F-302 | Relay服务应根据设备-用户绑定关系建立转发映射：飞行器TCP会话 ↔ App TCP会话，确保数据只转发给已绑定且已认证的App端 | P0 | 安全测试 | ICD-07-R-005 |
| CP-F-303 | Relay服务应实现旁路数据采集：从透传的MAVLink流中旁路抓取关键消息（HEARTBEAT、GLOBAL_POSITION_INT、SYS_STATUS、VFR_HUD、GPS_RAW_INT、BATTERY_STATUS、自定义消息50001/50003），写入时序数据库，不得影响主通道转发延迟 | P0 | 性能测试+数据验证 | ICD-07 §3.2 |
| CP-F-304 | 旁路采集写入频率：精简包字段1Hz（位置、高度、速度、电量、飞行模式、喷洒状态），完整包字段0.2Hz（电池详情、电机状态、作业进度、避障距离） | P0 | 数据采样验证 | ICD-07 §3.2 |
| CP-F-305 | 遥测数据应存储于时序数据库，保留周期≥90天；超过90天的数据自动归档或降采样保留 | P1 | 数据保留验证 | ICD-07-I-035 |
| CP-F-306 | 云平台应提供历史遥测查询API（GET /api/v1/devices/{id}/telemetry），支持时间范围筛选和下采样查询，返回JSON格式遥测数据 | P0 | 接口测试 | ICD-07 §6.2 |
| CP-F-307 | Relay服务应检测MAVLink流中的告警标志位（SYS_STATUS中的errors_count、HEARTBEAT中的system_status），检测到告警事件时触发推送通知至绑定用户的App | P1 | 告警模拟测试 | — |
| CP-F-308 | Relay服务应基于MAVLink HEARTBEAT消息保活：30秒无心跳判定飞行器断连，更新设备在线状态并通知相关App | P0 | 模拟断连测试 | ICD-07-R-004 |
| CP-F-309 | 云平台应提供设备最新遥测快照API（GET /api/v1/devices/{id}/status），返回设备在线状态和最近一次遥测数据，用于App首页设备列表展示 | P0 | 接口测试 | ICD-07 §6.2 |
3.4 远程指令服务（CP-F-4xx）
| 编号 | 需求描述 | 优先级 | 验证方式 | 来源 |
|---|---|---|---|---|
| CP-F-401 | Relay服务应支持指令转发：App通过同一TCP连接发送MAVLink COMMAND_LONG/COMMAND_INT消息，Relay透传至飞行器的TCP会话 | P0 | 指令端到端测试 | ICD-07 §4.2 |
| CP-F-402 | TCP会话层安全验证：会话建立时进行Token+HMAC验证，验证通过后会话内的MAVLink指令免重复认证；Token有效期≤2小时，过期后需重新认证 | P0 | 安全测试 | ICD-07-I-010~011 |
| CP-F-403 | Relay服务应实现指令权限分级拦截：L1查询类（仅Token）由REST API直接返回，不走MAVLink通道；L2安全操作类（Token+HMAC）通过Relay透传；L3控制类（V1.0不支持）在Relay层直接拦截并返回"不支持"错误 | P0 | 权限测试 | ICD-07 §4.1 |
| CP-F-404 | V1.0支持的远程指令范围：一键返航（MAV_CMD_NAV_RETURN_TO_LAUNCH）、紧急停机（MAV_CMD_COMPONENT_ARM_DISARM disarm）、暂停作业（MAV_CMD_DO_PAUSE_CONTINUE pause）、恢复作业（MAV_CMD_DO_PAUSE_CONTINUE continue）、设置返航高度（MAV_CMD_DO_SET_HOME） | P0 | 指令功能测试 | ICD-07 §4.3 |
| CP-F-405 | Relay服务应跟踪指令执行结果：监听飞行器返回的MAVLink COMMAND_ACK消息并透传至App；超过3秒未收到ACK时，Relay应在审计日志中标记"超时" | P0 | 超时模拟测试 | ICD-07-I-014 |
| CP-F-406 | Relay服务应记录所有转发的COMMAND消息至指令审计日志，包含：发送者用户ID、设备ID、指令类型、指令参数、时间戳、执行结果（ACK/超时/拒绝）；日志保留≥1年 | P0 | 日志审查 | ICD-07-I-012, ICD-07-I-054 |
| CP-F-407 | 紧急停机指令应在Relay转发后≤500ms内到达飞行器端（Relay内部处理延迟，不含网络传输延迟） | P0 | 延迟测试 | ICD-07-I-013 |
| CP-F-408 | 当直连数据链与4G远程通道同时存在时，云平台不做优先级仲裁——由飞行器端飞控判定直连指令优先级更高（ICD-07-I-015），Relay仅负责透传 | P0 | 文档审查+联调 | ICD-07-I-015 |
| CP-F-409 | 云平台应提供管理员接口，支持强制断开指定设备的TCP会话（POST /api/v1/relay/sessions/{id}/disconnect），用于紧急安全干预 | P1 | 接口测试 | ICD-07 §6.2 |
3.5 作业数据管理（CP-F-5xx）
| 编号 | 需求描述 | 优先级 | 验证方式 | 来源 |
|---|---|---|---|---|
| CP-F-501 | 云平台应存储每次作业的完整记录，包括：作业日期、设备ID、操作员、地块名称/边界、作业面积、用药量、飞行轨迹（GPS点序列）、作业时长、起止时间 | P0 | 数据完整性验证 | SYS-C-004, SYS-C-032 |
| CP-F-502 | 作业记录应由App在作业完成后通过REST API上传至云平台；Relay旁路采集的飞行轨迹数据作为补充和校验 | P0 | 上传流程测试 | — |
| CP-F-503 | 云平台应提供作业记录查询API（GET /api/v1/devices/{id}/missions），支持按时间范围、地块、设备筛选，返回作业记录列表 | P0 | 接口测试 | ICD-07 §6.2 |
| CP-F-504 | 云平台应提供作业统计报表功能：按日/周/月汇总作业面积、用药量、飞行时长、作业架次 | P1 | 报表验证 | — |
| CP-F-505 | 云平台应支持作业数据导出，格式为CSV和JSON，包含完整作业记录和飞行轨迹 | P1 | 导出文件验证 | SYS-C-032 |
| CP-F-506 | 云平台应支持地块数据云端同步：用户在App中标绘的地块信息（名称、边界坐标、面积）同步至云端，跨设备/跨App实例可用 | P1 | 同步测试 | — |
| CP-F-507 | 作业记录保留周期≥1年，支持事后追溯和监管检查需求 | P0 | 数据保留验证 | ICD-07-I-035, SYS-C-004 |
3.6 固件管理与OTA（CP-F-6xx）
| 编号 | 需求描述 | 优先级 | 验证方式 | 来源 |
|---|---|---|---|---|
| CP-F-601 | 云平台应分别管理飞控、电调、遥控器三类固件的版本信息，每个版本包含：版本号、发布日期、变更说明、适用机型、固件包SHA256校验和 | P1 | 版本管理验证 | ICD-07-I-034 |
| CP-F-602 | 云平台应支持固件包上传与存储：固件包存储于对象存储，上传时自动计算SHA256校验和并记录 | P1 | 上传流程测试 | — |
| CP-F-603 | 云平台应提供固件版本查询API（GET /api/v1/firmware/{model}/latest）和固件下载API（GET /api/v1/firmware/{model}/{version}），App通过这些接口检查更新和下载固件包 | P1 | 接口测试 | ICD-07 §6.2 |
| CP-F-604 | 云平台应支持OTA灰度发布策略：按百分比（如先推送10%设备）或按设备分组（如先推送测试组）逐步发布新固件 | P1 | 灰度策略验证 | ICD-07-I-034 |
| CP-F-605 | 云平台应支持固件版本回滚：当新版本出现严重问题时，管理员可将指定设备或设备组的推荐版本回退至上一稳定版本 | P1 | 回滚流程测试 | ICD-07-I-034 |
| CP-F-606 | 云平台应跟踪每台设备的OTA升级状态：未开始/下载中/安装中/成功/失败，App可查询升级进度 | P1 | 状态跟踪验证 | — |
| CP-F-607 | 固件包下载应支持断点续传，避免在网络不稳定时反复下载 | P2 | 断点续传测试 | — |
3.7 GEO围栏服务（CP-F-7xx）
| 编号 | 需求描述 | 优先级 | 验证方式 | 来源 |
|---|---|---|---|---|
| CP-F-701 | 云平台应维护禁飞区数据库，包含机场净空区、军事管控区等禁飞/限飞区域的地理边界数据；数据来源对接方案 [TBD-需讨论：民航局UOM系统 or 人工维护] | P0 | 数据完整性验证 | SYS-F-023, ICD-07-I-033 |
| CP-F-702 | 云平台应提供围栏数据增量同步API（GET /api/v1/geo/zones），支持按区域查询（矩形边界/中心点+半径），App定期拉取更新并缓存至本地 | P0 | 接口测试+增量验证 | ICD-07 §6.2, ICD-07-I-033 |
| CP-F-703 | 云平台应支持自定义围栏：用户可在App中创建自定义作业区域和禁飞区域，同步至云端存储，跨设备可用 | P1 | 自定义围栏流程测试 | — |
| CP-F-704 | GEO围栏数据更新时，云平台应记录更新版本号和时间戳，App可通过版本号判断本地缓存是否需要刷新 | P1 | 版本比对验证 | — |
3.8 地图服务（CP-F-8xx）
| 编号 | 需求描述 | 优先级 | 验证方式 | 来源 |
|---|---|---|---|---|
| CP-F-801 | 云平台应托管离线地图切片（卫星图/地形图），存储于对象存储，供App在无网络环境下使用 | P1 | 地图加载测试 | — |
| CP-F-802 | 云平台应提供地图下载API（GET /api/v1/maps相关接口），支持按区域（经纬度范围）和缩放级别下载地图切片包 | P1 | 接口测试+下载验证 | ICD-07 §6.2 |
| CP-F-803 | 云平台应支持用户上传航测高清地图：App完成航测作业后，将重建的高清地图上传至云端存储（POST /api/v1/maps/upload），供后续作业规划使用 | P2 | 上传下载测试 | ICD-07 §6.2 |
| CP-F-804 | 云平台应提供用户高清地图列表查询（GET /api/v1/maps/list），返回用户已上传的地图元数据（名称、区域、上传时间、文件大小） | P2 | 接口测试 | ICD-07 §6.2 |
3.9 机队管理（CP-F-9xx）— V1.5/V2规划，V1.0不实现
注意：本节需求为V1.5/V2版本规划，V1.0种子用户版不实现。列出以便架构预留。
| 编号 | 需求描述 | 优先级 | 目标版本 | 来源 |
|---|---|---|---|---|
| CP-F-901 | 云平台应提供多机实时状态看板：在Web管理界面或App中展示所有在线设备的实时位置、状态、电量等信息 | P2 | V1.5 | — |
| CP-F-902 | 云平台应支持机队作业调度：多台飞行器协同作业时，云端分配各机作业区域并下发航线 | P2 | V2.0 | — |
| CP-F-903 | 云平台应提供机队运维统计：按设备汇总飞行时长、作业面积、故障次数、维护提醒（基于飞行小时数） | P2 | V1.5 | — |
| CP-F-904 | 多机看板实时更新应采用WebSocket推送（V1.5架构升级），避免轮询带来的延迟和服务器压力 | P2 | V1.5 | §2.3.1升级路径 |
3.10 部署架构（CP-F-0xx）
| 编号 | 需求描述 | 优先级 | 验证方式 | 来源 |
|---|---|---|---|---|
| CP-F-001 | 云平台核心组件包括：MAVLink TCP Relay服务、REST API后端服务、时序数据库、关系数据库、对象存储、监控告警系统 | P0 | 架构审查 | ICD-07 §6.1 |
| CP-F-002 | MAVLink TCP Relay为云平台核心组件，应轻量高性能，推荐使用Go或Rust实现，单实例支持≥1,000并发TCP连接 | P0 | 压力测试 | — |
| CP-F-003 | 数据库选型：时序数据库推荐TDengine或InfluxDB（遥测数据）；关系数据库推荐PostgreSQL（用户/设备/作业数据） [TBD-需讨论] | P0 | 技术评审 | — |
| CP-F-004 | 对象存储用于存储固件包、地图切片文件、航测图片；推荐阿里云OSS或MinIO [TBD-需讨论] | P1 | 技术评审 | — |
| CP-F-005 | 监控与告警：部署Prometheus + Grafana（或云厂商监控服务），监控Relay连接数、API响应时间、数据库性能、磁盘使用率等关键指标 | P1 | 监控面板验证 | — |
部署方案选型 [TBD-需讨论]：
| 方案 | 描述 | 优势 | 劣势 | 适用场景 |
|---|---|---|---|---|
| 方案A：云服务器自建 | 阿里云/腾讯云ECS部署全部组件（Relay+后端+TSDB+PostgreSQL+MinIO） | 成本可控、灵活配置 | 运维工作量大 | 种子用户阶段（V1.0） |
| 方案B：混合方案（推荐） | ECS部署Relay+后端，阿里云OSS存固件/地图，云TSDB存遥测，RDS存关系数据 | 运维托管、高可用 | 月度成本稍高 | V1.0~V1.5过渡 |
| 方案C：全托管方案 | Kubernetes集群 + 全托管数据库 + CDN + 消息队列 | 弹性扩展、高可用 | 成本高、架构复杂 | V2.0万台级别 |
4. 性能需求
| 编号 | 性能指标 | 我方目标值（V1.0） | 未来扩展目标 | 优先级 | 验证方式 |
|---|---|---|---|---|---|
| CP-P-001 | 同时在线设备数 | ≥1,000台 | ≥10,000台（V2.0） | P0 | 压力测试 |
| CP-P-002 | MAVLink TCP Relay透传延迟 | ≤50ms（Relay内部处理延迟，不含网络传输） | — | P0 | 延迟测试 |
| CP-P-003 | 遥测旁路采集延迟 | 旁路采集写入TSDB≤500ms（从Relay接收到存储完成），不影响主通道转发 | — | P0 | 性能测试 |
| CP-P-004 | REST API响应时间（P95） | ≤300ms | ≤200ms（V2.0） | P0 | 接口性能测试 |
| CP-P-005 | 系统可用性 | ≥99.5% | ≥99.9%（V2.0） | P0 | 运行监控统计 |
| CP-P-006 | 遥测数据存储容量 | 支持100台设备×365天全量遥测数据（估算：100台 × 86,400条/天 × 365天 ≈ 31.5亿条） | 10,000台×365天 | P0 | 容量规划验证 |
| CP-P-007 | 并发API请求 | ≥500 QPS | ≥5,000 QPS（V2.0） | P1 | 压力测试 |
| CP-P-008 | TCP Relay单设备消息吞吐量 | ≥100 msg/s | — | P1 | 吞吐量测试 |
| CP-P-009 | 固件包下载速度 | ≥1 MB/s（App端4G网络条件下） | — | P1 | 下载速度测试 |
| CP-P-010 | 历史遥测查询响应时间 | 单设备24小时数据查询≤2秒 | — | P1 | 查询性能测试 |
5. 安全需求
| 编号 | 安全需求描述 | 触发条件 | 系统响应 | 优先级 | 验证方式 |
|---|---|---|---|---|---|
| CP-S-001 | 所有通信链路应使用TLS 1.2+加密传输：飞行器↔Relay使用mTLS（设备证书双向认证），App↔Relay使用TLS + Token认证，App↔REST API使用HTTPS | 所有通信场景 | 拒绝明文连接 | P0 | 安全扫描 |
| CP-S-002 | 设备证书管理：云平台应维护产品CA，支持设备证书的签发（出厂预置）、吊销（设备报废/丢失）、续期（证书到期前自动更新）流程 | 设备全生命周期 | 吊销的证书不可建立连接 | P0 | 证书生命周期测试 |
| CP-S-003 | 敏感数据加密存储：用户密码使用bcrypt/argon2哈希存储；设备证书私钥不存储于云端；用户手机号等PII字段使用AES-256加密存储 | 数据写入时 | 加密后存储 | P0 | 数据库审查 |
| CP-S-004 | 访问控制：所有API接口应实施RBAC权限检查，未授权请求返回403；管理员接口（relay管理、用户管理等）仅限Admin角色访问 | 每次API请求 | 拒绝越权访问 | P0 | 权限矩阵测试 |
| CP-S-005 | 安全审计日志：记录所有登录/登出、设备绑定/解绑、远程指令下发、权限变更、管理员操作等安全相关事件，包含操作者、时间、IP、操作内容；日志保留≥1年 | 安全相关操作 | 写入审计日志 | P0 | 日志审查 |
| CP-S-006 | DDoS防护：云平台应部署DDoS防护措施（云厂商DDoS高防/WAF），TCP Relay端口应有连接速率限制（单IP≤10连接/秒） | 异常流量 | 拦截恶意流量 | P1 | 安全演练 |
| CP-S-007 | 所有远程指令必须经过时间戳验证（±30秒窗口）和nonce去重（5分钟窗口），防止重放攻击 | 远程指令下发 | 拒绝过期/重复指令 | P0 | 重放攻击测试 |
| CP-S-008 | 连续3次设备认证失败后，Relay应锁定该设备远程指令通道30分钟，并通过遥测数据上报安全事件 | 认证连续失败 | 锁定+告警 | P0 | 安全测试 |
| CP-S-009 | 云平台应每季度进行一次安全扫描，每年进行一次渗透测试，发现的高危/严重漏洞应在72小时内修复 | 定期执行 | 漏洞修复 | P1 | 安全报告审查 |
6. 合规需求
| 编号 | 法规/标准 | 需求描述 | 优先级 | 认证周期预估 |
|---|---|---|---|---|
| CP-C-001 | 《数据安全法》 | 云平台服务器必须部署于中国境内机房，飞行数据和用户数据不得出境存储或传输 | P0 | — |
| CP-C-002 | 《个人信息保护法》(PIPL) | 用户注册时应明示收集信息范围并获取同意；提供用户数据查询、导出、删除功能；个人信息处理应遵循最小必要原则 | P0 | — |
| CP-C-003 | 民航局监管要求 | 飞行数据应完整留存，支持民航局可能的监管数据报送要求 [TBD-需讨论：具体报送接口和格式待民航局明确] | P1 | TBD |
| CP-C-004 | 日志审计合规 | 安全审计日志应满足《网络安全法》关于网络日志留存不少于六个月的要求；云平台安全日志保留≥1年 | P0 | — |
| CP-C-005 | 等级保护 | 云平台应通过等保二级评测（100台设备规模）；未来规模扩大至万台级别时应升级至等保三级 [TBD-需讨论时间节点] | P1 | 等保二级：2-3个月 |
7. 接口需求
| 接口编号 | 对端子系统 | 接口类型 | 接口描述 | 详细定义文档 |
|---|---|---|---|---|
| CP-I-001 | 飞控系统(FC) — 经4G模块 | MAVLink TCP (mTLS) | 飞行器通过4G建立TCP连接至Relay，发送/接收MAVLink v2消息流 | ICD-07 §3 |
| CP-I-002 | 操控App(APP) — 实时通道 | MAVLink TCP (Token) | App通过TCP连接至Relay，接收遥测数据流/发送远程指令 | ICD-07 §3~4 |
| CP-I-003 | 操控App(APP) — 业务通道 | REST API (HTTPS) | App通过HTTPS调用云平台REST API，进行用户认证、设备管理、作业数据、OTA、GEO围栏、地图等业务操作 | ICD-07 §6.2 |
| CP-I-004 | 短信网关 | HTTPS API | 用户注册/登录时发送短信验证码；告警事件推送短信通知 | [TBD-供应商选型] |
| CP-I-005 | 推送服务 | HTTPS API | 告警事件、OTA通知等推送至App端（APNs/华为Push/小米Push） | [TBD-供应商选型] |
REST API接口汇总
以下API路径与ICD-07 §6.2保持完全一致：
| API路径 | 方法 | 说明 | 认证方式 | 对应PRD需求 |
|---|---|---|---|---|
/api/v1/auth/login | POST | 用户登录，获取JWT Token | 账号密码 | CP-F-202 |
/api/v1/auth/refresh | POST | 刷新Token | Refresh Token | CP-F-203 |
/api/v1/devices | GET | 获取用户绑定的设备列表 | JWT | CP-F-107 |
/api/v1/devices/{id}/bindcode | POST | 设备绑定（扫码/手动输入） | JWT | CP-F-101 |
/api/v1/devices/{id}/status | GET | 获取设备在线状态和最新遥测 | JWT | CP-F-309 |
/api/v1/devices/{id}/telemetry | GET | 查询历史遥测数据（时间范围查询） | JWT | CP-F-306 |
/api/v1/devices/{id}/missions | GET | 查询作业记录列表 | JWT | CP-F-503 |
/api/v1/devices/{id}/cmd | POST | 下发L1查询类远程指令 | JWT | CP-F-403 |
/api/v1/relay/status | GET | Relay服务状态（在线设备数、连接数） | JWT(管理员) | CP-F-001 |
/api/v1/relay/sessions | GET | 查看当前活跃TCP会话列表 | JWT(管理员) | CP-F-409 |
/api/v1/relay/sessions/{id}/disconnect | POST | 强制断开指定设备TCP会话 | JWT(管理员) | CP-F-409 |
/api/v1/geo/zones | GET | 查询GEO围栏数据（按区域查询） | JWT | CP-F-702 |
/api/v1/firmware/{model}/latest | GET | 查询最新固件版本 | JWT | CP-F-603 |
/api/v1/firmware/{model}/{version} | GET | 下载固件包 | JWT | CP-F-603 |
/api/v1/maps/upload | POST | 上传航测高清地图 | JWT | CP-F-803 |
/api/v1/maps/list | GET | 获取用户高清地图列表 | JWT | CP-F-804 |
8. 约束与假设
8.1 设计约束
技术约束：
- MAVLink TCP Relay必须保持轻量，不解析MAVLink消息内容（仅旁路采集），确保透传延迟≤50ms
- V1.0版本REST API与Relay服务可部署在同一台服务器，V1.5+需分离部署
- 时序数据库需支持高频写入（100台设备 × 每秒1~5条消息 = 100~500 writes/s）
团队约束：
- 当前无专职后端团队，云平台V1.0由App团队兼任开发，架构须尽量简单
- 优先选择成熟开源组件，减少自研工作量
成本约束：
- V1.0（100台设备）云服务器月度成本应控制在 ≤5,000元/月 [TBD-需讨论]
- 优先考虑按量付费，避免大额预付
8.2 假设条件
- 飞行器4G模块由硬件团队完成选型和集成，云平台仅需对接标准TCP连接
- App团队已具备MAVLink协议栈开发能力（直连链路已验证）
- 种子用户阶段（100台）不需要高可用部署（单机/双机即可），V1.5+再考虑集群化
- 物联网SIM卡流量资费方案由商务团队谈定，云平台按既定方案执行
- 离线地图数据来源由产品团队确定（购买卫星图服务商授权 or 开源地图数据）
9. 验收标准
9.1 种子用户版（V1.0，10月交付）必须通过项
| 测试项 | 通过标准 | 对应需求编号 |
|---|---|---|
| 设备注册与绑定 | 扫码/手动输入激活码完成绑定，绑定后设备出现在用户设备列表 | CP-F-101, CP-F-107 |
| 设备mTLS认证 | 飞行器使用X.509证书成功建立TCP连接，无证书设备被拒绝 | CP-F-102, CP-S-001 |
| 用户登录认证 | 账号+密码+短信验证码登录成功，获取JWT Token | CP-F-202, CP-F-203 |
| MAVLink TCP透传 | 飞行器MAVLink数据通过Relay正确透传至App，端到端延迟≤3秒（含网络） | CP-F-301, CP-P-002 |
| 遥测旁路采集 | Relay旁路采集的遥测数据正确写入TSDB，采集不影响主通道延迟 | CP-F-303, CP-F-304 |
| 远程指令转发 | App发送返航/停机/暂停/恢复指令，飞行器正确接收并执行 | CP-F-401, CP-F-404 |
| 指令审计日志 | 所有远程指令被完整记录（发送者、指令、时间、结果） | CP-F-406 |
| 历史遥测查询 | 通过API按时间范围查询设备历史遥测数据，数据完整且响应≤2秒 | CP-F-306, CP-P-010 |
| 作业记录存储 | App上传的作业记录正确存储于云端，可通过API查询 | CP-F-501, CP-F-503 |
| GEO围栏同步 | App通过API获取GEO围栏数据，数据完整且增量更新正确 | CP-F-702 |
| 数据加密传输 | 所有通信链路TLS 1.2+，抓包验证无明文传输 | CP-S-001 |
| 服务器境内部署 | 验证所有服务器和数据存储位于中国境内 | CP-C-001 |
9.2 应当通过项
| 测试项 | 通过标准 | 对应需求编号 |
|---|---|---|
| 设备在线状态准确性 | 设备断连后5秒内状态更新为离线，API查询结果正确 | CP-F-103 |
| RBAC权限控制 | 观察者角色无法下发指令，操作员无法访问管理员接口 | CP-F-204, CP-S-004 |
| OTA固件查询 | App通过API查询到最新固件版本信息 | CP-F-603 |
| 作业统计报表 | 按日/周/月查询作业统计数据，数据准确 | CP-F-504 |
| 系统可用性 | 连续7天运行，可用性≥99.5% | CP-P-005 |
| 并发连接测试 | 模拟100台设备同时在线，Relay和API响应正常 | CP-P-001 |
9.3 可延后项
| 测试项 | 计划版本 | 对应需求编号 |
|---|---|---|
| OTA灰度发布 | V1.0+ | CP-F-604 |
| 固件版本回滚 | V1.0+ | CP-F-605 |
| 离线地图下载 | V1.0+ | CP-F-801, CP-F-802 |
| 航测地图上传 | V1.5 | CP-F-803 |
| 机队管理看板 | V1.5 | CP-F-901 |
| 多机协同调度 | V2.0 | CP-F-902 |
| 等保二级评测 | V1.0后 | CP-C-005 |
10. 待决事项 (TBD)
| 编号 | 事项描述 | 责任人 | 期望决定日期 | 影响范围 |
|---|---|---|---|---|
| TBD-CP-001 | 云平台部署方案选型：方案A自建 vs 方案B混合 vs 方案C全托管（推荐V1.0采用方案B） | 后端团队+产品经理 | 2025-05 | 全部云平台开发 |
| TBD-CP-002 | 时序数据库选型：TDengine vs InfluxDB | 后端团队 | 2025-05 | 遥测数据存储 |
| TBD-CP-003 | 对象存储方案：阿里云OSS vs 腾讯云COS vs MinIO自建 | 后端团队 | 2025-05 | 固件/地图存储 |
| TBD-CP-004 | GEO禁飞区数据来源：对接民航局UOM系统 vs 人工维护 vs 第三方数据服务 | 产品经理 | 2025-06 | CP-F-701 |
| TBD-CP-005 | 离线地图数据来源和授权方案 | 产品经理 | 2025-06 | CP-F-801 |
| TBD-CP-006 | 短信验证码服务商选型（阿里云短信/腾讯云短信等） | 后端团队 | 2025-05 | CP-F-201, CP-F-202 |
| TBD-CP-007 | MAVLink TCP Relay实现方案：Go自研 vs Rust自研 vs 基于开源组件二次开发 | 后端团队 | 2025-05 | CP-F-002, CP-F-301 |
| TBD-CP-008 | V1.0云服务器预算上限确认 | 产品经理+财务 | 2025-05 | §8.1成本约束 |
| TBD-CP-009 | 民航局飞行数据报送的具体接口和格式要求 | 产品经理+法务 | 2025-06 | CP-C-003 |
| TBD-CP-010 | 等保二级评测启动时间节点 | 安全团队+产品经理 | 2025-07 | CP-C-005 |
附录
附录A：需求追溯矩阵
| 子系统需求编号 | 系统级需求来源 | ICD来源 | 验证方式 | 验证状态 |
|---|---|---|---|---|
| CP-F-101~108 | SYS-C-002 | ICD-07-I-040~042, ICD-07-I-052 | 接口测试+端到端流程 | 未验证 |
| CP-F-201~208 | — | ICD-07-I-045~047 | 接口测试+安全测试 | 未验证 |
| CP-F-301~309 | SYS-P-050 | ICD-07-R-001~005, ICD-07-I-001~005 | 端到端透传+性能测试 | 未验证 |
| CP-F-401~409 | SYS-S-001 | ICD-07-I-010~016, ICD-07 §4 | 指令端到端+安全测试 | 未验证 |
| CP-F-501~507 | SYS-C-004, SYS-C-032 | ICD-07-I-035 | 数据完整性验证 | 未验证 |
| CP-F-601~607 | — | ICD-07-I-034 | 版本管理+OTA流程 | 未验证 |
| CP-F-701~704 | SYS-F-023 | ICD-07-I-033 | 围栏数据验证 | 未验证 |
| CP-F-801~804 | — | ICD-07 §6.2 | 地图加载+下载测试 | 未验证 |
| CP-P-001~010 | SYS-P-050 | ICD-07-P-001~006 | 压力测试+性能测试 | 未验证 |
| CP-S-001~009 | SYS-S-001 | ICD-07-I-040~054 | 安全测试+渗透测试 | 未验证 |
| CP-C-001~005 | SYS-C-002, SYS-C-004 | ICD-07-I-030 | 合规审查 | 未验证 |
文档结束