1概览与工作原理
国安盾面板 SDK 是一个「本机授权代理」客户端。应用启动时向本机面板要一次授权,面板用自己的登录态去服务端换一张票据,校验通过应用才继续运行。应用不需要处理登录、令牌、续费、离线窗口——这些全部由面板统一负责。
一次授权的完整链路
- 应用启动:调用
status()(或直接用require())。 - 连本机管道:面板不在运行,就用注册表里的安装路径以
--agent静默拉起。 - 面板校验:调用方路径 → 管理员禁用名单 → 登录态 → 服务端签票。
- 返回结果:通过则返回票据并缓存;失败则返回错误码,应用退出。
面板会依次检查四件事,任何一项不通过就返回对应错误码:
- 调用方身份:发起请求的进程 exe 必须落在该应用的安装目录内,挡住随手写的冒名程序(
IMPOSTOR)。 - 管理员禁用:该账号是否被后台停用了这个应用(
DISABLED)。 - 登录态:面板必须已登录(
NOT_LOGIN)。 - 服务端授权:向服务端校验该账号对这个应用的权限,并签发票据(
NO_LICENSE/EXPIRED/NETWORK)。
两种接入方式
gad_sdk.py,三行代码接入。
适用与不适用
| 场景 | 是否适用 | 说明 |
|---|---|---|
| 自有源码、能加代码的程序 | 适用 | A 轨,本文档描述的就是这条路径 |
| Python(含 PyInstaller 打包) | 直接支持 | 使用 gad_sdk.py |
| C++ / C# / Electron / Go / Rust | 协议支持 | 按协议自己实现,约 50 行代码 |
| 完全没有源码的第三方 exe | 暂不支持 | 需要后续「加密启动壳」方案,尚未开放 |
2快速开始(3 行接入)
前置条件
- 目标机器已安装国安盾面板(下载安装包),并已登录账号。
- 你已经在面板后台/市场里登记了这个应用,拿到了唯一的应用 ID(例如
wechat-multi)。应用 ID 只能用小写字母、数字、连字符。
第 1 步:把 SDK 放进程序目录
下载 gad_sdk.py,放到你的主程序同一目录(PyInstaller 打包时也会自动收进包内)。
第 2 步:在入口最前面加授权校验
要求:必须在创建任何窗口、启动任何业务逻辑之前执行。顺序反了,用户看到界面后程序才退出,体验会很差。
import sys
import gad_sdk
# 第二个参数是弹窗里显示的应用名;校验失败时 SDK 会自动弹提示并返回 False
if not gad_sdk.require("your-app-id", "你的应用名"):
sys.exit(1)
# 通过之后才创建窗口 / 启动业务
第 3 步:验证
命令行跑一下 SDK 自测,能打印出管道名、面板路径、缓存路径和当前授权状态就说明打通了:
python gad_sdk.py your-app-id
正常会输出类似:
管道名 : 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接口调用方法
require(app_id, app_name=None, offline_hours=24, quiet=False) → bool
应用启动时调用这一个就够了。内部会走完整判定;不通过时自动弹窗说明原因(可用 quiet=True 关掉,改成自己弹)。
| 参数 | 类型 | 说明 |
|---|---|---|
app_id | str | 应用唯一标识,必须与清单一致 |
app_name | str / None | 弹窗标题里显示的名字,不传则用 app_id |
offline_hours | int | 面板彻底连不上时允许的离线兜底小时数,默认 24;传 0 表示完全不允许离线 |
quiet | bool | True 时不弹窗,只返回结果(命令行/无人值守场景) |
返回 True 表示授权通过,可以继续;False 表示拒绝,必须退出。
status(app_id, offline_hours=24) → dict
只判定、不弹窗。适合需要自己控制提示样式的程序(游戏、Electron、C# 等)。
| 返回字段 | 说明 |
|---|---|
valid | bool,是否放行 |
source | handshake(实时握手)/ 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)。
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_VERSION | SDK 版本号常量,当前 "1.1.3" |
status() 每次启动都会实时握手(面板没运行就把它拉起);24 小时缓存只在「面板彻底不可用」时兜底。这样面板在的时候,权限变更(禁用、到期)能立刻生效。4协议规范(任意语言自行实现)
4.1 通道
Windows 命名管道,名字规则:
\\.\pipe\GuoAnDunPanel_<SID>
<SID>是当前登录用户的 SID,形如S-1-5-21-1234567890-1234567890-1234567890-1001。- 取不到 SID 时,面板会退回用
<用户名>(环境变量USERNAME)。你的实现也照这个回退即可。 - 管道带 SID,是为了同机多用户同时登录时互不干扰。
取 SID 的常见写法:
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 —— 探活
请求:
{"v":1,"cmd":"ping"}
应答:
{"v":1,"ok":true,"cmd":"ping","logged_in":true,"user":"your-name","panel":"1.0.132"}
用来判断面板是否在运行、是否已登录,不产生授权记录。
4.4 handshake —— 申请授权
请求:
{"v":1,"cmd":"handshake","app":"your-app-id"}
成功应答:
{"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"}
失败应答:
{"v":1,"ok":false,"cmd":"handshake","app":"your-app-id",
"code":"NOT_LOGIN","msg":"请先登录国安盾账号后使用"}
4.5 show —— 打开主面板
请求 {"v":1,"cmd":"show"},面板会从托盘代理切换成完整界面。一般只在「授权失败引导用户登录」时用得上。
4.6 票据格式(了解即可,不需要自己验签)
票据是 Base64 编码的一行文本:
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>.json | SDK 自动读写;排障可删 |
| 管道名 | \\.\pipe\GuoAnDunPanel_<SID> | SDK 自动拼;自己实现时按第 4 节 |
可选环境变量(一般不需要)
| 变量 | 作用 | 默认 |
|---|---|---|
GAD_AGENT_IDLE_SEC | 让被拉起的面板在空闲 N 秒后自动退出(仅调试用) | 不设置=常驻托盘 |
GAD_GRANT_REFRESH_SEC | 面板同步权限(禁用名单)的间隔秒数 | 600 |
6.2 推荐的使用方式
如果是 GUI 程序,建议「先写日志、再弹窗」,否则弹窗是模态的,日志要等用户点确定才写,排障会很被动:
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% 的问题在第一步就能定位:
- 先跑自测:
python gad_sdk.py your-app-id。它会打印管道名、面板路径、缓存路径和实时状态。 - 看错误码:对着第 5 节确认是「没登录」「没权限」还是「连接问题」。
- 看面板日志:
%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。
正规做法:
- 开发期:联系面板维护方,把你的源码目录/构建输出目录加入调试白名单(仅开发机,正式环境不配置)。
- 发布后:让用户从面板应用市场安装,安装目录会自动登记,无需任何额外配置。
--agent 方式静默拉起(只在托盘留图标,不弹窗),再握手。用户不需要手动打开面板。7示例代码
7.1 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,自己控制提示)
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)
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)
#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
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
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("授权通过")
}
GuoAnDunPanel_S-1-5-...,而你的程序拼成了 GuoAnDunPanel_用户名,就连不上。生产环境请按 4.1 节正确取 SID。8打包与上架
8.1 安装包(package.zip)结构
把主程序 exe 和它的依赖目录一起压缩,全部放在 zip 顶层,不要多套一层文件夹:
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:用后台(推荐)
- 打开 https://guoandun.com/admin.html 登录。
- 「应用管理」→ 上传新应用:填应用 ID、名称、版本、SDK 版本号,选安装包和图标。
- 保存后系统自动算
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 自带)
certutil -hashfile package.zip SHA256
download/apps/ 目录禁止直链(直接访问返回 403)。面板下载时会改走 https://guoandun.com/api/download.php?app=<id>&ver=<ver>&file=package.zip&token=<登录令牌>,由服务端校验权限后再流式输出,并记录下载日志。你不需要自己拼这个地址,面板会自动处理。9调试工具
9.1 SDK 自测(内置)
直接运行 SDK 文件即可,会打印管道名、面板路径、缓存路径和实时状态:
python gad_sdk.py your-app-id
9.2 管道连通性自检
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:
{ "minSdkVersion": "1.1.0" }
清单里声明了 sdkVersion 且低于该值的应用,市场卡片会标「SDK 过旧」。调整这个值即可全量提醒升级,无需重新发布面板。
10.4 下载记录
每次通过门禁下载都会写入 app_downloads(账号、应用、版本、IP、时间),可在后台查看异常下载。
11安全边界声明
已经做到的
| 措施 | 作用 |
|---|---|
| 调用方进程路径校验 | 发起握手的 exe 必须落在该应用的安装目录内,挡住冒名程序 |
| 票据设备绑定 | 票据里带设备指纹,拷到别的机器无效 |
| HMAC 签名 | 改本地票据文件(比如把到期时间往后改)会验签失败 |
| 时钟回拨检测 | 系统时间往回调超过 5 分钟即判定异常,要求联网 |
| 服务端实时校验 | 禁用、到期、退款在同步周期内即可生效 |
明确不做的
- 不读取账号密码:登录态只存在面板自己的数据目录里,应用连不到。
- 不上传业务数据:握手只传应用 ID 与设备标识,不传程序数据、文件、截图。
- 不修改系统:不装驱动、不注入进程、不改系统设置。
已知限制
- 对象存储直链(302 外链)目前无法做强门禁,后续用签名 URL 解决。
- 调用方身份识别失败时按放行处理(避免误伤合法应用),这是有意的取舍。
12下载与版本
版本记录
| 版本 | 变更 |
|---|---|
1.1.2 | 每次启动实时握手(面板不在则自动拉起),缓存仅在面板不可用时兜底;修复启动时被安全软件误报的问题 |
1.1.1 | 修复授权失败弹窗会残留一个空白窗口的问题 |
1.1.0 | 首个公开版本:本机管道授权、24 小时离线、自动拉起面板 |
gad_sdk.py 并重新打包,无需改动你的业务代码。建议同时更新清单里的 sdkVersion 字段。