代码仓
中
更新时间: 2026/11/16
在AtomGit上查看源码

libroute_mapper4lua ​

openUBMC 北向接口数据映射器组件(route_mapper)。

1. 组件概述 ​

1.1 组件简介 ​

libroute_mapper4lua(route_mapper)是 openUBMC 北向接口(redfish、web-backend、cli、snmp)的数据映射机制核心组件。组件位于接口协议层与资源树(mdb,基于 D-Bus 的资源树)之间:框架解析数据映射配置,将接口请求转发到资源树,拼装返回对应格式的数据。

组件基于 Lua + C 混合实现,运行于 skynet 服务框架之上,依赖 libmc4lua、liblogger、securec 等公共库。映射器类型(MapperType)由路由前缀区分,见 src/route_mapper/common.lua:

前缀映射器类型说明
/redfishREDFISHredfish 接口协议层
/UI/RestWEBRESTweb-backend 接口协议层
/cli/v1CLIcli 命令行接口协议层
/snmp/v1SNMPsnmp 接口协议层

1.2 解决什么问题 ​

各北向协议层(redfish、web-backend、cli、snmp)访问底层资源时,若各自实现资源访问逻辑,会导致重复开发且行为不一致。libroute_mapper4lua 提供统一的数据映射能力,解决以下核心问题:

  • 接口请求与资源树解耦:接口层只需调用映射器提供的统一接口,无需感知资源树结构、鉴权方式与数据拼装细节。
  • 数据拼装所见即所得:通过 RspBody/ReqBody 配置声明响应/请求体结构,响应体顺序与配置保持一致。
  • 数据校验与处理归一:内置枚举、范围、正则等校验项以及类型转换、前缀/后缀、Script/Plugin 等数据处理机制,各协议层共用一套规则。
  • 客户定制能力:支持客户层级定制(config_patch)与全局变量批量字段替换(Oem 厂商名定制等)。

1.3 核心功能 ​

  • 核心功能一:接口路由匹配与访问(match)。按 uri + method 匹配映射配置,执行鉴权、Uri 校验、请求体校验、资源树访问、数据拼装,返回错误列表、响应体与拓展信息。
  • 核心功能二:CLI 命令探测(probe)。支持 CLI 前缀缩写贪心匹配、命令补全、Y/N 确认、密码鉴权提示、-v/-t/-d/-l 命令字解析与提示信息返回。
  • 核心功能三:worker 独立服务封装(process)。将资源访问封装到 skynet 独立服务(worker_service)中,供 redfish、web_backend 等协议层跨服务调用,并通过 load 支持运行时动态加载配置。
  • 核心功能四:资源树访问封装(ProcessingFlow)。支持 Property/Method/List/Task/Paging 五种资源访问类型,统一封装 mdb 自省、批量获取、分页、任务等访问逻辑。
  • 核心功能五:数据校验与处理。内置 enum/range/regex/length/nonempty/ip_format/privilege/script/system_lockdown 校验项,以及 convert/count/date_format/expand/lpair/option/plugin/prefix_add/prefix_trim/script/suffix_add/suffix_trim/switch 数据处理项。
  • 核心功能六:定制与扩展。支持客户层级配置定制(config_patch)、全局变量批量字段替换、Script/Plugin 二次开发扩展、redfish 接口 IP 白名单免鉴权(可选能力)。

1.4 关键术语表 ​

术语解释
映射器(Mapper)本组件对数据映射机制的统称,对应 route_mapper.route_mapper 主类
ProcessingFlow映射配置中资源树访问步骤的数组,每个元素为一次资源访问(Property/Method/List/Task/Paging)
MdbMapper资源树访问封装基类,对应 mdb_mapper 目录
UriMethod接口访问方法封装(Get/Post/Patch/Delete),对应 method 目录
数据引用(DataReference)${xxx} 形式的引用机制,用于在配置中引用请求体、响应体、上下文、Statements 等数据
Statements映射配置中的前置/后置数据处理步骤,包含 Input 与 Steps
DataValidate请求体/响应体数据校验机制,基于 JSON Schema
MatchStatusCLI 命令探测的匹配状态:0=匹配(MATCHED)、1=路由匹配但值未匹配(V_MATCHED)、2=未匹配(UN_MATCHED)
worker_service资源访问的 skynet 独立服务,协议层跨服务调用资源访问的中间层
资源树(mdb)openUBMC 底层基于 D-Bus 的对象模型,是映射器访问的目标数据源

