fix: 规范化 web_backend README-web

已开启

fix: 规范化 web_backend README #18

zjh8822创建于 9月13日从zjh8822/web_backend： codex/update-api-readme-20260913 合入到 openUBMC/web_backend： main

fix: 规范化 web_backend README #18

已开启

zjh8822创建于 9月13日

从zjh8822/web_backend codex/update-api-readme-20260913合入到openUBMC/web_backend main

共 3 个文件变更+94-4

MCHANGELOG.md+4-0

	@@ -1,6 +1,10 @@
1	# Changelog	1	# Changelog
2	All notable changes to this project will be documented in this file.	2	All notable changes to this project will be documented in this file.
3		3
		4	+## [1.130.16] - 2026-9-13
		H H HuangJiayi9月13日 CHANGELOG更新位置有误
		5	+### Fixed
		6	+- 规范化README文档结构，统一API、日志、问题定界和FAQ说明
		7	+
4	## [1.130.15] - 2026-9-10	8	## [1.130.15] - 2026-9-10
5	### Fixed	9	### Fixed
6	- 修复适配映射器json处理变更	10	- 修复适配映射器json处理变更

MREADME.md+89-3

	@@ -16,8 +16,10 @@ See the Mulan PSL v2 for more details.
16		16
17	\| 项目 \| 内容 \|	17	\| 项目 \| 内容 \|
18	\| :--- \| :--- \|	18	\| :--- \| :--- \|
19	-\| 文档作者 \| openUBMC 社区维护者 \|	19	+\| 组件版本 \| 1.130.16 \|
20	-\| 最后更新 \| 2026-09-03 \|	20	+\| 首发版本 \| 1.120.9 \|
		21	+\| 文档作者 \| openUBMC 社区 \|
		22	+\| 最后更新 \| 2026-09-13 \|
21	\| 许可证 \| Mulan PSL v2 \|	23	\| 许可证 \| Mulan PSL v2 \|
22	\| 组件类型 \| application \|	24	\| 组件类型 \| application \|
23		25
	@@ -77,6 +79,10 @@ flowchart LR
77		79
78	REST 根路径为 /UI/Rest。覆盖 AccessMgnt、BMCSettings、System、Maintenance、Services、SSOHandler、KVMHandler、KerberosHandler 和 GeneralDownload 等路由；静态 controller 还提供固件上传、认证图片、任务查询和 NTP 密钥导入等接口。	80	REST 根路径为 /UI/Rest。覆盖 AccessMgnt、BMCSettings、System、Maintenance、Services、SSOHandler、KVMHandler、KerberosHandler 和 GeneralDownload 等路由；静态 controller 还提供固件上传、认证图片、任务查询和 NTP 密钥导入等接口。
79		81
		82	+#### 参数说明
		83	+
		84	+请求参数由路由映射中的 URI、HTTP 方法、请求头、查询参数和 JSON 请求体定义。非 GET 请求还要求携带有效的 SessionId Cookie 和 `x-csrf-token`。
		85	+
80	#### 返回值与异常	86	#### 返回值与异常
81		87
82	REST 错误响应使用 error 数组，元素包含 code 和 message（UnrecognizedRequestBody 除外）。	88	REST 错误响应使用 error 数组，元素包含 code 和 message（UnrecognizedRequestBody 除外）。
	@@ -109,6 +115,19 @@ WebUI 登录后，使用 Cookie 和 CSRF 令牌调用系统、账户、BMC 设
109	- 生产监听地址由 dist/config.cfg 的 WEBBACKEND_PORTAL_LISTEN 配置；代码默认值为 0.0.0.0:8081。	115	- 生产监听地址由 dist/config.cfg 的 WEBBACKEND_PORTAL_LISTEN 配置；代码默认值为 0.0.0.0:8081。
110	- DELETE 是否可用由 AllowHttpDelete 属性控制，默认 true。	116	- DELETE 是否可用由 AllowHttpDelete 属性控制，默认 true。
111		117
		118	+#### 调试示例
		119	+
		120	+```bash
		121	+curl -i -c cookie.txt -H 'Content-Type: application/json' \
		122	+ -d '{"UserName":"<user>","Password":"<encrypted-password>"}' \
		123	+ http://<bmc_ip>:8081/UI/Rest/AccessMgnt/Session
		124	+
		125	+响应示例：
		126	+
		127	+成功：`HTTP/1.1 200 OK`，`Set-Cookie: SessionId=<session-id>`，响应体包含 CSRF 令牌。
		128	+失败：认证失败返回 `401`。
		129	+```
		130	+
112	### 2.2 D-Bus 对象：PublicKey / GetPubKey	131	### 2.2 D-Bus 对象：PublicKey / GetPubKey
113		132
114	#### 功能说明	133	#### 功能说明
	@@ -129,11 +148,26 @@ WebUI 登录后，使用 Cookie 和 CSRF 令牌调用系统、账户、BMC 设
