Nebula 网络验证 · 接口文档

所有客户端接口统一入口：

POST http://<域名>/api/index.php?action=<接口名>

（配置了 .htaccess 后也可用 POST http://<域名>/api/<接口名>）

不想手写协议？

sdk/ 目录提供零依赖的 C++ SDK（header-only），把 sdk/nebula/ 目录 + nebula_sdk.hpp 一起拖进项目即可，
无需 OpenSSL / libcurl（用系统自带的 bcrypt.dll / winhttp.dll，仅 Windows + MSVC）。配置只需改一个文件：sdk/nebula/client/config.hpp。

#include "nebula_sdk.hpp"

auto c = nebula::createDefaultClient("machine_id", "Windows", "1.0.1");
c->init();
auto lr = c->login("用户名", "密码");
c->startHeartbeat(lr.token, /* 心跳回调 */, 60000);

本文档描述的是协议层细节，适合需要自行实现客户端（其他语言 / 特殊需求）的场景。

一、通信协议（Nebula 3.1）

3.1 的核心设计：ECDH P-256 临时握手协商会话密钥，客户端不持有任何静态对称机密——逆向者即使 dump 出整个进程内存，也拿不到可用于伪造请求的密钥。

1.1 会话握手（handshake）

客户端启动后（或会话失效时）先调用 action=handshake 建立会话。请求为明文 JSON（完整性由响应的 ES256 签名保证）：

{
  "app_key": "SWxxxx",
  "eph_pub": "<base64(客户端临时 ECDH P-256 公钥, 65字节 uncompressed)>",
  "nc":      "<base64(客户端随机数 16 字节)>",
  "ts":      1726000000,
  "mhash":   "<sha256(machine_id) hex>"
}

响应（外层含 ES256 防伪签名，业务数据在 data 层）：

{
  "code":  0,
  "data": {
    "proto":   31,
    "sid":     "<32位hex会话ID>",
    "eph_pub": "<base64(服务端临时 ECDH 公钥)>",
    "ns":      "<base64(服务端随机数 16 字节)>",
    "ts_s":    1726000000,
    "sign":    "<base64(ES256 签名)>",
    "sig_kid": "<密钥标识>",
    "sig_algo": "ES256"
  }
}

sign 的签名对象为 sid | eph_pub_S | ns | nc | ts_s——绑定双方临时公钥与 nonce，握手响应不可重放、不可篡改、不可中间人换钥。客户端验签通过后计算会话密钥：

服务端握手接口独立频控（10 次/分钟）；同一 mhash 旧会话自动清理。会话有效期由服务端控制，5002 即重新握手。

1.2 业务请求信封

除明文白名单外，所有业务请求统一 3.1 信封：

{
  "proto":  31,
  "sid":    "<32位hex会话ID>",
  "seq":    42,
  "t":      1726000000,
  "data":   "<base64(iv[12] + AES-256-GCM密文 + tag[16])>",
  "mac":    "<HMAC-SHA256 hex>",
  "app_key": "SWxxxx"
}

1.2.1 安全性质

• 零静态机密：AES_KEY / SIGN_SALT 已随 3.0 移除，客户端编译产物中不存在任何长期对称密钥；逆向 dump 堆内存最多拿到当次会话的临时密钥（会话结束即作废）
• 前向隔离：每次握手重新生成双方临时密钥对，一个会话泄露不影响其他会话
• 防重放：GCM 认证加密（密文+tag 不可篡改）+ seq 单调递增 + HMAC 绑定 sid|seq|t 三重防线
• 防伪造服务器：握手与业务响应均带服务端长期 ES256 私钥签名（公钥 pin 在客户端），hosts 劫持 / 假服务器直接失效

1.3 响应格式

业务响应使用同一会话的 GCM 信封（IV 与请求对称，用请求的 seq），外层附带 ES256 防伪签名与明文 code：

{
  "proto":  31,
  "sid":    "<会话ID>",
  "data":   "<base64(iv[12] + GCM密文 + tag[16])>",
  "code":   0,
  "sig":      "<base64(ES256 签名)>",
  "sig_kid":  "<密钥标识>",
  "sig_algo": "ES256"
}

sig / sig_kid / sig_algo 为响应防伪签名（服务端长期私钥签名，客户端内置公钥验签）：

校验顺序：先验 sig（防伪造服务器）→ 再 GCM 解密 data（tag 自带完整性）。该签名与离线宽限票据签名共用一对密钥（config/grace_keys.php），客户端需在 nebula/client/config.hpp 的 kRespSignPubKey 填入对应公钥（必填）。

解密 data 后得到业务响应：

{
  "code": 0,
  "msg":  "登录成功",
  "time": 1726000000,
  "data": { }
}

1.3.1 明文白名单接口

以下接口无敏感数据，支持明文直接调用（不带 3.1 信封）：

注意：init 不在白名单——3.1 起 init 必须先完成握手、走 GCM 会话信封（配置/公告/版本策略属敏感下发内容）。

这一组白名单接口同时还满足：不要求会话、不受最低版本强制更新拦截、
不计入每日调用配额、维护模式下照常放行。

响应一律加密（不论请求是明文还是 GCM 信封）：

• 所有接口（含白名单接口、错误响应）都返回加密信封
• 白名单接口只是允许请求侧不带信封，响应侧始终加密，防止响应被中间人直接读取

客户端解析响应时无需区分请求方式，统一按 1.3 节的信封流程验签 + 解密即可。

白名单在 config/config.php 的 security.plain_whitelist 中配置（handshake 恒为公开）。
其余接口在 enforce_crypto = true（默认）时必须携带完整 3.1 信封，
否则返回 1001 缺少必要字段 sid/seq/data。

1.4 业务状态码

二、客户端接口

2.1 init · 初始化

拉取服务器配置、公告、版本信息。建议客户端启动第一步调用。

