用户模式

用户模式适合需要账号体系的软件，终端用户通过用户名密码登录，管理员在控制台管理用户账号和到期时间。

POST /api/v1/user/register — 用户注册

创建新的终端用户账号，密码长度不少于 6 位。

请求参数

参数名	类型	必填	说明
`app_key`	string	是	软件 App Key
`username`	string	是	用户名
`password`	string	是	密码（不少于 6 位）
`nonce`	string	是	随机字符串
`timestamp`	number	是	Unix 时间戳（秒）
`sign`	string	是	请求签名

返回数据（result）

字段名	类型	说明
`username`	string	注册成功的用户名

POST /api/v1/user/login — 用户登录

使用用户名/密码登录，返回 token 及到期时间。

请求参数

参数名	类型	必填	说明
`app_key`	string	是	软件 App Key
`username`	string	是	用户名
`password`	string	是	登录密码
`device_id`	string	否	设备唯一标识（用于设备绑定）
`nonce`	string	是	随机字符串
`timestamp`	number	是	Unix 时间戳（秒）
`sign`	string	是	请求签名

返回数据（result）

字段名	类型	说明
`token`	string	会话令牌
`username`	string	用户名
`expiresAt`	number \| null	账号到期 Unix 时间戳，永久有效时为 `null`
`config`	string	用户或软件的自定义配置数据

POST /api/v1/user/heartbeat — 保活心跳

刷新用户会话有效期。

请求参数

参数名	类型	必填	说明
`app_key`	string	是	软件 App Key
`token`	string	是	登录获取的会话令牌
`nonce`	string	是	随机字符串
`timestamp`	number	是	Unix 时间戳（秒）
`sign`	string	是	请求签名

返回数据（result）

字段名	类型	说明
`expiresAt`	number	新的会话到期 Unix 时间戳

POST /api/v1/user/logout — 用户登出

销毁用户会话 token。成功时 result 字段不存在。

请求参数

参数名	类型	必填	说明
`app_key`	string	是	软件 App Key
`token`	string	是	登录获取的会话令牌
`nonce`	string	是	随机字符串
`timestamp`	number	是	Unix 时间戳（秒）
`sign`	string	是	请求签名

POST /api/v1/user/unbind_device — 解绑设备

将指定设备从当前用户的绑定设备列表中移除，需软件开启"允许解绑"功能，且当前 token 有效。

请求参数

参数名	类型	必填	说明
`app_key`	string	是	软件 App Key
`token`	string	是	登录获取的会话令牌
`device_id`	string	是	要解绑的设备 ID
`nonce`	string	是	随机字符串
`timestamp`	number	是	Unix 时间戳（秒）
`sign`	string	是	请求签名

成功时 result 字段不存在。

GET /api/v1/user/data — 读取用户数据

读取当前登录用户自己的云端数据。数据按 key 独立保存，不同用户读取同一个 key 时会得到各自的数据。

适合保存软件登录后的用户配置、偏好、进度、云存档等数据。若保存敏感内容，建议客户端加密后再上传。

请求参数（Query）

参数名	类型	必填	说明
`app_key`	string	是	软件 App Key
`token`	string	是	登录获取的会话令牌
`key`	string	是	数据键名，最多 64 字符，支持字母、数字、下划线、点、冒号、短横线
`nonce`	string	是	随机字符串
`timestamp`	number	是	Unix 时间戳（秒）
`sign`	string	是	请求签名

返回数据（result）

字段名	类型	说明
`key`	string	数据键名
`value`	string	数据内容
`updatedAt`	string	最后更新时间

POST /api/v1/user/data — 保存用户数据

创建或覆盖当前登录用户指定 key 的数据。单个用户在同一软件下的云端数据总量最多 5MB，单个 key 的 value 最多 1MB，建议保存 JSON 字符串。若保存敏感内容，建议客户端加密后再上传。

请求参数

参数名	类型	必填	说明
`app_key`	string	是	软件 App Key
`token`	string	是	登录获取的会话令牌
`key`	string	是	数据键名
`value`	string	是	数据内容，单个 key 最大 1MB，当前用户总量最大 5MB
`nonce`	string	是	随机字符串
`timestamp`	number	是	Unix 时间戳（秒）
`sign`	string	是	请求签名

返回数据（result）

字段名	类型	说明
`key`	string	数据键名
`value`	string	数据内容
`updatedAt`	string	最后更新时间

DELETE /api/v1/user/data — 删除用户数据

删除当前登录用户指定 key 的数据。

请求参数

参数名	类型	必填	说明
`app_key`	string	是	软件 App Key
`token`	string	是	登录获取的会话令牌
`key`	string	是	数据键名
`nonce`	string	是	随机字符串
`timestamp`	number	是	Unix 时间戳（秒）
`sign`	string	是	请求签名

成功时 result 字段不存在。

npm SDK 示例

const login = await client.user.login({
    username: "alice",
    password: "123456",
    deviceId: "device-001",
});

await client.user.setData({
    token: login.token,
    key: "settings",
    value: JSON.stringify({ theme: "dark", volume: 80 }),
});

const data = await client.user.getData({
    token: login.token,
    key: "settings",
});

const settings = JSON.parse(data.value);