129		148
130	调用 GET /UI/Rest/AccessMgnt/Encryption 获取同一公钥，用于加密密码等敏感字段。	149	调用 GET /UI/Rest/AccessMgnt/Encryption 获取同一公钥，用于加密密码等敏感字段。
131		150
		151	+#### 返回值与异常
		152	+
		153	+成功返回当前公钥字符串；初始化尚未完成时可能返回空值，密钥状态异常由加密层返回错误。
		154	+
132	#### 限制条件	155	#### 限制条件
133		156
134	公钥轮换周期为 7 天；收到 InvalidPubKey 时必须重新获取公钥。	157	公钥轮换周期为 7 天；收到 InvalidPubKey 时必须重新获取公钥。
135		158
136	-### 2.5 任务查询 API：GET /UI/Rest/Task/:TaskId	159	+#### 调试示例
		160	+
		161	+```bash
		162	+curl -i -b cookie.txt http://<bmc_ip>:8081/UI/Rest/AccessMgnt/Encryption
		163	+
		164	+响应示例：
		165	+
		166	+成功：`HTTP/1.1 200 OK`，响应体包含 `PublicKey`。
		167	+失败：会话无效返回 `InvalidSession`。
		168	+```
		169	+
		170	+### 2.3 任务查询 API：GET /UI/Rest/Task/:TaskId
137		171
138	#### 功能说明	172	#### 功能说明
139		173
	@@ -149,6 +183,25 @@ WebUI 登录后，使用 Cookie 和 CSRF 令牌调用系统、账户、BMC 设
149		183
150	不存在、格式非法或已回收的任务返回 ResourceMissingAtURI。	184	不存在、格式非法或已回收的任务返回 ResourceMissingAtURI。
151		185
		186	+#### 应用场景
		187	+
		188	+客户端创建耗时任务后，通过任务 ID 轮询执行状态和进度。
		189	+
		190	+#### 限制条件
		191	+
		192	+TaskId 取值范围为 1～32，且任务必须尚未回收。
		193	+
		194	+#### 调试示例
		195	+
		196	+```bash
		197	+curl -i -b cookie.txt http://<bmc_ip>:8081/UI/Rest/Task/1
		198	+
		199	+响应示例：
		200	+
		201	+成功：`HTTP/1.1 200 OK`，响应体包含 `Name`、`state`、`prepare_progress` 和 `ErrorCode`。
		202	+失败：任务不存在或已回收时返回 `ResourceMissingAtURI`。
		203	+```
		204	+
152	## 3. 组件扩展案例	205	## 3. 组件扩展案例
153		206
154	### 3.1 拓展能力概述	207	### 3.1 拓展能力概述
	@@ -205,6 +258,19 @@ WebUI 登录后，使用 Cookie 和 CSRF 令牌调用系统、账户、BMC 设
205	\| NoPrivilegeToOperateSpecifiedFile \| 文件权限不足 \| 用户权限或属主不满足 \| 检查 File 接口和文件属主。 \|	258	\| NoPrivilegeToOperateSpecifiedFile \| 文件权限不足 \| 用户权限或属主不满足 \| 检查 File 接口和文件属主。 \|
206	\| MalformedJSON \| 配置 JSON 非法 \| 缺少 ConfigData \| 按导入格式修正。 \|	259	\| MalformedJSON \| 配置 JSON 非法 \| 缺少 ConfigData \| 按导入格式修正。 \|
207		260
		261	+### 5.3 最小化复现与证据收集
		262	+
		263	+1. 记录完整 URL、HTTP 方法、请求头、Cookie、CSRF 令牌、请求体和响应。
		264	+2. 对非 GET 请求先确认 SessionId 和 `x-csrf-token`，再检查路由映射及后端 D-Bus 错误。
		265	+3. 保存 web_backend 日志、对应 controller 日志和 `/UI/Rest/Task/:TaskId` 状态。
		266	+4. 敏感字段问题使用最新公钥重新加密后复现，检查 `Encrypted-Properties`。
		267	+
		268	+### 5.4 调试方法
		269	+
		270	+- 使用 `curl` 按真实请求顺序登录并调用接口，保留响应头和响应体。
		271	+- 检查 `WEBBACKEND_ROUTE_MAPPER_CFG_PATH` 和预编译 `config.lua` 是否覆盖源 JSON 路由。
		272	+- 对文件上传、导入导出和任务问题同时检查 `/tmp/web`、TaskService 和依赖组件日志。
		273	+
208	## 6. 常见问题解答	274	## 6. 常见问题解答
209		275
210	### Q1：登录成功后，其他接口仍返回 InvalidSession，为什么？	276	### Q1：登录成功后，其他接口仍返回 InvalidSession，为什么？
	@@ -213,6 +279,8 @@ WebUI 登录后，使用 Cookie 和 CSRF 令牌调用系统、账户、BMC 设