请求参数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "server_time": 1726000000,
    "site_name": "Nebula 网络验证",
    "heartbeat_interval": 60,
    "session_ttl": 3600,
    "register_enable": true,
    "maintain_mode": false,
    "grace": {
      "enable": true,
      "seconds": 3600,
      "max_seconds": 7200,
      "algorithm": "ES256",
      "kid": "3f9a1c2b",
      "public_key": "-----BEGIN PUBLIC KEY-----\nMFkw...\n-----END PUBLIC KEY-----",
      "ticket_prefix": "G1",
      "usage": "心跳失败时，本地用 public_key 验签后可在 until 前离线运行"
    },
    "crypto": { "proto": 31, "algo": "AES-256-GCM", "kex": "ECDH-P256", "sign": "ES256" },
    "version": {
      "client_ver": "1.0.0",
      "latest": "1.1.0",
      "min": "1.0.0",
      "need_update": true,
      "force_update": false,
      "update_url": "https://example.com/app.exe",
      "update_note": "修复若干问题"
    },
    "notices": [
      { "id": 1, "title": "欢迎使用", "content": "系统已上线", "type": 4 }
    ]
  }
}

notices 仅下发 列表公告（type=4，公告栏展示用，按归属软件过滤）；弹窗公告（type=2）与立即公告（type=3）由客户端经 notice 接口配合 SDK popupNotices() / flashNotices() 处理。

离线宽限票据的完整使用方式见 2.16 离线宽限协议。

2.2 register · 注册

登录方式为 code（卡密直登）时本接口自动关闭，返回 1004 当前仅支持激活码登录，无需注册。
官网侧（/web/api.php?action=register）行为一致。

请求参数

响应

{ "code": 0, "msg": "注册成功", "data": { "user_id": 10, "username": "testuser" } }

2.3 login · 登录

登录方式由后台「系统设置 → 登录方式」单选决定，客户端按 init 下发的
data.login 规格（method / fields）直接提交对应字段。
三种方式互斥，不存在「一次请求塞多个字段、服务端猜」的兼容逻辑：
字段与该方式不匹配时直接返回 1001。

init 下发的登录规格：

"login": {
  "method": "password",
  "label": "用户名 + 密码",
  "need_username": true,
  "need_password": true,
  "need_code": false,
  "fields": ["username", "password"]
}

公共请求参数

各登录方式的字段

激活码登录的语义（username_code / code 共用）

注意：code（卡密直登）方式下注册功能会自动关闭（register 返回 1004），
因为该方式不依赖账号体系，注册出来的账号没有可用密码。

成功响应

{
  "code": 0,
  "msg": "登录成功",
  "data": {
    "token": "a1b2c3...",
    "expire_at": 1726003600,
    "ttl": 3600,
    "login_method": "password",
    "account_created": false,
    "user": {
      "user_id": 10,
      "username": "testuser",
      "nickname": "testuser",
      "vip_expire": 1728592000,
      "vip_text": "2026-10-11 12:00:00",
      "points": 0,
      "max_devices": 2,
      "status": 1,
      "group_id": 1
    },
    "vip": { "valid": true, "code": 0, "msg": "ok", "expire_at": 1728592000, "points": 0 },
    "device": {
      "machine_id": "a1b2c3d4",
      "auto_bound": true,
      "max_devices": 2,
      "bound_count": 1
    },
    "grace": {
      "ticket": "G1.eyJ2IjoxLCJ1IjoxMCwibSI6ImExYjJjM2Q0...<base64url>.<sig-base64url>",
      "until": 1726007200,
      "seconds": 3600,
      "issued_at": 1726003600,
      "server_time": 1726003600,
      "algorithm": "ES256",
      "kid": "3f9a1c2b",
      "machine_bind": "a1b2c3d4e5f6a7b8",
      "public_key": "-----BEGIN PUBLIC KEY-----\nMFkw...\n-----END PUBLIC KEY-----"
    }
  }
}

设备超限响应（code 4001）

{
  "code": 4001,
  "msg": "设备数量已达上限",
  "data": {
    "max_devices": 1,
    "bound_count": 1,
    "devices": [ { "machine_id": "...", "device_name": "...", "last_seen": "..." } ]
  }
}

2.4 heartbeat · 心跳

客户端需按 heartbeat_interval（默认 60 秒）定时上报。

请求参数

正常响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "online": true,
    "server_time": 1726000060,
    "next_interval": 60,
    "remain": 2591960,
    "remain_text": "30天",
    "vip_expire": 1728592000,
    "points": 0,
    "session_ttl": 3600,
    "force_offline": false,
    "has_notice": false,
    "grace": {
      "ticket": "G1.eyJ2IjoxLCJ1IjoxMCwibSI6ImExYjJjM2Q0...<base64url>.<sig-base64url>",
      "until": 1726007260,
      "seconds": 3600,
      "issued_at": 1726003660,
      "server_time": 1726003660,
      "algorithm": "ES256",
      "kid": "3f9a1c2b",
      "machine_bind": "a1b2c3d4e5f6a7b8"
    }
  }
}

离线宽限票据字段

heartbeat 每次都会刷新票据，客户端成功收到即覆盖旧票据；票据本身绑定当前会话令牌，
因此一旦被踢下线，旧票据在最迟 until 之后即彻底失效（详见 2.16）。

被踢下线（需立即处理）

{ "code": 1002, "msg": "账号已在其他设备登录", "data": { "need_relogin": true } }

{ "code": 1002, "msg": "账号已被强制下线", "data": { "need_relogin": true } }

1002 按会话失效原因区分文案：账号已在其他设备登录＝同账号在其他设备登录顶号；
账号已被强制下线＝管理员强制下线 / 封禁 / 设备解绑等系统操作；会话已退出＝主动登出。

{ "code": 4002, "msg": "当前设备已被解绑", "data": { "kick": true, "need_relogin": true } }

