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:
| 前缀 | 映射器类型 | 说明 |
|---|
/redfish | REDFISH | redfish 接口协议层 |
/UI/Rest | WEBREST | web-backend 接口协议层 |
/cli/v1 | CLI | cli 命令行接口协议层 |
/snmp/v1 | SNMP | snmp 接口协议层 |
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 |
| MatchStatus | CLI 命令探测的匹配状态: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 | 响应头 |
ActionRspBbody | Action 类型接口自定义响应体 |
PropAccessTree | 属性访问树,仅 redfish 事件订阅用户(资源扫描)支持 |
ListAccessInfo | List 信息,仅 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 | 输入 | object | D-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 扩展能力概述
组件支持三类扩展能力:
- 客户层级定制(
config_patch):按客户包名加载定制配置,对 Uri 层级与属性层级进行配置合并,支持全局变量批量字段替换(Oem 厂商名定制等)。 - Script/Plugin 二次开发:数据处理(
process)支持 Script(Lua 脚本)与 Plugin(编排插件)类型,可扩展数据处理逻辑。 - 可选能力开关:通过
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:%s | DEBUG | 接口访问开始 | 正常日志,无需处理 |
Interface access end, uri:%s, method:%s | DEBUG | 接口访问结束 | 正常日志,无需处理 |
processing_flow_%d foreach_%d timeout,[path=%s, interface=%s] | NOTICE | 单个 ProcessingFlow 访问资源树超时(>300ms) | 排查资源树侧响应是否变慢 |
uri:%s, method:%s timeout, t1=%d, t2=%d | NOTICE | 单个接口访问超时(>3000ms) | 排查资源访问链路耗时 |
Failed to load lua file content | ERROR | 加载 Lua 配置失败 | 检查配置文件是否存在及格式 |
Load %s success | INFO | 配置文件加载成功 | 正常日志,无需处理 |
Failed to load path %s, err=%s | ERROR | 路由加载失败 | 检查路由配置文件格式 |
whitelist file is oversize/invalid | ERROR | redfish 免鉴权白名单文件过大/非法 | 检查白名单文件大小与格式 |
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.0 | 2026-11-01 | openUBMC 社区 | 初始版本创建 |