使用前务必先克隆当前接口或者导出拉到最下面

WeChatPadPro 后台与接口使用说明

适用场景：在 adminmax.knowhub.cloud 后台获取密钥，完成 WeChatPadPro 服务端配置，并通过接口完成扫码登录与初始化。

前置条件

可以访问后台站点：https://adminmax.knowhub.cloud/

已具备 Redis 服务（示例：172.0.0.0:6379，密码 123456）

具备 WeChatPadPro 项目的源码与运行环境

说明：后台默认仅支持 Telegram 登录 或 GitHub 登录 两种方式；不支持注册。

一、后台登录与生成 TokenKey

打开后台首页：https://adminmax.knowhub.cloud/，通过 Telegram 或 GitHub 完成登录。

登录成功后进入 Token 管理 页面：
https://adminmax.knowhub.cloud/user/access-tokens

点击 生成 Token（或同等按钮），得到一个 TokenKey。

复制该 TokenKey，后续会在服务端配置与接口调用时使用。

套餐说明

后台提供不同的套餐可选：

登录后台后，在【套餐购买】页面可以查看并升级套餐，不同版本对应不同的 Key 上限。

二、服务端配置（conf/app.conf）

在项目的 conf/app.conf 中完成以下配置（示例）：

提示：若使用 Docker 或 K8s，请以环境变量或挂载文件的方式注入同等配置。

三、启动项目（Linux 二进制）

你当前使用的是 二进制启动：linux-amd64/wechatpadpromax08。建议采用如下目录结构与两种启动方式（临时 nohup 或持久化 systemd）。

目录结构示例

/opt/wechatpadpro/
├─ linux-amd64/
│  └─ wechatpadpromax08        # 可执行文件（Linux amd64）
├─ conf/
│  └─ app.conf                 # 前文已配置好 token_key_for_validate 与 Redis
└─ logs/
   └─ app.out                  # 运行日志

一次性部署

端口放通：默认示例端口为 8080（见 app.conf 的 httpport）。若有防火墙，放通入站 8080/TCP。

Ubuntu（UFW）：sudo ufw allow 8080/tcp

CentOS/RHEL（firewalld）：sudo firewall-cmd --add-port=8080/tcp --permanent && sudo firewall-cmd --reload

SELinux（如启用）请确保放通应用监听端口，或参照本机安全策略进行放行。

使用 systemd 持久化运行（推荐）

创建服务文件：/etc/systemd/system/wechatpadpro.service

加载并启动：

若你将 app.conf 放在其他路径，请确保二进制能读取到（通常为工作目录下的 conf/app.conf）。不同构建可能支持 -c/--config 等参数，如存在可按需追加到 ExecStart。

四、登录与初始化的完整接口流程

下述接口路径以项目约定为准；字段命名/请求方式以实际实现或 swagger 定义为准。示例仅用于理解流程。

1）生成设备 Token（/Admin/GenAuthKey）

作用：使用 token_key_for_validate 进行鉴权，换取当前设备的 Device Token，后续所有登录相关接口均需携带。

Endpoint：/Admin/GenAuthKey

鉴权：在 Header 中携带后台生成的 token_key_for_validate

返回：device_token（或等价字段）、有效期等

若该接口需要额外参数（例如设备名、设备 ID），请按实际实现传入。

2）获取登录二维码（/Login/GetQRMac）

作用：为当前设备下发一次性的二维码信息，用于微信扫码登录。

Endpoint：/Login/GetQRMac

鉴权：Header 携带 device_token

返回：uuid（本次扫码会话标识）、qr（二维码内容；可能是 URL 或 base64 图片）等

将返回的二维码渲染或直接展示给用户进行扫码。

3）轮询扫码状态（/Login/CheckMacQR）

作用：使用上一步的 uuid 轮询查询扫码状态，直到用户确认登录或超时。

Endpoint：/Login/CheckMacQR

请求参数：uuid=<从获取二维码返回的 uuid>

建议轮询频率：2~3 秒一次，注意超时与退避

典型状态：pending / scanned / confirmed / expired / success（以实际为准）

当返回表示 登录成功 的状态后，进入下一步初始化。

4）初始化（/Login/Newinit）

作用：完成会话初始化，返回与你账号绑定的微信侧关键信息。

Endpoint：/Login/Newinit

鉴权：携带 device_token（或项目要求的密钥）

返回：包含你的微信相关响应（如昵称、UIN、头像等字段，以实际为准）

若能拿到与你账号相关的微信响应，即表示全链路登录成功。

五、快速自检（cURL 示例）

下列仅为示例，字段名/头信息请按实际实现或 swagger 定义调整。

六、常见问题与排查

后台只能登录、不可注册？ 这是预期行为。目前仅支持 Telegram / GitHub 登录。

调用 /Admin/GenAuthKey 失败：

确认 token_key_for_validate 与后台生成的 TokenKey 一致；

检查是否放在正确的 Header（例如 Authorization 或项目自定义头）。

二维码无法展示：

若返回的是 base64，请确保前端按 data:image/png;base64, 前缀渲染；

若返回的是 URL，直接以图片/链接方式展示。

轮询无结果或超时：

确认 uuid 未过期；

适当降低轮询频率（2~3s），并实现超时与重试；

检查服务器时钟是否正确（时区/时间不同步会导致签名或过期判断异常）。

Redis 连接异常：

redislink 与 redispass 是否正确；

网络策略（如 Docker 网络、K8s Service、云防火墙）是否放通 6379 端口。

初始化成功但后续接口失败：

检查是否在 Header 中持续携带 device_token；

关注 Token 是否过期，必要时重新生成。

七、安全建议

妥善保管 TokenKey 与 Device Token，只在服务端保存与使用；

为不同环境（开发/测试/生产）分别生成 Token，并限制最小权限与有效期；

对登录与关键操作开启审计日志，方便定位问题；

对公网暴露的接口做好速率限制与 IP 访问控制；

Redis 建议设置强口令与仅内网访问，必要时启用 TLS。

如果你需要将本文档导出为独立的 .md 文件或补充 swagger 中的字段级说明，可在对话里告诉我，我会追加接口参数表与返回字段表。

WeChatPadPro 快速入门内测

使用前务必先克隆当前接口或者导出拉到最下面#

WeChatPadPro 后台与接口使用说明#

目录#

前置条件#

一、后台登录与生成 TokenKey#

#

套餐说明#

二、服务端配置（conf/app.conf）#

三、启动项目（Linux 二进制）#

目录结构示例#

一次性部署#

使用 systemd 持久化运行（推荐）#

四、登录与初始化的完整接口流程#

1）生成设备 Token（/Admin/GenAuthKey）#

2）获取登录二维码（/Login/GetQRMac）#

3）轮询扫码状态（/Login/CheckMacQR）#

4）初始化（/Login/Newinit）#

五、快速自检（cURL 示例）#

六、常见问题与排查#

七、安全建议#