mirror of
https://github.com/dptech-corp/Uni-Lab-OS.git
synced 2025-12-17 13:01:12 +00:00
14 KiB
14 KiB
Uni-Lab 配置指南
Uni-Lab 支持通过 Python 配置文件进行灵活的系统配置。本指南将帮助您理解配置选项并设置您的 Uni-Lab 环境。
配置文件格式
Uni-Lab 支持 Python 格式的配置文件，它比 YAML 或 JSON 提供更多的灵活性，包括支持注释、条件逻辑和复杂数据结构。
默认配置示例
首次使用时，系统会自动创建一个基础配置文件 local_config.py：
# unilabos的配置文件
class BasicConfig:
ak = "" # 实验室网页给您提供的ak代码，您可以在配置文件中指定，也可以通过运行unilabos时以 --ak 传入，优先按照传入参数解析
sk = "" # 实验室网页给您提供的sk代码，您可以在配置文件中指定，也可以通过运行unilabos时以 --sk 传入，优先按照传入参数解析
# WebSocket配置，一般无需调整
class WSConfig:
reconnect_interval = 5 # 重连间隔（秒）
max_reconnect_attempts = 999 # 最大重连次数
ping_interval = 30 # ping间隔（秒）
完整配置示例
您可以根据需要添加更多配置选项：
#!/usr/bin/env python
# coding=utf-8
"""Uni-Lab 配置文件"""
# 基础配置
class BasicConfig:
ak = "your_access_key" # 实验室访问密钥
sk = "your_secret_key" # 实验室私钥
working_dir = "" # 工作目录（通常自动设置）
config_path = "" # 配置文件路径（自动设置）
is_host_mode = True # 是否为主站模式
slave_no_host = False # 从站模式下是否跳过等待主机服务
upload_registry = False # 是否上传注册表
machine_name = "undefined" # 机器名称（自动获取）
vis_2d_enable = False # 是否启用2D可视化
enable_resource_load = True # 是否启用资源加载
communication_protocol = "websocket" # 通信协议
# WebSocket配置
class WSConfig:
reconnect_interval = 5 # 重连间隔（秒）
max_reconnect_attempts = 999 # 最大重连次数
ping_interval = 30 # ping间隔（秒）
# OSS上传配置
class OSSUploadConfig:
api_host = "" # API主机地址
authorization = "" # 授权信息
init_endpoint = "" # 初始化端点
complete_endpoint = "" # 完成端点
max_retries = 3 # 最大重试次数
# HTTP配置
class HTTPConfig:
remote_addr = "http://127.0.0.1:48197/api/v1" # 远程地址
# ROS配置
class ROSConfig:
modules = [
"std_msgs.msg",
"geometry_msgs.msg",
"control_msgs.msg",
"control_msgs.action",
"nav2_msgs.action",
"unilabos_msgs.msg",
"unilabos_msgs.action",
] # 需要加载的ROS模块
命令行参数覆盖配置
Uni-Lab 允许通过命令行参数覆盖配置文件中的设置，提供更灵活的配置方式。命令行参数的优先级高于配置文件。
支持命令行覆盖的配置项
以下配置项可以通过命令行参数进行覆盖：
| 配置类 | 配置字段 | 命令行参数 | 说明 |
|---|---|---|---|
BasicConfig |
ak |
--ak |
实验室访问密钥 |
BasicConfig |
sk |
--sk |
实验室私钥 |
BasicConfig |
working_dir |
--working_dir |
工作目录路径 |
BasicConfig |
is_host_mode |
--is_slave |
主站模式（参数为从站模式，取反） |
BasicConfig |
slave_no_host |
--slave_no_host |
从站模式下跳过等待主机服务 |
BasicConfig |
upload_registry |
--upload_registry |
启动时上传注册表信息 |
BasicConfig |
vis_2d_enable |
--2d_vis |
启用 2D 可视化 |
HTTPConfig |
remote_addr |
--addr |
远程服务地址 |
特殊命令行参数
除了直接覆盖配置项的参数外，还有一些特殊的命令行参数：
| 参数 | 说明 |
|---|---|
--config |
指定配置文件路径 |
--port |
Web 服务端口（不影响配置文件） |
--disable_browser |
禁用自动打开浏览器（不影响配置文件） |
--visual |
可视化工具选择（不影响配置文件） |
--skip_env_check |
跳过环境检查（不影响配置文件） |
配置优先级
配置项的生效优先级从高到低为：
- 命令行参数：最高优先级
- 环境变量：中等优先级
- 配置文件：基础优先级
使用示例
# 通过命令行覆盖认证信息
unilab --ak "new_access_key" --sk "new_secret_key"
# 覆盖服务器地址
unilab --addr "https://custom.server.com/api/v1"
# 启用从站模式并跳过等待主机
unilab --is_slave --slave_no_host
# 启用上传注册表和2D可视化
unilab --upload_registry --2d_vis
# 组合使用多个覆盖参数
unilab --ak "key" --sk "secret" --addr "test" --upload_registry --2d_vis
预设环境地址
--addr 参数支持以下预设值，会自动转换为对应的完整 URL：
test→https://uni-lab.test.bohrium.com/api/v1uat→https://uni-lab.uat.bohrium.com/api/v1local→http://127.0.0.1:48197/api/v1- 其他值 → 直接使用作为完整 URL
配置选项详解
基础配置 (BasicConfig)
基础配置包含了系统运行的核心参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
ak |
str | "" |
实验室访问密钥（必需） |
sk |
str | "" |
实验室私钥（必需） |
working_dir |
str | "" |
工作目录，通常自动设置 |
is_host_mode |
bool | True |
是否为主站模式 |
slave_no_host |
bool | False |
从站模式下是否跳过等待主机服务 |
upload_registry |
bool | False |
启动时是否上传注册表信息 |
machine_name |
str | "undefined" |
机器名称，自动从 hostname 获取（不可配置） |
vis_2d_enable |
bool | False |
是否启用 2D 可视化 |
communication_protocol |
str | "websocket" |
通信协议，固定为 websocket |
认证配置
ak 和 sk 是必需的认证参数：
- 获取方式：在 Uni-Lab 官网 注册实验室后获得
- 配置方式：
- 命令行参数：
--ak "your_key" --sk "your_secret"（最高优先级） - 配置文件：在
BasicConfig类中设置 - 环境变量：
UNILABOS_BASICCONFIG_AK和UNILABOS_BASICCONFIG_SK
- 命令行参数：
- 优先级顺序：命令行参数 > 环境变量 > 配置文件
- 安全注意：请妥善保管您的密钥信息
推荐做法：
- 开发环境：使用配置文件
- 生产环境：使用环境变量或命令行参数
- 临时测试：使用命令行参数
WebSocket 配置 (WSConfig)
WebSocket 是 Uni-Lab 的主要通信方式：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
reconnect_interval |
int | 5 |
断线重连间隔（秒） |
max_reconnect_attempts |
int | 999 |
最大重连次数 |
ping_interval |
int | 30 |
心跳检测间隔（秒） |
HTTP 配置 (HTTPConfig)
HTTP 客户端配置用于与云端服务通信：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
remote_addr |
str | "http://127.0.0.1:48197/api/v1" |
远程服务地址 |
预设环境地址：
- 生产环境：
https://uni-lab.bohrium.com/api/v1 - 测试环境：
https://uni-lab.test.bohrium.com/api/v1 - UAT 环境：
https://uni-lab.uat.bohrium.com/api/v1 - 本地环境：
http://127.0.0.1:48197/api/v1
ROS 配置 (ROSConfig)
配置 ROS 消息转换器需要加载的模块：
class ROSConfig:
modules = [
"std_msgs.msg", # 标准消息类型
"geometry_msgs.msg", # 几何消息类型
"control_msgs.msg", # 控制消息类型
"control_msgs.action", # 控制动作类型
"nav2_msgs.action", # 导航动作类型
"unilabos_msgs.msg", # UniLab 自定义消息类型
"unilabos_msgs.action", # UniLab 自定义动作类型
]
您可以根据实际使用的设备和功能添加其他 ROS 模块。
OSS 上传配置 (OSSUploadConfig)
对象存储服务配置，用于文件上传功能：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
api_host |
str | "" |
OSS API 主机地址 |
authorization |
str | "" |
授权认证信息 |
init_endpoint |
str | "" |
上传初始化端点 |
complete_endpoint |
str | "" |
上传完成端点 |
max_retries |
int | 3 |
上传失败最大重试次数 |
环境变量支持
Uni-Lab 支持通过环境变量覆盖配置文件中的设置。环境变量格式为：
UNILABOS_{配置类名}_{字段名}
环境变量示例
# 设置基础配置
export UNILABOS_BASICCONFIG_AK="your_access_key"
export UNILABOS_BASICCONFIG_SK="your_secret_key"
export UNILABOS_BASICCONFIG_IS_HOST_MODE="true"
# 设置WebSocket配置
export UNILABOS_WSCONFIG_RECONNECT_INTERVAL="10"
export UNILABOS_WSCONFIG_MAX_RECONNECT_ATTEMPTS="500"
# 设置HTTP配置
export UNILABOS_HTTPCONFIG_REMOTE_ADDR="https://uni-lab.bohrium.com/api/v1"
环境变量类型转换
- 布尔值：
"true","1","yes"→True；其他 →False - 整数：自动转换为
int类型 - 浮点数：自动转换为
float类型 - 字符串：保持原值
配置文件使用方法
1. 指定配置文件启动
# 使用指定配置文件启动
unilab --config /path/to/your/config.py
2. 使用默认配置文件
如果不指定配置文件，系统会按以下顺序查找：
- 环境变量
UNILABOS_BASICCONFIG_CONFIG_PATH指定的路径 - 工作目录下的
local_config.py - 首次使用时会引导创建配置文件
3. 配置文件验证
系统启动时会自动验证配置文件：
- 语法检查：确保 Python 语法正确
- 类型检查：验证配置项类型是否匹配
- 必需项检查：确保
ak和sk已配置
最佳实践
1. 安全配置
-
不要将包含密钥的配置文件提交到版本控制系统
-
使用环境变量或命令行参数在生产环境中配置敏感信息
-
定期更换访问密钥
-
推荐配置方式：
# 生产环境 - 使用环境变量 export UNILABOS_BASICCONFIG_AK="your_access_key" export UNILABOS_BASICCONFIG_SK="your_secret_key" unilab # 或使用命令行参数 unilab --ak "your_access_key" --sk "your_secret_key"
2. 多环境配置
为不同环境创建不同的配置文件并结合命令行参数：
configs/
├── local_config.py # 本地开发
├── test_config.py # 测试环境
├── prod_config.py # 生产环境
└── example_config.py # 示例配置
环境切换示例：
# 本地开发环境
unilab --config configs/local_config.py --addr local
# 测试环境
unilab --config configs/test_config.py --addr test --upload_registry
# 生产环境
unilab --config configs/prod_config.py --ak "$PROD_AK" --sk "$PROD_SK"
3. 配置管理
- 保持配置文件简洁，只包含需要修改的配置项
- 为配置项添加注释说明其作用
- 定期检查和更新配置文件
- 命令行参数优先使用场景：
- 临时测试不同配置
- CI/CD 流水线中的动态配置
- 不同环境间快速切换
- 敏感信息的安全传递
4. 灵活配置策略
基础配置文件 + 命令行覆盖的推荐方式：
# base_config.py - 基础配置
class BasicConfig:
# 非敏感配置写在文件中
is_host_mode = True
upload_registry = False
vis_2d_enable = False
class WSConfig:
reconnect_interval = 5
max_reconnect_attempts = 999
ping_interval = 30
# 启动时通过命令行覆盖关键参数
unilab --config base_config.py \
--ak "$AK" \
--sk "$SK" \
--addr "test" \
--upload_registry \
--2d_vis
故障排除
1. 配置文件加载失败
错误信息：[ENV] 配置文件 xxx 不存在
解决方法：
- 确认配置文件路径正确
- 检查文件权限是否可读
- 确保配置文件是
.py格式
2. 语法错误
错误信息：[ENV] 加载配置文件 xxx 失败
解决方法：
- 检查 Python 语法是否正确
- 确认类名和字段名拼写正确
- 验证缩进是否正确（使用空格而非制表符）
3. 认证失败
错误信息：后续运行必须拥有一个实验室
解决方法：
- 确认
ak和sk已正确配置 - 检查密钥是否有效
- 确认网络连接正常
4. 环境变量不生效
解决方法：
- 确认环境变量名格式正确（
UNILABOS_CLASS_FIELD） - 检查环境变量是否已正确设置
- 重启系统或重新加载环境变量
5. 命令行参数不生效
错误现象：设置了命令行参数但配置没有生效
解决方法：
- 确认参数名拼写正确（如
--ak而不是--access_key） - 检查参数格式是否正确（布尔参数如
--is_slave不需要值） - 确认参数位置正确（所有参数都应在
unilab之后） - 查看启动日志确认参数是否被正确解析
6. 配置优先级混淆
错误现象：不确定哪个配置生效
解决方法：
- 记住优先级：命令行参数 > 环境变量 > 配置文件
- 使用
--ak和--sk参数时会看到提示信息 - 检查启动日志中的配置加载信息
- 临时移除低优先级配置来测试高优先级配置是否生效