1. 部署上云 API 2 应用运行与设备管控底座
上云 API 2 说明文档(KOC3)
  • 快速开始
  • 申请许可证
  • 联系我们
  • 软件下载
  • 使用上云 API 2 设备模拟器
  • 鉴权接入指南
  • 部署上云 API 2 应用运行与设备管控底座
    • 部署指南
    • 部署前准备
    • 开始部署
    • 能力扩展
  • 设备上云
    • 设备上云
    • 设备固件版本
  • 集成前端独立组件
    • 集成指南
    • 驾驶舱和设备小窗
    • 驾驶舱模块化配置
    • 设备管理组件
    • 航线组件
    • 直播大屏
    • 飞行记录
    • 集成参考
    • PaasJS 新增特性
  • SDK 文档
    • 基本介绍
      • SDK 简介
      • 功能特性
    • 快速入门
      • 准备工作
      • 使用流程
    • 接口调用
      • 接口调用时序图
    • SDK API 文档
      • 使用 API 文档查阅接口详情
    • SDK版本迁移指南
      • 迁移概述
      • 新增方法详情
      • API 变更详情
      • 迁移操作步骤
    • 功能集合
      • SDK初始化
      • SDK配置
      • DRC链路
      • 飞机状态监听
      • 飞向目标点
      • 飞行参数设置
      • 飞行记录导出
      • POI 环绕飞行
      • 一键起飞
      • 航线任务管理
      • 航线任务控制
      • 航线资产管理
      • 机场状态监听
      • 控制权管理
      • 机场控制
      • 飞行控制
      • AI Box 管理
      • AI 智能告警
      • 机载 AI 控制
      • 机载 AI 算法管理
      • PSDK 控制
      • PSDK 资源管理
      • RTK 标定
      • 安全服务
      • 固件管理
      • 媒体服务
      • 日志管理
      • 三维重建
      • 设备管理
      • 设备保修维护
      • 设备健康管理
      • 设备远程调试
      • 设备在线状态
      • 相机控制
      • 直播录制
      • 直播设备管理
      • 直播视频流
      • 直播同步
      • 中继器控制
      • 自定义 SEI
      • WHEP 自定义拉流
      • 网络测速
      • 地图元素管理
      • 频闪灯配置
  • 使用上云 API 2 AI Plugin
    • 上云 API 2 AI Plugin 使用指南
  • 使用上云 API 2 二次开发 Demo
    • 上云 API 2 二次开发 Demo 部署指南
    • 上云 API 2 二次开发 Demo - 无人机管理平台使用说明
  • 排障指南
    • 前端独立组件排障指南
    • SDK排障指南
  1. 部署上云 API 2 应用运行与设备管控底座

能力扩展

离线地图#

离线地图瓦片数据支持卫星地图数据和路网地图数据的配置。私有版安装包随包附带了一份深圳区域的卫星栅格地图,可以不做任何配置直接使用安装包自带资源。若需要获取其他区域的离线地图数据,可以选择以下任一格式的数据进行导入配置:XYZ 格式地图瓦片、MBTiles 格式地图瓦片或者用户自定义地图服务。

坐标系说明#

用户若选择基于 GeoTiff 等原始数据转换 XYZ、MBTiles 或发布自定义地图服务,原始数据需要为网络墨卡托(WebMercator)地图投影坐标系(编码 EPSG:3857),或者 WGS84 地理坐标系(编码为 EPSG:4326)自行通过 GIS 软件进行投影转换。
若用户能自行获取 XYZ、MBTiles 离线瓦片数据,则需要注意瓦片的行列顺序。

XYZ 格式地图瓦片#