1.5 外部交互边界图 ​

  • control(单例)通过 skynet.newservice('route_mapper/worker_service/main') 创建独立的 worker_service skynet 服务,并通过 skynet.call(worker, 'lua', 'init'/'process', ...) 进行跨服务调用。
  • worker_service 内部通过 skynet.dispatch('lua', ...) 分发命令,worker.init 创建 RouteMapper 实例,worker.process 调用 route_mapper:match 完成路由匹配与资源访问。
  • 组件对外仅通过 Lua 模块接口(match/probe/process/interface)提供服务,不直接对外暴露 D-Bus 接口。
  • 组件通过 sd_bus(mc.mdb.mdb_service)访问资源树,通过 mc/mdb 公共库完成 D-Bus 通信。
  • 可选能力 redfish_noauth_supported(mds/service.json 选项,默认 false)开启时,根据 IP 白名单实现 redfish 接口免鉴权。
  • C 公共库 libroutemapper_utils(src/lualib-src/libroute_mapper_uilts.c)为 Lua 层提供无回显输入、超时输入、构建类型判断、LDAP 用户角色、ETag、时间戳等能力。

2. API 使用说明与示例 ​

2.1 match ​

功能说明 ​

match 是映射器提供的主要接口,接口协议层调用此接口,将接口请求转发到资源树并拼装返回对应格式的数据。

属性内容
接口名route_mapper.route_mapper:match
废弃状态正常可用
替代接口无

参数说明 ​

参数名方向类型描述取值范围
uri输入string请求的 uri 路径,如 /redfish/v1/Systems/1映射配置中已注册的 uri
method输入string请求方法get/patch/post/delete(大小写不敏感)
params输入table更多参数信息,见下表详见下
errs输出table错误 Message 列表空表表示成功;元素为错误消息对象
rsp_body输出table/userdata响应体(JsonObject)随映射配置 RspBody 而定
extra_info输出table拓展信息,见下表详见下

params 格式:

shell
{
    "header": {},       ->      请求头
    "body": {},         ->      请求体
    "query": {},        ->      查询参数
    "user": {},         ->      用户信息
    "is_auth": true/false  ->   是否需要鉴权(默认值为 false)
    "select": {},       ->      指定获取的属性(Telemetry 采集指定属性)
}

返回值与异常 ​

返回值含义触发条件处理建议
errs 为空成功路由匹配且资源访问成功无
errs 含 ResourceMissingAtURI路由未匹配uri/method 在映射配置中不存在检查 uri 与 method 是否正确
抛错(error)参数非法未初始化 bus,或 method 非法检查映射器是否完成初始化、method 是否为 get/patch/post/delete

应用场景 ​

  • redfish、web_backend 协议层处理接口请求时调用 match,获取错误列表、响应体与拓展信息后拼装为对应协议格式。
  • Telemetry 服务采集数据时通过 select 指定采集属性,映射器仅访问关联的 ProcessingFlow(src/route_mapper/query/select.lua)。
  • worker_service 的 process 亦是对 match 的二次封装(见 2.2)。

限制条件 ​

  • 调用前映射器必须完成初始化(init),且 bus 非空。
  • match 返回的错误/响应体为 cjson JsonObject(userdata),接口层可通过 cjson.encode 序列化。
  • 事件订阅用户(UserName = 'redfish_user' 且 Interface = 'Redfish')访问时,extra_info 额外携带 PropAccessTree、ListAccessInfo(见下)。

extra_info 字段:

