|
|
# 密码验证与系统设置接口文档
|
|
|
|
|
|
## 概述
|
|
|
|
|
|
本模块提供密码验证、会话管理以及系统时间设置功能。设备运行在离线环境下，通过密码保护敏感操作，会话有效期为 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;
|
|
|
}
|
|
|
```
|