XYZ 格式支持的瓦片文件格式为 JPG(或 JPEG)、PNG。推荐使用带透明度的 PNG 瓦片。
数据获取:
对于 XYZ 格式的地图瓦片,推荐下述两种方式进行数据获取:
方式一: 通过地图下载工具进行地图文件下载,例如 MobileAtlasCreator、水经微图、太乐地图。
方式二: 将影像 TIF 数据(需含有坐标系)转为 XYZ 格式瓦片集合。
说明: 部分在线地图数据源可能存在坐标偏移情况,请选择合适的数据源以避免坐标偏移问题。
数据发布 — 可视化操作:
进入 AIO 管理后台进行配置
image.png
数据发布 — 命令行操作:
1.
/var/lib/flighthub2/asset-map/png-tiles/ 下放置卫星底图瓦片数据,/var/lib/flighthub2/asset-map/street-tiles/ 放置路网瓦片数据,若这两个文件夹下存在原有的 PNG/JPG 瓦片文件集合,需要删除该文件集合。其中 ${INSTALLATION_PATH} 为部署安装包 env 文件中的环境变量。
2.
将新的 XYZ 卫星底图或者路网瓦片文件放入。
3.
修改地图配置文件
地图配置文件路径:/var/lib/flighthub2/asset-map/map_config.yaml,修改配置文件可以实现地图数据源的新增/删除/修改。
一个数据项中的参数介绍:
参数名称参数用途参数说明
name界面上显示的名称使用常规字符串,不含特殊符号,不为空
type地图上图标类型default - 即随安装包默认携带的卫星地图;custom - 表示自定义的离线数据。此参数仅影响右下角的地图底图图标样式
link卫星数据 URL占位符 {z}、{x}、{y} 与实际文件夹、文件名的层级一致,后缀名与数据文件的后缀名一致。举例:http://myhost.org/services/my-xyz-data1/tiles/{z}/{x}/{y}.png
street_link配套的街道数据 URL可选项,若数据项无配套路网数据,可省略此选项。配置规则与 link(卫星数据 URL)一致。
min_z数据可用最小层级可选,默认值为 0,请提供数据源的真实最小层级,只影响卫星数据。地图缩小到对应级别时,所有小于这个层级的数据都会以这个层级的数据为基准缩放。如果没有配置,小于真实最小层级时会显示为空白。
max_z数据可用最大层级可选,无默认值,请提供数据源的真实最大层级,只影响卫星数据。地图放大到对应级别时,所有大于这个层级的数据都会以这个层级的数据为基准缩放。如果没有配置,大于真实最大层级时会显示为空白。
示例如下:
说明:
XYZ 卫星底图地图瓦片链接的拼接规则:${SERVICE_DOMAIN}:${MAP_CUSTOM_TCP_PORT}/ + 地图瓦片文件在 /var/lib/flighthub2/asset-map/png-tiles/ 下的剩余路径。
XYZ 路网瓦片链接的拼接规则:${SERVICE_DOMAIN}:${MAP_CUSTOM_TCP_PORT}/ + 地图瓦片文件在 /var/lib/flighthub2/asset-map/street-tiles/ 下的剩余路径。
瓦片数据格式需要与瓦片文件路径后缀保持一致,如 JPG 格式瓦片的后缀为 .jpg
4.
执行离线地图发布脚本
在 ${部署安装包解压目录}/tool/map/ 路径下执行命令:

MBTiles 格式地图瓦片#

数据获取:
点击跳转链接 并下载红框内的地图文件(仅支持瓦片地图)。
image.png
说明:
可以使用 QGIS 直接将 WGS84 坐标系(EPSG 编号 4326 或 EPSG 编号 3857)的栅格(tif)数据制作成 mbtiles 数据包,也可以用其它工具(命令行工具或 GIS 客户端软件)制作。
部分在线地图数据源可能存坐标偏移情况,请选择合适的数据源以避免坐标偏移问题。
数据发布 — 可视化操作:
进入 AIO 管理后台进行配置
image.png
数据发布 — 命令行操作:
1.
/var/lib/flighthub2/asset-map/mbtiles/ 下可以放置卫星底图数据或路网数据的 mbtiles 文件,支持同时存放多个不同的 mbtiles 数据。
2.
将新的 .mbtiles 地图文件放入。
3.
在 ${部署安装包解压目录}/tool/map/ 路径下执行离线地图发布脚本:
说明: 卫星底图地图或路网(mbtiles 数据格式)的拼接规则:
${SERVICE_DOMAIN}:${MAP_SERVER_TCP_PORT}/services/{mbtiles_file_name}/tiles/{z}/{x}/{y}.{瓦片格式}
假设 mbtiles 文件名称为:satelite-2017-11-01-china_shenzhen.mbtiles,mbtiles 中瓦片的格式为 jpg,则 mbtiles 访问链接为:
${SERVICE_DOMAIN}:${MAP_SERVER_TCP_PORT}/services/satelite-2017-11-01-china_shenzhen/tiles/{z}/{x}/{y}.jpg

