IpManager 接口文档

简介

简述：该文件定义了IpManager类，用于统一管理RflySim仿真平台中通信交互所需的IP地址与端口配置。

在RflySim无人机仿真框架中，地面站、飞控、仿真环境等不同组件往往运行在不同的网络节点或进程上，需要统一的IP地址信息管理来保障各模块间的网络通信正常建立。该模块负责维护各类通信链路对应的地址配置信息，为SDK中其他通信控制模块提供统一的地址查询与管理入口，适用于多机仿真、分布式仿真等需要区分不同节点通信地址的场景，简化了IP配置的维护与调用流程。

快速开始

最简可用示例，复制后修改最少配置即可运行。

from RflySimSDK.ctrl.IpManager import IpManager

# 检查IP配置文件是否存在且路径有效
exists, config_path = IpManager.is_valid()
print(f"IP配置文件状态: 存在={exists}, 路径={config_path}")

# 检测当前程序是否运行在Docker/K8s容器中
in_container = IpManager.is_container()
print(f"当前是否运行在容器中: {in_container}")

# 获取配置文件中的本机IP，获取失败使用默认127.0.0.1
local_ip = IpManager.get_local_ip()
print(f"获取到的本机IP地址为: {local_ip}")

# 也可自定义获取失败时的默认IP
custom_default_ip = "192.168.1.100"
local_ip_custom = IpManager.get_local_ip(custom_default_ip)
print(f"自定义默认IP后的本机IP地址为: {local_ip_custom}")

环境与依赖

• Python 环境：>= 3.8.10
• 依赖库：json、os
• 前置准备：调用此接口前，必须先正确配置RflySim SDK的IP连接相关参数并完成SDK环境初始化。

核心接口说明

该模块 IpManager.py 包含了配置变量、辅助函数及核心业务类。

全局常量与枚举定义

本节列出模块中所有可直接引用的全局常量和枚举定义。

独立常量

无

---

全局/独立函数

无

---

IpManager 类

IP地址管理工具类，用于从配置文件中获取RflySim平台各组件（RflySim3D、CopterSim、QGroundControl）的IP地址，同时支持环境检测和配置校验，适配本地和分布式仿真场景。

---

is_valid()

功能说明：检查IP配置文件路径是否有效，且配置文件是否存在。 参数列表 (Args)： 无参数 返回值 (Returns)：

• tuple: 第一个元素为bool表示配置是否有效，第二个元素为str表示配置文件路径

异常 (Raises)：

• 无

---

is_container()

功能说明：检测当前程序是否运行在容器环境（Docker/K8s等）中。 参数列表 (Args)： 无参数 返回值 (Returns)：

• bool: 若运行在容器中返回True，否则返回False

异常 (Raises)：

• 无

---

get_local_ip(original_ip)

功能说明：从配置文件获取本机IP地址。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
original_ip	Any | 否 |127.0.0.1`	查找失败或不需要查找时返回的默认IP地址

返回值 (Returns)：

• str: 本机IP地址字符串

异常 (Raises)：

• 无

示例：

from RflySimSDK.ctrl import IpManager
local_ip = IpManager.get_local_ip()
print("本机IP为：", local_ip)

---

get_rflysim3d_ip(original_ip)

功能说明：获取RflySim3D的IP地址。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
original_ip	Any	否	127.0.0.1	查找失败或不需要查找时返回的默认IP地址

返回值 (Returns)：

• str: RflySim3D IP地址字符串

异常 (Raises)：

• 无

示例：

from RflySimSDK.ctrl import IpManager
rflysim3d_ip = IpManager.get_rflysim3d_ip()
print("RflySim3D IP为：", rflysim3d_ip)

---

get_coptersim_ip(copter_id, original_ip)

功能说明：获取指定飞机ID对应的CopterSim IP地址，当CopterSim与SDK不在同一台计算机时，会自动请求CopterSim将数据发送到本机。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
copter_id	Any	是	None	目标飞机的ID号
original_ip	Any	否	127.0.0.1	查找失败或不需要查找时返回的默认IP地址

返回值 (Returns)：

• str: CopterSim IP地址字符串

异常 (Raises)：

• 无

示例：

from RflySimSDK.ctrl import IpManager
# 获取ID为1的无人机对应的CopterSim IP
coptersim_ip = IpManager.get_coptersim_ip(1)
print("CopterSim IP为：", coptersim_ip)

---

get_qgc_ip(original_ip)

功能说明：获取QGroundControl地面站的IP地址。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
original_ip	Any	否	127.0.0.1	查找失败或不需要查找时返回的默认IP地址

返回值 (Returns)：

• str: QGC IP地址字符串

异常 (Raises)：

• 无

---

进阶用法示例

展示复杂组合场景（如多类协作、异步控制、批量操作）

针对多无人机协同仿真集群的组网场景，我们可以结合IpManager实现批量IP有效性校验，同时配合多机控制模块完成异构仿真组件的IP地址自动适配。例如针对同时运行PX4仿真、RflySim3D渲染以及QGC地面站的多节点分布式部署场景，可以批量获取不同服务的IP并提前完成连通性校验，避免仿真启动后出现连接失败问题，示例代码如下：

from RflySimSDK.ctrl import IpManager
import concurrent.futures

# 异步批量校验多个仿真组件IP的连通性
def check_ip_valid(service_name, get_ip_method):
    ip = get_ip_method()
    return (service_name, ip, IpManager.is_valid(ip))

# 需要校验的服务列表，覆盖不同类型仿真组件
service_list = [
    ("RflySim3D", IpManager.get_rflysim3d_ip),
    ("CopeliSim仿真", IpManager.get_coptersim_ip),
    ("QGC地面站", IpManager.get_qgc_ip)
]

# 异步批量校验，提升大规模集群场景下的启动效率
with concurrent.futures.ThreadPoolExecutor() as executor:
    futures = [executor.submit(check_ip_valid, name, method) for name, method in service_list]
    for future in concurrent.futures.as_completed(futures):
        service_name, ip, is_valid = future.result()
        if is_valid:
            print(f"{service_name} IP {ip} 连通性正常")
        else:
            print(f"警告：{service_name} IP {ip} 无法连通，请检查网络配置")

# 获取本机IP用于跨设备分布式仿真组网
local_ip = IpManager.get_local_ip()
print(f"本机组网IP为：{local_ip}")

该方案实现了异步批量IP校验，能够适配多机分布式集群仿真、异构组件协作的复杂场景，提前排查网络配置问题。

注意事项与避坑指南

• 多网卡环境IP获取异常：get_local_ip()方法默认优先获取活跃网卡的IP，如果设备存在多个物理网卡或虚拟网卡（如VPN、Docker虚拟网卡），可能会获取到错误的内网IP，需要手动根据网段过滤确认正确的组网IP。
• 容器部署网络判断失效：如果将仿真组件部署在Docker容器中，is_container()方法仅能识别默认网络配置下的容器环境，自定义桥接网络或主机网络模式下可能无法正确识别，需要手动配置IP映射规则。
• IP有效性校验范围限制：is_valid()方法仅校验IP格式是否正确与基础连通性，无法校验对应端口是否开放或仿真服务是否正常启动，连通性校验通过后仍需添加服务启动状态判断逻辑。
• 依赖环境配置错误：IpManager类的所有方法依赖RflySim核心配置文件读取IP信息，如果SDK初始化失败或配置文件缺失，所有获取IP的方法都会返回默认占位地址，使用前需要确认SDK已经完成正确初始化。

更新日志

• 2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云