给新客户开通协议授权（一步一步）

适用：新开一家客户 / 新一台服务器，要让他的系统能用我们的企微协议。全程约 10 分钟，你不用手动传任何大文件。

先分清三样东西（别混）

叫什么	在哪	干什么用
你的总控台	admin.zonqinhui.top（你的后台）	签发授权、吊销、续期、看谁在线 —— 你只在这里点鼠标
对方的网站服务器	客户自己那台（宝塔）	跑我们的 SCRM 程序（后端）
对方的协议服务	同一台机器上也行	跑协议 jar 的那个程序（端口常见 8083 / 9912）由我们远程帮他装

一句话：授权就是「把他那台机器的身份证号登记到你的总控台，再把一张许可证放回他机器上」。

登上对方的服务器（只要一次）

宝塔面板 → 左侧「终端」，或者你自己用 SSH 工具连上去。必须是 root（终端默认就是）。

下面所有命令都是整段复制 → 粘贴到终端 → 回车。

装协议服务（让他自己去你那里下载）

粘贴这两行（第二行末尾的 客户简称-公网IP 换成这家客户的名字和他的 IP，方便你以后认）：

# 第 1 行：下载安装脚本（注意是 -o 小写字母 o，不是 -O）
curl -fsSLo install.sh 'https://admin.zonqinhui.top/pub/protocol/dl?file=install.sh'
# 第 2 行：装。--addr 是这台机器在你的总控台里显示的名字
sh install.sh --url https://admin.zonqinhui.top --port 9912 --addr '客户简称-公网IP'

跑完之后你会看到类似这样的输出：

（前面会有一个下载进度条，107MB，大约 1~2 分钟）
FINGERPRINT {"addr":"客户简称-公网IP","host":"VM-xxx","jarPath":"/www/work/...jar","sha256":"003b3446...","port":9912}
PARITY match
   ✅ 跟母版一致 —— 这台协议机跑的就是母版那一份

这行的意思是：协议程序装好了，跑的是你母版上最新那一版。你全程没有传过文件 —— 是他的机器自己来你这里下载的。

如果这台机器上已经跑了两个协议（比如 9912 和 9913），第二行一定要带 --port 9912 点名，否则脚本会不知道该动哪一个而停下来。

抄下两个「机器身份证」

① 协议机指纹

curl http://127.0.0.1:9912/auth/machine-code

会回一行 {"errcode":0,"machineCode":"f8b8f947..."} —— 中间那串 32 位字符抄下来。

② 调用方指纹（他网站程序那台）

cd /www/wwwroot/他的站点目录
/www/server/nodejs/v20.20.2/bin/node -e "console.log(require('./server/machine-info.cjs').fingerprint())"

也会回一串 32 位字符，抄下来。（node 路径每台机器可能不同，宝塔「软件商店 → Node.js 版本管理器」里能看到；也可以直接问我。）

回你的总控台：签发

打开 admin.zonqinhui.top → 顶栏下面一行左边那个白色按钮 协议授权 → 拉到底部的表单，填：

字段	填什么
客户名称	写清楚是谁、哪台（例：某某酒业 · 134.175.43.200）
协议机机器指纹	第 3 步 ①那串（必填）
调用方机器指纹	第 3 步 ②那串（建议填；留空=谁都能调）
有效期（天）	默认 365，想给多久就填多少天
IP 白名单 / 绑定域名	留空就行（留空=不限，绑定靠上面两个指纹已经够了）

点 签发 / 保存。上面台账里会多出一行，带一个授权号（形如 PA-260928-XXXX）。

把许可证放回他的机器（两个位置）

点台账里那行的 授权文件 下载，得到一个文件 protocol-license.json（不到 1KB）。

用宝塔左侧「文件」把它上传（可以直接拖进去）到两个地方：

放到哪	典型路径	给谁读
协议服务的目录	`/www/work/`（jar 所在那个目录）	协议程序：判断「你有没有资格调我」
网站程序的根目录	`/www/wwwroot/他的站点/`	后端程序：给每个请求签名

放完不用重启，下一秒就生效。两个位置都要放，少放一个就还是连不上。

上传后，在宝塔文件管理器里右键这个文件 → 属性 → 所有者改成 www（不然程序写不进去，会报权限错误）。

省事版：如果嫌上传麻烦，也可以在他的协议服务环境变量里加一行 PROTOCOL_AUTH_CONSOLE=https://admin.zonqinhui.top，协议会自己来报到取证 —— 但网站根目录那一份还是必须放。

在他的后台填协议地址，点测试

他的 SCRM 后台 → 系统设置 → 企业微信接口配置 → 主接口地址填：

http://127.0.0.1:9912

（协议和他网站在同一台机器上就填 127.0.0.1；端口按实际装的填）
然后点 测试接口 —— 显示「连通 / 成功」就通了。

回你的总控台看结果

「协议授权」台账里那一行会显示：状态在线、从哪来（他的 IP）、有效期还剩多少天、几钟前报过到。

变绿 = 全部打通。以后停他、续期、看他在不在，都在这一个表里操作。

出问题看这里

现象	原因	怎么办
测试接口报「9401 缺少 X-PC-Auth 授权头」	他网站程序还是老版本（不会签名），或网站根目录没放许可证	先把他的后端升到最新版，再把许可证放进网站根目录
报「FINGERPRINT_MISMATCH 调用方指纹不符」	两家共用同一台协议机	一台协议机只认一份许可证 ⇒ 两家共用就把同一份文件都放上；想各用各的就各装一台协议
测试通了，但台账一直不显示「在线」	协议没配心跳地址	协议的环境变量加 `PROTOCOL_AUTH_CONSOLE=https://admin.zonqinhui.top`，重启协议一次
换服务器 / 重装系统后突然全 401	机器指纹变了	重新走第 3 步取新指纹，在第 4 步里改一下，重新下载许可证放回

以后怎么管

停掉谁：台账那行点「吊销」（最多 5 分钟生效；想立刻生效就删掉他协议目录下的许可证文件）
续期：点「编辑」→ 改天数 → 保存 → 重新下载许可证放回去（两个位置都要换）
恢复：吊销错了就点「恢复」
看谁在用：就是这个表 —— 客户名、从哪来（IP）、还剩几天、多久前报过到

最后更新：2026-09-29 · 有哪一步看不懂直接把截图发我。