本文档介绍HTTP协议接口（Web REST/Redfish）调试过程中遇到的常见问题定位方法，以及使用Postman工具进行接口测试的方法。

接口调试常见问题定位方法 ​

检查映射配置基本语法问题 ​

在进行HTTP接口调试前，建议先检查接口映射配置是否存在基本的语法问题。openUBMC提供了映射器配置检查工具，可以在开发阶段自动发现配置错误。

使用bingo build检查配置 ​

在rackmount项目下执行bingo build命令时，会自动运行映射器配置检查工具，为开发者检查映射配置的基本用法正确性。

# 进入rackmount项目目录
cd /path/to/rackmount

# 执行构建命令（会自动触发配置检查）
bingo build

配置检查内容 ​

映射器配置检查工具会验证以下内容：

注意：配置检查工具只能发现基本的语法和结构问题，无法发现运行时的逻辑错误。配置检查通过后，仍需要在实际环境中测试接口功能。

如何在实际环境中调试 ​

在调试接口之前，首先需要了解映射配置在环境中的执行顺序，这有助于快速定位问题发生的环节。

映射配置执行顺序 ​

映射配置按以下顺序执行：

1. ResourceExist校验Uri合法性

   • 校验请求的URI路径是否在映射配置中存在
   • 如果不存在，返回404错误

2. 校验ReqBody

   • 校验请求体是否符合映射配置中定义的格式
   • 如果格式不正确，返回400错误

3. 按映射配置顺序依次执行ProcessingFlow

   • 按照配置文件中ProcessingFlow的顺序依次执行
   • 每个ProcessingFlow中的Statements按顺序执行
   • 支持调用脚本或插件处理业务逻辑

4. 按RspBody的映射配置填充响应体

   • 根据RspBody配置从资源树获取数据填充响应体
   • PATCH接口特殊处理：PATCH接口的RspBody按对应GET接口的配置填充
   • 其他方法（GET/POST/PUT/DELETE）使用当前接口的RspBody配置

针对性调试方法 ​

调试时应按照上述执行顺序，在每个环节检查可能出现的问题：

调试ProcessingFlow/Statements中的值 ​

如果需要查看ProcessingFlow/Statements中的某个值是否正确，可以将该值配置到响应体中进行查看：

{
    "RspBody": {
        "debug_value": {
            "StatementsA": "${Statements/a()}",
            "ProcessingFlow1": "${ProcessingFlow[1]/Destination/List}"
        }
    }
}

发送请求后，从响应体中查看debug_value字段的值，确认ProcessingFlow/Statements是否正确执行。

调试插件中的值 ​

如果需要查看插件中某个变量的值，可以使用log函数将其打印到日志中：

local log = require 'mc.logging'
local cjson = require 'cjson'
-- 插件代码示例
function process(input) {
    local tmp_value
    ... -- your code

    -- 打印到日志
    -- 如果是lua table可以用cjson提供的encode函数转换成string快速打印
    -- 在日志等级后添加_easy可以防止日志限流导致日志未打印或打印不全
    log:error_easy('tmp_value=%s', cjson.encode(tmp_value)) 

    ...
}

然后在BMC端查看日志：

# 查看web_backend或redfish日志
tail -f /var/log/app.log | grep "tmp_value"

调试脚本中的值 ​

脚本中的值无法直接打印到日志，调试时可以采用以下方法：

1. 临时将脚本改为插件：将脚本代码复制到插件中，使用log打印调试
2. 调试完成后改回脚本：确认逻辑正确后，将插件改回脚本形式

示例步骤：

// 原脚本配置（无法打印日志）
"Type": "Script",
"Formula": "your_script.lua"

// 临时改为插件（可以打印日志），将脚本文件复制到插件目录下
"Type": "Plugin",
"Formula": "orchestrator.your_script.func(Input)"

在插件代码中添加log日志。调试完成后，将插件改回脚本配置，删除或注释掉log语句。

判断请求是否到达BMC ​

