SDK 接入文档

让应用在启动时向本机国安盾面板要一次授权。面板统一持有登录态与权限,应用只连本机命名管道,不接触账号密码、不上传业务数据。支持 Python 三行接入,也提供完整协议规范供任意语言自行实现。

SDK 版本 1.1.3 面板要求 ≥ 1.0.130(建议 1.0.132) 系统 Windows 10 / 11 传输 本机命名管道

1概览与工作原理

先弄清楚 SDK 到底做了什么,再决定用哪种接入方式。

国安盾面板 SDK 是一个「本机授权代理」客户端。应用启动时向本机面板要一次授权,面板用自己的登录态去服务端换一张票据,校验通过应用才继续运行。应用不需要处理登录、令牌、续费、离线窗口——这些全部由面板统一负责。

一次授权的完整链路

  1. 应用启动:调用 status()(或直接用 require())。
  2. 连本机管道:面板不在运行,就用注册表里的安装路径以 --agent 静默拉起。
  3. 面板校验:调用方路径 → 管理员禁用名单 → 登录态 → 服务端签票。
  4. 返回结果:通过则返回票据并缓存;失败则返回错误码,应用退出。

面板会依次检查四件事,任何一项不通过就返回对应错误码:

  1. 调用方身份:发起请求的进程 exe 必须落在该应用的安装目录内,挡住随手写的冒名程序(IMPOSTOR)。
  2. 管理员禁用:该账号是否被后台停用了这个应用(DISABLED)。
  3. 登录态:面板必须已登录(NOT_LOGIN)。
  4. 服务端授权:向服务端校验该账号对这个应用的权限,并签发票据(NO_LICENSE / EXPIRED / NETWORK)。

两种接入方式

方式 A:Python SDK(推荐) 程序是 Python 写的,直接用 gad_sdk.py,三行代码接入。
方式 B:按协议自己实现 C++ / C# / Electron / Go 等,按协议规范连命名管道即可,不需要 SDK 源码。闭源程序同样适用。
接入不等于开源。SDK 是「本机授权客户端」代码,嵌进你的程序里运行,不会暴露你的业务源码,也不要求你公开任何东西。如果你连多带一个文件都不愿意,可以直接用协议规范自己实现。

适用与不适用

场景是否适用说明
自有源码、能加代码的程序适用A 轨,本文档描述的就是这条路径
Python(含 PyInstaller 打包)直接支持使用 gad_sdk.py
C++ / C# / Electron / Go / Rust协议支持按协议自己实现,约 50 行代码
完全没有源码的第三方 exe暂不支持需要后续「加密启动壳」方案,尚未开放

2快速开始(3 行接入)

以 Python 为例。整套流程 10 分钟内可以跑通。

前置条件

  • 目标机器已安装国安盾面板(下载安装包),并已登录账号。
  • 你已经在面板后台/市场里登记了这个应用,拿到了唯一的应用 ID(例如 wechat-multi)。应用 ID 只能用小写字母、数字、连字符。

第 1 步:把 SDK 放进程序目录

下载 gad_sdk.py,放到你的主程序同一目录(PyInstaller 打包时也会自动收进包内)。

第 2 步:在入口最前面加授权校验

要求:必须在创建任何窗口、启动任何业务逻辑之前执行。顺序反了,用户看到界面后程序才退出,体验会很差。

python
import sys
import gad_sdk

# 第二个参数是弹窗里显示的应用名;校验失败时 SDK 会自动弹提示并返回 False
if not gad_sdk.require("your-app-id", "你的应用名"):
    sys.exit(1)

# 通过之后才创建窗口 / 启动业务

第 3 步:验证

命令行跑一下 SDK 自测,能打印出管道名、面板路径、缓存路径和当前授权状态就说明打通了:

bat
python gad_sdk.py your-app-id

正常会输出类似:

