web_backend

Provide backend service hosting Web REST interfaces.

web_backend 是 openUBMC 平台的 Web REST 后端服务组件，为 WebUI 提供 REST API 接入能力。组件基于 openUBMC 微组件框架（skynet + D-Bus 资源协作接口 + MDS）构建，通过 route_mapper 将前端 /UI/Rest/** 请求映射为对资源协作接口属性、方法的读写调用。

• 许可证：Mulan PSL v2
• 组件类型：application

---

1. 组件概述

web_backend 在前端 REST 请求与底层资源协作接口接口之间提供统一接入层，核心功能：

1. 路由映射：按 route_mapper 映射配置（JSON）与脚本/插件（Lua），将 HTTP 请求转换为资源协作接口读写并组装响应。
2. 鉴权接入：基于 Cookie（SessionId）与 x-csrf-token 完成会话校验，初始化用户上下文（权限、用户名、IP、角色等）。
3. 敏感字段加密：对请求体中标记为敏感的字段（如密码）使用 RSA 公私钥加解密。
4. 任务管理：登记并跟踪底层异步任务，通过 /UI/Rest/Task/:TaskId 提供进度查询。
5. 操作日志与配置管理：操作日志落盘、配置导入/导出。

与外部系统的交互边界：WebUI 通过 HTTP 访问 web_backend，web_backend 通过 D-Bus 会话总线（busctl --user）访问 openUBMC 资源协作接口上的其它微组件（iam、account、compute、firmware_mgmt 等），自身也向资源协作接口注册对象（见 2.2 节）。

运行方式：进程入口 src/service/main.lua，以 skynet 服务 web_backend 注册；HTTP 监听地址由 WEBBACKEND_PORTAL_LISTEN 决定（默认 0.0.0.0:8081，发布配置 127.0.0.1:30081）；systemd 单元 web_backend.service。

---

2. API 使用说明和示例

2.1 REST API

REST 接口统一挂载在 /UI/Rest 下，部分接口由映射配置。在rackmount组件interface_config/web_backend/mapping_config/**/*.json 动态加载。

认证方式（Root.auth）：

• GET 请求：仅需 Cookie 携带 SessionId，通过 ValidateSession进行校验。
• 非 GET（POST/PATCH/DELETE）：需 Cookie 携带 SessionId 且请求头携带 x-csrf-token，通过 ValidateSessionWithCsrf进行校验。

鉴权成功后从 bmc.kepler.SessionService.Session 读取用户上下文（Privilege、UserName、ClientIp、RoleId、AccountId 等）。

可能抛出的异常及触发条件（错误码来自 webrest_utils.lua、webrest_root.lua、portal_agent.lua）：

错误码	触发条件
InvalidSession	缺少 Cookie、缺少 SessionId，或会话校验失败
NoValidSession	非 GET 请求未携带 x-csrf-token
ReauthFailed	二次认证用户名/密码错误或账户锁定
InsufficientPrivilege	权限不满足接口或文件操作要求
InvalidPubKey	敏感字段解密失败（公钥不匹配，前端需刷新公钥）
UnrecognizedRequestBody	请求体不是合法 JSON 对象
SystemLockdownForbid	系统锁定时接口不允许操作
ResourceMissingAtURI	URI 资源不存在，或任务 ID 无效
ActionNotSupported	URI 存在但请求方法不支持
TaskLimitExceeded	并发任务数超过 32
FileNotExist	下载/上传文件不存在
PropertyValueFormatError	属性值格式非法（如操作日志消息非 ASCII）
NoPrivilegeToOperateSpecifiedFile	无权限操作指定文件
FirmwareUploadError	固件上传失败（后缀/大小/路径校验不过）
SpecifiedFileExist	目标文件已存在
InvalidParam / InvalidField / PropertyMissing	请求参数非法 / 字段非法 / 必填缺失
KeyFileTypeNotSupported	NTP 组密钥文件类型不支持
MalformedJSON	导入配置 JSON 格式错误
InternalError	组件内部错误（DB 更新、导出失败等）

2.2 D-Bus 对象

web_backend 向资源协作接口注册 3 个对象（mds/model.json）：

对象	路径	接口	方法/属性	权限
PublicKey	/bmc/kepler/Managers/:ManagerId/WebService/Encryption/PublicKey	bmc.kepler.Managers.Encryption.PublicKey	方法 GetPubKey	ReadOnly
OperationLog	/bmc/kepler/LogRecorder/OperationLog	bmc.kepler.LogRecorder.OperationLog	方法 Add	ConfigureSelf
WebService	/bmc/kepler/Managers/:ManagerId/WebService	bmc.kepler.Managers.WebService	属性 AllowHttpDelete	读 ReadOnly / 写 BasicSetting

• GetPubKey：返回当前 RSA 公钥，供前端加密敏感字段（密钥每 7 天刷新）。
• Add：追加操作日志，消息须为可打印 ASCII，否则抛 PropertyValueFormatError。
• AllowHttpDelete：是否允许使用HTTP DELETE方法，默认 true，持久化到 t_webservice（Id=1）。

