Zhi_Lian 网络验证 · 多语言对接文档

统一入口 /api/open · 37 类接口 · AES-256-GCM / ChaCha20-Poly1305 加密 · SHA256 / Ed25519 双签名方案

20 种语言示例 12 种已真实服务器实测零依赖优先开箱即用

📢 征稿：语言示例 · 采纳即赠 1 个月使用权

本 SDK 目前提供 20 种语言的对接示例（Python、Go、Java、C#、C、C++、Rust、Zig、Nim、Lua、按键精灵、懒人精灵、Lazarus、PureBasic、PHP、Kotlin、Swift、TypeScript/JavaScript、aardio、Delphi），其中部分示例尚未在真实服务器实测。现征集两类贡献，一经采纳均赠 1 个月使用权：

投稿一 · 新语言清单之外的语言（如 Ruby、Elixir、Dart/Flutter、PowerShell 等）对接示例：

✅ 按本页「协议总览」实现：统一入口 /api/open，加密与签名规范保持一致；
✅ 覆盖全部 34 个客户端接口，附带演示（获取公告即可验证连通）；
✅ 附带该语言的运行/编译说明与依赖清单。

投稿二 · 修正现有示例实测现有示例并修正问题（尤其标注未实测的几种）：

✅ 在真实服务器上完成「公告 / 公开效验 / 版本检测 / 更新地址」连通验证；
✅ 修复实测中发现的编译错误、加密签名偏差、平台 API 兼容问题；
✅ 提交修正后的代码 + 实测环境说明（语言/平台版本、验证截图或输出）。

奖励投稿经审核采纳收录进官方 SDK 后，赠送 1 个月使用权（新语言与修正均可，多投多得）。

投稿方式：联系管理员提交代码文件、实测记录与使用说明。收录时会保留/标注作者署名。

一、快速开始（三步）

后台「应用管理」拿到：App UUID、App Secret、AES 密钥、ChaCha20 密钥、验签公钥；
修改所选语言示例文件顶部的配置区；
运行示例 —— 默认演示获取公告(1)，公告能取到即对接成功（其余接口同一调用路径）。

提示：机器码在示例中为占位值，生产环境务必在客户端真实采集；扣点(28)务必带 biz_no 幂等标记防重复扣费。

二、协议总览

统一入口：POST {服务端地址}/api/open（Content-Type: application/json）

// 请求体
{
  "app_uuid":  "应用UUID",
  "api_type":  接口号(整数),
  "algorithm": 加密算法(0=明文, 1=AES-256-GCM, 2=ChaCha20-Poly1305),
  "data":      "按 algorithm 加密后的参数 JSON（base64）",
  "timestamp": 当前Unix秒,
  "sign":      签名
}

签名方案

方案 0（对称）：sign = SHA256("app_uuid|api_type|algorithm|data|timestamp|secret") 转大写 hex；
方案 1（Ed25519）：请求不签名，sign 填 32 位随机 hex nonce（服务端做时间窗 + 防重放）；响应携带 ed_sign 供客户端验签。

密文格式（两种算法相同）

base64( 12字节随机nonce + 密文 + 16字节tag )，key 为 32 字节（64 位 hex）。

响应体与验签

// 响应体：code 0=成功 / 2=强制更新拦截 / 其他=失败
{ "code": 0, "data": "加密结果(同请求算法)", "msg": "", "timestamp": "Unix秒", "sign" / "ed_sign": "" }
// 响应验签（方案0）：SHA256("code|data|msg|timestamp|secret") 大写 hex
// 响应验签（方案1）：Ed25519 验签 "code|data|msg|timestamp"

对接要点：响应里的 timestamp 是字符串（强类型语言按字符串处理再参与验签拼接，不要当数字读取）。

三、各语言示例与依赖