{ "code": 2004, "msg": "账号已过期", "data": { "kick": true, "need_activate": true } }

客户端收到带 kick 或 need_relogin 的响应时，应停止业务功能并回到登录界面。

2.5 activate · 激活卡密

请求参数

响应

{
  "code": 0,
  "msg": "激活成功：增加时长 30天",
  "data": {
    "card_type": 1,
    "detail": "增加时长 30天",
    "user": { "user_id": 10, "vip_expire": 1731196800, "vip_text": "2026-11-10 12:00:00", "points": 0 }
  }
}

2.6 unbind · 解绑设备

请求参数

每账号每日最多解绑 3 次，超出需联系管理员。

响应

{
  "code": 0,
  "msg": "设备解绑成功",
  "data": { "machine_id": "a1b2c3d4", "bound_count": 0, "devices": [] }
}

2.7 devices · 设备列表

请求参数：token

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "max_devices": 2,
    "bound_count": 1,
    "current": "a1b2c3d4",
    "devices": [
      {
        "id": 5,
        "machine_id": "a1b2c3d4",
        "device_name": "Windows PC",
        "os_info": "Windows 10 x64",
        "ip": "1.2.3.4",
        "status": 1,
        "status_text": "正常",
        "bind_at": "2026-09-01 10:00:00",
        "last_seen": "2026-09-10 08:30:00",
        "online": true
      }
    ]
  }
}

2.8 userinfo · 用户信息

请求参数：token

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "user": { },
    "group_name": "默认用户组",
    "vip": { "valid": true },
    "remain": 2591960,
    "remain_text": "30天",
    "register_time": "2026-09-01 10:00:00",
    "last_login": "2026-09-10 08:00:00",
    "device": { "max_devices": 2, "bound_count": 1 }
  }
}

2.9 notice · 公告

无需登录，可用 GET。

请求参数：id（可选，查单条）

仅下发「客户端公告」：type=2 弹窗公告（客户端弹出窗口展示）、type=3 立即公告（弹出展示，客户端确认后本地记为已读、不再显示）、type=4 列表公告（客户端公告栏展示）。官网门户公告（type=1）只在官网首页展示，不下发给客户端。归属软件为 0 时全部软件通用，否则仅归属软件的客户端可见。

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "系统公告",
        "content": "内容...",
        "type": 4,
        "type_text": "列表公告",
        "created_at_text": "2026-09-10 08:00:00"
      }
    ],
    "total": 1
  }
}

2.10 version · 版本校验

请求参数

响应

{
  "code": 0,
  "msg": "发现新版本",
  "data": {
    "current": "1.0.0",
    "latest": "1.1.0",
    "min": "1.0.0",
    "channel": "stable",
    "need_update": true,
    "force_update": false,
    "download_url": "https://example.com/app.exe",
    "file_hash": "sha256...",
    "file_size": 10485760,
    "changelog": "修复若干问题"
  }
}

完整性比对（客户端必做）：下载更新包完成后，本地计算文件哈希/大小并与响应比对，不一致即丢弃文件并提示重新下载，不得执行：

• 文件哈希：file_hash 为 32 位 hex（MD5）或 64 位 hex（SHA256，按长度识别算法）
• 文件大小：file_size 字节（0 = 后台未填写，跳过该项比对）

C++ SDK 已内置工具：Bcrypt::fileHashHex(路径, 是否SHA256) 与 Bcrypt::fileSizeBytes(路径)，且 init() 的 version 对象已带出 file_hash / file_size（InitResult 同名字段）。

客户端完整性自校验（防篡改）：响应中的 self_file_hash / self_file_size 是客户端上报版本号在「版本管理」里登记的哈希与字节数（服务端按 software_id + client_ver + channel 查已发布记录）。客户端启动时计算自身 exe 的哈希/大小与之比对，不一致即判定文件被篡改，应弹窗并拒绝运行。该版本未登记、未发布或未填哈希时，两字段为 '' / 0，客户端跳过校验。SDK 已内置 nebula::verifySelfIntegrity(InitResult&) 一键校验。

⚠️ 发布版本时填写的 file_hash / file_size 必须是该版本客户端 exe 的真实值——一旦登记并发布，所有自报该版本号的客户端都会被强制比对，值填错会把正常客户端一并拦截。

2.11 online · 在线人数

公开接口，无需登录，也无需会话密钥 k，可直接 GET 或明文调用。

请求参数：无

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "online": 128,
    "timeout": 180,
    "server_time": 1789024346
  }
}

统计口径

统计的是 nb_sessions 中 status = 1 且 last_active 在心跳超时
（policy.heartbeat_timeout，默认 180 秒）内的会话数，与后台首页
「在线会话」完全一致。

同一账号多设备登录会分别计数。若要「去重用户数」或「在线设备数」，
属于另一套口径，需要单独加接口。

轮询建议：客户端/官网展示用的话 30~60 秒拉一次即可，受 IP 限流保护
（客户端 120 次/分，官网 240 次/分）。

官网入口

官网侧对应 GET /web/api.php?action=online，返回明文 JSON（结构同上，
无加密信封），同样无需登录、不校验 CSRF：

{"code":0,"msg":"ok","time":1789024346,"data":{"online":128,"timeout":180,"server_time":1789024346}}

2.12 download · 客户端下载地址（官网）

该接口仅在官网侧提供（GET /web/api.php?action=download）。
客户端不需要单独调用它 —— 客户端从 init / version 响应的
download_url / file_hash / file_size 字段获取同一份信息。

公开接口，无需登录、不校验 CSRF、维护模式下照常放行，返回明文 JSON。

请求参数：无

响应（已配置下载地址）