在进行HTTP接口调试之前，首先需要了解HTTP请求在BMC中的执行顺序，这有助于快速定位问题发生的环节。

HTTP请求在BMC中的执行顺序 ​

HTTP请求在BMC中的完整执行路径如下：

各环节出现问题排查方法 ​

怀疑请求在某环节丢失时，可以按照下面的方法进行排查定位：

检查网卡接收（tcpdump抓包） ​

使用tcpdump在网卡层面抓包，确认请求是否到达BMC网卡。

# 抓取HTTPS流量（默认端口443）
tcpdump -i any port 443 -n -A

# 抓取特定客户端的流量（以192.168.1.100为例）
tcpdump -i any host 192.168.1.100 -n

# 抓取HTTP流量（默认端口80）
tcpdump -i any port 80 -n -A

# 将抓包结果保存到文件，使用Wireshark分析
tcpdump -i any port 443 -w /tmp/capture.pcap

判断依据：

• 如果能抓到包：说明请求到达了网卡，继续下一步检查
• 如果抓不到包：说明网络层面有问题，检查网络连通性、防火墙等

第二步：检查iptables防火墙规则 ​

确认iptables规则是否允许HTTP/HTTPS对应端口的流量通过（以443端口为例）。

# 查看iptables规则
iptables -L -n -v

# 查看INPUT链规则（入站流量）
iptables -L INPUT -n -v --line-numbers

# 检查443端口是否开放
iptables -L INPUT -n -v | grep 443

# 检查是否有拒绝规则
iptables -L INPUT -n -v | grep DROP
iptables -L INPUT -n -v | grep REJECT

可以比较发送前后端口流量记录，用于判断请求是否到iptables。

判断依据：

• 如果有ACCEPT规则允许HTTP/HTTPS端口：说明防火墙配置正确
• 如果有DROP/REJECT规则：说明被防火墙拦截
• 如果没有相关规则：检查默认策略是否为ACCEPT

第三步：检查nginx日志 ​

nginx日志会记录所有到达nginx的请求，是判断请求是否到达nginx的关键依据。一般判断请求是否被nginx收到，查看access_log即可。

环境日志路径：

• access日志：/dev/shm/log/web/access_log
• error日志：/dev/shm/log/web/error_log一键收集日志路径：
• access日志：3rdDump/access_log
• error日志：3rdDump/error_log

# 实时查看access日志
tail -f /dev/shm/log/web/access_log

# 查看最近的请求记录
tail -n 50 /dev/shm/log/web/access_log

# 按条件筛选日志（查找特定IP或URI）
grep "192.168.1.100" /dev/shm/log/web/access_log
grep "/redfish/v1" /dev/shm/log/web/access_log

# 查看error日志
tail -n 100 /dev/shm/log/web/error_log

access日志格式说明：

$remote_addr - $remote_user [$time_iso8601] $msec $request_time "$request_method $uri $server_protocol" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$http_x_forwarded_for";

示例日志：

192.168.1.100 - - [2026-02-04T20:47:32+00:00] 1770238052.558 0.429 "GET /redfish/v1/Managers/1/LogServices/OperateLog/Entries HTTP/1.1" 200 12345 "-" "PostmanRuntime/7.32.1" "-"

从日志中可以获取：

• 客户端IP地址
• 请求时间
• 请求方法和URI
• 响应状态码
• 响应字节数
• User-Agent信息

判断依据：

• 如果access日志有记录：说明请求通过了nginx，继续检查后台组件
• 如果access日志无记录：说明请求没有到达nginx，检查nginx服务状态
• 如果error日志有错误：查看错误信息定位问题

第四步：检查后台组件日志 ​

后台组件（web_backend/redfish）负责实际的业务逻辑处理。

# 查看运行日志是否有异常
tail -f /var/log/app.log

判断依据：

• 如果日志正常：说明后台组件处理正常
• 如果有错误日志：根据错误信息定位问题

第五步：检查服务进程状态 ​

检查相关服务是否正常运行。