text
管道名 : GuoAnDunPanel_S-1-5-21-...-1001
面板   : C:\Program Files\国安盾面板\GuoAnDunPanel.exe
缓存   : C:\Users\你\AppData\Local\GuoAnDun\grants\your-app-id.json
状态   : {"valid": true, "source": "handshake", "user": "your-name", ...}
三个必须遵守的规则
  • 校验放在最前面,不要等窗口出来再校验。
  • 不要吞掉返回值。返回 False 就必须退出,不要「先放行再说」。
  • 不要自己伪造 valid。票据由面板签发、绑定设备,改本地文件无效。

3接口调用方法

Python SDK 的全部公开接口。所有函数都是同步阻塞的,建议在 UI 线程启动前调用。

require(app_id, app_name=None, offline_hours=24, quiet=False) → bool

应用启动时调用这一个就够了。内部会走完整判定;不通过时自动弹窗说明原因(可用 quiet=True 关掉,改成自己弹)。

参数类型说明
app_idstr应用唯一标识,必须与清单一致
app_namestr / None弹窗标题里显示的名字,不传则用 app_id
offline_hoursint面板彻底连不上时允许的离线兜底小时数,默认 24;传 0 表示完全不允许离线
quietboolTrue 时不弹窗,只返回结果(命令行/无人值守场景)

返回 True 表示授权通过,可以继续;False 表示拒绝,必须退出。

status(app_id, offline_hours=24) → dict