{
  "code": 0,
  "msg": "ok",
  "time": 1789024865,
  "data": {
    "configured": true,
    "version": "1.0.0",
    "download_url": "https://dl.example.com/nebula/NebulaMenu_1.0.0.zip",
    "file_name": "NebulaMenu_1.0.0.zip",
    "file_size": 19000000,
    "file_hash": "68fe07199e140572ed7d7e681109a5edf52d52faa98a9c96c116556aa21d2180",
    "changelog": ""
  }
}

数据来源：nb_versions 表 stable 渠道最新已发布（status = 1）记录；
该表无记录时回落 config.php 的 version.update_url。

安全约束：只回传 http:// / https:// 开头的地址。若后台误填
javascript: 等伪协议，一律按「未配置」处理（configured = false、
download_url 置空），避免前端直接跳转执行。

下载地址在后台「版本管理」页填写（字段：下载地址 / 文件哈希 / 文件大小）。

与其他入口同源：官网首页展示的「最新版本」与首页在线人数条上的版本号，
服务端渲染与前端刷新都取自同一份数据（Version::latest('stable')）。
因此官网首页、下载按钮文案、客户端 version 接口三者不会出现版本号不一致的情况。

2.13 logout · 退出

请求参数：token

2.14 设备指纹（可选）

machine_id 是客户端自己算的字符串，伪造成本极低：改一个字节就是"新设备"。
device_fp 让客户端再上报多个硬件组件的特征串，服务端据此做加权指纹校验，
用于识别机器码伪造、模拟器/虚拟机和一机多号。

C++ SDK（sdk/nebula_sdk.hpp，配置区在 sdk/nebula/client/config.hpp）已内置自动采集（WMI 硬件序列号取哈希 + 主网卡裸 MAC，device_name 自动取真实电脑主机名），使用 SDK 时无需手动构造本字段。

上报格式（login 请求中的可选字段，对象或 JSON 字符串均可）：

"device_fp": {
  "board": "9f2c…",        // 主板
  "cpu":   "1a7b…",        // CPU
  "disk":  "c3d4…",        // 系统盘序列号
  "bios":  "55ee…",        // BIOS/UEFI
  "mac":   "001122334455", // 主网卡（给裸 MAC 时可用于识别虚拟机网卡）
  "gpu":   "77aa…"         // 显卡
}

每个组件填该硬件的哈希或特征串（服务端只做等值比较与相似度计算，
不关心具体算法）。mac 若直接给 12 位裸 MAC，会额外匹配常见虚拟机网卡 OUI。

组件权重与判定规则

| 组件 | 权重 | 换掉后是否容忍 || ---------- | -: | ------------------- || board 主板 | 30 | ❌ 核心组件，变化即判定疑似伪造机器码 || cpu CPU | 25 | ❌ 核心组件，变化即判定疑似伪造机器码 || disk 系统盘 | 20 | ✅ 容忍（升级 SSD 属正常） || bios | 15 | ✅ 容忍 || mac 网卡 | 10 | ✅ 容忍（换网卡/虚拟网卡最常见） || gpu 显卡 | 10 | ✅ 容忍 |

• 核心组件（board / cpu，可通过 device_fp.core_components 调整）双方都上报时， 只要有一个不一致 → 记 fp_changed。
• 核心组件缺失时，回落到加权相似度与 device_fp.drift_threshold 比较。

风险标记

命中标记会随 login 响应的 data.device.risk 数组返回，并写入 nb_logs
（action = device_risk）。默认仅记录不拦截；需要硬拦截时在 config/config.php 打开：

'device_fp' => [
    'block_on_drift' => true,  // 疑似伪造机器码时拒绝登录（返回 4005）
    'block_vm'       => true,  // 命中模拟器/虚拟机时拒绝登录（返回 4005）
],

init 响应的 data.device_fp 会下发组件清单与权重，客户端可据此决定采集哪些项。

未上报 device_fp 的客户端不受任何影响：服务端跳过全部指纹逻辑，
行为与升级前逐字节一致，因此各对接方可以按自己的节奏升级。

2.15 限流与枚举防护

除全局「单 IP 每分钟请求数」外，卡密相关接口另有三层防护：

card_try_window（默认 600 秒） || 来源枚举 | 防止「每次换一个卡号」的随机枚举 | card_miss_limit（默认 30 次）
card_miss_window（默认 600 秒） |

• 单卡限流键内只存卡密的 SHA-256 摘要，不落明文，限流表泄露也不会泄露卡密。
• 枚举计数只累计「卡密不存在」（3001）的失败，不影响正常业务。
• 生效范围：activate、login（username_code / code 两种激活码方式）、 /agent/ 的激活码注册。
• 超限统一返回 5001。

2.16 离线宽限协议

目的：服务器抖动、网络波动或临时宕机时，已登录的客户端不必立刻掉线，
可凭一张服务端私钥签名的离线宽限票据在本地验签后继续运行一段时间，
避免「服务端一抖，全体用户掉线」引发投诉。

票据结构

G1.<payload-b64url>.<signature-b64url>

载荷字段

载荷不含用户名、密码等任何敏感信息；机器码与令牌只以摘要形式出现，
即使票据泄露也无法反推原始值。

客户端本地验签流程

1. 从 init（或 login）拿到 public_key（PEM）与 ticket_prefix，缓存到本地。
2. 每次成功调用 login / heartbeat 后，用响应里的 grace.ticket 覆盖本地票据。
3. 当 heartbeat 请求失败（超时、连接被拒、返回 5xx 且非业务错误）时：
   1. 校验 grace 处于开启状态，且本地存在票据；
   2. 按 . 切分得到 3 段，第一段必须等于 G1；
   3. 用缓存的 public_key 对 G1.<payload-b64url> 做 ES256 验签，失败 → 判定被篡改，回普通模式；
   4. base64url 解码载荷，校验 m == sha256(本地机器码)前16位、k == sha256(当前token)前16位；
   5. 用 服务端时间 为准（可借 server_time 校正本地时钟），若 now > g + clock_skew → 宽限已到期；
   6. 全部通过 → 允许继续离线运行，直到 until；期间持续重试心跳，一旦恢复立即用新票据刷新。