# 检查nginx进程状态
# 一般会有1个master进程，2个worker进程
ps -aux | grep nginx

# 检查后台组件所属进程状态
ps -aux | grep interface

# 检查nginx端口监听状态
netstat -tlnp | grep -E "80|443"

排查流程总结 ​

根据上述检查结果，可以快速定位问题：

Postman工具使用指南 ​

Postman是一款功能强大的API测试工具，支持HTTP协议的各种请求方法，非常适合用于Web REST和Redfish接口的调试测试。

安装Postman ​

Postman提供多平台支持：

• 桌面版：从官网https://www.Postman.com/downloads/下载安装
• 浏览器插件版：支持Chrome浏览器

Postman基本界面介绍 ​

Postman主界面包含以下主要部分：

1. 请求方法选择：GET、POST、DELETE、PATCH等
2. URL输入框：输入请求的完整URL
3. Authorization标签页：配置认证信息
4. Headers标签页：配置请求头
5. Body标签页：配置请求体
6. 响应区域：查看服务器返回的响应
7. 代码片段图标（</>）：点击可生成各种编程语言的请求代码（如cURL、JavaScript、Python等），方便将请求集成到代码中
8. Cookies标签页：管理请求相关的Cookie，可以查看、添加或编辑Cookie，Postman会自动保存和管理服务端返回的Cookie信息

Web REST接口测试 ​

Login登录 ​

Web REST接口使用X-CSRF-Token进行认证，首先需要调用登录接口获取Token。

登录接口信息：

• URL：https://<BMC_IP>/UI/Rest/Login
• 方法：POST
• Content-Type：application/json

请求示例：

1. 在Postman中创建新请求，设置以下参数：

   • Method: POST
   • URL: http://192.168.1.100/UI/Rest/Login

2. 设置请求头（Headers）：

   txt

   Content-Type: application/json

3. 设置请求体（Body），选择raw或JSON格式：

   json

   {
       "Username": "admin",
       "Password": "admin123",
       "Type": "Local",
       "Domain": "AutomaticMatching"
   }

4. 发送请求，成功返回示例：

   json

   {
       "Session": {
           "SessionID": "987654321aaa",
           "UserID": "2",
           "LoginTime": "2026-02-03T18:00:00+00:00",
           "UserName": "Administrator",
           "IP": "12.34.56.78",
           "Role": [
               "Administrator"
           ]
       },
       "DaysBeforeExpiration": 4294967295,
       "InsecurePromptEnabled": "Off",
       "LastLoginTime": "2026-02-03T17:55:00+00:00",
       "LastLoginIP": "12.34.56.78",
       "XCSRFToken": "abcdef1234567890abcdef1234567890"
   }

5. 保存返回的XCSRFToken，后续请求需要使用。

使用X-CSRF-Token访问接口 ​

获取Token后，在后续的Web REST请求中需要携带Token进行认证。

配置方式：在Headers中添加Token

在Headers标签页添加：

X-CSRF-Token: abcdef1234567890abcdef1234567890

请求示例：

GET https://192.168.1.100/UI/Rest/Services/PortConfig
Headers:
    X-CSRF-Token: abcdef1234567890abcdef1234567890

Token过期处理 ​

Web REST的Token有时效性（可以登录web页面在服务管理-Web服务查看/修改超时时长），当Token过期时，接口会返回401状态码。此时需要重新调用Login接口获取新Token。

Cookie会话管理 ​

openUBMC的Web REST接口实际采用Cookie/SessionId+Token共同认证的方式。当调用Login登录后，服务端会将响应头Set-Cookie字段的值置为当前激活会话的信息，服务端可以在响应体Cookies字段获取这些信息，特别是SessionId字段。获取Cookies各字段的值后，在后续的Web Rest请求中需要在请求头中携带Cookie: SessionId=xxx进行认证。

Token和Cookie是关联的，Token进行API鉴权，Cookie维持会话状态；Token告诉服务器“这个请求有API访问权限”，而Cookie告诉服务器“这个用户会话有效”。