只判定、不弹窗。适合需要自己控制提示样式的程序(游戏、Electron、C# 等)。

返回字段说明
validbool,是否放行
sourcehandshake(实时握手)/ cache(面板连不上时的离线兜底)
code成功为 OK,失败见错误码表
msg可直接展示给用户的中文说明
user当前登录的面板账号
expire授权到期时间(付费应用有意义)
from_cache票据是否来自面板的离线缓存

handshake(app_id) → dict

只做一次握手,返回面板的原始应答(含 ticket / expire / issued / offline_hours)。一般不需要直接调用,status() 已经封装。

heartbeat(app_id, launch=False) → dict 1.1.3 新增

运行期复查授权。启动时用 require() 管入场,程序跑起来之后用 heartbeat() 定时复查——这样账号在别的电脑登录、把本机顶下线时,你的程序能自动退出,而不是一直挂到用户手动关闭(这正是「一台设备」授权约定的要求)。

返回含义你该怎么做
ok=True, revoked=False授权仍有效什么都不用做
ok=False, revoked=True面板明确判定失效:NOT_LOGIN(被顶下线/未登录)/ NO_LICENSE / EXPIRED / DISABLED / IMPOSTOR结束自己拉起的子进程,提示用户后退出程序
ok=False, revoked=False面板暂时连不上(PANEL_NOT_FOUND / NO_RESPONSE)不要退出——用户可能只是关了面板,等下一次心跳

与 status() 的两点区别:不做 24 小时缓存兜底(心跳要的是"现在还有效吗");默认不拉起面板(每 60 秒拉一次不合适,确有需要传 launch=True)。

python
def watch(app_id, on_revoke, interval=60):
    # 在主线程外起个后台线程,每 60 秒复查一次
    while True:
        time.sleep(interval)
        info = gad_sdk.heartbeat(app_id)
        if info["revoked"]:
            on_revoke(info)     # 结束子进程 + 提示 + 退出
            return

其余工具函数

函数作用
heartbeat(app_id, launch=False)运行期复查授权(1.1.3 新增,见上)
clear_cache(app_id)删除本地票据缓存,下次启动强制重新握手(排障用)
panel_exe()按注册表、常见安装目录的顺序定位面板 exe,找不到返回 None
cache_path(app_id)返回票据缓存文件路径
pipe_name()返回本机管道名(不含 \\.\pipe\ 前缀),多语言实现时用来对齐命名规则
SDK_VERSIONSDK 版本号常量,当前 "1.1.3"
为什么状态判定不缓存太久?从 1.1.2 起,status() 每次启动都会实时握手(面板没运行就把它拉起);24 小时缓存只在「面板彻底不可用」时兜底。这样面板在的时候,权限变更(禁用、到期)能立刻生效。

4协议规范(任意语言自行实现)

不想用 Python SDK?照这一节实现约 50 行代码即可,C++ / C# / Electron / Go 都适用。

4.1 通道

Windows 命名管道,名字规则:

text
\\.\pipe\GuoAnDunPanel_<SID>
  • <SID> 是当前登录用户的 SID,形如 S-1-5-21-1234567890-1234567890-1234567890-1001。
  • 取不到 SID 时,面板会退回用 <用户名>(环境变量 USERNAME)。你的实现也照这个回退即可。
  • 管道带 SID,是为了同机多用户同时登录时互不干扰。

取 SID 的常见写法:

text
C#   WindowsIdentity.GetCurrent().User.Value
C++  OpenProcessToken + GetTokenInformation(TokenUser) + ConvertSidToStringSidW
Node whoami /user /fo csv /nh   → 第二列是 SID
Go   同上,exec.Command("whoami", "/user", "/fo", "csv", "/nh")

4.2 报文格式

  • UTF-8 编码,一行一个 JSON,以 \n 结尾。
  • 客户端连上后发一行请求,面板回一行应答,然后主动断开。一次连接只处理一个请求。
  • 所有应答都有 v(协议版本,当前 1)和 ok(布尔)。

4.3 ping —— 探活

请求:

json
{"v":1,"cmd":"ping"}

应答:

json
{"v":1,"ok":true,"cmd":"ping","logged_in":true,"user":"your-name","panel":"1.0.132"}

用来判断面板是否在运行、是否已登录,不产生授权记录。

4.4 handshake —— 申请授权

请求:

json
{"v":1,"cmd":"handshake","app":"your-app-id"}

成功应答:

json
{"v":1,"ok":true,"cmd":"handshake","app":"your-app-id","code":"OK","msg":"",
 "ticket":"YmFzZTY0...","expire":"2026-11-22 06:44:14",
 "issued":1761968657,"offline_hours":24,"from_cache":false,"user":"your-name"}

失败应答:

json
{"v":1,"ok":false,"cmd":"handshake","app":"your-app-id",
 "code":"NOT_LOGIN","msg":"请先登录国安盾账号后使用"}

4.5 show —— 打开主面板

请求 {"v":1,"cmd":"show"},面板会从托盘代理切换成完整界面。一般只在「授权失败引导用户登录」时用得上。

4.6 票据格式(了解即可,不需要自己验签)

票据是 Base64 编码的一行文本:

text
base64( uid | app | expire | serverTime | device | HMAC-SHA256(payload) )
  • device 是设备指纹:票据拷到别的机器上无效。
  • 签名密钥只在服务端与面板内,接入应用不需要也不应该验签——面板已经把过关了。
  • 你只需要:拿到 ok:true 就放行,把票据原样存下来即可(可选,仅用于下次离线兜底)。
实现注意:读应答时按「读到换行」为一条完整报文,不要假设一次 read 就能读完;也不要一直等连接关闭(面板回完会断开,但 Windows 管道断开时机可能晚于数据到达)。

5错误码对照

按这张表决定「提示什么」和「要不要退出」。
code含义给用户的提示是否可离线兜底
OK授权通过——
NOT_LOGIN面板未登录请打开国安盾面板并登录账号后重试否
NO_LICENSE该账号未开通此应用(付费应用)该应用为会员专享,请联系客服开通否
EXPIRED授权已到期授权已到期,请续费后再使用否
DISABLED被管理员停用该应用已被管理员停用,请联系客服否
NETWORK面板拿不到服务端结果且无可用缓存网络不可用,请联网后重试面板内兜底
IMPOSTOR调用方进程不在该应用允许目录内请从面板应用市场安装本程序否
PANEL_NOT_FOUND本机没有安装面板请先安装国安盾面板并登录24h 缓存
NO_RESPONSE找到面板但握手无响应/超时无法连接面板,请确认面板能正常运行24h 缓存
BAD_PARAM缺少 app 参数或报文不是 JSON 对象(开发期错误)检查请求格式否
BAD_CMD未知命令(开发期错误)检查 cmd 字段否
UNKNOWN其他未分类失败按授权失败处理否
只对 PANEL_NOT_FOUND / NO_RESPONSE 做离线兜底。其余错误都是明确的拒绝(未登录、无权限、被停用、到期、冒名),绝不能用缓存放行,否则等于给绕过开口子。

6开发文档与排错

怎么配置、怎么用、报错怎么查。

6.1 需要配置的东西

配置项值 / 位置说明
应用 ID你自己的代码里,如 my-cleaner必须与上架清单 update/apps/<id>.json 的 id 完全一致
面板定位注册表 HKLM\SOFTWARE\GuoAnDunPanel\InstallPath安装版写入;绿色版回退 HKCU。SDK 已自动处理,一般不用管
票据缓存%LOCALAPPDATA%\GuoAnDun\grants\<app_id>.jsonSDK 自动读写;排障可删
管道名\\.\pipe\GuoAnDunPanel_<SID>SDK 自动拼;自己实现时按第 4 节

可选环境变量(一般不需要)

变量作用默认
GAD_AGENT_IDLE_SEC让被拉起的面板在空闲 N 秒后自动退出(仅调试用)不设置=常驻托盘
GAD_GRANT_REFRESH_SEC面板同步权限(禁用名单)的间隔秒数600

6.2 推荐的使用方式

如果是 GUI 程序,建议「先写日志、再弹窗」,否则弹窗是模态的,日志要等用户点确定才写,排障会很被动:

python
verdict = gad_sdk.status("your-app-id")
logger.info("授权%s:%s %s" % (
    "通过" if verdict["valid"] else "未通过",
    verdict.get("code", ""), verdict.get("msg", "")))

if not verdict["valid"]:
    gad_sdk.require("your-app-id", "你的应用名")   # 负责弹窗
    return 1

6.3 遇到错误怎么办

按下面顺序查,90% 的问题在第一步就能定位:

  1. 先跑自测:python gad_sdk.py your-app-id。它会打印管道名、面板路径、缓存路径和实时状态。
  2. 看错误码:对着第 5 节确认是「没登录」「没权限」还是「连接问题」。
  3. 看面板日志:%LOCALAPPDATA%\GuoAnDun\GuoAnDunPanel\app.log,搜 agent request / agent handshake。
现象多半原因怎么解决
PANEL_NOT_FOUND面板没装,或注册表里没有安装路径安装面板;绿色版首次运行一次让它写注册表
NO_RESPONSE管道名对不上(SID 取错)或面板卡住用 pipe_name() 打印实际名字;结束面板进程重开
IMPOSTOR你现在用源码/输出目录在跑,不是从市场安装的见下方 6.4
NOT_LOGIN面板没登录打开面板登录;或调用 show 把面板叫出来
DISABLED后台把这个账号的这个应用停用了后台「授权管理」里启用
弹窗后立刻退出、无任何日志校验写在了窗口创建之后把校验移到入口最前面
装好后双击没反应zip 里漏了依赖目录,或 exe 不在顶层见第 8 节的 zip 结构

6.4 为什么会 IMPOSTOR,怎么合法调试

面板会校验「调用你的进程的 exe 路径」。从市场安装的程序在登记目录里,正常。但你在 源码目录 / 输出目录 里直接跑时,exe 不在登记目录,就会被判 IMPOSTOR。

正规做法:

  • 开发期:联系面板维护方,把你的源码目录/构建输出目录加入调试白名单(仅开发机,正式环境不配置)。
  • 发布后:让用户从面板应用市场安装,安装目录会自动登记,无需任何额外配置。
面板没运行会不会失败?不会。SDK 会先用注册表里的安装路径把面板以 --agent 方式静默拉起(只在托盘留图标,不弹窗),再握手。用户不需要手动打开面板。

7示例代码

直接复制可用。Python 用 SDK,其他语言按协议实现。

7.1 Python 最小示例

python
import sys
import gad_sdk

if __name__ == "__main__":
    if not gad_sdk.require("your-app-id", "你的应用名"):
        sys.exit(1)
    # 正常启动你的程序
    main()

7.2 Python 完整示例(Tkinter,自己控制提示)

python
import sys, tkinter as tk
from tkinter import messagebox
import gad_sdk

APP_ID, APP_NAME = "your-app-id", "你的应用名"

def main():
    verdict = gad_sdk.status(APP_ID)
    if not verdict["valid"]:
        root = tk.Tk(); root.withdraw()
        messagebox.showerror("无法启动 " + APP_NAME,
                             "%s\n\n请打开国安盾面板并登录后重试。" % verdict.get("msg", "授权校验失败"),
                             parent=root)
        root.destroy()
        return 1
    root = tk.Tk()
    root.title(APP_NAME)
    tk.Label(root, text="授权通过,当前用户:%s" % verdict.get("user", "")).pack(padx=40, pady=30)
    root.mainloop()
    return 0

if __name__ == "__main__":
    sys.exit(main())

7.3 C#(WinForms / WPF)

csharp
using System;
using System.IO;
using System.IO.Pipes;
using System.Text;
using System.Text.Json;
using System.Security.Principal;

static class GadAuth
{
    static string PipeName()
    {
        string sid = WindowsIdentity.GetCurrent().User?.Value;
        return "GuoAnDunPanel_" + (string.IsNullOrEmpty(sid) ? Environment.UserName : sid);
    }

    // 返回 true 才允许继续运行
    public static bool Require(string appId)
    {
        try
        {
            using var pipe = new NamedPipeClientStream(".", PipeName(), PipeDirection.InOut);
            pipe.Connect(2000);
            var req = JsonSerializer.Serialize(new { v = 1, cmd = "handshake", app = appId });
            var bytes = Encoding.UTF8.GetBytes(req + "\n");
            pipe.Write(bytes, 0, bytes.Length);
            pipe.Flush();

            using var reader = new StreamReader(pipe, Encoding.UTF8);
            string line = reader.ReadLine();
            if (string.IsNullOrEmpty(line)) return Fail("NO_RESPONSE", "面板无响应");

            using var doc = JsonDocument.Parse(line);
            var root = doc.RootElement;
            bool ok = root.TryGetProperty("ok", out var okEl) && okEl.GetBoolean();
            if (ok) return true;
            string code = root.TryGetProperty("code", out var c) ? c.GetString() ?? "" : "";
            string msg  = root.TryGetProperty("msg",  out var m) ? m.GetString() ?? "" : "";
            return Fail(code, msg);
        }
        catch (TimeoutException) { return Fail("PANEL_NOT_FOUND", "未找到国安盾面板"); }
        catch (Exception ex)    { return Fail("NO_RESPONSE", ex.Message); }
    }

    static bool Fail(string code, string msg)
    {
        System.Windows.Forms.MessageBox.Show(
            msg + "\n\n请打开国安盾面板并登录后重试。(" + code + ")",
            "无法启动");
        return false;
    }
}

// 入口最前面:
// if (!GadAuth.Require("your-app-id")) return;

7.4 C++(Win32)

cpp
#include <windows.h>
#include <string>

static std::wstring PipePath() {
    wchar_t user[256] = {0}; DWORD n = 256;
    GetUserNameW(user, &n);                    // 取不到 SID 时的回退,与面板一致
    return std::wstring(L"\\\\.\\pipe\\GuoAnDunPanel_") + user;
}

bool GadHandshake(const char* appId, std::string* rawReply) {
    HANDLE h = CreateFileW(PipePath().c_str(), GENERIC_READ | GENERIC_WRITE, 0,
                           nullptr, OPEN_EXISTING, 0, nullptr);
    if (h == INVALID_HANDLE_VALUE) { *rawReply = "PANEL_NOT_FOUND"; return false; }

    std::string req = std::string("{\"v\":1,\"cmd\":\"handshake\",\"app\":\"") + appId + "\"}\n";
    DWORD written = 0;
    WriteFile(h, req.data(), (DWORD)req.size(), &written, nullptr);

    char buf[65536] = {0}; DWORD read = 0;
    ReadFile(h, buf, sizeof(buf) - 1, &read, nullptr);
    CloseHandle(h);

    *rawReply = std::string(buf, read);
    return rawReply->find("\"ok\":true") != std::string::npos;
}

// 入口最前面:
// std::string reply;
// if (!GadHandshake("your-app-id", &reply)) { MessageBoxA(0, reply.c_str(), "无法启动", 0); return 1; }

7.5 Node.js / Electron

javascript
const net = require("net");
const os = require("os");
const { execSync } = require("child_process");

function pipeName() {
  let sid = "";
  try {
    // 输出形如 "PC\user","S-1-5-21-..."
    sid = execSync("whoami /user /fo csv /nh", { encoding: "utf8" })
      .trim().split(",")[1].replace(/"/g, "");
  } catch (e) {}
  return "\\\\.\\pipe\\GuoAnDunPanel_" + (sid || os.userInfo().username);
}

function handshake(appId, timeoutMs = 3000) {
  return new Promise((resolve) => {
    const sock = net.connect(pipeName());
    let buf = "";
    const done = (r) => { try { sock.destroy(); } catch (e) {} resolve(r); };
    const timer = setTimeout(() => done({ ok: false, code: "NO_RESPONSE", msg: "timeout" }), timeoutMs);

    sock.on("connect", () =>
      sock.write(JSON.stringify({ v: 1, cmd: "handshake", app: appId }) + "\n"));

    sock.on("data", (d) => {
      buf += d.toString("utf8");
      const i = buf.indexOf("\n");
      if (i >= 0) {
        clearTimeout(timer);
        try { done(JSON.parse(buf.slice(0, i))); }
        catch (e) { done({ ok: false, code: "BAD_RESPONSE", msg: String(e) }); }
      }
    });

    sock.on("error", (e) => { clearTimeout(timer); done({ ok: false, code: "PANEL_NOT_FOUND", msg: e.message }); });
  });
}

// 主进程启动时:
// const r = await handshake("your-app-id");
// if (!r.ok) { dialog.showErrorBox("无法启动", r.msg || r.code); app.quit(); }

7.6 Go

go
package main

import (
    "bufio"
    "encoding/json"
    "fmt"
    "os"
    "os/exec"
    "strings"
)

func pipeName() string {
    if out, err := exec.Command("whoami", "/user", "/fo", "csv", "/nh").Output(); err == nil {
        parts := strings.Split(strings.TrimSpace(string(out)), ",")
        if len(parts) >= 2 {
            if sid := strings.Trim(parts[1], "\""); sid != "" {
                return `\\.\pipe\GuoAnDunPanel_` + sid
            }
        }
    }
    return `\\.\pipe\GuoAnDunPanel_` + os.Getenv("USERNAME")
}

func main() {
    f, err := os.OpenFile(pipeName(), os.O_RDWR, 0)
    if err != nil {
        fmt.Println("PANEL_NOT_FOUND:", err)
        os.Exit(1)
    }
    defer f.Close()

    req, _ := json.Marshal(map[string]any{"v": 1, "cmd": "handshake", "app": "your-app-id"})
    f.Write(append(req, '\n'))

    line, _ := bufio.NewReader(f).ReadString('\n')
    var resp map[string]any
    json.Unmarshal([]byte(line), &resp)

    if ok, _ := resp["ok"].(bool); !ok {
        fmt.Println("授权未通过:", resp["code"], resp["msg"])
        os.Exit(1)
    }
    fmt.Println("授权通过")
}
C++ / Go 示例取不到 SID 时用的是用户名回退。面板优先用 SID。若你的系统上 SDK 打印的管道名是 GuoAnDunPanel_S-1-5-...,而你的程序拼成了 GuoAnDunPanel_用户名,就连不上。生产环境请按 4.1 节正确取 SID。

8打包与上架

推荐用后台一键完成;没有后台权限时也可以手工放文件。

8.1 安装包(package.zip)结构

把主程序 exe 和它的依赖目录一起压缩,全部放在 zip 顶层,不要多套一层文件夹:

text
package.zip
├─ 你的程序.exe          ← launch 字段就填这个文件名
├─ _internal\            ← PyInstaller 依赖目录,原样一起压
│   └─ ...
└─ (其他 dll / 资源)
  • 不要只压 exe:漏了依赖目录,装好后双击会没反应。
  • 不要套外层文件夹:exe 必须在 zip 顶层。
  • sha256 和 size 按整个 zip 计算。

8.2 上架清单字段

字段必填说明
id是应用唯一标识,小写字母/数字/连字符,与代码里一致
name是市场显示名,1~40 字
version是语义化版本,如 1.1.2
launch是主程序 exe 文件名(相对安装目录)
url是安装包地址,形如 https://guoandun.com/download/apps/<id>/<ver>/package.zip
sha256 / size是整个 zip 的哈希与字节数,不一致会拒装
exeSize否exe 未压缩大小,仅用于界面展示
sdkVersion建议内置 SDK 版本;低于面板最低要求会在卡片上标「SDK 过旧」
minHostVersion建议要求的面板最低版本,接入 SDK 建议 1.0.130
paid / vis / price是免费:0 / free / 空;付费:1 / paid / 价格文案
category / icon / notes否分类、图标地址、更新说明

8.3 方式 A:用后台(推荐)

  1. 打开 https://guoandun.com/admin.html 登录。
  2. 「应用管理」→ 上传新应用:填应用 ID、名称、版本、SDK 版本号,选安装包和图标。
  3. 保存后系统自动算 sha256/size、写清单、挂到市场索引。

8.4 方式 B:手工放文件(无后台权限时)

#放什么位置
1安装包download/apps/<id>/<version>/package.zip
2应用清单update/apps/<id>.json
3市场条目update/index/page-1.json 的 apps 数组里加一条
4图标appicons/<id>.png(建议 256×256)

计算哈希(Windows 自带)

bat
certutil -hashfile package.zip SHA256
下载为什么要带 token?download/apps/ 目录禁止直链(直接访问返回 403)。面板下载时会改走 https://guoandun.com/api/download.php?app=<id>&ver=<ver>&file=package.zip&token=<登录令牌>,由服务端校验权限后再流式输出,并记录下载日志。你不需要自己拼这个地址,面板会自动处理。

9调试工具

SDK 自带命令行自测;配合面板日志可以定位绝大多数问题。

9.1 SDK 自测(内置)

直接运行 SDK 文件即可,会打印管道名、面板路径、缓存路径和实时状态:

bat
python gad_sdk.py your-app-id

9.2 管道连通性自检

python
import json, gad_sdk

print("管道名:", gad_sdk.pipe_name())
print("面板路径:", gad_sdk.panel_exe())
print("ping:", gad_sdk.handshake("your-app-id"))

9.3 面板日志

位置:%LOCALAPPDATA%\GuoAnDun\GuoAnDunPanel\app.log。搜这些关键字:

关键字含义
agent server listening面板的授权管道已就绪,后面是实际管道名
agent request收到了谁的请求,含 cmd 与 app
agent handshake握手结果:ok / code / 是否来自缓存 / 票据长度
拒绝冒名调用调用方路径不在允许目录(IMPOSTOR)
agent mode: tray shown (resident)面板以常驻代理方式在托盘运行

9.4 常用排障动作

  • 删缓存强制重新握手:python -c "import gad_sdk; gad_sdk.clear_cache('your-app-id')"
  • 确认面板在跑:任务管理器看 GuoAnDunPanel.exe;或在托盘找图标。
  • 面板路径不对:删掉注册表项后重新运行一次安装版/绿色版。

10可视化后台

10.1 应用管理

  • 上传新应用:填 ID、名称、版本、SDK 版本号,选安装包 + 图标,一键登记。
  • 编辑:改名称、描述、版本、价格、minHostVersion、sdkVersion。
  • 上架 / 下架:下架只从市场索引移除,清单保留(授权校验仍需要清单)。
  • 删除:连同清单一起删,慎用。

10.2 授权管理

按账号 × 应用粒度管理:可对任意账号启用/禁用任意应用(免费应用同样有效),也可设置到期时间。用户客户端会在同步周期(默认 10 分钟)内生效,下一次启动立即拦截。

10.3 最低 SDK 版本

服务端文件 update/sdk_min.json:

json
{ "minSdkVersion": "1.1.0" }

清单里声明了 sdkVersion 且低于该值的应用,市场卡片会标「SDK 过旧」。调整这个值即可全量提醒升级,无需重新发布面板。

10.4 下载记录

每次通过门禁下载都会写入 app_downloads(账号、应用、版本、IP、时间),可在后台查看异常下载。

11安全边界声明

请如实理解这套机制能做到什么、做不到什么。
这是「提高门槛」,不是「防破解」。它把「把程序拷走就能用」变成「必须过面板这一关」,能挡住普通用户和随手写的冒名程序;但本机管理员总有办法绕过。要做强防护,需要后续的加密启动壳或服务端一次性挑战。

已经做到的

措施作用
调用方进程路径校验发起握手的 exe 必须落在该应用的安装目录内,挡住冒名程序
票据设备绑定票据里带设备指纹,拷到别的机器无效
HMAC 签名改本地票据文件(比如把到期时间往后改)会验签失败
时钟回拨检测系统时间往回调超过 5 分钟即判定异常,要求联网
服务端实时校验禁用、到期、退款在同步周期内即可生效

明确不做的

  • 不读取账号密码:登录态只存在面板自己的数据目录里,应用连不到。
  • 不上传业务数据:握手只传应用 ID 与设备标识,不传程序数据、文件、截图。
  • 不修改系统:不装驱动、不注入进程、不改系统设置。

已知限制

  • 对象存储直链(302 外链)目前无法做强门禁,后续用签名 URL 解决。
  • 调用方身份识别失败时按放行处理(避免误伤合法应用),这是有意的取舍。

12下载与版本

SDK 本体与示例工程。
gad_sdk.py Python SDK 单文件,直接放进程序目录。
gad_sdk-1.1.3.zip SDK + 各语言示例 + README,解压即用。
国安盾面板安装包 接入与调试都需要先装面板并登录。

版本记录

版本变更
1.1.2每次启动实时握手(面板不在则自动拉起),缓存仅在面板不可用时兜底;修复启动时被安全软件误报的问题
1.1.1修复授权失败弹窗会残留一个空白窗口的问题
1.1.0首个公开版本:本机管道授权、24 小时离线、自动拉起面板
升级提示:SDK 升级只需替换程序目录里的 gad_sdk.py 并重新打包,无需改动你的业务代码。建议同时更新清单里的 sdkVersion 字段。