*openUBMC 支持redfish/web rest接口风扇位置信息展示详细设计说明书*

<table>
    <tr>
        <td>所属SIG组:</td>
        <td></td>
    </tr>
    <tr>
        <td>落入版本:</td>
        <td>openUBMC26.3.0</td>
    </tr>
    <tr>
        <td>设计人员:</td>
        <td>jiazeyuan</td>
    </tr>
    <tr>
        <td>日期:</td>
        <td>2026-02-07</td>
    </tr>
</table>

**Copyright © 2026 openUBMC Community**

您对&quot;本文档&quot;的复制，使用，修改及分发受木兰宽松许可证, 第2版协议(以下简称&quot;MulanPSL2&quot;)的约束。
为了方便用户理解，您可以通过访问<https://license.coscl.org.cn/MulanPSL2>了解MulanPSL2的概要 (但不是替代)。
MulanPSL2的完整协议内容您可以访问如下网址获取：<https://license.coscl.org.cn/MulanPSL2>。

**改版记录**

<table>
    <tr>
        <th>日期</th>
        <th>修订版本</th>
        <th>修订描述</th>
        <th>作者</th>
        <th>审核</th>
    </tr>
    <tr>
        <td>2026/2/7</td>
        <td>1.0</td>
        <td>初稿</td>
        <td>jiazeyuan</td>
        <td>/</td>
    </tr>
</table>

**List of abbreviations**  **缩略语清单** ：

<table>
    <tr>
        <th>Abbreviations 缩略语</th>
        <th>Full spelling 英文全名</th>
        <th>Chinese explanation 中文解释</th>
    </tr>
    <tr>
        <td>IMU</td>
        <td>Intelligent Management Unit</td>
        <td>智能管理单元</td>
    </tr>
    <tr>
        <td>NCSI</td>
        <td>Network Controller Sideband Interface</td>
        <td>网络控制器边带接口</td>
    </tr>
    <tr>
        <td>MCTP</td>
        <td>Management Component Transport Protocol</td>
        <td>管理设备传输协议</td>
    </tr>
    <tr>
        <td>BMC</td>
        <td>Baseboard Management Controller</td>
        <td>基板管理控制器</td>
    </tr>
    <tr>
        <td>DT</td>
        <td>Developer Testing(开发者测试)</td>
        <td>是指开发者所做的测试，有别于专职测试人员进行的测试活动</td>
    </tr>
    <tr>
        <td>UT</td>
        <td>Unit Testing(单元测试)</td>
        <td>对最小粒度的功能单元进行验证的测试</td>
    </tr>
    <tr>
        <td>IT</td>
        <td>Integration Testing(集成测试)</td>
        <td>组件/模块/微服务对外接口测试，即1个组件/模块/微服务内部集成测试</td>
    </tr>

</table>

[TOC]

# 1.功能分析
## 1.1 功能背景
<!-- 描述该需求的来源或背景，比如：支撑XXX功能、XXX优化等；以及该需求对用户（含组件）带来什么具体价值，如果没有该需求，对用户（含组件）带来什么损失； -->

【北向接口】为支持风扇位置信息的查询，增加北向redfish和web接口查询。

sig评审材料：https://discuss.openubmc.cn/t/topic/4534

## 1.2 功能描述
<!-- 描述该需求交付的整体功能，主要实现XXX功能，解决XXX问题，明确方案如何实现 -->

支持redfish/web rest接口风扇位置信息展示

## 1.3 功能场景
<!-- 描述该需求的业务使用场景，内容包括：
1) 场景出发条件及对象：什么角色/工具/接口等在什么具体情况下使用该特性，使用对象技能如何？
2) 使用时间及频度
3) 描述该特性主要有哪些场景、子场景及关键任务操作 -->

使用场景：
* 通过redfish接口查询风扇信息
* 在前端展示风扇信息


## 1.4 功能列表
<!-- 描述该需求交付的功能列表，内容包括：列出功能详细描述，标题、描述。 -->

| 功能编号 | 功能标题 | 功能描述 |
| ------- | ------- | -------- |
| 1 | 支持web_backend返回风扇位置信息 | 在web_backend返回的风扇数据中新增Position属性  |
| 2 | 支持redfish返回风扇位置信息 | ThermalSubsystem/Fans接口封装并返回风扇的Location属性  |

# 2.功能设计
## 2.1 总体方案分析
<!-- 描述该方案的总体设计（注：相关输出方案可同步刷新到各组件仓） -->

### 2.1.1 方案详细设计
#### 2.1.1.1 方案概述
<!-- 描述该方案的整体实现，内容包括：涉及的关键点，实现策略等 -->
资源树接口已经支持风扇的Position属性，只在北向返回风扇位置属性。