用户自定义地图服务#

数据获取:
请用户准备自己的图瓦片服务作为离线地图数据源,部分在线地图数据源可能存在坐标偏移情况,请选择合适的数据源以避免坐标偏移问题。
数据发布 — 可视化操作:
进入 AIO 管理后台进行配置
image.png
数据发布 — 命令行操作:
1.
修改地图配置文件
地图配置文件路径:/var/lib/flighthub2/asset-map/map_config.yaml,修改配置文件可以实现地图数据源的新增/删除/修改。
一个数据项的参数介绍如下:
参数名称参数用途参数说明
name界面上显示的名称使用常规字符串,不含特殊符号,不为空
type地图上图标类型default - 即随安装包默认携带的卫星地图;custom - 表示自定义的离线数据。此参数仅影响右下角的地图底图图标样式
link卫星数据 URLURL 中的占位符 {z}、{x}、{y} 与发布的数据服务层级关系一致,后缀名与数据服务瓦片格式的后缀名一致。举例:http://myhost.org/services/test-data/{z}/{x}/{y}.png
street_link配套的街道数据 URL可选项,若数据项无配套路网数据,可省略此选项。配置规则与 link(卫星数据 URL)一致。
min_z数据可用最小层级可选,默认值为 0,请提供数据源的真实最小层级,只影响卫星数据。地图缩小到对应级别时,所有小于这个层级的数据都会以这个层级的数据为基准缩放。如果没有配置,小于真实最小层级时会显示为空白。
max_z数据可用最大层级可选,无默认值,请提供数据源的真实最大层级,只影响卫星数据。地图放大到对应级别时,所有大于这个层级的数据都会以这个层级的数据为基准缩放。如果没有配置,大于真实最大层级时会显示为空白。
示例如下:
2.
在 ${部署安装包解压目录}/tool/map/ 路径下执行离线地图发布脚本

AR 街道地图部署#

数据获取:
点击跳转链接 并下载红框内的地图文件:
image.png
数据发布 — 命令行操作:
1.
数据存放路径:/var/lib/flighthub2/asset-map/mbtiles/
2.
修改地图配置文件路径:/var/lib/flighthub2/asset-map/map_config.yaml,ar_resource 这一块表示本次新增的 AR 地图资源
示例如下:
说明: link 的拼接规则:假设 mbtiles 文件名称为 osm-2020-02-10-v3.11_china_shenzhen.mbtiles
${SERVICE_DOMAIN}:${MAP_SERVER_TCP_PORT}/services/osm-2020-02-10-v3.11_china_shenzhen/tiles/{z}/{x}/{y}.pbf
注意:从 maptiler 下载的地图数据都是 mbtiles 格式,且瓦片格式都是:pbf

账号系统切换#

上云 API 2 平台默认本地帐号系统,支持第三方账号系统接入。两种账号体系的登录账号和组织管理方式有所差异,具体说明可查看文档压缩包中的"组织管理"文档。
账号系统切换指引如下:
1.
进入 AIO 管理后台进行配置
image.png
2.
选择所需系统并配置

域名/IP 切换#

通过 AIO 管理后台界面可实现域名与 IP 访问模式的切换。如下:
image.png

HTTP/HTTPS 切换#

通过 AIO 管理后台界面可实现 HTTP/HTTPS 协议切换,如下:
image.png

切换为 HTTP#

关闭 HTTPS 即可。
注意: 由于浏览器安全策略限制,在 http 模式下无法正常录音,因此如果您需要使用喊话器功能,请配置开启 https 模式。
image.png

切换为 HTTPS#

image.png

启用系统自签证书#

