📋 文档信息 ​

📋 变更历史记录 ​

🎯 机制概述 ​

部件加载时，不会用定制文件整体替换基础 CSR，而是把一份定制叠加到基础 CSR 上。

定制只有两种，二者不同时出现：

• 机型定制：按机型差异修改
• 客户定制：按客户差异修改

实际加载为 基础 CSR + 机型定制，或 基础 CSR + 客户定制。没有对应定制文件时，只使用基础 CSR。

合并做什么 ​

• 改属性：同名对象合并字段，定制侧覆盖基础侧
• 加对象：定制文件中的新对象名会加入 Objects
• 删对象：用 Customization.DeletedObjects 按名称删除软件对象
• 改拓扑：ManagementTopology 单独合并，与对象删除互不影响

📂 文件放哪里 ​

按当前使用的定制类型，只配其中一套目录：

基础 CSR 位于 /opt/bmc/sr，由产品自带，不在本机制中探测。

身份名由部件 Connector 的 Bom、Id、AuxId 拼出：

• 常见形式：{Bom}_{Id}_{AuxId}，例如 14140130_19e50222_19e500a1
• 没有 Bom 时：{Id} 或 {Id}_{AuxId}

客户定制文件要加 _cust.sr 后缀，例如：

14140130_19e50222_19e500a1_cust.sr

机型定制不加该后缀。只有客户定制会读取 index.json。

🔍 如何选中定制文件 ​

系统先按带 Bom 的身份名查找，找不到再用不带 Bom 的身份名。

机型定制：只按文件名全匹配，不读 index.json。

客户定制：一批部件要共用同一份定制时，先用 index.json 做前缀/后缀匹配；未命中再找 {身份名}_cust.sr。索引一旦命中，不会再叠加同目录下的全匹配文件。

📑 客户定制索引 index.json ​

仅客户定制使用，路径固定为：

/opt/bmc/extend/{customer}/sr/index.json

用于把一批身份名映射到同一份定制文件，避免为每个部件复制一份 {身份名}_cust.sr。

规则字段 ​

{
  "Rules": [
    { "Rule": "Prefix", "Pattern": "14100513", "MatchedFile": "14100513_common_cust.sr" },
    { "Rule": "Suffix", "Pattern": "_19e500a1", "MatchedFile": "nic_tail_cust.sr" }
  ]
}

MatchedFile 不以 .sr 结尾时，会自动补成 *_cust.sr。不要写路径分隔符或 ..。

匹配原则 ​

• 一次只命中一条规则
• Prefix 优先于 Suffix
• 同类规则中，更长的 Pattern 优先
• 精确到某个身份名的文件不必写入索引，直接放 {身份名}_cust.sr 即可

🔗 对象如何合并 ​

定制文件只需写出要改的部分。

{
  "Objects": {
    "PCIeNicCard_1": {
      "bmc.dev.PCIeDevice": {
        "DeviceName": "hisi_1822"
      }
    }
  }
}

上例只改 PCIeNicCard_1 的设备名，该对象上其它字段保持不变。

🗑️ 删除软件对象 ​

在定制文件顶层增加 Customization，用 DeletedObjects 列出要删除的对象名。删除发生在对象合并之后，因此同一份文件里可以既改对象、又删对象。

{
  "Objects": {
    "PCIeNicCard_1": {
      "bmc.dev.PCIeDevice": {
        "DeviceName": "hisi_1822"
      }
    }
  },
  "Customization": {
    "DeletedObjects": ["OpticalModule_0"]
  }
}

只删除软件对象，例如 PCIeNicCard_1、NetworkPort_0、OpticalModule_0、SRUpgrade_1。不要用来删除硬件或拓扑对象，例如 I2c_8、Eeprom_1、Connector_1、Scanner_SerdesLom1Pres。

DeletedObjects 不会同步清理 ManagementTopology 中的引用。拓扑需要改时，请单独写 ManagementTopology。

🗺️ 拓扑如何合并 ​

ManagementTopology 与 Objects 分开合并：

• 同名节点合并属性；数组按去重追加
• 定制中的新节点会加入拓扑
• 删除对象不会自动摘掉拓扑里的同名引用

📝 配置示例 ​

1. 机型定制 ​

文件：/opt/bmc/extend/{platform_id}_{board_id}/sr/14140130_19e50222_19e500a1.sr

{
  "Objects": {
    "PCIeNicCard_1": {
      "bmc.dev.PCIeDevice": {
        "DeviceName": "hisi_1822"
      }
    }
  },
  "Customization": {
    "DeletedObjects": ["OpticalModule_0"]
  }
}

覆盖网卡设备名，并删除不需要的光模块对象。

2. 单个部件的客户定制 ​

文件：/opt/bmc/extend/{customer}/sr/14140130_19e50222_19e500a1_cust.sr

内容与机型定制相同，但文件名带 _cust.sr，且放在客户定制目录。

3. 一批部件共用一份客户定制 ​

index.json：

{
  "Rules": [
    { "Rule": "Prefix", "Pattern": "14100513", "MatchedFile": "14100513_common_cust.sr" }
  ]
}

身份名以 14100513 开头的部件都会加载 14100513_common_cust.sr。

🔧 使用指南 ​

配置步骤 ​

1. 选定定制类型：机型定制或客户定制，只使用其中一种。
2. 按身份名命名文件：机型用 {身份名}.sr，客户用 {身份名}_cust.sr。
3. 只写差异：在 Objects 中覆盖或新增需要的对象与字段。
4. 按需删除软件对象：将对象名写入 DeletedObjects。
5. 客户定制且一批部件共用时：在客户目录编写 index.json，把共享文件与索引放在同一目录。
6. 加载后核对：确认目标对象属性、删除结果和拓扑符合预期。

注意事项 ​

• 机型与客户不同时配置：同一场景只走一种定制。
• 一份定制只选一个文件：客户定制下，索引命中后不会再合并同目录的 {身份名}_cust.sr。
• 只删软件对象：误删硬件对象后，拓扑引用可能悬空。
• 空对象不能清字段：要用 DeletedObjects 删对象，或显式写出要覆盖的字段。
• null 会覆盖原值：不要用 null 表示“保持原值”。
• 改完索引需重新加载：index.json 不会在运行中自动刷新。

❓ 常见问题 ​

Q1: 定制文件放好了却完全没生效？ ​

A: 先确认当前是机型定制还是客户定制，再检查文件是否在对应目录、客户文件是否带 _cust.sr，以及部件身份名是否与文件名一致。

Q2: 写了 index.json，实际却用了 {身份名}_cust.sr？ ​

A: 规则未命中，或 MatchedFile 指向的文件不存在。确认 Pattern 与身份名的前缀/后缀一致，且共享文件与 index.json 在同一目录。index.json 只用于客户定制。

Q3: 为什么命中了更宽的规则，而不是更具体的后缀规则？ ​

A: Prefix 优先于 Suffix。需要更具体的匹配时，使用更长的 Prefix，或不要同时配置会抢先命中的宽前缀。

Q4: 对象删了，拓扑里还能看到相关总线/节点？ ​

A: 这是预期行为。DeletedObjects 只删除 Objects 中的对象，拓扑需单独配置。

Q5: 机型目录里的 index.json 为什么不生效？ ​

A: index.json 只用于客户定制。机型定制只按 {身份名}.sr 全匹配。