跳到主要内容

模块仓库源管理

XRobot 项目中,模块功能通常以“模块仓库”的形式分布在多个 Git 仓库中。官方提供了默认的模块源,但为了支持 私有模块、自定义组件、内网镜像或加速服务,你可以自定义多个模块源(Source)。

本页将介绍 XRobot 的多源模块仓库管理机制及命令行工具 xrobot_src_man 的用法,帮助你灵活配置、聚合和查找模块仓库。


为什么需要模块源管理?

  • ✅ 网络访问官方仓库缓慢?你可以添加镜像源或内网加速源。
  • ✅ 有内部模块?你可以添加私有 index.yaml 文件并独立命名空间。
  • ✅ 避免模块命名冲突?每个源拥有独立 namespace,模块互不影响。
  • ✅ 模块升级或迁移?支持同名模块来自不同来源,灵活选择优先级。

基础概念

名称说明
模块源(Source)一个 index.yaml 文件,描述若干模块仓库的列表,绑定命名空间(namespace)
sources.yaml用户本地的模块源列表,包含多个 index.yaml 的地址、优先级等信息
index.yaml单个源的模块列表和命名空间定义文件,可托管在公网或本地

一、快速上手:使用官方模块源

无需配置,默认使用官方源:xrobot-modules/index.yaml

创建 sources.yaml 模板

xrobot_src_man create-sources

查看当前所有可用模块

xrobot_src_man list

输出示例:

Available modules:
xrobot-org/BlinkLED source: https://xrobot-org.github.io/xrobot-modules/index.yaml (actual namespace: xrobot-org)

二、添加私有模块源

你可以为项目添加自定义 index.yaml,用于包含私有模块或镜像仓库。

1. 创建 sources.yaml 并加入多个源

xrobot_src_man create-sources --output Modules/sources.yaml

然后编辑该文件:

sources:
- url: https://xrobot-org.github.io/xrobot-modules/index.yaml
priority: 0
- url: https://your-domain.com/private-index.yaml
priority: 1

2. 本地添加私有源(本地路径也支持)

xrobot_src_man add-source ./Modules/my-index.yaml --priority 1

三、镜像/内网加速支持

某些 index.yaml 支持指定 mirror_of 字段,表示该源是另一个源的镜像,例如:

namespace: your-team
mirror_of: xrobot-org
modules:
- https://git.your-company.com/BlinkLED.git
- https://git.your-company.com/MySensor.git

四、创建与维护自定义 index.yaml

你可以创建并维护自己的 index.yaml 文件,便于组织私有模块。

1. 创建 index.yaml 模板

xrobot_src_man create-index --output Modules/my-index.yaml --namespace yourns

如需标记为镜像:

xrobot_src_man create-index --output my-index.yaml --namespace yourns --mirror-of xrobot-org

2. 向 index.yaml 添加模块仓库

xrobot_src_man add-index https://github.com/yourorg/MyModule.git --index Modules/my-index.yaml

五、模块查询与验证

你可以查询任意模块来源和地址:

查询所有模块

xrobot_src_man list

获取某模块的地址及来源

xrobot_src_man get yourns/MyModule

查找模块在所有源中的位置(包括镜像)

xrobot_src_man find yourns/MyModule