image.png
1.
客户端浏览器需要信任自签发根证书,请按照所属环境(Linux、macOS、Windows)选择性阅读。
2.
如何信任自签证书:
Linux 环境:
在服务器和终端电脑设备的谷歌浏览器中(设置 > 隐私和安全 > 安全 > 管理证书)信任自签发 pem 证书,请按以下截图流程将自签发的根证书 ca.pem 导入系统。
macOS 环境:
1.
双击自签发的根证书 ca.pem,在弹窗中选择 "系统" 后点击 "添加"。
2.
在 "钥匙串访问" 中找到证书。
3.
双击证书,在信任标签下的 "使用此证书时" 选项修改为 "始终信任",关闭窗口。
Windows 环境:
1.
在谷歌浏览器(设置 > 隐私和安全 > 安全 > 管理证书)中找到 "管理证书"。
image.png
2.
选择 "受信任的根证书颁发机构",点击导入。
image.png
3.
找到自签发的根证书 ca.pem 的位置,导入证书。
image.png
4.
显示导入成功后,重启谷歌浏览器。
image.png

启用自定义证书#

image.png
将自定义证书的 CRT、KEY 信息填入并保存。

修改上云 API 2 服务默认端口#

进入 AIO 管理后台即可修改,如下:
image.png

私有化自适应网络功能#

自适应网络功能用于多网卡 / 跨子网场景下实现设备和上云 API 2 服务跨网络、跨地址稳定互通。

适用场景说明#

说明: 当前仅支持私有化上云的设备(不支持第三方上云)
1.
已完成上云 API 2 部署,且上云 API 2 页面能在当前网络正常访问。
2.
服务器(FH2 Server)存在多个对外访问方式,包括(举例部分场景):
多网卡 或 多种外部访问方式(IP 或域名)。
不同子网设备需要接入同一平台(跨子网访问)。
3.
机场/手飞设备位于与服务器不同的子网,需要访问上云 API 2 服务,例如:
办公网络 (10.66.x.x) 内的服务器。
新增的设备子网 (11.11.x.x) 要与现有业务互通。

部署形态#

部署形态示意:
image.png

配置步骤#

打开网络自适应开关
进入 AIO 管理后台:
开关对应【部署形态图】中的 MULTIPLE_ENABLE
image.png
补充说明
受设备及功能迭代影响,当前自适应网络功能仅支持 Dock 3 及手飞设备(私有化上云)。如需适配其他机型或上云方式,请配置兼容设备名单:
image.png
示例:
单设备:Dock 2(SN: 8UNX4)上云 IP 为 234.198.222.1,配置如下:"8UNX4:234.198.222.1"
多设备:在上述基础上增加设备(SN: 7IAUY,域名: www.baidu.com),配置如下:`"8UNX4:234.198.222.1:7IAUY:www.baidu.com"`
注意事项: 所有符号均须为英文半角,严禁使用中文冒号。

配置 SMTP 服务#

面向有启用「邮件通知 / 告警订阅」需求的管理员。
本文档将说明如何填写配置、如何选择/申请 SMTP 中继(以 Mailgun 为例),以及常见问题排查。

前期准备#

可用的 SMTP 中继服务(以下两种用户类型,任选其一):
1.
已拥有公司内 SMTP 中继(如自建 Postfix/Exchange,或企业邮箱提供的 SMTP);
2.
暂时没有 SMTP 中继,可先申请第三方服务(本文以 Mailgun 为例)。
能访问上云 API 2 部署主机,并可编辑其 env 配置文件 的权限。
网络层允许访问 SMTP 服务(常见端口:587/STARTTLS 或 465/TLS)。

必须填写的配置项(env)#

把下面 4 个键值写入上云 API 2 的 env 文件,保存并应用生效:
DEVOPS_SMTP_HOST:SMTP 中继服务地址(如 smtp.company.com、smtp.mailgun.org)。
DEVOPS_SMTP_USER:用于 SMTP 认证的用户名(常见形态:邮箱地址,如 noreply@your-domain.com 或 postmaster@your-domain.com)。
DEVOPS_SMTP_PASS:SMTP 认证密码或 API/应用专用密码。
DEVOPS_DEFAULT_LANG:期望接收的告警邮件语言,cn 或 en。当告警模板语言与该值不一致时,告警邮件会被跳过(用于控制只收某一种语言的告警邮件)。
上述 4 项配置需要用户在上云 API 2 的 env 中进行配置和保存,保存后在上云 API 2 的根路径下执行命令应用配置更新:
提示: 请确保发件人地址(From)与域名一致(例如 noreply@your-domain.com 与你控制的 your-domain.com),并完成 SPF/DKIM 配置,以提高投递成功率。

