redfish ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

redfish 是 openUBMC 面向外部管理工具提供的北向 RESTful 管理接口，基于 DMTF Redfish 标准实现。组件以 Skynet 服务运行，入口为 src/service/main.lua，注册服务名为 redfish，通过 REDFISH_PORTAL_LISTEN 配置监听地址，默认监听 0.0.0.0:8080。portal_agent 负责 HTTP 请求处理、鉴权、路由分发、事件订阅、任务服务和 TelemetryService 管理。

1.2 解决什么问题 ​

• 提供标准化、跨厂商一致的服务器管理接口，降低外部工具适配成本。
• 通过事件订阅实现主动告警和资源变化通知，避免只依赖轮询。
• 将固件升级等长时间操作转换为异步任务，便于查询进度和处理异常。
• 通过 TelemetryService 提供指标定义、采集、聚合和报告能力。
• 支持产品定制插件，在不修改核心代码的情况下扩展请求、响应和事件行为。

1.3 核心功能 ​

• Redfish API 路由分发：接收 HTTP/HTTPS 请求，支持 GET、PATCH、POST、DELETE 等操作，并通过路由映射器访问资源协作接口。
• 会话与认证管理：支持 Session-Based 认证和 Basic 认证，管理会话创建、查询和删除。
• 事件订阅与上报：管理 EventService/Subscriptions，按事件类型、严重度、消息 ID 和资源条件向订阅目标发送事件。
• 任务服务：管理异步任务及其子任务，支持任务状态、进度和 Task Monitor 查询。
• 固件升级：提供固件升级入口，支持 BMC、BIOS、CPLD 等目标组件，并通过任务查询升级进度。
• 遥测服务：管理 MetricDefinition、MetricReportDefinition、Trigger 和 MetricReport。
• Schema 与动态资源：提供 SchemaStore、JSONSchemas、动态 Schema 和资源树静态资源访问能力。

1.4 关键术语表 ​

1.5 外部交互边界图 ​

2. API 使用说明与示例 ​

2.1 Session 创建认证 ​

功能说明 ​

创建 Redfish 会话并返回 Session ID 和 X-Auth-Token，后续请求通过该 Token 访问受保护资源。

参数说明 ​

返回值与异常 ​

应用场景 ​

管理客户端首次连接 BMC 时创建会话，后续请求携带 Token 访问资源；会话结束后可删除对应 Session。

限制条件 ​

• Session 有生命周期限制，超时后需要重新创建。
• 并发 Session 数量受平台配置限制。
• 建议通过 HTTPS 访问，避免凭据和 Token 明文传输。

调试示例 ​

# 创建会话，保存响应头和响应体
curl -k -i -X POST https://BMC_IP/redfish/v1/SessionService/Sessions \
  -H "Content-Type: application/json" \
  -d '{"UserName":"admin","Password":"<password>"}'

响应示例：

成功：`HTTP/1.1 201 Created`，响应包含 `Location` 和 `X-Auth-Token`。
失败：认证失败返回 `401`。

# 使用响应中的 X-Auth-Token 访问受保护资源
curl -k -H "X-Auth-Token: <token>" \
  https://BMC_IP/redfish/v1/Systems

响应示例：

成功：`HTTP/1.1 200 OK`。
失败：返回对应 HTTP 错误码和 error 数组。

2.2 事件订阅创建 ​

功能说明 ​

客户端通过事件订阅将 BMC 产生的告警和资源变更事件推送到指定 HTTP/HTTPS 目标。订阅成功后，服务器返回 201 和订阅资源的 Location URI；后续可通过该 URI 查询或修改订阅。

参数说明 ​

返回值与异常 ​

应用场景 ​

用于网管平台、运维平台或事件接收服务订阅 BMC 告警、资源状态变化和 Telemetry 指标报告。

限制条件 ​

• 服务器不保留订阅创建前的历史事件。
• 事件投递依赖目标 URL 网络可达；HTTP 目标可能受到平台安全策略限制。
• 订阅字段、数量、重试策略和心跳周期受平台配置和插件策略约束。

调试示例 ​

curl -k -X POST https://BMC_IP/redfish/v1/EventService/Subscriptions \
  -H "X-Auth-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "Destination": "https://listener.example.com/redfish-events",
    "EventTypes": ["Alert", "ResourceUpdated"],
    "Context": "ops-monitor",
    "SendHeartbeat": true,
    "HeartbeatIntervalMinutes": 5,
    "DeliveryRetryPolicy": "RetryForever"
  }'

响应示例：

成功：`HTTP/1.1 201 Created`，响应包含订阅资源 `Location`。
失败：参数错误返回 `400`，Token 无效返回 `401`。

2.3 固件升级 ​

功能说明 ​

通过 UpdateService 接口提交固件升级任务，任务异步执行，客户端可通过返回的 Task URI 或 Task Monitor 查询进度。实际支持的目标组件和文件格式以当前平台的升级映射配置为准。

参数说明 ​

返回值与异常 ​

应用场景 ​

用于 BMC、BIOS、CPLD 等组件的固件升级。升级过程中可能触发 BMC 重启，应在维护窗口执行。

限制条件 ​

• 升级任务为异步执行，需要轮询 Task 状态。
• 部分升级需要在设备下电或重启后生效。
• 升级文件大小、格式、目标组件和路径权限由当前平台策略限制。

调试示例 ​

curl -k -X POST \
  https://BMC_IP/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate \
  -H "X-Auth-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ImageURI": "https://firmware.example.com/image.hpm",
    "TransferProtocol": "HTTPS",
    "Targets": ["/redfish/v1/UpdateService/FirmwareInventory/ActiveBMC"]
  }'