参考判断逻辑（伪代码）

ok = verify_es256(pubkey, "G1." + payload_b64, sig)
     && payload.m == sha16(machine_id)
     && payload.k == sha16(token)
     && now <= payload.g + clock_skew
if ok: run_offline_until(payload.g)
else:  return_to_login()

安全边界

配置项（config.php → grace）

密钥轮换：只要更换了 key_file（或删除让其重新生成），kid 随之改变，
客户端下次 init 时比对 kid 不一致即会重新拉取公钥；旧票据在此期间自然全部失效。

兼容性：本协议为纯增量能力。客户端完全不处理 grace 字段时，
行为与升级前一致（网络失败即掉线）；服务端未启用时也不会下发该字段。

2.17 官网互动接口

入口：POST /web/api.php?action=<接口名>，明文 JSON。
认证方式为浏览器会话 Cookie（NBWEBSID），与后台管理会话互不干扰。
写接口需带 X-CSRF 请求头（值取自页面注入的 window.__NB_WEB__.csrf）。

接口一览

| action | 说明 | 登录 | CSRF || ---------- | ------------------------------------ | :-: | :--: || plan | 价格套餐列表（仅 status=1，按 sort 倒序） | — | 免 || shot | 客户端截图列表（仅 status=1，只放行 http/https） | — | 免 || msg_list | 留言板列表（仅已审核通过的；分页，每页 10 条主楼） | — | 免 || msg_post | 发布留言 / 回复 | ✔ | ✔ || msg_like | 点赞 / 取消点赞（切换语义） | ✔ | ✔ || fb_types | 反馈类型选项 | — | 免 || fb_list | 我的反馈列表（仅返回本人） | ✔ | 免 || fb_post | 提交反馈 | ✔ | ✔ |

msg_list 响应结构（主楼 + 两层回复，一次取回避免 N+1）

{"code":0,"data":{"list":[{"id":12,"username":"星尘","content":"…","likes":3,
  "reply_to":"","mine":false,"liked":false,"created_at":"2026-09-10 20:00:00",
  "replies":[{"id":13,"username":"官方客服","content":"…","reply_to":"星尘",
              "likes":0,"mine":false,"liked":false,"created_at":"…"}]}],
  "total":1,"page":1,"pages":1}}

• mine / liked 仅在登录时有意义；匿名访问恒为 false
• 分页作用于主楼条数，回复随主楼一并返回

msg_post 参数与规则

• 落库 status = 0（待审核），响应 {"id":12,"pending":true}
• 只允许两层：parent_id 指向的留言其 parent_id 必须为 0，否则报「只支持两层回复」
• 限流：单账号 3 条 / 分钟

msg_like 参数：id（留言 ID，必须是已审核通过的）

• 响应 {"liked":true,"likes":4}；重复调用即取消点赞
• 靠 nb_message_likes(message_id,user_id) 唯一键兜底并发； 取消时用 GREATEST(likes,1)-1，计数永不为负
• 限流：单账号 30 次 / 分钟

fb_post 参数与规则

• 限流：单账号 5 条 / 小时
• 响应附带最新反馈列表，前端可直接重绘

fb_list 响应结构（状态与回复可见性）

{"code":0,"data":{"list":[{"id":3,"type":2,"type_text":"问题反馈",
  "title":"…","content":"…","contact":"","status":2,"status_text":"已回复",
  "reply":"…","reply_admin":"客服A","replied_at":"2026-09-10 20:10:00",
  "created_at":"2026-09-10 20:00:00"}],"types":{"1":"功能建议","2":"问题反馈",
  "3":"卡密/订单","4":"其他"}}}

• 状态：0 待处理 / 1 处理中 / 2 已回复 / 3 已关闭
• 隐私规则：只有状态为 2 或 3 时才下发 reply / reply_admin， 其余状态返回空串 —— 避免前端显示「空回复框」，也避免回复草稿外泄

审核策略：先审后显示

留言与回复提交后均为「待审核」，只有后台通过（status = 1）才会出现在 msg_list
与官网首屏。前端收到 pending:true 后会提示「已提交，通过审核后展示」，
避免用户误以为发送失败而重复提交。

优雅降级：若站点尚未执行 install/migrate_web_interact.php，
上述接口一律返回空列表（list: []），官网区块显示「暂无内容」，不会整页报错。
WebInteract::tableReady() 按请求缓存 SHOW TABLES 结果，避免重复查询。

三、管理后台接口

<后台目录> = 你站点上真实的后台目录名：安装向导会把默认的 admin/ 随机改名（消除被扫描的默认路径），实际值见 config/config.php 的 admin.path，下文一律用它代入；文档中出现的 admin 仅为占位示意。

接口入口：POST /<后台目录>/index.php?action=<接口名>
页面入口：GET /<后台目录>/home.php（输出管理界面）

3.1 认证方式

登录后返回 token，后续请求通过 请求头 传递：

X-Token: <管理员token>
X-CSRF:  <CSRF令牌>

管理端默认返回明文 JSON，便于前端 JS 处理。如需加密，请求体加 "encrypt": 1。

CSRF 令牌

所有写操作必须携带 CSRF 令牌（X-CSRF 头或 body 的 csrf 字段）。
令牌由页面入口 /<后台目录>/home.php 注入到 window.__NB__.csrf，并绑定当前 PHP session cookie。

• 只读接口（列表、详情、统计、导出等）豁免 CSRF 校验
• 令牌缺失或错误返回 code=1006

如果你的客户端不是浏览器（如脚本、自动化工具），需先 GET /<后台目录>/home.php
并保持 cookie，再从中提取 CSRF 令牌，后续请求同时带上 cookie 和令牌。

3.2 接口清单

登录方式配置项 login_methods