两类用户的配置路径#

已拥有公司内 SMTP 中继#

1.
向邮件/IT 管理员获取:
SMTP 主机地址(如 smtp.company.com)
认证账号、密码(有时需开通「应用专用密码」)
推荐端口与加密方式(常见:587 + STARTTLS 或 465 + TLS)
2.
在上云 API 2 的 env 中填入:
DEVOPS_SMTP_HOST = 提供的 SMTP 主机
DEVOPS_SMTP_USER = 你的发件账号(建议使用功能型账号,如 noreply@your-domain.com)
DEVOPS_SMTP_PASS = 对应密码/应用专用密码
DEVOPS_DEFAULT_LANG = cn 或 en
3.
生效配置:保存 env 后,进入上云 API 2 根目录执行:
4.
外发前的自检清单:
触发一封测试邮件(如在系统中触发一次告警或使用你的运维脚本/工具)
若收不到邮件,请参考下文的常见问题排查

暂时没有 SMTP 中继(以 Mailgun 为例)#

Mailgun 是主流邮件服务商之一,支持域名维度的发送与 SMTP 接入。
操作步骤:
1.
注册并登录 Mailgun(选择合适的区域/套餐)。
2.
添加你要发送的域名(如 your-domain.com):
按向导在你的 DNS 服务商处添加 SPF、DKIM(必需)与(可选的)MX、跟踪 CNAME 等记录。
等待 DNS 生效并在 Mailgun 控制台完成域名验证。
3.
创建/获取 SMTP 凭据:
主机:smtp.mailgun.org
用户名:通常为 postmaster@your-domain.com(或你在 Mailgun 上创建的 SMTP 用户)
密码:在控制台生成/查看。
4.
在上云 API 2 的 env 中填写:
DEVOPS_SMTP_HOST=smtp.mailgun.org
DEVOPS_SMTP_USER=postmaster@your-domain.com(或你的发件人账号)
DEVOPS_SMTP_PASS=<在 Mailgun 控制台复制的密码>
DEVOPS_DEFAULT_LANG=cn(或 en)
5.
生效配置:保存 env 后在上云 API 2 根目录执行:
6.
验证:触发一封测试邮件,若收不到邮件,请参考下文的常见问题排查

网络与安全注意事项#

网络出口放行: 开放到 SMTP 中继的 TCP 587/465 出站访问。
凭据最小化: 仅赋予发信所需权限;避免复用个人邮箱密码,优先使用「应用专用密码」。
密钥管理: 将 DEVOPS_SMTP_PASS 视作机密,限制可见范围,并定期轮换。
发件人规范: 实际 From 地址应属于你已验证的域名;避免使用公共域(如 @gmail.com)作为业务系统的 From。

如何验证配置后 SMTP 连通性(可选)#

1) 基于 OpenSSL 检查 STARTTLS(端口 587)
看到证书与 250-STARTTLS 等扩展能力,说明握手正常。正常情况下的示例输出如下:
depth=2 C = US, O = DigiCert Inc, OU = www.digicert.com, CN = DigiCert Global Root G2
verify return:1
depth=1 C = US, O = DigiCert Inc, CN = DigiCert Global G2 TLS RSA SHA256 2020 CA1
verify return:1
depth=0 C = US, ST = Texas, L = San Antonio, O = "MAILGUN TECHNOLOGIES, INC", CN = *.mailgun.org
verify return:1
250 STARTTLS
2) 使用 swaks(若已安装)发送一封测试邮件
如果配置生效,您能在收件邮箱中收到对应的邮件。
上述只是连通性/凭据校验手段;业务内的模板/告警邮件仍以系统实际配置为准。

变更与回滚建议#

调整 env 后记得执行 ./setuptools update 应用。
若需回滚,可恢复之前的 env 版本并再次执行 ./setuptools update。
变更窗口建议选择低峰期,并在变更完成后通过测试邮件验证。

常见问题排查(FAQ)#