字段说明
Echoes回显模板配置,仅 cli 涉及
TaskInfo任务接口额外携带的字段(含 SubTaskIds)
RspHeader响应头
ActionRspBbodyAction 类型接口自定义响应体
PropAccessTree属性访问树,仅 redfish 事件订阅用户(资源扫描)支持
ListAccessInfoList 信息,仅 redfish 事件订阅用户(资源扫描)支持
AutoPagingEnabled集合资源是否默认分页,仅配置了 AutoPagingEnabled 时返回

2.2 process ​

功能说明 ​

process 是 match 的二次封装,位于 src/route_mapper/worker_service/control.lua,用于 skynet 服务组件(当前是 redfish 和 web_backend)的接口访问。协议层在独立服务中做资源访问,实现资源访问与协议层解耦。

属性内容
接口名route_mapper.worker_service.control:process
废弃状态正常可用
替代接口无

参数说明 ​

参数名方向类型描述取值范围
uri输入string请求的 uri 路径映射配置中已注册的 uri
method输入string请求方法get/patch/post/delete
params输入table与 match 的 params 一致同 match
ret[1]输出table错误列表空表表示成功
ret[2]输出table响应体(rsp_body)随映射配置而定
ret[3]输出table拓展信息(extra_info)同 match 的 extra_info

返回值与异常 ​

返回值含义触发条件处理建议
ret[1] 为空成功正常执行完成无
ret[1] 非空失败资源访问失败或校验失败按错误 Message 排查
抛错 MalformedJSON请求体非法Actions 接口请求体为 null检查请求体是否为合法 JSON

应用场景 ​

  • redfish、web_backend 等 skynet 服务组件通过 process 跨服务调用资源访问。
  • worker 服务(src/route_mapper/worker_service/worker.lua)的 process 实际调用 route_mapper:match,支持 JsonObject 裸指针传递与 ActionRspBbody 返回。

限制条件 ​

  • 需在 skynet 服务框架中运行(依赖 skynet.newservice / skynet.call)。

2.3 probe ​

功能说明 ​

probe 用于 CLI 的命令探测,仅适用于 CLI 映射器(映射器类型为 /cli/v1)。支持前缀缩写贪心匹配(greed_match)、命令补全、-t/-d/-l 命令字解析以及 -v 参数提示。

属性内容
接口名route_mapper.route_mapper:probe
废弃状态正常可用
替代接口无

参数说明 ​

参数名方向类型描述取值范围
bus输入objectD-Bus 连接对象已初始化的 bus
uri输入string待探测的 cli 命令 uri(可含前缀缩写)以 /cli/v1 开头的 uri
method输入string请求方法get/patch/post/delete
req_header输入table请求头(含 SystemId 等)可选
req_body输入table请求体(-v 后接参数列表)可选,默认 {}

返回值与异常 ​

probe 返回 ret_data,格式如下(MatchStatus 常量定义见 src/route_mapper/common.lua:MATCHED=0、V_MATCHED=1、UN_MATCHED=2):