目录	语言 / 版本	加密支持	依赖	运行方式
`python/`	Python 3.8+	全部	requests, pycryptodome	`python debug_all_apis.py`（GUI 调试器）
`go/`	Go 1.21+	全部（含 Ed25519 验签）	golang.org/x/crypto	`go mod tidy && go run .` 已实测
`javascript-typescript/`	Node.js 18+	全部（内置 crypto）	无	`node zhilian.js` / `npx tsx zhilian.ts` 已实测
`php/`	PHP 7.2+	全部（sodium 内置）	curl 扩展	`php zhilian.php`
`java/`	JDK 17+	AES/ChaCha/SHA256（Ed25519 需 15+）	无（JDK 内置）	`java ZhiLianClient.java` 已实测
`C#/`	.NET 8	AES/ChaCha/SHA256	无	`dotnet run` 已实测
`kotlin/`	JDK 17 + Kotlin	同 Java	无（JDK 内置）	`gradle run` 或 IDE 运行
`swift/`	Swift 5.9+	全部（CryptoKit/swift-crypto）	无	`swift run`
`rust/`	Rust 1.75+	全部	reqwest / aes-gcm / chacha20poly1305 / ed25519-dalek 等	`cargo run --release` 已实测
`C++/`	C++17	AES/ChaCha/Ed25519	已内置 deps/（libcurl+LibreSSL 预编译 + json.hpp）	运行 `build.sh` 后 `./zhilian.exe` 已实测
`C/`	C99	AES/ChaCha/Ed25519	已内置 deps/（libcurl+LibreSSL 预编译 + cJSON）	运行 `build.sh` 后 `./zhilian.exe` 已实测
`delphi/`	Delphi 10.4+	AES-GCM（CNG）/明文，方案 0	无（Windows 内置）	IDE 打开编译
`zig/`	Zig 0.14+	全部（标准库）	无	`zig run main.zig` 已实测
`nim/`	Nim 2.x（Windows）	AES-GCM/SHA256（CNG）	无	`nim c -d:release -r zhilian.nim` 已实测
`lua/`	Lua 5.3+	明文+SHA256（纯 Lua）	LuaSocket	`lua zhilian.lua`
`lazarus/`	FPC 3.2+	AES-GCM（CNG）/明文，方案 0	无（Windows 内置）	IDE 编译运行已实测
`lanren/`	懒人精灵高级版（Lua）	明文+SHA256（纯 Lua）	懒人内置 HTTP	插件导入 `ZLSDK.lua`（未实测）
`anjian/`	按键精灵PC（Q 语言）	明文（sign=nonce）	WinHTTP 内置	放 lib 目录（未实测）
`purebasic/`	PureBasic 5.73+	AES-GCM/SHA256（内置）	无	IDE F5
`aardio/`	aardio 10+	明文（保证连通），方案 0	无	aardio 打开运行

已实测 = 已在真实服务器验证：获取公告 / 公开效验 / 版本检测 / 更新地址全部返回真实数据且响应验签通过。未标注的语言为源码交付（本机无对应运行环境），协议逻辑与已验证语言完全同源。

四、接口清单（与服务端 dispatch 完全一致）

类型	名称	关键参数
1	获取程序公告	-
2	获取更新地址	-
3	检测最新版本	version
4	获取卡密信息	card
5	卡密登录	card, machine_code, version, device_name, challenge
6	账号登录	username, password, machine_code, version, device_name, challenge
7	账号注册	username, password, email, code, card, machine_code
8	账号充值	username, card
9	发送注册验证码	email
10	领取试用	username, password
11	发送找回密码验证码	email
12	找回密码	email, code, new_password
13	退出登录	token
14	获取到期时间	token
15	检测账号状态（心跳）	token
16	获取程序数据	token
17	获取变量数据	token, alias
18	执行远程函数	token, alias, params(JSON)
19	获取账号数据	token
20	修改账号密码	token 或 username + old_password + new_password
21	转绑	username, password, machine_code, replace_machine, device_name
22	设置账号数据	token, data
23	封停用户	username
24	拉黑账号	username
25	扣除时间	username, minutes
26	WinLicense 授权下发	token, machine_code
28	扣减点数	token, amount, biz_no(幂等), remark
29	查询点数余额	token
30	设备试用登录	machine_code, version, device_name, email, code
31	发送设备试用验证码	email, machine_code
34	获取公开效验（挑战码）	machine_code
35	执行 LUA 函数	token, alias, params(JSON)
36	VMP 授权下发	token, vmp_hwid(VMP硬件ID，Base64)
37	在线支付下单	token(可空), tier_id
38	VMP 公钥配置下发	加密端专用
52	旧 IP 转绑	已废弃并入 21

五、安全建议

生产环境必须使用加密算法（1 或 2），明文仅限本地调试（服务端可按应用禁用明文）；
有条件优先用签名方案 1（Ed25519）：请求不带可伪造的对称签名，Secret 不参与请求签名；
机器码务必在客户端真实采集（示例中是占位值）；
扣点(28)务必带 biz_no 幂等标记，防止网络重试导致重复扣费；
响应的 ed_sign/sign 验签建议保留——能及时发现中间人篡改。

六、常见问题

提示「当前应用未允许明文传输」 → 应用已禁用明文，把 algorithm 改为 1 或 2；
「请求解密失败」 → 检查密钥 hex 是否完整（64 位）、密文是否为 nonce+密文+tag 完整拼接；
「会话无效或已被顶号」 → token 失效（过期/被顶/已退出），重新登录；
「请求已处理，请勿重复提交」 → 防重放命中（nonce 重复或时间窗外），重新生成 sign；
C/C++ 运行报缺 DLL → libcurl-x64.dll 需与 exe 同目录（build.sh 会自动复制）。