• 三选一，互斥；同时作用于客户端 /api/login 与官网 /web/api.php?action=login。
• 出厂默认写在 config/config.php 的 policy.login_methods，后台保存后以数据库 nb_settings 为准。
• 客户端通过 init 的 data.login 获知当前方式；切换后客户端需重新 init。
• code 方式下 register 自动关闭（返回 1004）。

策略项取值优先级（lib/Policy.php）

以下策略项由 Policy 统一取值，数据库优先、配置文件回退：

判定规则（Setting::isSet() 只查数据库，语义明确）：

• 数据库中不存在该键 → 使用 config/config.php 里的出厂值（未保存过的站点行为与升级前一致）
• 数据库中已存在该键 → 一律以库中值为准（即使值是 0 / 空串也算「已配置」）

setting_get 返回的 data.effective 会逐项给出 config / db / effective / source
四个字段，后台「系统设置 → 安全设置」下方的「当前生效值」面板据此展示，
可一眼确认改动是否已落到运行时。

补边界：heartbeat_interval / heartbeat_timeout / rate_limit_per_min 为 0 或非数字时
回落默认值；unbind_per_day 为负时归零（不限制）。

bigscreen — 数据大屏

请求

{
  "op": "data",     // data（默认）| flush_cache
  "days": 7,        // 趋势曲线天数（默认 7）
  "hours": 24       // 在线曲线小时数（默认 24）
}

op=flush_cache 会清空业务缓存键（心跳缓冲与统计缓冲除外），返回 { "count": <清空的键数> }。

响应 data 主要字段

runtime 是排查缓存 / 聚合问题的第一现场：心跳「缓冲不落库」属正常（等 cron 或阈值触发），
若长时间持续增长则说明 cron 未运行。

analytics — 留存复购

请求

{ "days": 30, "cohort_days": 7 }

响应主要字段

retention / repurchase / tier 的口径说明随响应一并返回（meta 字段），便于前端展示提示。

3.3 角色权限

权限在接口层校验（AdminAuth::READONLY_ACTIONS），不依赖前端隐藏按钮。
即使直接构造请求，只读角色也无法执行写操作。

3.3.1 批量操作接口说明

user_batch_op — 用户批量操作

{
  "op": "status | add_days | add_points | kick | delete",
  "ids": [1, 2, 3],
  "value": 0,          // status 时: 0封禁 1正常 2冻结
                       // add_days 时: 天数（可为负）
                       // add_points 时: 点数（可为负，结果不小于0）
  "password": "xxx"    // 仅 op=delete 需要，二次密码确认
}

单次最多 500 个用户。delete 仅超管可用，且需密码确认。

user_import — 用户批量导入

{
  "content": "用户名,密码,昵称,邮箱,会员天数,点数,设备上限\nuser1,pass123456,昵称,,30,100,2",
  "dup": "skip",       // skip=跳过已存在  update=更新已存在
  "default_days": 0    // CSV 未指定天数时的默认值
}

返回：{ ok, update, skip, fail, errors[] }

card_batch_op — 卡密批量操作

{ "op": "void | extend | delete_batch", "ids": [1,2,3], "days": 30, "batch_id": 5 }

• void：批量作废（仅影响未使用的卡密）
• extend：批量延长卡密自身有效期（永久卡不受影响）
• delete_batch：删除批次记录（未使用的卡密一并删除，已使用的保留）

device_ban — 拉黑机器码

{ "device_ids": [1,2], "reason": "异常刷接口", "days": 7 }

days=0 表示永久。拉黑同时会解绑设备并踢下线。

3.3.2 审计日志

audit_list 参数：

audit_detail 返回字段级变更：

{
  "audit": { "admin_name": "admin", "action_text": "编辑用户", "created_at": "..." },
  "changes": [
    { "field": "points", "label": "点数", "old": "10", "new": "110" },
    { "field": "vip_expire", "label": "会员到期", "old": "未激活", "new": "2026-12-31 00:00:00" }
  ]
}

密码类字段只记录「已设置/已修改」，不记录明文或哈希。

3.4 示例：管理员登录

curl -X POST "http://127.0.0.1/<后台目录>/index.php?action=login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin888"}'

响应：

{
  "code": 0,
  "msg": "登录成功",
  "data": {
    "token": "9f8e7d6c...",
    "expire_at": 1726007200,
    "admin": { "id": 1, "username": "admin", "nickname": "admin", "role": 1, "role_text": "超级管理员" }
  }
}

3.5 示例：生成卡密

curl -X POST "http://127.0.0.1/<后台目录>/index.php?action=card_generate" \
  -H "Content-Type: application/json" \
  -H "X-Token: 9f8e7d6c..." \
  -d '{
    "count": 100,
    "type": 1,
    "duration": 2592000,
    "max_devices": 2,
    "prefix": "VIP",
    "name": "国庆活动批次",
    "expire_days": 0
  }'

参数说明：

响应（只返回前 50 条预览）：

{
  "code": 0,
  "msg": "成功生成 100 张卡密",
  "data": {
    "batch_id": 3,
    "count": 100,
    "codes": ["VIP-AB12-CD34-EF56-GH78", "..."],
    "preview_count": 50,
    "type": 1,
    "duration": 2592000,
    "expire_at": 0
  }
}

完整卡密请通过 card_export 导出。

四、代理商后台接口（/agent/）

代理商（分销）拥有完全独立的后台，与主管理后台互不可见：

4.1 认证方式

与主后台一致：登录拿 token，后续请求带 X-Token，写操作再带 X-CSRF。
CSRF 令牌由页面入口 /agent/ 注入到 window.__NBAG__.csrf（绑定 NBAGSID 会话）。

4.2 接口清单

4.3 代理商注册（激活码）

代理商有两种来源：主管理员在后台创建，或凭「代理商激活码」自助注册。