那为什么使用Postman时我们不需要显式传入Cookie呢？

发送Login登录成功后，点击Postman页面的Cookies按钮，可以查看Postman维护的向各个环境发送请求的Cookies信息，查看这个页面刚才登录成功的环境的Cookies信息，可以发现保存的信息中SessionId的值与Login登录成功后返回的Cookies信息相同。每次向服务端发送登录请求成功，Postman会保存服务端IP-会话信息，并在你后续访问中自动携带，因此不需要用户手动显式传入。

Redfish接口测试 ​

Redfish接口支持两种认证方式：Basic Auth（用户密码认证）和Session认证。

方法1：Basic Auth认证 ​

Basic Auth是最简单的认证方式，每次请求都携带用户名和密码。

配置方式：

1. 在Postman中创建新请求

2. 进入Authorization标签页，配置如下：

   • Type: Basic Auth
   • Username: 输入BMC用户名（如admin）
   • Password: 输入密码

3. Postman会自动在请求头中添加Authorization字段

请求示例：

GET https://192.168.1.100/redfish/v1/Managers
Authorization: Basic YWRtaW46YWRtaW4xMjM=

注意事项：

• Basic Auth会将用户名密码进行Base64编码传输，非加密
• 建议在HTTPS环境下使用
• 适合简单的接口测试场景

方法2：Session认证 ​

Session认证更安全，通过创建会话获取Token，后续请求使用该Token。

Step 1：创建Session ​

创建Session接口信息：

• URL：https://<BMC_IP>/redfish/v1/SessionService/Sessions
• 方法：POST
• Content-Type：application/json

请求配置：

1. 使用Basic Auth方式（参考上面方法1）

2. 设置请求头：

   txt

   Content-Type: application/json

3. 设置请求体：

   json

   {
       "UserName": "admin",
       "Password": "admin123"
   }

4. 发送请求，成功返回示例（状态码201）：

   json

   {
       "@odata.context": "/redfish/v1/$metadata#Session.Session",
       "@odata.id": "/redfish/v1/SessionService/Sessions/123456789aaa",
       "@odata.type": "#Session.v1_7_2.Session",
       "Id": "123456789aaa",
       "Name": "User Session",
       "ClientOriginIPAddress": "12.34.56.78",
       "CreatedTime": "2026-02-03T18:00:00+00:00",
       "Roles": [
           "Administrator"
       ],
       "SessionType": "Redfish",
       "OemSessionType": "Redfish",
       "Oem": {
           "openUBMC": {
               "UserAccount": "Administrator",
               "LoginTime": "2026-02-03T18:00:00+00:00",
               "UserIP": "12.34.56.78",
               "UserTag": "Redfish",
               "MySession": true,
               "UserId": 2,
               "UserValidDays": null,
               "AccountInsecurePromptEnabled": false,
               "UserRole": [
                   "Administrator"
               ]
           }
       }
   }

5. 从响应头Headers中获取Token：

   • 响应头字段：X-Auth-Token

Step 2：使用Session Token访问接口 ​

获取Session Token后，在后续请求中使用。

配置方式：

在Headers标签页添加：

X-Auth-Token: <你的Session Token值>

请求示例：

GET https://192.168.1.100/redfish/v1/Systems/1
Headers:
    X-Auth-Token: <Session_Token>

Step 3：删除Session ​

测试完成后，建议删除Session释放资源。

删除Session接口：

• URL：https://<BMC_IP><Session_URI>（从创建Session的响应体@odata.id中获取）
• 方法：DELETE
• Headers: 携带X-Auth-Token

Postman环境变量使用 ​

为了简化Token管理，可以使用Postman的环境变量功能。

1. 创建环境变量

   • 点击右上角眼睛图标
   • 点击"Add"创建新环境
   • 添加变量：bmc_ip、username、password、redfish_token

2. 在请求中使用变量

URL: https://{{bmc_ip}}/redfish/v1/Systems/1

Postman高级调试技巧 ​

查看响应状态码 ​

