API接口文档 · 极光网络验证系统

基础信息

API 基础地址：http://你的服务器IP:8001
数据格式：application/json
字符编码：UTF-8
认证方式：Bearer Token（在请求头添加：Authorization: Bearer YOUR_TOKEN）

用户类型 API

供客户端和普通用户使用的接口

认证相关

POST /api/auth/send-verification-code 公开

发送邮箱验证码

发送邮箱验证码用于注册（需要先调用此接口获取验证码）

请求参数

请求示例

限制规则

参数名	类型	必填	说明
`email`	string	必填	邮箱地址
`software_key`	string	可选	软件密钥（用于邮件个性化）

POST /api/auth/send-verification-code HTTP/1.1
Host: 你的服务器IP:8001
Content-Type: application/json

{
  "email": "test@example.com",
  "software_key": "a1b2c3d4e5f6..."
}

✅ 成功响应

{
  "code": 0,
  "message": "验证码已发送至您的邮箱",
  "data": {
    "email": "test@example.com"
  }
}

频率限制：

同一邮箱1分钟内只能发送1次
同一邮箱每天最多发送10次
同一IP每小时最多发送20次

POST /api/auth/register 公开

用户注册

用户注册接口，需要邮箱验证码验证

请求参数

请求示例

参数名	类型	必填	说明
`software_key`	string	必填	软件密钥（64位十六进制）
`username`	string	必填	用户名（3-50字符）
`password`	string	必填	密码（至少6字符）
`email`	string	必填	邮箱地址
`verification_code`	string	必填	邮箱验证码（6位数字）
`machine_code`	string	可选	设备指纹/机器码
`source`	string	可选	用户来源

POST /api/auth/register HTTP/1.1
Host: 你的服务器IP:8001
Content-Type: application/json

{
  "software_key": "a1b2c3d4e5f6...",
  "username": "testuser",
  "password": "password123",
  "email": "test@example.com",
  "verification_code": "123456",
  "machine_code": "abc123",
  "source": "windows_client"
}

✅ 成功响应

{
  "code": 0,
  "message": "注册成功",
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_type": "bearer",
    "user": {
      "id": 1,
      "username": "testuser",
      "software_id": 1,
      "software_name": "极光工具箱",
      "expire_at": "2026-12-31 23:59:59"
    }
  }
}

POST /api/auth/login 公开

用户登录

用户登录，返回访问令牌

请求参数

请求示例

参数名	类型	必填	说明
`software_key`	string	可选	软件密钥（管理员登录不需要）
`username`	string	必填	用户名
`password`	string	必填	密码

POST /api/auth/login HTTP/1.1
Host: 你的服务器IP:8001
Content-Type: application/json

{
  "software_key": "a1b2c3d4e5f6...",
  "username": "testuser",
  "password": "password123"
}

GET /api/auth/me 需认证

获取当前用户信息

获取当前登录用户的详细信息

需要在请求头中携带Token：Authorization: Bearer YOUR_TOKEN

POST /api/auth/change-password 需认证

修改密码

修改当前用户的登录密码

请求参数

请求示例

参数名	类型	必填	说明
`old_password`	string	必填	旧密码
`new_password`	string	必填	新密码（至少6字符）

POST /api/auth/change-password HTTP/1.1
Host: 你的服务器IP:8001
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "old_password": "oldpass123",
  "new_password": "newpass456"
}

软件信息（公开API）

GET /api/softwares/public/{software_key}/version 公开

获取软件版本号

获取软件最新版本号（公开API，无需认证）

适用场景：客户端检测版本更新、自动升级提示

GET /api/softwares/public/{software_key}/announcement 公开

获取软件公告

获取软件公告内容（支持HTML格式）

卡密相关

POST /api/cards/use 需认证

使用卡密

使用卡密为账号续费或延长会员时间

请求参数

请求示例

响应示例

参数名	类型	必填	说明
`code`	string	必填	16位卡密代码

卡密类型：day(天卡)、week(周卡)、month(月卡)、year(年卡)、permanent(永久卡)

POST /api/cards/use HTTP/1.1
Host: 你的服务器IP:8001
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "code": "ABCD1234EFGH5678"
}

✅ 成功响应

{
  "code": 0,
  "message": "卡密使用成功！会员已延长 30 天",
  "data": {
    "new_expire_at": "2026-03-25 14:30:00",
    "days_added": 30
  }
}

❌ 失败响应示例

// 卡密不存在
{"code": 400, "message": "卡密不存在"}

// 卡密已被使用
{"code": 400, "message": "卡密已被使用"}

// 不适用于当前软件
{"code": 400, "message": "此卡密不适用于当前软件"}

云JS函数

POST /api/js-functions/execute 需认证

执行云函数

执行云端JavaScript函数，支持参数传递和返回值获取

请求参数

请求示例

响应示例

参数名	类型	必填	说明
`function_name`	string	必填	函数名称
`params`	object	可选	函数参数（JSON对象）

POST /api/js-functions/execute HTTP/1.1
Host: 你的服务器IP:8001
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "function_name": "calculatePrice",
  "params": {
    "price": 100,
    "discount": 0.8
  }
}

云函数示例：