213	- 一句话答案：SessionId Cookie 或非 GET 所需的 x-csrf-token 未正确传递，或会话已过期。	279	- 一句话答案：SessionId Cookie 或非 GET 所需的 x-csrf-token 未正确传递，或会话已过期。
214	- 根因说明：GET 只校验 Cookie；非 GET 还校验 CSRF 令牌。	280	- 根因说明：GET 只校验 Cookie；非 GET 还校验 CSRF 令牌。
215	- 解决方案：保存 Set-Cookie 中的 SessionId，并在非 GET 请求头发送 x-csrf-token。	281	- 解决方案：保存 Set-Cookie 中的 SessionId，并在非 GET 请求头发送 x-csrf-token。
		282	+- 规避方案：接口请求统一携带 Cookie，并对请求头完整性做自动化检查。
		283	+- 适用版本：1.130.14。
216		284
217	### Q2：提交含密码请求返回 InvalidPubKey，如何处理？	285	### Q2：提交含密码请求返回 InvalidPubKey，如何处理？
218		286
	@@ -221,6 +289,7 @@ WebUI 登录后，使用 Cookie 和 CSRF 令牌调用系统、账户、BMC 设
221	- 根因说明：服务每 7 天轮换密钥，并只保留一代次新私钥。	289	- 根因说明：服务每 7 天轮换密钥，并只保留一代次新私钥。
222	- 解决方案：GET /UI/Rest/AccessMgnt/Encryption 获取公钥，重新加密后重试。	290	- 解决方案：GET /UI/Rest/AccessMgnt/Encryption 获取公钥，重新加密后重试。
223	- 规避方案：不要长期缓存公钥。	291	- 规避方案：不要长期缓存公钥。
		292	+- 适用版本：1.130.14。
224		293
225	### Q3：返回 TaskLimitExceeded，任务查询不到怎么办？	294	### Q3：返回 TaskLimitExceeded，任务查询不到怎么办？
226		295
	@@ -228,6 +297,8 @@ WebUI 登录后，使用 Cookie 和 CSRF 令牌调用系统、账户、BMC 设
228	- 一句话答案：任务槽位最多 32 个，终态任务约 10 分钟后回收。	297	- 一句话答案：任务槽位最多 32 个，终态任务约 10 分钟后回收。
229	- 根因说明：task_mgnt.lua 使用固定 32 槽位并每秒轮询任务。	298	- 根因说明：task_mgnt.lua 使用固定 32 槽位并每秒轮询任务。
230	- 解决方案：降低并发，等待任务进入 Completed、Killed 或 Exception 后重试。	299	- 解决方案：降低并发，等待任务进入 Completed、Killed 或 Exception 后重试。
		300	+- 规避方案：客户端限制未完成任务数量并轮询终态后释放任务。
		301	+- 适用版本：1.130.14。
231		302
232	### Q4：新增 JSON 路由后没有生效，如何排查？	303	### Q4：新增 JSON 路由后没有生效，如何排查？
233		304
	@@ -235,3 +306,18 @@ WebUI 登录后，使用 Cookie 和 CSRF 令牌调用系统、账户、BMC 设
235	- 一句话答案：路由未加载、预编译配置覆盖源 JSON，或 URI/方法不匹配。	306	- 一句话答案：路由未加载、预编译配置覆盖源 JSON，或 URI/方法不匹配。
236	- 根因说明：存在 config.lua 时优先加载预编译映射，否则递归加载 JSON。	307	- 根因说明：存在 config.lua 时优先加载预编译映射，否则递归加载 JSON。
237	- 解决方案：核对 WEBBACKEND_ROUTE_MAPPER_CFG_PATH，重新生成并重启服务。	308	- 解决方案：核对 WEBBACKEND_ROUTE_MAPPER_CFG_PATH，重新生成并重启服务。
		309	+- 规避方案：路由变更后先检查预编译配置是否被优先加载。
		310	+- 适用版本：1.130.14。
		311	+
		312	+## 附录
		313	+
		314	+### 附录A 参考资料
		315	+
		316	+- [openUBMC 官网](https://www.openubmc.cn/)
		317	+- [openUBMC/web_backend 代码仓库](https://gitcode.com/openUBMC/web_backend)
		318	+
		319	+### 附录B 修订记录
		320	+
		321	+\| 版本 \| 日期 \| 修订人 \| 修订内容 \|
		322	+\| :--- \| :--- \| :--- \| :--- \|
		323	+\| v1.0 \| 2026-09-13 \| openUBMC 社区 \| 初始版本创建 \|

Mmds/service.json+1-1

	@@ -1,6 +1,6 @@
1	{	1	{
2	"name": "web_backend",	2	"name": "web_backend",
3	- "version": "1.130.15",	3	+ "version": "1.130.16",
4	"type": "application",	4	"type": "application",
5	"deployConfig": "interface.service",	5	"deployConfig": "interface.service",
6	"author": "Huawei",	6	"author": "Huawei",