2.3 应用场景与限制条件

应用场景：WebUI 后端 REST 接入层；HTTP 请求映射到资源协作接口读写；敏感字段加密传输；异步任务统一跟踪。

限制条件：

• 并发请求上限 4（MAX_CONCURRENT_REQUEST_NUM），超出排队。
• 任务并发上限 32（MAX_TASK_RSC_NUM）。
• 依赖大量 bmc.kepler.* 接口（见 mds/service.json 的 required），需配套部署。
• RSA 密钥每 7 天刷新，前端解密失败（InvalidPubKey）时需重新拉取公钥。

2.4 调试示例

查看资源对象

busctl --user tree bmc.kepler.web_backend

查询/设置 AllowHttpDelete 属性

busctl --user get-property bmc.kepler.web_backend /bmc/kepler/Managers/1/WebService bmc.kepler.Managers.WebService AllowHttpDelete
busctl --user set-property bmc.kepler.web_backend /bmc/kepler/Managers/1/WebService bmc.kepler.Managers.WebService AllowHttpDelete b true

追加操作日志（OperationLog / Add）

busctl --user call bmc.kepler.web_backend /bmc/kepler/LogRecorder/OperationLog bmc.kepler.LogRecorder.OperationLog Add a{ss}s 3 Interface Busctl UserName Administrator ClientAddr 127.0.0.1 "debug operation log message"

REST 登录示例

curl -k -i -X POST https://<BMC_IP>/UI/Rest/Login \
  -H "Content-Type: application/json" \
  -d '{"UserName":"Administrator","Password":"<password>","Type":"Local","Domain":""}'

---

3. 问题定界指南

现象	归属	排查要点
401 InvalidSession / NoValidSession	web_backend（鉴权）	检查 Cookie 的 SessionId、非 GET 的 x-csrf-token
403 InsufficientPrivilege	web_backend 或底层组件	检查用户权限是否满足 user_privilege
403 InvalidPubKey	web_backend（加密层）	前端重新拉取公钥
400 UnrecognizedRequestBody	web_backend（解析）	请求体不是合法 JSON
404 ResourceMissingAtURI	web_backend（路由/任务）	检查 URI 或任务 ID
400 TaskLimitExceeded	web_backend（任务）	并发任务超 32，等待释放
文件下载 FileNotExist / NoPrivilegeToOperateSpecifiedFile	web_backend（文件）	检查路径与文件权限
操作日志 PropertyValueFormatError	web_backend（日志）	消息含非 ASCII 字符
导入配置 MalformedJSON / InternalError	web_backend（配置）	检查 JSON 结构，看 [config_mgmt] 日志

关键日志：前缀/关键字 web_backend、[config_mgmt]、access begin/end、start web_backend service successfully。错误码见 2.1 节。

调试/复现方法：

2. busctl --user tree bmc.kepler.web_backend 确认资源对象。
3. 用 2.5 节 busctl 命令绕过 HTTP 层，判断问题在 web_backend 还是底层组件。
4. curl -i 抓 HTTP 状态码与错误码字符串。
5. 动态日志调到 debug 级别后复现。

---

4. 日志说明

日志路径由 dist/config.cfg 定义：

配置项	值	说明
logger	/data/var/log/bmc/web_backend.log	组件运行日志
logpath	/data/var/log/bmc	日志目录
OPERATE_LOG_PATH	/var/log/operate_log	操作日志
RUN_LOG_PATH	/var/log/running_log	运行日志
SECURITY_LOG_PATH	/var/log/security_log	安全日志

一键日志收集：web_backend 源码注册了 Debug 接口的 dlog_level_change / dlog_type_change 回调，但未注册 on_dump，一键收集走框架默认逻辑，无组件自定义收集内容。

---

5. FAQ

Q1：登录成功后，其它接口仍然返回 InvalidSession，为什么？

答：这是会话校验没通过——web_backend 没在请求里拿到合法的 SessionId，或者会话已经过期了。

• 根因：web_backend 的鉴权规则是，GET 请求只认 Cookie 里的 SessionId；POST/PATCH/DELETE 请求除了 SessionId，还要求请求头里带 x-csrf-token。这两者缺了任何一个，都会返回 InvalidSession（缺 token 时是 NoValidSession）。
• 解决方案：登录接口返回的 SessionID 要写进 Cookie，XCSRFToken 要放进 x-csrf-token 请求头，两个一起用；如果会话过期了，就重新登录拿一套新的。

Q2：提交含密码请求返回 InvalidPubKey？

答：前端加密公钥已失效，需重新拉取。

• 根因：RSA 密钥每 7 天刷新，旧公钥密文无法被新私钥解密。
• 解决方案：重新调用 GET /UI/Rest/AccessMgnt/Encryption 获取最新公钥后重试。

Q3：返回 TaskLimitExceeded，任务查询不到？

答：并发任务数已达上限 32。

• 根因：最多同时跟踪 32 个任务，超出拒绝新任务。
• 解决方案：等待任务完成（终态任务 10 分钟后自动销毁释放槽位）。