跳到主要内容

模块仓库源管理

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