• 主后台「业务管理 → 代理商激活码」生成激活码，码上写死了这些规格： 每种卡类型激活后进入的用户组（可按类型分别指定）、设备上限、是否允许作废、控量模式、 代理生成卡密的固定前缀、注册后赠予余额、每种卡类型的额度/单价、可用注册次数（max_uses，1 = 一次性）、有效期
• 注册接口把上述规格一次性复制到 nb_agents 与 nb_agent_types， 代理商登录后无法自改 —— 因此「卡密激活后进入哪个用户组」始终由主管理员决定
• 用户组取值优先级：该卡类型的 group_id（nb_agent_types.group_id）→ 代理兜底组（nb_agents.group_id）→ 0（不换组）
• 卡密前缀：激活码 / 代理档案上的 card_prefix 非空时，代理生成卡密一律强制使用此前缀 （card_generate 忽略代理提交的同名字段）；为空则不限制，仍由代理在 /agent/ 自行填写
• 注册后赠予余额（nb_agent_codes.init_balance，单位：分）：仅控量模式为 2（余额计费） 时生效， 注册时写入 nb_agents.balance，代理到手即可发货；其它模式一律写 0
• 注册成功后 nb_agents.reg_code 记录所用激活码，便于对账；主后台激活码列表直接显示「该码注册了哪些代理」
• 同一激活码并发注册用带条件的 UPDATE 消费次数（used_count < max_uses），不会超发； 注册过程任一步失败会把次数退回
• 失败码：2004 账号已被占用、2005 激活码无效/已停用、2006 可用次数已用完、2007 激活码已过期、 6003 后台已关闭自助注册
• 限流：同一 IP 10 分钟最多 5 次注册尝试

4.4 代理商充值卡密（续费 / 加量）

与「注册激活码」分工不同：激活码用于开户，充值卡密用于给已有代理续费 / 加量。
主后台「业务管理 → 代理商激活码 → 充值卡密」页签批量生成，代理商在 /agent/ → 「充值卡密」自助兑换。

• 表 nb_agent_recharge_codes：code / kind / amount（分）/ card_type / quota / quota_map（多卡类型张数 JSON，如 {"1":10,"2":-1}） / status / max_uses / used_count / expire_at / last_agent_id / last_used_at
• 多卡类型张数：kind=2 时优先读 quota_map，为空则回退旧字段 card_type + quota（单类型，兼容存量卡密）； 单类型卡密生成时也会顺带回写 card_type / quota。取值规则：0 = 该类型不充值（不入库）， -1 = 该类型设为「不限量」，小于 -1 收敛为 -1，非法卡类型直接丢弃；至少要有一种类型有效，否则拒绝生成
• 生成参数：count（≤200）、prefix（默认 RCG，形如 RCG-XXXX-XXXX）、kind、 amount_yuan（kind=1）、quota_map（kind=2，多类型） 或 card_type + quota（kind=2，单类型旧写法）、 max_uses（>1 可当通用充值码）、expire_days（0 = 永久）、remark
• 兑换：AgentRecharge::redeem() 在同一事务内先带条件 UPDATE 扣次数 （status=1 AND used_count < max_uses，防并发重复兑换），再按 quota_map 逐项入账， 最后写代理日志（action=recharge，明细形如「时长卡 +10 张、点数卡 设为不限量」）
• 已是「不限量」的类型再充值仍保持不限量（IF(quota_total < 0, -1, ...)）
• 已兑换过的卡密不可删除，只能停用（保留追溯）；停用 / 过期 / 次数用尽的卡密兑换时会被拒绝
• 代理端在「充值卡密」页可看到当前余额与各类型额度，兑换成功后即时刷新
• 升级脚本：php install/migrate_agent_recharge.php（建表）+ php install/migrate_recharge_quota_map.php（多类型，均可重复执行）

4.5 控量模式（nb_agents.charge_mode）与按卡类型计费

额度与单价按卡类型分别配置（nb_agent_types：agent_id + card_type 唯一），
nb_agents.quota_total / unit_price 为历史字段，自 v1.1 起不再参与计费。

| 值 | 名称 | 生成时的扣减规则 || - | ---- | ---------------------------------------------------------------------- || 1 | 张数额度 | 扣该卡类型的 quota_used；该类型 quota_total = -1 表示不限，enabled = 0 表示不开放此类型 || 2 | 余额计费 | 扣 balance（分）：该卡类型的单价 × 张数；类型单价为 0 时回落到「系统设置 → 代理商默认单价」 || 3 | 不限量 | 不扣减，仅记录归属与日志（仍要求该类型已开放） |

• 额度/余额的扣减使用带条件的 UPDATE 保证并发安全；生成失败（如卡密去重后为 0 张）会自动补偿退回
• 代理不能自定义「设备上限」「激活用户组（按卡类型）」「卡密固定前缀」与「各类型额度/单价」——统一取代理档案（或激活码预设）， 避免越权发放高权限卡密
• 余额计费下 Agent::typeList() 会为每种卡类型给出 can_make / can_make_text （= balance ÷ 该类型单价，不足一张按 0 计），代理端「发货规格」据此显示每种卡还能生成多少张
• 主后台「编辑代理商」与「生成激活码」表单都提供按卡类型的额度/单价/激活用户组矩阵； 充值走 agent_save 的 op=grant，提交 types: {"4": 2, "1": 1} 表示给永久卡 +2 张、时长卡 +1 张

4.6 生成卡密请求示例

{
  "count": 10,
  "type": 1,
  "duration": 30,
  "prefix": "VIP",
  "expire_days": 0,
  "name": "双十一批次",
  "remark": ""
}

• type：1 时长卡 / 2 点数卡 / 3 次数卡 / 4 永久卡（必须为该代理已开放的类型）
• duration：时长卡填天数（服务端换算为秒），其他类型填原始数值，永久卡可传 0
• 单次最多 500 张；生成限流：每分钟 10 次、每天 100 次