#### 2.1.1.2 开发视图
<!-- 开发视图面向系统开发及软件管理，描述系统代码结构，构建结构的视图，主要解决系统技术实现和开发的问题，它依托逻辑视图，描述代码、构建结构 -->

```mermaid
graph TB
    subgraph "北向接口"
        A[redfish]
        C[web_backend]
    end

    subgraph "资源树"
        B[资源树]
    end

    subgraph "Web"
        D[Web 前端]
    end

    A --> B
    C --> B
    D --> C
```

#### 2.1.1.3 运行视图
<!-- 运行视图面向系统运行，描述系统启动过程、运行期交互的视图，主要解决系统运行期交互，描述各可执行交付件在运行期的交互关系 -->
redfish/web向资源树查询获取位置属性信息

### 2.1.2 内部依赖分析
<!-- 是否涉及与其他组件接口依赖，如果涉及需要确认当前是否已完成，是否匹配当前需求开发诉求 -->
依赖资源树风扇的Position属性和Slot属性（已实现）

service: bmc.kepler.thermal_mgmt 

path: /bmc/kepler/Systems/:SystemId/Thermal/Fans/:Id

interface: bmc.kepler.Systems.Fan

### 2.1.3 外部依赖分析
<!-- 是否涉及与平台SDK的依赖关系 -->
不涉及

### 2.1.4 北向接口分析
<!-- 需要分析当前功能是否有以下接口影响，如果有影响，则需要具体的补充影响点。其中注意点如下：
（1）如果有新增IPMI接口，请排查代码中IPMI命令注册的过滤字段，是否完全和IPMI命令的定义一致？
（2）新增一个接口时，需要咨询SIG组是否还有其他的接口受影响 -->
| 特性 | SNMP | CLI | WEB | KVM_VMM | IPMI(RMCP/RMCP+) | HMM | Redfish |
| ---- | ---- | ---- | --- | ------ | ---------------- | --- | ------- |
| 北向支持风扇位置属性查询 | NA | NA | Y | NA | NA | NA | Y |


### 2.1.5 兼容性分析
<!-- 当前的功能对现有在网的功能是否有影响，具体的影响点进行分析之后输出影响分析表格 -->
不涉及

### 2.1.6 定制化接口分析
<!-- 如果支持定制化设置，则需要给出定制化时的默认值（空定制化项条件下的设置值），如果涉及到定制化接口变更或新增，注意定制化接口文档需配套修改。注意定制化默认值变更对白牌包的影响 -->
不涉及

### 2.1.7 导入导出分析
<!-- 如果支持导入导出的配置，则需要分析导入导出的schema。 -->
不涉及

### 2.1.8 传感器分析
<!-- 如果需要新增传感器，则需要提前登记和评审新增的传感器要素。新增传感器评审需要上SIG-Interface进行评审 -->
不涉及

### 2.1.9 精准告警事件分析
<!-- 如果需要新增事件，则需要提前登记和评审新增的时间要素 -->
不涉及

### 2.1.10 系统锁定分析
<!-- 对外的接口或者命令是否支持系统锁定 -->
不涉及

### 2.1.11 用例场景分析
<!-- 以表格的形式输出该需求涉及的用例场景 -->
| 编号 | 用例场景 | 预期 | 
| --- | --- | --- | 
| 1 | redfish支持风扇位置属性查询 | 获取位置为真实值（和资源树上的一致） |
| 2 | redfish支持风扇位置属性查询（Position属性包含Slot信息） | 获取位置为真实值（和资源树上的一致，不会额外包含Slot信息） |
| 3 | redfish支持风扇位置属性查询（风扇不在位场景） | 可以正常返回风扇位置（和资源树上的一致） |
| 4 | web支持风扇位置属性查询 | 获取位置为真实值 |
| 5 | web支持风扇位置属性查询（Position属性包含Slot信息） | 获取位置为真实值（和资源树上的一致，不会额外包含Slot信息） |
| 6 | web支持风扇位置属性查询（风扇不在位场景） | 可以正常返回风扇位置（和资源树上的一致），前端显示风扇不在位，风扇信息显示为 "--"  |

## 2.2 非功能质量属性设计
### 2.2.1 扩展性分析
<!-- 考虑后续新增类似功能可以很好地扩展 -->
不涉及。

### 2.2.2 重用性分析
<!-- 是否为通用处理方式、接口，如果是得考虑重用性 -->
不涉及

### 2.2.3 可测试性分析
<!-- 此需求如何验证，是否可直接验证，or通过XXX功能覆盖验证，or需要单独怎加测试接口验证 -->
使用相关工具发送相关命令，直接验证