json
{
    "MatchStatus": 0/1/2,
    "Details": {
        "Uri": "/cli/v1/fru0/powerstate",            // 补全后的命令
        "Mapper": {                                  // MatchStatus为0时此字段生效
            "Type": "Task/Paging/Ordinary",          // 映射类型,cli服务端根据此类型决定处理过程
            "Skip": 0,                               // Type为Paging时此字段生效
            "Top": 20,                               // Type为Paging时此字段生效
            "Path": "/bmc/kepler/UpgradeService"     // Type为Task时生效
        },
        "Confirm": {                                 // Y/N确认信息,MatchStatus为0时此字段生效
            "Condition": true/false,
            "Description": "This operation will reboot openUBMC system.\nContinue? [Y/N]:"
        },
        "Authentication": {                          // 密码鉴权校验,MatchStatus为0时此字段生效
            "Condition": true/false,
            "Description": "Password:"
        },
        "ReqErrs": [xxx],                            // -v后接参数检查结果,MatchStatus为0时此字段生效
        "ReqHeader": {                               // 配置了ReqHeader时此字段生效
            "SystemId": {"1", "2"}
        }
    },
    "Reminder": {                                    // MatchStatus为0/1时此区域段生效
        "Usage": "xxx",
        "Brief": "xxx",
        "Example": "xxx",
        "-v": [
            {
                "Command": "destination",
                "Description": "The destination index that will be set. The values can be 1, 2, 3 or 4."
            }
        ]
    }
}
返回值含义触发条件处理建议
MatchStatus=0(MATCHED)匹配路由匹配且值匹配正常执行命令
MatchStatus=1(V_MATCHED)路由匹配但值未匹配请求头/参数个数与配置不符按 Reminder 中 -v 提示补全参数
MatchStatus=2(UN_MATCHED)未匹配路由未匹配或为前缀缩写按 Reminder 中 -t/-d 提示补全命令
抛错(error)非 CLI 映射器映射器类型不是 /cli/v1仅 CLI 映射器可调用 probe

MatchStatus=2 时 Reminder 返回 -t/-d 命令列表:

json
{
    "Reminder": {
        "-t": [
            {
                "Command": "fru0",
                "Description": "Get the information of the fru0"
            }
        ],
        "-d": []
    }
}

应用场景 ​

  • cli 协议层(命令行工具)输入命令时调用 probe,实现命令前缀补全、参数提示、Y/N 确认与密码鉴权交互。
  • 1.130.2 起支持 -l 命令字解析:-l 占 uri 第 3 位、-t 占第 4 位、-d 占第 5 位;CLI 侧通过 set_cli_l_supported(true) 开启(src/route_mapper/route_mapper.lua)。未开启时 -t 占第 3 位、-d 占第 4 位。

限制条件 ​

  • uri 或 method 为 nil 时会直接抛错。
  • 前缀缩写采用贪心匹配,非法模式串会通过 pcall 规避,不影响命令探测。

2.4 interface 模块接口 ​

功能说明 ​

interface.lua(src/route_mapper/interface.lua)封装给接口协议层呈现的通用接口。m 为普通表(非 class),协议层直接按函数名调用。当前已支持:

接口名说明
get_user_input(bus, prompt)获取用户标准输入(只取首字符),带 CLI 会话超时(默认 900 秒)
check_the_input_operation(bus, prompt)检查输出是否继续,y/Y 表示继续
check_valid_input(bus, prompt, valid_list)校验用户输入是否在合法输入列表中
get_config_path(bus, conf_path, manufacturer)获取 json 配置定制对象(带缓存)
clear_config_path_cache(conf_path)清除全量配置缓存
load_mapping(bus, conf_path, func, manufacturer)加载全量配置并执行定制处理
load_intf_mapping(bus, conf_path, manufacturer)加载映射表(最小化接口,带缓存)
load_data(bus, conf_path, suffix, manufacturer)加载指定后缀(mapper/route_tree 等)的 Lua 配置并执行全局变量替换
get_replace_relation(bus, prefix_path)获取映射配置中全局变量替换关系
read_and_replace_schema(path, replace_relation, file_type)读取文件并执行全局变量替换,json 类型返回有序 JsonObject

返回值与异常 ​

返回值含义触发条件处理建议
见各接口正常正常执行无
无返回值/nil失败配置加载失败检查配置路径与配置文件格式

应用场景 ​

  • 协议层初始化时通过 load_mapping/load_intf_mapping 加载映射配置。
  • CLI 交互通过 get_user_input/check_the_input_operation/check_valid_input 处理用户输入。
  • 厂商定制通过 get_replace_relation/read_and_replace_schema 处理全局变量替换。

限制条件 ​

  • load_data 仅支持 Lua 配置文件的加载(预编译文件或源码),加载前会执行全局变量替换。
  • get_config_path/load_intf_mapping 带缓存,全量配置变更后需调用 clear_config_path_cache 清除缓存。