// 函数名: calculatePrice
function calculatePrice(params) {
    const { price, discount } = params;
    const finalPrice = price * discount;
    return {
        originalPrice: price,
        finalPrice: finalPrice,
        saved: price - finalPrice
    };
}

✅ 成功响应

{
  "code": 0,
  "message": "执行成功",
  "data": {
    "result": {
      "originalPrice": 100,
      "finalPrice": 80,
      "saved": 20
    },
    "execution_time": 15
  }
}

管理类型 API

管理员专用的接口，需要管理员权限

用户管理

GET /api/users/list/paginated 管理员

分页获取用户列表

支持搜索和过滤的分页用户列表

查询参数：page、page_size、software_id、search、is_banned

GET /api/users/detail/{user_id} 管理员

获取用户详细信息

获取指定用户的详细信息

POST /api/users/ 管理员

创建用户

手动创建新用户

PUT /api/users/update-detail/{user_id} 管理员

更新用户信息

更新用户的详细信息（备注、IP、机器码、到期时间等）

POST /api/users/ban 管理员

封号/解封用户

封禁或解封用户账号

DELETE /api/users/{user_id} 管理员

删除用户

删除用户（敏感操作，需要管理员密码确认）

软件管理

GET /api/softwares/ 管理员

获取所有软件列表

获取系统中所有软件的列表

POST /api/softwares/ 管理员

创建软件

创建新软件（自动生成软件密钥）

PUT /api/softwares/{software_id} 管理员

更新软件信息

更新软件名称、版本、公告等信息

DELETE /api/softwares/{software_id} 管理员

删除软件

删除软件（会级联删除该软件的所有用户）

POST /api/softwares/{software_id}/regenerate-key 管理员

重新生成软件密钥

重新生成软件的密钥（需要管理员密码确认）

卡密管理

POST /api/cards/generate 管理员

批量生成卡密

批量生成卡密（1-100张）

请求参数

请求示例

参数名	类型	必填	说明
`software_id`	int	可选	软件ID（null=通用卡密）
`type`	string	必填	卡类型：day/week/month/year/permanent
`count`	int	必填	生成数量（1-100）
`remark`	string	可选	备注

POST /api/cards/generate HTTP/1.1
Host: 你的服务器IP:8001
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "software_id": 1,
  "type": "month",
  "count": 10,
  "remark": "2024年1月活动卡密"
}

GET /api/cards/ 管理员

获取卡密列表

分页获取卡密列表，支持过滤

查询参数：software_id、used、page、page_size

DELETE /api/cards/{card_id} 管理员

删除卡密

删除指定的卡密

云JS函数管理

GET /api/js-functions/ 管理员

获取所有函数

获取所有云函数列表

POST /api/js-functions/ 管理员

创建函数

创建新的JavaScript云函数

PUT /api/js-functions/{function_id} 管理员

更新函数

更新云函数的代码和配置

DELETE /api/js-functions/{function_id} 管理员

删除函数

删除指定的云函数

日志统计

GET /api/logs/operations 管理员

获取操作日志

获取系统操作日志列表（分页）

GET /api/logs/statistics/{period} 管理员

获取统计数据

获取指定周期的统计数据（today/week/month/year）

GET /api/dashboard/stats 管理员

获取Dashboard统计

获取仪表盘的综合统计数据

POST /api/logs/batch/set-expire 管理员

批量设置到期时间

批量设置用户的到期时间

POST /api/logs/batch/set-trial 管理员

批量设置试用状态

批量设置用户的试用状态

系统设置

GET /api/settings/env 管理员

获取环境变量

获取系统环境变量配置

POST /api/settings/env 管理员

更新环境变量

更新系统环境变量配置

POST /api/settings/restart 管理员

重启服务

重启后端服务

GET /api/settings/blacklist 管理员

获取IP黑名单

获取所有黑名单IP

POST /api/settings/blacklist 管理员

添加IP到黑名单

添加IP地址到黑名单

DELETE /api/settings/blacklist/{ip} 管理员

从黑名单移除IP

从黑名单中移除IP地址

GET /api/settings/whitelist 管理员

获取IP白名单

获取所有白名单IP

POST /api/settings/whitelist 管理员

添加IP到白名单

添加IP地址到白名单

DELETE /api/settings/whitelist/{ip} 管理员

从白名单移除IP

从白名单中移除IP地址

API密钥管理

GET /api/api-keys/ 管理员

获取API密钥列表

获取所有API密钥

POST /api/api-keys/ 管理员

创建API密钥

创建新的API密钥（用于外部调用）

DELETE /api/api-keys/{key_id} 管理员

删除API密钥

删除指定的API密钥

POST /api/api-keys/{key_id}/regenerate 管理员

重新生成API密钥

重新生成API密钥的值

错误码说明

常见错误码及解决方法

错误码	说明	解决方法
`0`	成功	-
`-1`	通用错误	查看错误消息
`400`	请求参数错误	检查请求参数格式和内容
`401`	未授权（Token无效或过期）	重新登录获取新Token
`403`	禁止访问（被封禁、已到期等）	联系管理员处理
`404`	资源不存在	检查API地址是否正确
`429`	请求过于频繁	降低请求频率
`500`	服务器内部错误	联系技术支持