Nebula Python SDK 接入文档

📚 本文属 Nebula 文档中心，相关文档：C++ SDK 接入 · API 接口

适用对象：Python SDK（定向分发获取，可附已编译的 Nebula.exe 示例程序）
SDK 组成：nebula/ 协议层（无 UI 依赖，可单独引用）+ nebula/ui/ Pygame 桌面登录界面

1. 概述

Nebula Python SDK 与 C++ 版协议同规格，内置：

  • 通信协议（Nebula 3.1）：ECDH P-256 会话握手 + AES-256-GCM 加密信封 + seq 单调防重放，与 C++ SDK 同规格——客户端零静态对称机密，会话失效自动重握手
  • 响应防伪造：响应 ES256|RS256 非对称验签——未配置公钥时 SDK 拒绝连接（防伪造服务器设计）
  • 完整流程：init → login（password / username_code / code 三种方式按后台下发自动适配）→ heartbeat → logout
  • 内置能力：完整性自校验、自动更新（下载 → hash+size 强校验 → 替换 → 重启）、弹窗/立即公告、版本/维护/被踢提示、功能密钥 NF1 数据包
  • 内置界面：440×420 无边框登录窗（自绘标题栏、系统级拖拽）+ 800×500 主窗（心跳接管，被踢/顶号自动回登录），接入方零 UI 代码

2. 环境要求

  • Python 3.10 ~ 3.13（⚠ Python 3.14 暂不可用：pygame 尚无对应预编译包，pip 会回退源码编译并因 distutils.msvccompiler 被移除而失败）
  • 依赖：pip install pygame cryptography（界面层 pygame ≥ 2.6，SDK 层 cryptography ≥ 42）

3. 五分钟接入

① 配置 nebula/config.py（唯一需要修改的文件）：kApiUrl / kAppKey / kRespSignPubKey / kTlsCertSha256，均可在后台「软件管理」与「系统设置 → 安全」复制。协议 3.1 起客户端不再持有 AES_KEY / SIGN_SALT，通信密钥由 ECDH 握手临时协商。

② 运行：python main.py —— 启动即后台 init（不卡界面），登录界面按服务器下发的登录方式自动切换；登录成功进入主窗并接管心跳，被踢/顶号自动回登录界面。

不想跑 Python 环境？包内附已编译的 Nebula.exe（PyInstaller 单文件），解压双击即可体验。测试卡密见本页顶部下载区。

4. 目录结构

TEXT
sdk-py/
├── main.py                    # 示例入口：登录窗 → 主窗 循环
├── nebula/
│   ├── config.py              # 接入方配置（唯一需要修改的文件）
│   ├── crypto.py              # ECDH P-256 / HKDF / AES-256-GCM / ES256 验签
│   ├── envelope.py            # 3.1 会话：握手 / GCM 信封 / seq 防重放 / 自动重握手
│   ├── client.py              # init / login / heartbeat / logout + 机器码
│   │                          #   + 自校验 / 自动更新 / 公告 / 内置提示
│   ├── device_fp.py           # 设备指纹（自动上报，无需接入方处理）
│   ├── feature.py             # 功能密钥数据包 NF1（seal / open_pack）
│   └── ui/                    # 登录窗 / 主窗 / 主题 / 绘图
├── docs/                      # 界面截图
├── test_smoke.py              # 联调自测（15 项断言）
└── test_ui_headless.py        # 界面 headless 测试

5. 独立使用 SDK（不带界面）

PY
from nebula import create_default_client

client = create_default_client()
ir = client.init()                      # InitResult：ok / site_name / login_spec / version ...
if ir.ok:
    lr = client.login("用户名", "密码")   # 按后台登录方式组装字段（卡密直登时 secret 即卡密）
    if lr.ok:
        # LoginResult：token / feature_key / user(vip_text, points, max_devices) ...
        client.start_heartbeat(lr.token, lambda hb: print(hb.remain_text))
        # ... 业务逻辑 ...
        client.logout(lr.token)
  • HeartbeatInfo 回调字段：remain_text / vip_expire / kick（后台踢出）/ force_offline（顶号）/ need_relogin（会话失效）——出现异常状态时 SDK 内置界面会自动回登录，独立使用时请自行处理
  • login_spec.method：password / username_code / code，决定 login 两个参数的含义