2.5 C 公共库 libroutemapper_utils ​

功能说明 ​

C 公共库(src/lualib-src/libroute_mapper_uilts.c,构建产物 libroutemapper.utils)为 Lua 层提供以下能力:

函数名说明
get_line_without_echo(prompt)无回显获取输入(密码输入),限定长度 1024,非法字符报错
get_user_input(prompt, timeout)获取用户标准输入(首字符),支持超时(超时向父进程发 SIGTERM)
build_type_is_release()判断当前构建是否为 release
get_ldap_user_role(uid)通过 LDAP 用户 uid 获取角色
get_etag(cs_type, str)生成 ETag(取 hash 前 8 位,拼 W/"xxx" 格式)
get_time_of_day()获取当前时间戳(毫秒)

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

组件支持三类扩展能力:

  1. 客户层级定制(config_patch):按客户包名加载定制配置,对 Uri 层级与属性层级进行配置合并,支持全局变量批量字段替换(Oem 厂商名定制等)。
  2. Script/Plugin 二次开发:数据处理(process)支持 Script(Lua 脚本)与 Plugin(编排插件)类型,可扩展数据处理逻辑。
  3. 可选能力开关:通过 mds/service.json 的 redfish_noauth_supported 选项控制 redfish IP 白名单免鉴权模块(src/redfish_noauth)是否安装。

3.2 扩展点说明 ​

  • 配置定制(config_patch):映射配置路径(如 mapping_config)同层级的 customer/<客户名>/ 目录下存放定制配置。加载时由 src/route_mapper/config_patch/ 的 Uri 级(uri.lua)与属性级(property.lua)定制合并逻辑将定制配置合入平台配置。json 配置场景走 config_patch/json_config_patch/。
  • 数据处理扩展(process):映射配置中 ProcessingFlow/Statements 的 Type 可配置为 Script(引用 script 目录下的 Lua 脚本)或 Plugin(引用 plugins 目录下的编排插件),由 src/route_mapper/orchestrator/orchestrator.lua 加载。
  • redfish 免鉴权(redfish_noauth):redfish_noauth_supported=true 时安装 src/redfish_noauth/main.lua。白名单文件为 /opt/bmc/conf/redfish_noauth_whitelist.json,格式为 {"IPWhiteList": ["x.x.x.x", ...]},文件最大 16KB;命中白名单的 IP 访问 redfish 接口时免鉴权并授予全部权限。
  • 全局变量替换:映射配置读取时对 config.lua/mapper.lua/route_tree.lua 等文件内容执行全局变量替换(src/route_mapper/config_patch/global_variable.lua),用于 Oem 厂商名、Oid 等字段的批量替换。

4. 日志说明 ​

4.1 关键日志信息 ​

日志片段日志级别含义解读建议处理动作
Interface access begin, uri:%s, method:%sDEBUG接口访问开始正常日志,无需处理
Interface access end, uri:%s, method:%sDEBUG接口访问结束正常日志,无需处理
processing_flow_%d foreach_%d timeout,[path=%s, interface=%s]NOTICE单个 ProcessingFlow 访问资源树超时(>300ms)排查资源树侧响应是否变慢
uri:%s, method:%s timeout, t1=%d, t2=%dNOTICE单个接口访问超时(>3000ms)排查资源访问链路耗时
Failed to load lua file contentERROR加载 Lua 配置失败检查配置文件是否存在及格式
Load %s successINFO配置文件加载成功正常日志,无需处理
Failed to load path %s, err=%sERROR路由加载失败检查路由配置文件格式
whitelist file is oversize/invalidERRORredfish 免鉴权白名单文件过大/非法检查白名单文件大小与格式

5. 问题定界指南 ​

5.1 典型问题定界 ​

