# 密码验证与系统设置接口文档 ## 概述 本模块提供密码验证、会话管理以及系统时间设置功能。设备运行在离线环境下，通过密码保护敏感操作，会话有效期为 30 分钟。 --- ## 一、密码验证 ### 1.1 验证密码 验证操作密码，成功后返回 session_id，后续请求携带该 ID 即可免密访问。 #### Method - `/m9z/password/verify` #### 请求参数示例 ```json { "jsonrpc": "2.0", "method": "/m9z/password/verify", "params": { "password": "000000" }, "timestampin": "1743523200000" } ``` #### 参数说明 | 参数名 | 类型 | 说明 | 必填 | 备注 | |---------|------|--------|----|--------------| | password | string | 操作密码 | 是 | 首次默认值为 000000 | #### 成功响应示例 ```json { "jsonrpc": "2.0", "result": { "success": true, "session_id": "a1b2c3d4e5f6...", "message": "verified" }, "error": { "message": "ok", "code": 200 } } ``` #### 错误响应示例（密码错误） ```json { "jsonrpc": "2.0", "result": null, "error": { "message": "invalid password", "code": 401 } } ``` --- ### 1.2 修改密码 修改操作密码，需要提供原密码。 #### Method - `/m9z/password/change` #### 请求参数示例 ```json { "jsonrpc": "2.0", "method": "/m9z/password/change", "params": { "old_password": "000000", "new_password": "123456" }, "timestampin": "1743523200000" } ``` #### 参数说明 | 参数名 | 类型 | 说明 | 必填 | 备注 | |-------------|------|------|----|------------| | old_password | string | 原密码 | 是 | | | new_password | string | 新密码 | 是 | 至少 6 位字符 | #### 成功响应示例 ```json { "jsonrpc": "2.0", "result": { "success": true, "message": "password changed" }, "error": { "message": "ok", "code": 200 } } ``` #### 错误响应示例（原密码错误） ```json { "jsonrpc": "2.0", "result": null, "error": { "message": "old password incorrect", "code": 401 } } ``` #### 错误响应示例（新密码太短） ```json { "jsonrpc": "2.0", "result": null, "error": { "message": "new password must be at least 6 characters", "code": 400 } } ``` --- ## 二、会话认证机制 ### 2.1 工作流程 1. 前端首次访问时，弹出密码输入框 2. 调用 `/m9z/password/verify` 获取 `session_id` 3. 将 `session_id` 存储在本地（localStorage） 4. 后续所有需要认证的请求，在请求中携带 `session_id` ### 2.2 请求携带 session_id ```json { "jsonrpc": "2.0", "method": "/m9z/device/setMode", "params": { "mode": 1 }, "session": "a1b2c3d4e5f6...", "timestampin": "1743523200000" } ``` ### 2.3 认证失败响应 当 session_id 过期或未提供时，接口返回 401 错误，前端应引导用户重新输入密码。 ```json { "jsonrpc": "2.0", "result": null, "error": { "message": "session expired or invalid", "code": 401 } } ``` ### 2.4 会话有效期 - 默认有效期：30 分钟 - 每次验证成功后刷新有效期 - 过期后需重新输入密码 --- ## 三、白名单接口 以下接口无需密码验证即可访问： | Method 前缀 | 说明 | |-----------------------|-----------------| | `/m9z/password/*` | 密码相关接口 | | `/m9z/get*` | 所有读取接口 | | `/m9z/fault*` | 故障相关接口 | | `/m9z/system/getTime` | 获取系统时间 | --- ## 四、系统时间设置 ### 4.1 获取系统时间 获取当前设备系统时间，用于前端校准显示。 #### Method - `/m9z/system/getTime` #### 请求参数示例 ```json { "jsonrpc": "2.0", "method": "/m9z/system/getTime", "params": {}, "session": "a1b2c3d4e5f6...", "timestampin": "1743523200000" } ``` #### 成功响应示例 ```json { "jsonrpc": "2.0", "result": { "timestamp": 1743523200, "datetime": "2026-04-01 12:00:00", "timezone": "Local" }, "error": { "message": "ok", "code": 200 } } ``` #### 响应参数说明 | 参数名 | 类型 | 说明 | 备注 | |---------|--------|-----------|--------------| | timestamp | int64 | Unix 时间戳 | 秒级 | | datetime | string | 日期时间字符串 | 格式：YYYY-MM-DD HH:mm:ss | | timezone | string | 时区信息 | Local 表示本地时区 | --- ### 4.2 设置系统时间 修改设备系统时间。设备运行在离线环境时，用于手动校准时间。 #### Method - `/m9z/system/setTime` #### 请求参数示例 ```json { "jsonrpc": "2.0", "method": "/m9z/system/setTime", "params": { "datetime": "2026-04-01 14:30:00" }, "session": "a1b2c3d4e5f6...", "timestampin": "1743523200000" } ``` #### 参数说明 | 参数名 | 类型 | 说明 | 必填 | 备注 | |---------|------|------|----|-----------------------------------| | datetime | string | 目标时间 | 是 | 支持多种格式，见下方说明 | #### 支持的时间格式 | 格式 | 示例 | |---------------------------|-------------------| | YYYY-MM-DD HH:mm:ss | 2026-04-01 14:30:00 | | YYYY-MM-DDTHH:mm:ssZ | 2026-04-01T14:30:00Z | | YYYY-MM-DD HH:mm | 2026-04-01 14:30 | | YYYY-MM-DD | 2026-04-01 | #### 成功响应示例 ```json { "jsonrpc": "2.0", "result": { "success": true, "message": "system time updated", "old_time": "2026-04-01 14:25:30", "new_time": "2026-04-01 14:30:00", "unix_time": 1743531000 }, "error": { "message": "ok", "code": 200 } } ``` #### 响应参数说明 | 参数名 | 类型 | 说明 | 备注 | |---------"|--------|--------|------------| | success | bool | 是否成功 | | | message | string | 状态信息 | | | old_time | string | 修改前时间 | 格式同上 | | new_time | string | 修改后时间 | 格式同上 | | unix_time | int64 | 新时间戳 | 秒级 | #### 错误响应示例（格式错误） ```json { "jsonrpc": "2.0", "result": null, "error": { "message": "invalid datetime format, supported: 2006-01-02 15:04:05, 2006-01-02T15:04:05Z, 2006-01-02 15:04, 2006-01-02", "code": 400 } } ``` #### 错误响应示例（未提供时间） ```json { "jsonrpc": "2.0", "result": null, "error": { "message": "datetime is required", "code": 400 } } ``` --- ## 五、注意事项 ### 5.1 权限要求 - 设置系统时间需要 root 权限，应用需以 root 方式运行 ### 5.2 NTP 设置 - 设置时间时会自动关闭 NTP 同步，防止时间被覆盖 - 设置完成后会自动同步到硬件时钟（RTC） ### 5.3 存储位置 - 密码数据存储在：`程序目录/data/m9zTtyPwd.json` - 密码使用 SHA256 + 自定义盐值加密存储 ### 5.4 建议的前端实现 ```javascript // 1. 初始化时检查 session let sessionId = localStorage.getItem('m9z_session_id'); // 2. 封装请求方法，自动携带 session async function callRpc(method, params = {}) { const response = await fetch('/jsonrpc', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', method, params, session: sessionId, timestampin: Date.now().toString() }) }); const data = await response.json(); // 3. 处理认证失败 if (data.error?.code === 401) { // 弹出密码输入框 sessionId = null; localStorage.removeItem('m9z_session_id'); showPasswordDialog(); throw new Error('session expired'); } return data; } // 4. 密码验证成功后保存 session async function verifyPassword(password) { const res = await callRpc('/m9z/password/verify', { password }, true); if (res.result?.success) { sessionId = res.result.session_id; localStorage.setItem('m9z_session_id', sessionId); } return res; } ```