响应示例：

成功：`HTTP/1.1 202 Accepted`，响应包含任务 `Location`。
失败：参数、权限或升级冲突返回 `400/401/409`。

# 根据响应 Location 查询任务
curl -k -H "X-Auth-Token: <token>" \
  https://BMC_IP/redfish/v1/TaskService/Tasks/<task_id>

响应示例：

成功：`HTTP/1.1 200 OK`。
失败：返回对应 HTTP 错误码和 error 数组。

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

组件支持产品和客户定制扩展，包括请求预处理、响应后处理、URI 定制、事件订阅策略和事件编解码。定制代码以插件或配置形式加载，不修改核心代码。

3.2 扩展点说明 ​

3.3 二次开发指导 ​

1. 按产品定制目录约定实现 custom_request_response 或 redfish_subscription_plugin，不要直接修改核心 controller。
2. 定制函数必须位于组件白名单中，并在测试环境验证请求、响应和异常路径。
3. 事件编码定制应保持 Redfish Schema 兼容，确认 @odata.id、EventType 和 MessageId 等字段完整。
4. 定制配置变更后重启对应服务，检查插件加载日志，并回归会话、事件订阅和任务接口。

4. 日志说明 ​

4.1 一键日志收集 ​

组件注册 on_dump 回调，一键收集时会导出 redfish_event_log.json，内容包含事件 ID、SubscriptionId、时间和事件数据。事件日志按批处理并主动休眠，避免一键收集期间 CPU 占用过高。

同时按平台框架收集安全日志和操作日志：

4.2 关键日志信息 ​

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

5.3 最小化复现与证据收集 ​

1. 记录完整 URL、HTTP 方法、请求头、请求体、响应状态和响应体。
2. 对认证问题保存 Session 创建响应、X-Auth-Token 和账号状态。
3. 对事件问题保存订阅 URI、Destination、EventTypes、Context 和事件投递日志。
4. 对固件升级问题保存 Task URI、任务状态、升级文件格式、文件大小和目标资源。
5. 收集 redfish、event、UpdateService、TaskService 和对应 MDS 依赖组件日志。

5.4 调试方法 ​

• 使用 curl -k -v 按真实调用顺序复现，保留请求和响应头。
• 先确认会话或 Basic 认证成功，再检查路由映射和后端资源。
• 事件问题优先验证订阅 URI、目标网络可达性和事件触发条件。
• 升级问题先检查任务状态，再检查文件路径、格式、目标组件和任务日志。
• 通过微组件调试接口调整日志级别和日志类型，复现后及时恢复。

6. 常见问题解答 ​

Q1：Redfish API 返回 401 Unauthorized，如何处理？ ​

• 问题描述：调用 Redfish 接口时返回 401 未授权错误。
• 一句话答案：Session 过期、Token 无效或请求未携带有效认证信息。
• 根因说明：Session 有生命周期限制，或者请求未携带正确的 X-Auth-Token。
• 解决方案：重新创建 Session 获取新 Token，并在请求头中正确携带 Token。
• 规避方案：设置合理的 Session 超时时间，客户端处理 Token 过期和重建。
• 适用版本：1.140.4。

Q2：事件订阅后未收到任何事件推送，如何处理？ ​

• 问题描述：已创建事件订阅，但 Destination 未收到事件。
• 一句话答案：订阅状态、事件类型或目标网络存在问题。
• 根因说明：EventService 未使能、EventTypes 配置错误、Destination 不可达或事件未触发。
• 解决方案：检查 EventService 的 ServiceEnabled 状态，验证 Destination URL 可达性和订阅过滤条件。
• 规避方案：上线前使用测试事件验证订阅链路，并监控投递失败日志。
• 适用版本：1.140.4。

Q3：固件升级任务一直处于 Running 状态，如何处理？ ​

• 问题描述：提交固件升级后 Task 状态持续为 Running。
• 一句话答案：升级任务仍在执行，或任务因文件、目标组件和系统状态异常而阻塞。
• 根因说明：固件包问题、目标组件不兼容、设备未满足升级条件或升级过程异常。
• 解决方案：查询 Task 和 SubTask 状态，检查升级文件、目标和后端升级日志，必要时等待 BMC 重启完成。
• 规避方案：在维护窗口升级，升级前校验文件、目标资源和当前系统状态。
• 适用版本：1.140.4。

Q4：POST 请求返回 405 Method Not Allowed，如何处理？ ​

• 问题描述：尝试 POST 操作时返回 405 错误。
• 一句话答案：该资源没有注册 POST 操作或当前资源为只读。
• 根因说明：URI 对应的路由未注册 POST 方法，或资源不支持该操作。
• 解决方案：查阅 Redfish API 文档和路由配置，确认 URI 支持的操作方法。
• 规避方案：客户端在调用前检查资源的 Allow 响应头或接口定义。
• 适用版本：1.140.4。

Q5：如何确认 Redfish 服务运行状态？ ​

• 问题描述：需要确认 Redfish 接口服务是否正常运行。
• 一句话答案：检查服务监听日志、路由映射初始化日志和 HTTP 根资源响应。
• 根因说明：服务未启动、依赖资源缺失或监听端口异常会导致接口不可用。
• 解决方案：检查 Listen http port 和路由映射初始化日志，使用 GET /redfish/v1 验证服务响应。
• 规避方案：部署后增加服务存活检查和基础 Redfish 资源探测。
• 适用版本：1.140.4。

附录 ​

附录A 参考资料 ​

• DMTF Redfish 官方规范
• Redfish Schema Index
• openUBMC 官网

附录B 修订记录 ​