web_backend
版本信息
| 项目 | 内容 |
|---|---|
| 组件版本 | 1.130.16 |
| 首发版本 | 1.120.9 |
| 文档作者 | openUBMC 社区 |
| 最后更新 | 2026-09-13 |
| 许可证 | 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 外部交互边界图
2. API 使用说明与示例
2.1 REST API 路由
功能说明
REST 根路径为 /UI/Rest。覆盖 AccessMgnt、BMCSettings、System、Maintenance、Services、SSOHandler、KVMHandler、KerberosHandler 和 GeneralDownload 等路由；静态 controller 还提供固件上传、认证图片、任务查询和 NTP 密钥导入等接口。
参数说明
请求参数由路由映射中的 URI、HTTP 方法、请求头、查询参数和 JSON 请求体定义。非 GET 请求还要求携带有效的 SessionId Cookie 和 x-csrf-token。
返回值与异常
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。
调试示例
bash
curl -i -c cookie.txt -H 'Content-Type: application/json' \
-d '{"UserName":"<user>","Password":"<encrypted-password>"}' \
http://<bmc_ip>:8081/UI/Rest/AccessMgnt/Session2.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 时必须重新获取公钥。
调试示例
bash
curl -i -b cookie.txt http://<bmc_ip>:8081/UI/Rest/AccessMgnt/Encryption2.3 任务查询 API：GET /UI/Rest/Task/:TaskId
功能说明
查询由 POST 路由创建的异步任务。响应包括 Name、state、start_time、prepare_progress、message_id、message_args 和归一化 ErrorCode。
参数说明
| 参数名 | 方向 | 类型 | 描述 | 取值范围 |
|---|---|---|---|---|
| TaskId | 输入 | 十进制整数 | 本地任务槽位编号。 | 1–32，且任务尚未回收。 |
返回值与异常
不存在、格式非法或已回收的任务返回 ResourceMissingAtURI。
应用场景
客户端创建耗时任务后，通过任务 ID 轮询执行状态和进度。
限制条件
TaskId 取值范围为 1～32，且任务必须尚未回收。
调试示例
bash
curl -i -b cookie.txt http://<bmc_ip>:8081/UI/Rest/Task/13. 组件扩展案例
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 | 按导入格式修正。 |
5.3 最小化复现与证据收集
- 记录完整 URL、HTTP 方法、请求头、Cookie、CSRF 令牌、请求体和响应。
- 对非 GET 请求先确认 SessionId 和
x-csrf-token，再检查路由映射及后端 D-Bus 错误。 - 保存 web_backend 日志、对应 controller 日志和
/UI/Rest/Task/:TaskId状态。 - 敏感字段问题使用最新公钥重新加密后复现，检查
Encrypted-Properties。
5.4 调试方法
- 使用
curl按真实请求顺序登录并调用接口，保留响应头和响应体。 - 检查
WEBBACKEND_ROUTE_MAPPER_CFG_PATH和预编译config.lua是否覆盖源 JSON 路由。 - 对文件上传、导入导出和任务问题同时检查
/tmp/web、TaskService 和依赖组件日志。
6. 常见问题解答
Q1：登录成功后，其他接口仍返回 InvalidSession，为什么？
- 问题描述：登录接口成功，后续请求被拒绝。
- 一句话答案：SessionId Cookie 或非 GET 所需的 x-csrf-token 未正确传递，或会话已过期。
- 根因说明：GET 只校验 Cookie；非 GET 还校验 CSRF 令牌。
- 解决方案：保存 Set-Cookie 中的 SessionId，并在非 GET 请求头发送 x-csrf-token。
- 规避方案：接口请求统一携带 Cookie，并对请求头完整性做自动化检查。
- 适用版本：1.130.14。
Q2：提交含密码请求返回 InvalidPubKey，如何处理？
- 问题描述：敏感字段请求被拒绝。
- 一句话答案：客户端公钥已过期或密文不匹配。
- 根因说明：服务每 7 天轮换密钥，并只保留一代次新私钥。
- 解决方案：GET /UI/Rest/AccessMgnt/Encryption 获取公钥，重新加密后重试。
- 规避方案：不要长期缓存公钥。
- 适用版本：1.130.14。
Q3：返回 TaskLimitExceeded，任务查询不到怎么办？
- 问题描述：创建异步任务失败，或旧任务无法查询。
- 一句话答案：任务槽位最多 32 个，终态任务约 10 分钟后回收。
- 根因说明：task_mgnt.lua 使用固定 32 槽位并每秒轮询任务。
- 解决方案：降低并发，等待任务进入 Completed、Killed 或 Exception 后重试。
- 规避方案：客户端限制未完成任务数量并轮询终态后释放任务。
- 适用版本：1.130.14。
Q4：新增 JSON 路由后没有生效，如何排查？
- 问题描述：返回 ResourceMissingAtURI 或 ActionNotSupported。
- 一句话答案：路由未加载、预编译配置覆盖源 JSON，或 URI/方法不匹配。
- 根因说明：存在 config.lua 时优先加载预编译映射，否则递归加载 JSON。
- 解决方案：核对 WEBBACKEND_ROUTE_MAPPER_CFG_PATH，重新生成并重启服务。
- 规避方案：路由变更后先检查预编译配置是否被优先加载。
- 适用版本：1.130.14。