### 2.2.4 资料分析
<!-- 是否涉及资料修改 -->
需要更新内部redfish和web资料文档

### 2.2.5 资源使用分析
<!-- 新增线程、内存分配、模型属性名长度是否合理，CPU占用率是否会激增，Flash中新增文件是否合理（频繁读写Flash会大幅缩短emmc寿命）；是否涉及消息队列，如果涉及请检查是否存在某些场景下消息队列会满导致消息丢失，例如大量消息发送到队列且处理消息需要耗费较长时间的场景。 -->
不涉及

### 2.2.6 可靠性分析
| 编号 | 场景 | 问题描述 | 可靠性影响 | 问题级别 | 建议解决方案/需求 | 讨论结果 | 跟踪人 | 备注 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | redfish获取风扇信息 | 风扇不在位 | 依然可以查到风扇位置信息，状态为不在位 | 一般 | 无 |  |  | 工具模拟异常场景 |
| 2 | web获取风扇信息 | 风扇不在位 | 后端返回风扇位置信息，前端显示风扇不在位  | 一般 | 无 |  |  | 工具模拟异常场景 |
| 3 | redfish/web获取风扇信息 | 风扇Position中已经配置Slot属性 | 不应该额外返回资源树的Slot属性 | 提示 | 通过函数判断 |  |  | 通过sr配置验证 |

### 2.2.7 安全性分析
| 安全合规项 | 是否涉及 | 现有的防护措施 |
| --- | --- | --- |
| 访问控制（通道、文件权限、用户权限、查询权限、配置权限、接口权限） | 不涉及 |  |
| 敏感数据 | 不涉及 |  |
| 日志（操作日志、维护日志、安全日志、运行日志） | 不涉及 |  |
| 文档 | 不涉及 |  |
| 加密及算法 | 不涉及 |  |
| 新增关键资源（密钥、证书、关键配置）备份、恢复 | 不涉及 |  |
| 新增对外接口入参校验 | 不涉及 |  |
| 新增开源及三方软件引入 | 不涉及 |  |
# 3.功能实现
<!-- 通过表格、流程图、简明文字描述提供，力求容易看懂、容易实现，详细描述细节。 -->
## 3.1 增加redfish查询接口和web_backend查询接口
### 3.1.1 功能实现设计
新增属性查询

### 3.1.2 功能详细设计

1、redfish查询接口： https://IP/redfish/v1/Chassis/:chassisid/ThermalSubsystem/Fans/:fanid

查询资源树上的Position、Slot属性，并在redfish当中新增Location属性

Location属性定义：
|属性名 | 类型 | 示例/默认值/取值约束 | readonly | 易变属性 | 实现PATCH | 操作权限 | 描述|
|--- | --- | --- | --- | --- | --- | --- | ---|
|*`Location`* | *`object `* | *`/`* | *`true`* | *`/`* | *`/`* | *`ReadOnly`* | *`风扇的物理位置信息对象`*|
|*`  PartLocation`* | *`object `* | *`/`* | *`true`* | *`/`* | *`/`* | *`ReadOnly`* | *`风扇部件的详细位置描述`*|
|*`    ServiceLabel`* | *`string`* | *`示例："CLU1 Slot1"`* | *`true`* | *`否`* | *`/`* | *`ReadOnly`* | *`服务标签，记录风扇的完整位置标识`*|
|*`    LocationType`* | *`string`* | *`示例："Slot"`* | *`true`* | *`否`* | *`/`* | *`ReadOnly`* | *`位置类型，描述风扇的安装方式`*|
|*`    LocationOrdinalValue`* | *`integer`* | *`示例：1`* | *`true`* | *`否`* | *`/`* | *`ReadOnly`* | *`风扇的安装槽位编号`*|

**Schema定义**：                 
```json
"Location": {
    "$ref": "http://redfish.dmtf.org/schemas/v1/Resource.json#/definitions/Location",
    "description": "The location of the fan.",
    "longDescription": "This property shall contain the location information of this fan."
},
```

响应示例：

```
{
    "@odata.context": "/redfish/v1/$metadata#Fan.Fan",
    "@odata.id": "/redfish/v1/Chassis/1/ThermalSubsystem/Fans/1",
    "@odata.type": "#Fan.v1_5_2.Fan",
    ...
    "Location": {
        "PartLocation": {
            "ServiceLabel": "CLU1 Slot1",
            "LocationType": "Slot",
            "LocationOrdinalValue": 1
        }
    }
}
```


2、web_backend查询接口： https://IP/UI/Rest/System/Thermal

新增 Position 属性查询

响应体中已经包含Fans对象，在get_sort_fans_info函数中获取风扇的资源树属性Position，并在风扇对象中返回。