Q1:提示认证失败(如 535 5.7.8 Authentication credentials invalid)?
核对 DEVOPS_SMTP_USER/DEVOPS_SMTP_PASS 是否正确、是否使用了「应用专用密码」。
账号是否允许 SMTP AUTH;企业邮箱/Exchange Online 可能默认关闭,需要管理员开启。
Q2:连接超时或无法连接?
检查到外网的 587/465 端口是否被防火墙/出口策略拦截。
若使用内网中继,确认 DNS 能解析到内网地址。
Q3:报证书校验错误?
通常是主机名与证书 CN/SAN 不匹配或根证书链不完整。更换为与证书匹配的主机名,并确保系统信任根证书。
Q4:邮件被拒收/进入垃圾箱?
确认已正确配置 SPF/DKIM(以及可选的 DMARC),发件域名与 From 地址一致。
Q5:我只想收中文(或英文)告警邮件,怎么设置?
设置 DEVOPS_DEFAULT_LANG=cn(仅收中文)或 DEVOPS_DEFAULT_LANG=en(仅收英文)。

进入 AIO 管理后台#

在浏览器中输入地址并访问,地址格式如下:
{{INTERNAL_IP}}:{{FH_SYSTEM_PORT}}
{{EXTERNAL_IP}}:{{FH_SYSTEM_PORT}}
{{SERVICE_DOMAIN}}:{{FH_SYSTEM_PORT}}
参数说明
访问地址示例192.168.1.101:30888
INTERNAL_IP编辑服务配置中您所配置的 IP 地址,默认为 192.168.1.101
FH_SYSTEM_PORT编辑服务配置中您所配置的端口号,默认为 30888
密码编辑服务配置中您所配置的密码
账号固定账号:admin

Prometheus 自定义指标与告警修改#

适用对象:使用容器部署的 Prometheus + Alertmanager;需要在上云 API 2 安装包里修改自定义指标阈值、增删规则、验证生效和排错。

流程概述#

1.
备份 monitor-cn.yml / monitor-en.yml
2.
修改 expr / labels / annotations(保留 groups: 顶层结构)
3.
在中文和英文两份文件中做同样修改
4.
docker exec prometheus 热加载
5.
验证规则加载、指标数值、告警触发、Alertmanager 接收、webhook 通知全链路

文件路径及配置#

规则文件路径:
${INSTALLATION_PATH}/conf/middleware-service/prometheus/rules
包含 monitor-cn.yml(中文)和 monitor-en.yml(英文)两份文件,强烈建议两边同步修改。

常用:修改阈值(以 DiskTemperature 为例)#

修改 expr 字段中的阈值后,热加载生效:

其他可修改项#

严重等级:labels.severity: warning | critical
与 Alertmanager 的 inhibit_rules、分流策略有关(配置里的 critical 会抑制同组 warning)。
告警文案:annotations.summary/description 支持模板:
{{ $labels.disk_name }} 插入标签值
{{ $value }} 插入当前数值
分组相关标签(影响去重/合并):Alertmanager 使用
group_by: ['alertname','instance','job','raid_name','disk_name','lang']
同组内的告警会合并发送;字段一致才视为"同一组"。

完整示例(中文规则)#

注意: 请确认你的文件顶层是 groups:,否则 Prometheus 不会加载!
同步更新 monitor-en.yml,确保英文环境下信息一致。

如何验证"新规则已生效"#

下列命令都在宿主机命令行内执行;把容器名改成实际名称(默认 prometheus / alertmanager)。
1. 看 Prometheus 是否加载了规则
2. 看指标有没有数据(实时)
如果 up 有值,说明目标抓取正常;
如果 disk_* 有值,说明业务指标在进来。
3. 看告警是否进入 pending/firing
4. 看 Alertmanager 是否收到了
5. 快速验证 WebHook 配置的有效性
放一条"必然触发"的测试规则(改完 reload):
热加载后,/api/v1/alerts 和 Alertmanager 应立即出现该告警;webhook 应立刻收到通知。

新增一条自定义告警(示例)#

假设你新增一个指标 disk_iops,希望 IOPS > 2000 告警:
保存后 reload,用 /api/monitor/metrics 确认指标存在后会触发/验证。请注意,新增的自定义告警的指标项,必须要有一个对应的指标上报源,否则 Prometheus 没得到指标就无从触发告警。

命令速查(容器环境)#

上一页
开始部署
下一页
设备上云
Built with