GeWe API 文档GeWe API微信 API 开发文档系列定位GeWe 全栈专栏 ·一、业务痛点与技术背景个人微信自动化落地时真正卡住团队的往往不是「发一条消息」而是连接底座不稳定痛点业务表现工程后果Token 硬编码 / 明文扩散多人共用同一 Key泄露后无法精确吊销登录态与业务强耦合扫码、掉线、重登混在业务代码里客服系统全线抖动多执行节点无统一抽象每个机器人一套脚本无法水平扩容缺少健康探测节点假在线消息静默失败GeWe 的核心抽象是Token 鉴权 执行节点设备级能力 标准 HTTP API。本文把它做成可生产复用的「连接底座」——后续 Webhook、消息、Agent、风控全部挂在这层之上。二、核心架构设计与数据流转┌─────────────┐ HTTPS/Token ┌──────────────┐ 执行指令 ┌─────────────┐ │ 业务服务集群 │ ─────────────────► │ GeWe Gateway │ ─────────────► │ 执行节点池 │ │ (SCRM/AI) │ ◄───────────────── │ (SaaS/私有化) │ ◄───────────── │ (微信会话) │ └─────────────┘ 登录态/结果 └──────────────┘ 回调事件 └─────────────┘ │ ▲ │ NodeRegistry / HealthCheck │ Webhook ▼ │ ┌─────────────────┐ ┌────────┴────────┐ │ Redis: node元数据│ │ 业务回调 Ingress │ │ 在线/限流/熔断 │ └─────────────────┘ └─────────────────┘数据流转要点控制台获取 Token → 写入密钥管理系统KMS / Vault / 环境变量加密禁止入库明文。登录执行节点 → 得到appid设备 ID与微信会话绑定关系。业务侧只认「逻辑机器人 ID」通过 NodeRegistry 映射到appid token。所有出站调用经统一 Client超时、重试、熔断、审计日志。控制台入口http://manager.geweapi.com。接入最小闭环见官方文档「快速开始」。三、关键代码与配置示例3.1 统一 HTTP ClientNode.js / TypeScriptimport axios, { AxiosInstance } from axios; import CircuitBreaker from opossum; export interface GeWeConfig { baseUrl: string; // SaaS 或私有化网关 token: string; // 切勿硬编码 defaultTimeoutMs: number; } export class GeWeClient { private http: AxiosInstance; private breaker: CircuitBreaker[string, unknown], unknown; constructor(private cfg: GeWeConfig) { this.http axios.create({ baseURL: cfg.baseUrl, timeout: cfg.defaultTimeoutMs, headers: { Content-Type: application/json, Authorization: Bearer ${cfg.token}, // 以实际文档 Header 为准 X-GEWE-TOKEN: cfg.token, }, }); this.breaker new CircuitBreaker( async (path: string, body: unknown) { const res await this.http.post(path, body); if (res.data?.ret ! 200 res.data?.code ! 0) { throw new Error(GeWeBizError: ${JSON.stringify(res.data)}); } return res.data; }, { timeout: cfg.defaultTimeoutMs, errorThresholdPercentage: 50, resetTimeout: 30_000 } ); } async invokeT(path: string, body: Recordstring, unknown): PromiseT { return this.breaker.fire(path, body) as PromiseT; } }3.2 执行节点注册表Redisexport type NodeStatus online | offline | warming | banned; export interface ExecNode { logicalId: string; // 业务侧机器人 ID appid: string; // GeWe 设备 ID wxid?: string; status: NodeStatus; region?: string; lastHeartbeatAt: number; qpsLimit: number; } export class NodeRegistry { constructor(private redis: Redis) {} key(logicalId: string) { return gewe:node:${logicalId}; } async upsert(node: ExecNode) { await this.redis.hset(this.key(node.logicalId), { ...node, lastHeartbeatAt: String(node.lastHeartbeatAt), qpsLimit: String(node.qpsLimit), }); await this.redis.sadd(gewe:nodes:all, node.logicalId); } async pickOnline(tag?: string): PromiseExecNode | null { const ids await this.redis.smembers(gewe:nodes:all); const candidates: ExecNode[] []; for (const id of ids) { const raw await this.redis.hgetall(this.key(id)); if (raw.status online) candidates.push(raw as unknown as ExecNode); } if (!candidates.length) return null; // 简单加权心跳越新越优先 candidates.sort((a, b) b.lastHeartbeatAt - a.lastHeartbeatAt); return candidates[0]; } }3.3 登录态巡检 Worker# login_watchdog.py import os, time, requests API os.environ[GEWE_BASE_URL] TOKEN os.environ[GEWE_TOKEN] HEADERS {X-GEWE-TOKEN: TOKEN, Content-Type: application/json} def check_online(appid: str) - bool: # 以文档「获取在线状态 / 登录信息」接口为准 r requests.post(f{API}/login/checkOnline, json{appid: appid}, headersHEADERS, timeout15) data r.json() return data.get(data, {}).get(online) is True def main(): appids os.environ[GEWE_APPIDS].split(,) while True: for appid in appids: ok check_online(appid.strip()) # 写 Prometheus / 推钉钉告警 / 更新 NodeRegistry print(fappid{appid} online{ok}) time.sleep(60) if __name__ __main__: main()3.4 最小闭环发第一条消息# 伪代码流程Token → 登录节点 → 发送文本 # 完整字段以文首官方文档为准 curl -X POST $GEWE_BASE_URL/message/postText \ -H Content-Type: application/json \ -H X-GEWE-TOKEN: $GEWE_TOKEN \ -d { appid: YOUR_APPID, toWxid: friend_wxid, content: 连接底座验证Hello GeWe }四、生产环境避坑与安全风控Token 生命周期按环境拆分dev/stage/prod泄露立即轮换CI 用短期凭证。登录窗口扫码有时效自动化部署中需「人工扫码 → 托管会话」两阶段不可阻塞主链路。假在线以「能发通探测消息 / 收到心跳事件」为准不要只信本地缓存状态。私有化 vs SaaSSaaS 侧重转发不落敏感内容强合规场景走私有化并自建审计。合规红线使用正常实名账号遵守平台规范与法律法规禁止骚扰、诈骗等违规用途见官方使用要求。熔断优先于重试对登录类接口禁止无脑重试对发送类接口用幂等键业务单号防重复触达。五、本篇交付清单Token 统一注入与 Client 封装执行节点注册表与在线选举登录态巡检 Worker与官方文档对齐的接入路径下一篇将展开Webhook 回调在 3 秒 SLA 下的事件分发架构。
个人微信API二次开发：从 Token 到执行节点的连接底座工程实践
GeWe API 文档GeWe API微信 API 开发文档系列定位GeWe 全栈专栏 ·一、业务痛点与技术背景个人微信自动化落地时真正卡住团队的往往不是「发一条消息」而是连接底座不稳定痛点业务表现工程后果Token 硬编码 / 明文扩散多人共用同一 Key泄露后无法精确吊销登录态与业务强耦合扫码、掉线、重登混在业务代码里客服系统全线抖动多执行节点无统一抽象每个机器人一套脚本无法水平扩容缺少健康探测节点假在线消息静默失败GeWe 的核心抽象是Token 鉴权 执行节点设备级能力 标准 HTTP API。本文把它做成可生产复用的「连接底座」——后续 Webhook、消息、Agent、风控全部挂在这层之上。二、核心架构设计与数据流转┌─────────────┐ HTTPS/Token ┌──────────────┐ 执行指令 ┌─────────────┐ │ 业务服务集群 │ ─────────────────► │ GeWe Gateway │ ─────────────► │ 执行节点池 │ │ (SCRM/AI) │ ◄───────────────── │ (SaaS/私有化) │ ◄───────────── │ (微信会话) │ └─────────────┘ 登录态/结果 └──────────────┘ 回调事件 └─────────────┘ │ ▲ │ NodeRegistry / HealthCheck │ Webhook ▼ │ ┌─────────────────┐ ┌────────┴────────┐ │ Redis: node元数据│ │ 业务回调 Ingress │ │ 在线/限流/熔断 │ └─────────────────┘ └─────────────────┘数据流转要点控制台获取 Token → 写入密钥管理系统KMS / Vault / 环境变量加密禁止入库明文。登录执行节点 → 得到appid设备 ID与微信会话绑定关系。业务侧只认「逻辑机器人 ID」通过 NodeRegistry 映射到appid token。所有出站调用经统一 Client超时、重试、熔断、审计日志。控制台入口http://manager.geweapi.com。接入最小闭环见官方文档「快速开始」。三、关键代码与配置示例3.1 统一 HTTP ClientNode.js / TypeScriptimport axios, { AxiosInstance } from axios; import CircuitBreaker from opossum; export interface GeWeConfig { baseUrl: string; // SaaS 或私有化网关 token: string; // 切勿硬编码 defaultTimeoutMs: number; } export class GeWeClient { private http: AxiosInstance; private breaker: CircuitBreaker[string, unknown], unknown; constructor(private cfg: GeWeConfig) { this.http axios.create({ baseURL: cfg.baseUrl, timeout: cfg.defaultTimeoutMs, headers: { Content-Type: application/json, Authorization: Bearer ${cfg.token}, // 以实际文档 Header 为准 X-GEWE-TOKEN: cfg.token, }, }); this.breaker new CircuitBreaker( async (path: string, body: unknown) { const res await this.http.post(path, body); if (res.data?.ret ! 200 res.data?.code ! 0) { throw new Error(GeWeBizError: ${JSON.stringify(res.data)}); } return res.data; }, { timeout: cfg.defaultTimeoutMs, errorThresholdPercentage: 50, resetTimeout: 30_000 } ); } async invokeT(path: string, body: Recordstring, unknown): PromiseT { return this.breaker.fire(path, body) as PromiseT; } }3.2 执行节点注册表Redisexport type NodeStatus online | offline | warming | banned; export interface ExecNode { logicalId: string; // 业务侧机器人 ID appid: string; // GeWe 设备 ID wxid?: string; status: NodeStatus; region?: string; lastHeartbeatAt: number; qpsLimit: number; } export class NodeRegistry { constructor(private redis: Redis) {} key(logicalId: string) { return gewe:node:${logicalId}; } async upsert(node: ExecNode) { await this.redis.hset(this.key(node.logicalId), { ...node, lastHeartbeatAt: String(node.lastHeartbeatAt), qpsLimit: String(node.qpsLimit), }); await this.redis.sadd(gewe:nodes:all, node.logicalId); } async pickOnline(tag?: string): PromiseExecNode | null { const ids await this.redis.smembers(gewe:nodes:all); const candidates: ExecNode[] []; for (const id of ids) { const raw await this.redis.hgetall(this.key(id)); if (raw.status online) candidates.push(raw as unknown as ExecNode); } if (!candidates.length) return null; // 简单加权心跳越新越优先 candidates.sort((a, b) b.lastHeartbeatAt - a.lastHeartbeatAt); return candidates[0]; } }3.3 登录态巡检 Worker# login_watchdog.py import os, time, requests API os.environ[GEWE_BASE_URL] TOKEN os.environ[GEWE_TOKEN] HEADERS {X-GEWE-TOKEN: TOKEN, Content-Type: application/json} def check_online(appid: str) - bool: # 以文档「获取在线状态 / 登录信息」接口为准 r requests.post(f{API}/login/checkOnline, json{appid: appid}, headersHEADERS, timeout15) data r.json() return data.get(data, {}).get(online) is True def main(): appids os.environ[GEWE_APPIDS].split(,) while True: for appid in appids: ok check_online(appid.strip()) # 写 Prometheus / 推钉钉告警 / 更新 NodeRegistry print(fappid{appid} online{ok}) time.sleep(60) if __name__ __main__: main()3.4 最小闭环发第一条消息# 伪代码流程Token → 登录节点 → 发送文本 # 完整字段以文首官方文档为准 curl -X POST $GEWE_BASE_URL/message/postText \ -H Content-Type: application/json \ -H X-GEWE-TOKEN: $GEWE_TOKEN \ -d { appid: YOUR_APPID, toWxid: friend_wxid, content: 连接底座验证Hello GeWe }四、生产环境避坑与安全风控Token 生命周期按环境拆分dev/stage/prod泄露立即轮换CI 用短期凭证。登录窗口扫码有时效自动化部署中需「人工扫码 → 托管会话」两阶段不可阻塞主链路。假在线以「能发通探测消息 / 收到心跳事件」为准不要只信本地缓存状态。私有化 vs SaaSSaaS 侧重转发不落敏感内容强合规场景走私有化并自建审计。合规红线使用正常实名账号遵守平台规范与法律法规禁止骚扰、诈骗等违规用途见官方使用要求。熔断优先于重试对登录类接口禁止无脑重试对发送类接口用幂等键业务单号防重复触达。五、本篇交付清单Token 统一注入与 Client 封装执行节点注册表与在线选举登录态巡检 Worker与官方文档对齐的接入路径下一篇将展开Webhook 回调在 3 秒 SLA 下的事件分发架构。