web_backend

版本信息

项目	内容
文档作者	openUBMC 社区维护者
最后更新	2026-09-03
许可证	Mulan PSL v2
组件类型	application

1. 组件概述

1.1 组件简介

web_backend 是 openUBMC 平台面向 WebUI 的 REST 后端服务。它以 Skynet 服务运行，入口为 src/service/main.lua，通过 HTTP 接收 /UI/Rest/** 请求，并借助 route mapper 处理请求信息，获取响应内容后返回。

1.2 解决什么问题

• 为 WebUI 提供统一 REST 入口，屏蔽底层微组件资源路径和 D-Bus 调用细节。
• 统一处理 Cookie/CSRF 会话鉴权、用户权限、系统锁定和请求体校验。
• 为密码等敏感字段提供 RSA 加密传输和服务端解密。
• 将异步资源任务转换为可轮询的 Web 任务 ID。
• 提供文件上传下载、配置导入导出和 WebService 配置能力。

1.3 核心功能

• 路由映射：从 WEBBACKEND_ROUTE_MAPPER_CFG_PATH 加载 JSON 映射或预编译 config.lua，支持 Lua 插件和脚本。
• 会话鉴权：GET 使用 SessionId Cookie；非 GET 请求还必须携带 x-csrf-token。
• 敏感字段解密：Encrypted-Properties 声明待解密字段，使用当前或次新 RSA 私钥解密；密钥每 7 天轮换。
• 异步任务管理：跟踪 bmc.kepler.TaskService.Task，最多登记 32 个任务，终态任务延迟 10 分钟回收。
• 文件与配置管理：固件上传、通用下载、配置导入/导出、NTP 密钥导入和文件权限校验。
• 可观测性：输出访问、启动和异常日志，并响应微组件调试日志级别和类型变更回调。

1.4 关键术语表

术语	解释
MDS/资源协作接口	openUBMC 的资源模型与 D-Bus 协作层。
SessionId	登录成功后建立的 GUI 会话标识，通过 Cookie 传递。
x-csrf-token	非 GET 请求使用的 CSRF 校验令牌。
TaskId	web_backend 本地任务槽位编号，用于 /UI/Rest/Task/:TaskId 查询任务。
Encrypted-Properties	声明请求体中需要 RSA 解密字段的 JSON 请求头。

1.5 外部交互边界图

flowchart LR
    A[WebUI / REST 客户端] -->|"HTTP<br>部署配置通常为 127.0.0.1:30081"| B[web_backend<br>Skynet，4 个工作线程]
    B -->|route_mapper| C[JSON 映射 / Lua 插件 / 脚本]
    B -->|鉴权上下文| D[Cookie + CSRF + 用户权限]
    B -->|运行时模块| E[RSA Crypter、Task Management、Config Management]
    B -->|D-Bus 会话总线 / MDS| F{依赖资源协作}
    F --> G[iam、account、certificate]
    F --> H[compute、bios、thermal_mgmt]
    F --> I[firmware_mgmt、bmc_upgrade、bmc_network]
    F --> J[其他 mds/service.json required 依赖]

2. API 使用说明与示例

2.1 REST API 路由

功能说明

REST 根路径为 /UI/Rest。覆盖 AccessMgnt、BMCSettings、System、Maintenance、Services、SSOHandler、KVMHandler、KerberosHandler 和 GeneralDownload 等路由；静态 controller 还提供固件上传、认证图片、任务查询和 NTP 密钥导入等接口。

返回值与异常

REST 错误响应使用 error 数组，元素包含 code 和 message（UnrecognizedRequestBody 除外）。

返回码	含义	触发条件	处理建议
InvalidSession	会话无效	缺少 Cookie/SessionId，或会话校验失败	重新登录并保存 SessionId。
NoValidSession	缺少 CSRF 凭据	非 GET 未携带 x-csrf-token	使用登录响应中的令牌。
InsufficientPrivilege	权限不足	用户不具备接口声明的 privilege	使用具备所需角色的账号。
InvalidPubKey	敏感字段解密失败	公钥已轮换或密文格式错误	重新获取公钥并加密。
UnrecognizedRequestBody	请求体不是 JSON 对象	PATCH/DELETE 或映射接口解析失败	检查 Content-Type 和 JSON 结构。
ResourceMissingAtURI	资源不存在	URI 或 TaskId 不存在	检查路径和任务是否已回收。
ActionNotSupported	方法不支持	URI 存在但未定义该方法	改用协议支持的方法。
TaskLimitExceeded	任务数量超限	同时登记任务达到 32 个	等待终态任务回收。
FileNotExist	文件不存在	下载文件缺失或无法打开	检查文件路径。
NoPrivilegeToOperateSpecifiedFile	文件权限不足	用户或文件属主权限不满足	检查用户权限和文件属主。
FirmwareUploadError	固件上传失败	后缀、大小、路径或移动校验失败	使用白名单文件并检查 /tmp/web。
MalformedJSON	导入 JSON 非法	缺少 ConfigData 或结构错误	修正配置 JSON。
PropertyValueFormatError	属性格式错误	操作日志含非 ASCII，或下载路径校验失败	使用可打印 ASCII 并检查路径。
SystemLockdownForbid	系统锁定禁止操作	锁定状态下调用受限接口	解除锁定或使用允许接口。

应用场景

WebUI 登录后，使用 Cookie 和 CSRF 令牌调用系统、账户、BMC 设置、维护、KVM 和固件接口；耗时操作返回 /UI/Rest/Task/id，客户端随后轮询任务状态。

限制条件

• portal agent 最多同时处理 4 个请求，超过部分排队。
• 全局最多登记 32 个异步任务；终态任务约 10 分钟后销毁。
• 生产监听地址由 dist/config.cfg 的 WEBBACKEND_PORTAL_LISTEN 配置；代码默认值为 0.0.0.0:8081。
• DELETE 是否可用由 AllowHttpDelete 属性控制，默认 true。

2.2 D-Bus 对象：PublicKey / GetPubKey

功能说明

提供当前 RSA 公钥。服务启动时生成密钥对，每 7 天刷新一次，并保留次新私钥以兼容客户端刷新延迟。

属性	内容
path	/bmc/kepler/Managers/:ManagerId/WebService/Encryption/PublicKey
interface	bmc.kepler.Managers.Encryption.PublicKey
method	GetPubKey

参数说明

无输入参数。返回当前公钥字符串；初始化尚未完成时可能为空。

应用场景

调用 GET /UI/Rest/AccessMgnt/Encryption 获取同一公钥，用于加密密码等敏感字段。

限制条件

公钥轮换周期为 7 天；收到 InvalidPubKey 时必须重新获取公钥。

2.5 任务查询 API：GET /UI/Rest/Task/:TaskId

功能说明

查询由 POST 路由创建的异步任务。响应包括 Name、state、start_time、prepare_progress、message_id、message_args 和归一化 ErrorCode。

参数说明

参数名	方向	类型	描述	取值范围
TaskId	输入	十进制整数	本地任务槽位编号。	1–32，且任务尚未回收。

返回值与异常

不存在、格式非法或已回收的任务返回 ResourceMissingAtURI。

3. 组件扩展案例

3.1 拓展能力概述

组件支持映射配置、Lua 插件/脚本和静态 controller 三类扩展。部署路径由 WEBBACKEND_ROUTE_MAPPER_CFG_PATH 与 WEBBACKEND_ROUTE_MAPPER_PLUGINS_PATH 指定；仓库测试示例位于 test/interface_config/mapping_config。

3.2 扩展点说明

扩展点	位置	触发时机
配置导入导出	src/lualib/micro_component/config_manage.lua	配置管理框架触发导入/导出时。
调试日志	src/lualib/micro_component/debug.lua	dlog_level_change 或 dlog_type_change 时。

4. 日志说明

4.1 一键日志收集

组件未实现自定义 on_dump 回调，只注册了调试日志级别/类型变更回调。因此一键日志收集按框架默认逻辑处理，仓库代码未定义额外的组件专属收集清单。

4.2 关键日志信息

日志片段	日志级别	含义解读	建议处理动作
start web_backend service successfully	NOTICE	portal agent、路由和微组件对象初始化完成。	缺失时检查依赖和启动配置。
Listen http port	INFO	HTTP socket 已监听。	核对监听配置和端口占用。
access begin(uri), pending_count=n	MASS	请求进入处理队列。	若并发频繁达到 n 说明请求积压，排查上游。
get reply falied, err=...	ERROR	controller 或 route mapper 处理异常。	结合 URI、请求体和 D-Bus 错误排查。
[config_mgmt] Import config is invalid	ERROR	导入内容缺少合法 ConfigData。	修正 JSON 结构。
get_object failed, path:..., interface:...	ERROR	底层任务对象不可访问。	检查 TaskService 和依赖组件。

5. 问题定界指南

5.1 典型问题定界

问题描述	是否为本组件问题	判断依据	关键证据收集方法
登录后返回 InvalidSession/NoValidSession	通常是	web_backend 负责 Cookie、SessionId 和 CSRF 校验；IAM 负责会话有效性。	抓取请求头、Cookie 和会话校验错误。
返回 InsufficientPrivilege	需分层判断	web_backend 和底层资源都可能执行权限检查。	检查用户权限与 D-Bus 错误。
返回 InvalidPubKey	是（加密层）	portal agent 解密敏感字段失败。	重新获取公钥并核对 Encrypted-Properties。
返回 ResourceMissingAtURI	可能是	URI 未加载或 TaskId 已回收。	检查映射目录、启动日志和任务 ID。
上传返回 FirmwareUploadError	是（文件校验层）	固件 controller 校验后缀、大小、路径和权限。	检查文件名、大小、/tmp/web、系统锁定和操作日志。
导入返回 MalformedJSON/InternalError	需分层判断	web_backend 校验 ConfigData，属性变更还涉及数据库。	查看 [config_mgmt] 和一键收集日志。

5.2 错误码速查表

错误码	含义	可能原因	排查建议
InvalidSession	会话无效	Cookie/SessionId 缺失或过期	重新登录并确认 Cookie。
NoValidSession	缺少 CSRF	非 GET 未发送 x-csrf-token	使用登录响应的 XCSRFToken。
InvalidPubKey	公钥不匹配	密钥轮换或密文错误	获取最新公钥后重试。
TaskLimitExceeded	任务槽位耗尽	同时登记 32 个任务	等待终态任务回收。
UnrecognizedRequestBody	JSON 对象解析失败	空体、数组或非法 JSON	检查请求体和 Content-Type。
FileNotExist	文件不存在	路径错误或文件已被移除	检查tmp目录下是否有该文件。
NoPrivilegeToOperateSpecifiedFile	文件权限不足	用户权限或属主不满足	检查 File 接口和文件属主。
MalformedJSON	配置 JSON 非法	缺少 ConfigData	按导入格式修正。

6. 常见问题解答

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

• 问题描述：登录接口成功，后续请求被拒绝。
• 一句话答案：SessionId Cookie 或非 GET 所需的 x-csrf-token 未正确传递，或会话已过期。
• 根因说明：GET 只校验 Cookie；非 GET 还校验 CSRF 令牌。
• 解决方案：保存 Set-Cookie 中的 SessionId，并在非 GET 请求头发送 x-csrf-token。

Q2：提交含密码请求返回 InvalidPubKey，如何处理？

• 问题描述：敏感字段请求被拒绝。
• 一句话答案：客户端公钥已过期或密文不匹配。
• 根因说明：服务每 7 天轮换密钥，并只保留一代次新私钥。
• 解决方案：GET /UI/Rest/AccessMgnt/Encryption 获取公钥，重新加密后重试。
• 规避方案：不要长期缓存公钥。

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

• 问题描述：创建异步任务失败，或旧任务无法查询。
• 一句话答案：任务槽位最多 32 个，终态任务约 10 分钟后回收。
• 根因说明：task_mgnt.lua 使用固定 32 槽位并每秒轮询任务。
• 解决方案：降低并发，等待任务进入 Completed、Killed 或 Exception 后重试。

Q4：新增 JSON 路由后没有生效，如何排查？

• 问题描述：返回 ResourceMissingAtURI 或 ActionNotSupported。
• 一句话答案：路由未加载、预编译配置覆盖源 JSON，或 URI/方法不匹配。
• 根因说明：存在 config.lua 时优先加载预编译映射，否则递归加载 JSON。
• 解决方案：核对 WEBBACKEND_ROUTE_MAPPER_CFG_PATH，重新生成并重启服务。