```mermaid
flowchart LR
    subgraph 调用层
        A[GerFans]
        B[get_sort_fans_info]
    end

    subgraph 处理层
        C[遍历风扇]
        D[判断单双转子]
        E[构建风扇对象]
    end

    A --> B
    B --> C
    C --> D
    D --> E
```
属性定义：
|属性名 | 类型 | 示例/默认值/取值约束 | readonly | 操作权限 | 描述|
|--- | --- | --- | --- | --- | ---|
|*`Fans`* | *`array`* | *`/`* | *`true`* | *`ReadOnly`* | *`风扇信息列表`*|
|*`    Position`* | *`string`* | *`示例："CLU1 Slot1"`* | *`true`* | *`ReadOnly`* | *`风扇位置信息`*|

响应示例：

```
{
    ...
    "Fans": [
        [
            {
                "Name": "Fan1",
                "ExpectedSpeedRatio": 80,
                "Speed": 11008,
                "SpeedRatio": 73,
                "Presence": 1,
                "Position": "CLU1 Slot1",
                "PartNumber": "02314BLG",
                "DutyCycle": 80,
                "FanId": 1,
                "Model": "02314BLG 8038+"
            }
        ],
        ...
    ],
    ...
}
```

预期前端界面：
```
风扇1
───────────────────────────────────────
型号              02314BLG 8038+
转速(RPM)         11008
期望速率比(%)     --
速率比(%)         73
部件编码          02314BLG
占空比(%)         80
位置              CLU1 Slot1
───────────────────────────────────────
```

风扇不在位时，预期前端界面：
```
风扇1
───────────────────────────────────────
型号              --
转速(RPM)         --
期望速率比(%)     --
速率比(%)         --
部件编码          --
占空比(%)         --
位置              --
───────────────────────────────────────
```
### 3.1.3 开发者测试
<!--
增加模块接口：以活动图/流程图等形式明确模块内处理流程，针对模块处理流程中的分支进行覆盖
修改模块接口处理流程：覆盖修改影响流程分支
-->
#### 3.1.3.1 单元测试
<!-- UT，主要是功能单元测试，测试对象是功能单元接口。UT测试设计要从黑盒（功能）角度设计，从输入(I)、处理（B）、预期输出（O）的角度进行用例分析设计，测试覆盖率仅作为反馈，用于分析哪些功能场景没有覆盖到，从而指导测试设计优化并补充测试用例 -->

NA
#### 3.1.3.2 集成测试
<!-- IT，主要是组件/模块内的集成测试，测试对象是模块/组件接口。IT测试设计将模块/组件当作黑盒测试，IT测试用例中禁止对组件/模块内部代码打桩，如果确实有少量场景难以构造，可以考虑在测试框架中统一打桩并提供接口供测试用例调用构造场景。
说明：API测试属于IT，其测试对象是微服务接口。
PCST，是指PC上的服务集成测试，测试对象是功能需求。PCST测试设计，要覆盖正常功能、异常功能和交叉功能，采用灰盒 -->

主要覆盖涉及的几个资源协作接口，保证集成测试结果正常

| 编号 | 用例场景 | 预期 | 
| --- | --- | --- | 
| 1 | redfish支持风扇位置属性查询 | 获取位置为真实值（和资源树上的一致） |
| 2 | redfish支持风扇位置属性查询（Position属性包含Slot信息） | 获取位置为真实值（和资源树上的一致，不会额外包含Slot信息） |
| 3 | redfish支持风扇位置属性查询（风扇不在位场景） | 可以正常返回风扇位置（和资源树上的一致） |
| 4 | web支持风扇位置属性查询 | 获取位置为真实值 |
| 5 | web支持风扇位置属性查询（Position属性包含Slot信息） | 获取位置为真实值（和资源树上的一致，不会额外包含Slot信息） |
| 6 | web支持风扇位置属性查询（风扇不在位场景） | 可以正常返回风扇位置（和资源树上的一致），前端显示风扇不在位，风扇信息显示为 "--"  |

## 3.2 列出涉及的接口
redfish查询接口： https://IP/redfish/v1/Chassis/:chassisid/ThermalSubsystem/Fans/:fanid

web_backend查询接口： https://IP/UI/Rest/System/Thermal

## 3.3 mdb命令

```
查询资源树属性
1、mdbctl lsobj Fan
2、mdbctl getprop <obj name> bmc.kepler.Systems.Fan Position
3、mdbctl getprop <obj name> bmc.kepler.Systems.Fan Slot
```
```
设置风扇在位状态
1、查看风扇1的scanner：mdbctl lsobj Scanner | grep Fan1_Presence
2、设置为不在位：mdbctl setprop set Scanner_Fan1_Presence_010103 bmc.kepler.Scanner Value 0
```