现象描述是否为本组件问题判断依据关键证据收集方法
北向接口返回 500不一定是可能是业务组件跑崩(映射器会封装为 InternalError),也可能是映射配置错误收集 /var/log/app.log,检查 processing_flow_%d foreach_%d 相关错误
路由未匹配,返回 ResourceMissingAtURI是映射配置中未注册该 uri/method检查映射配置 Resources/Interfaces 是否包含该路由
CLI 命令探测无提示是probe 返回 UN_MATCHED检查 -t/-d/-l 命令字配置与 cli_l_supported 设置
redfish 免鉴权不生效是白名单文件未加载或 IP 未命中检查 /opt/bmc/conf/redfish_noauth_whitelist.json 及日志 whitelist file is ...

5.2 错误码速查表 ​

错误消息通过 message.create_message 封装,MessageName 为错误标识。常见错误码如下:

错误码含义可能原因排查建议
ResourceMissingAtURI资源在 URI 处不存在路由未匹配或 Uri 校验失败检查 uri、method 与映射配置
ResourceNotFound资源不存在请求头 SystemId 指向的资源不存在检查 ReqHeader 中 SystemId
PropertyMissing缺少必填属性请求体缺少 Required=true 的属性按 -v 提示或接口文档补全参数
PropertyValueTypeError属性值类型错误属性值类型与配置不符检查属性值类型
PropertyValueOutOfRange属性值超出范围数字范围校验失败检查属性取值范围
StringValueTooShort / StringValueTooLong字符串长度过短/过长Length/Nonempty 校验失败检查字符串长度
PropertyItemDuplicate数组存在重复元素UniqueItems 校验失败检查数组元素是否重复
InsufficientPrivilege权限不足用户权限不满足接口 Privilege 配置检查用户权限
AuthorizationFailed鉴权失败web-backend 二次鉴权失败检查账号密码
PasswordChangeRequired首次登录需修改密码首次登录场景引导用户修改密码
QueryNotSupportedOnResource该资源不支持查询参数使用 $filter 但配置了 FilterForbidden去掉不支持的查询参数
InternalError内部错误业务组件访问异常收集 app.log 分析资源树访问失败原因
MalformedJSON请求体格式非法Actions 请求体为 null检查请求体是否为合法 JSON

6. 常见问题解答 ​

Q1:接口返回 ResourceMissingAtURI,如何处理? ​

  • 问题描述:调用接口返回 ResourceMissingAtURI 错误。
  • 一句话答案:映射配置中未注册该 uri/method,或 Uri 校验未通过。
  • 根因说明:match 在路由表(route:process)中未匹配到对应 uri+method 时返回该错误;若配置了 ResourceExist 且校验失败也会返回该错误。
  • 解决方案:检查映射配置 Resources 中是否包含该 uri 及对应 Interfaces 的 Type;检查 ResourceExist 校验条件。

Q2:接口返回 500(InternalError),如何处理? ​

  • 问题描述:接口返回 500 或 InternalError。
  • 一句话答案:多为资源树访问时业务组件抛错。
  • 根因说明:safe_call 捕获业务组件异常后,映射器封装为 InternalError 错误。
  • 解决方案:收集 /var/log/app.log,定位 processing_flow_%d foreach_%d 对应 ProcessingFlow 的资源访问路径与接口,排查资源树侧问题。

Q3:redfish 接口 IP 白名单免鉴权不生效? ​

  • 问题描述:配置了白名单但命中 IP 仍要求鉴权。
  • 一句话答案:组件未安装 redfish_noauth 模块或白名单文件格式不对。
  • 根因说明:免鉴权能力受 mds/service.json 选项 redfish_noauth_supported(默认 false)控制;且白名单文件 /opt/bmc/conf/redfish_noauth_whitelist.json 需满足 JSON 格式(IPWhiteList 数组)、IP 合法、文件不超过 16KB。
  • 解决方案:确认组件以 redfish_noauth_supported=true 构建安装;检查白名单文件格式与 IP 合法性;查看日志 whitelist file is oversize/invalid。

附录A 参考资料 ​

附录B 修订记录 ​

版本日期修订人修订内容
v1.02026-11-01openUBMC 社区初始版本创建