响应中的 data.codes 只返回前 50 条预览，data.cost 会说明本次扣的是哪个类型的额度或多少钱。

4.7 归属性

代理生成的卡密写入 nb_cards.agent_id，批次写入 nb_card_batches.agent_id：

• 主后台「卡密管理」可用 agent_id 筛选来源（'' 全部 / 0 官方直发 / >0 指定代理）
• card_export 同样支持 agent_id 参数
• 主后台删除代理商时，若其名下有卡密会被拒绝（避免归属变成野指针），需改为「禁用」
• 删除激活码时，若该码已被注册使用同样会被拒绝，需改为「停用」

4.8 相关系统设置

五、发卡网前台接口（/shop/）

发卡网前台为独立入口，无需后台会话。接口入口 /shop/api.php?action=，
买家会话为独立 Cookie（HttpOnly + SameSite=Lax）；登录方式跟随后台 login_methods
配置，登录/注册/找回均带图形验证码与 IP 限流。

支付回调 /shop/notify.php（易支付 POST）：MD5 验签 + 金额比对 + 幂等，
自动发货走事务 FOR UPDATE 取未使用卡密，缺货自动转人工。

六、安全说明

1. 固定 IV 的取舍：为便于客户端实现，IV 由密钥派生而非随机。这降低了语义安全性，但配合 HMAC 签名 + 时间戳 + nonce 防重放，已能抵御常见的抓包篡改与重放攻击。若需更高强度，可改为随机 IV 前置到密文（需同步修改客户端）。
2. 签名保护范围：签名覆盖 data 与时间戳、nonce，任何篡改都会导致校验失败。
3. 时间同步：客户端需保证系统时间准确，与服务端时差超过 time_window 会被拒绝（默认 300 秒）。
4. 限流策略：
   • 单 IP 每分钟 120 次通用接口调用
   • 单 IP 每分钟 10 次登录尝试
   • 单 IP 每分钟 20 次激活尝试
   • 单账号每日 3 次设备解绑
5. 密码存储：bcrypt（cost 10），兼容历史 md5 哈希自动升级。 管理员密码要求至少 8 位且含字母和数字；改密后该账号所有旧会话立即失效。
6. 管理端防护：
   • CSRF：写操作校验令牌（X-CSRF），只读接口豁免
   • 入口密钥：可配置 admin.entry_key，访问后台需带 ?k=密钥，错误时返回 404 不暴露后台
   • IP 白名单：可限制后台访问来源 IP
   • 二次密码确认：删除类敏感操作需重新输入管理密码
   • 登录防爆破：连续失败 N 次锁定账号（默认 5 次 / 15 分钟），失败尝试记录来源 IP
   • 审计追溯：所有写操作记录操作人、IP、UA、时间及字段级变更前后值
   • 会话隔离：管理端令牌存独立表（nb_admin_sessions），与用户会话互不影响
   • 代理商隔离：代理商使用 nb_agents + nb_agent_sessions + NBAGSID 会话， 仅能操作 agent_id 归属自己的卡密（作废、导出均做强校验），且无法自定义设备上限、用户组与各类型额度单价
   • 激活码即开户凭证：代理自助注册必须持有主管理员生成的激活码， 注册次数用条件 UPDATE 消费（不会超发），已注册过的码禁止删除（保留追溯）
   • 密钥不落地：AES 密钥只存在服务端配置，前端页面仅注入随机化的会话标识
7. 跨域：默认关闭（cors_origins 为空数组）。需要跨域时填具体域名，不要用 *， 因为管理端使用凭据（cookie + token），通配来源会导致凭据泄露。
8. 前端源码保护：
   • 界面逻辑按模块拆分到 admin/assets/js/，不内联在页面里
   • 接口地址、会话 key、CSRF 令牌由 PHP 动态注入，不硬编码在静态 JS 中
   • 敏感配置（密钥、盐值）从不下发到前端
9. 生产环境建议：
   • 使用 HTTPS，避免密钥在传输中暴露
   • 将 enforce_crypto 保持为 true
   • 修改后台目录名（mv admin manage_xxxx）
   • 配置后台入口密钥（admin.entry_key）
   • 开启管理端 IP 白名单
   • 关闭 debug 与 log.record_raw
   • 删除 install 目录
10. 离线宽限票据：
    • 用 ECDSA P-256（ES256） 非对称签名，服务端只持有私钥，客户端只拿到公钥—— 公钥泄露无法伪造票据，与「对称密钥下发到客户端」的方案有本质区别。
    • 私钥落盘在 config/grace_keys.php，位于部署模板已 deny 的 config/ 目录内； 切勿把该文件泄露给客户端或提交到公开仓库。
    • 票面绑定 user_id + 机器码摘要 + 会话令牌摘要 + 会员到期，换机器 / 换会话 / 篡改任一字段均验签失败。
    • 宽限只延长离线运行时间，联网后立即以服务端判定为准，不会成为「永久绕过封号」的后门。
    • 需要立即使所有已下发票据失效时：删除 config/grace_keys.php（服务端会自动重新生成密钥）， 或把 grace.seconds 设为 0 关闭该能力。
11. 缓存与聚合：
    • 缓存只存派生数据与计数（在线缓冲、心跳缓冲、统计缓冲、热点配置），不缓存明文密码等敏感字段。
    • Redis 未设密码时只监听内网 / 本机（127.0.0.1），切勿把无密码 Redis 暴露到公网。
    • 文件缓存落在 logs/cache，依赖部署模板对 logs/ 目录的整目录 deny； 若自行改动缓存目录，务必同步补充 deny 规则。
    • 心跳缓冲 / 统计缓冲不落业务数据，即使缓存整体丢失，也只会造成少量在线时长统计偏差， 不影响登录、激活、计费等核心链路（每个请求的判定仍实时读库）。