Postman响应区域顶部显示状态码，常用状态码：

查看响应时间 ​

Postman显示请求的响应时间（在状态码旁边），可以用于性能分析：

• 正常请求：通常在几百毫秒内
• 超过1秒：可能存在性能问题
• 超过30秒：可能触发超时

使用Collection组织请求 ​

将相关请求组织到Collection中：

1. 点击左侧Collections
2. 创建新Collection（如"BMC Web REST"、"BMC Redfish"）
3. 将请求添加到Collection中
4. 可以设置Collection级别的变量和认证

使用Console控制台查看完整请求和响应 ​

Postman Console控制台是一个强大的调试工具，可以查看请求和响应的完整详细信息，包括所有请求头、响应头、请求体、响应体等。

打开Console控制台 ​

有两种方式打开Console控制台：

1. 点击左下角的Console图标（类似终端的图标）
2. 使用快捷键 Ctrl + Alt + C（Windows/Linux）或 Cmd + Option + C（Mac）

Console控制台的主要功能 ​

Console控制台会记录所有请求的详细信息，包括：

使用场景 ​

场景1：查看自动添加的请求头

Postman会自动添加某些请求头（如User-Agent、Content-Length等），这些在主界面可能不显示。Console可以看到所有实际发送的请求头。

示例Console输出：
Request Headers:
    User-Agent: PostmanRuntime/7.32.1
    Accept: */*
    Cache-Control: no-cache
    Postman-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    Host: 192.168.1.100
    Accept-Encoding: gzip, deflate, br
    Connection: keep-alive

场景2：查看完整的响应头

某些调试信息（如会话Token、CORS相关）在响应头中，Console可以完整显示。

示例Console输出：
Response Headers:
    HTTP/1.1 201 Created
    Server: nginx/1.18.0
    Date: Tue, 03 Feb 2026 10:30:15 GMT
    Content-Type: application/json
    Content-Length: 1234
    Connection: keep-alive
    X-Auth-Token: abcdef1234567890abcdef1234567890
    Set-Cookie: SessionId=987654321aaa; Path=/; HttpOnly

场景3：调试请求失败原因

当请求失败时，Console会显示详细的错误信息，帮助定位问题。

示例Console输出（连接失败）：
Error: connect ETIMEDOUT
    at Object._errnoException (util.js:1024:11)
    at _exceptionWithHostPort (util.js:1046:20)
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1182:14)

场景4：性能分析

Timeline视图显示请求各阶段的时间消耗：

• DNS Lookup：DNS解析时间
• Connecting：建立TCP连接时间
• TLS Handshake：TLS握手时间（HTTPS）
• Sending：发送请求数据时间
• Waiting：服务器处理时间
• Receiving：接收响应数据时间

Console与主界面的区别 ​

调试技巧 ​

1. 开启日志记录：在发送请求前打开Console，确保能捕获完整的请求信息

2. 使用过滤功能：Console支持按关键词过滤日志，快速找到相关信息

3. 查看原始请求：Console可以查看实际发送的原始请求，与预期进行对比

4. 分析性能瓶颈：通过Timeline视图分析请求慢的原因（是网络慢还是服务器处理慢）

注意事项 ​

1. HTTPS证书问题：如果BMC使用自签名证书，Postman会提示证书错误，可以在Settings中关闭SSL证书验证（仅供测试环境使用）

2. Token过期：注意Token的有效期，过期后需要重新获取

3. 并发请求限制：BMC对并发请求数量有限制（当前最多支持4路并发），避免同时发送过多请求导致请求等待时间过长。nginx读取数据超过15分钟连接会超时，断开连接并返回502错误码。

4. 接口版本：注意Redfish接口的版本，不同版本的接口可能存在差异

5. 权限要求：某些操作需要特定权限，确保使用的账户具有相应权限

6. 日志记录：调试时注意查看BMC端日志，结合Postman响应进行问题定位

7. 请求超时设置：在Postman Settings中可以设置请求超时时间，默认为0（无限制）