6. 内置提示与自定义 UI

版本过期 / 发现新版本 / 服务器维护 / 被踢下线 / 自校验失败等提示默认用系统 MessageBoxW 弹出（标题 = 软件名 + 场景后缀）。一行接管：

PY
client.set_ui_handler(lambda kind, msg: log(msg))
# kind 取值：popup / flash / version / update / maintain / kick / integrity

7. 公告

PY
client.popup_notices()    # 弹窗公告（type=2，每次登录提示）
client.flash_notices()    # 立即公告（type=3，看过即不再显示）
# 已读记录存 %APPDATA%\NebulaSDK\notices_<app_key>.txt，30 天自动清理

8. 完整性自校验与自动更新

PY
client.auto_update_optional = False   # 可选更新也自动安装（默认 False 只提示）
client.allow_insecure_update = False  # 仅接受 https 更新地址（默认 False）

if not client.enforce_self_integrity():   # 启动自校验（失败已弹窗）
    return
up = client.auto_update()             # 检测→下载→校验→替换→退出重启
if up.state == UpdateState.Applied:   # 即将重启，直接 return
    return
client.version_alert()                # 版本提示（强制更新返回 False）
  • 仅接受 https 更新地址；下载后 hash（SHA256/MD5 自动识别）+ size 双校验，不匹配即丢弃
  • 替换采用 cmd 替换脚本：等待旧进程退出 → move → 重启 → 清理自身；打包态校验/替换目标即 exe 本身
  • ⚠ 发版前必须在后台「版本管理」重新登记新 exe 的哈希与大小，否则自校验会拦下自己

9. 功能密钥 NF1

格式 NF1.<b64(iv+AES-256-CBC)>.<HMAC>，encrypt-then-MAC、先验签后解密，与服务端互通。密钥仅登录成功后随 lr.feature_key 下发（init 免验证接口不下发）。

PY
from nebula import feature

# 开发期制作（也可用服务端工具生成）
pack = feature.seal("核心逻辑数据".encode(), "你的功能密钥")

# 运行期：登录成功拿到 lr.feature_key → 解密随程序分发的核心数据
data, err = feature.open_pack(open("core.dat", "rb").read(), lr.feature_key)
if err:
    ...   # 密钥不对 / 数据被改，直接拒绝运行

防破解建议：核心数据 NF1 加密随程序分发，patch 掉登录判定也拿不到密钥，密文数据永远解不开。

10. 打包与测试

打包成 exe（无控制台窗口）：

SH
python -m pip install pyinstaller
python -m PyInstaller --noconfirm --clean --onefile --windowed --name Nebula main.py
# 产物 dist/Nebula.exe；credentials.ini 自动生成在 exe 同目录，升级覆盖不丢凭证

测试：

SH
python test_smoke.py          # SDK 联调：init/登录正负向/功能密钥三态/心跳/登出
python test_ui_headless.py    # 界面主循环 headless 测试
python tools/screenshot.py    # 重新生成界面截图

11. 防护差异与自行加固

Python 版不具备 C++ 版的壳保护（VMProtect / Themida 标记）与原生级防篡改加固，仅保留协议层安全（加密信封 + 响应验签 + 功能密钥）；且 PyInstaller 打包的程序易被反编译提取 .pyc。对防护强度要求高的软件建议选用 C++ SDK，或自行叠加：

  • Nuitka 编译为原生代码（显著提高反编译门槛，优于纯 PyInstaller 分发）
  • PyArmor 脚本加密混淆
  • 核心算法写成 C/C++ 扩展（.pyd），可再过壳
  • 关键判定移至服务端，客户端只收结果不做本地判定
  • 用足 SDK 已内置能力：完整性自校验（后台登记 file_hash）+ 功能密钥 NF1（核心数据封包分发）

安全注意：nebula/config.py 含通信密钥，勿随源码公开分发（公开 demo 使用占位值）；credentials.ini 明文保存账号密码，介意可去掉保存逻辑。