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 Client（Node.js / TypeScript）
import 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 invoke<T>(path: string, body: Record<string, unknown>): Promise<T> { return this.breaker.fire(path, body) as Promise<T>; } }3.2 执行节点注册表（Redis）
export 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): Promise<ExecNode | 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}, headers=HEADERS, timeout=15) 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(f"appid={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 SaaS：SaaS 侧重转发不落敏感内容；强合规场景走私有化，并自建审计。
合规红线：使用正常实名账号，遵守平台规范与法律法规；禁止骚扰、诈骗等违规用途（见官方使用要求）。
熔断优先于重试：对登录类接口禁止无脑重试；对发送类接口用幂等键（业务单号）防重复触达。
五、本篇交付清单
Token 统一注入与 Client 封装
执行节点注册表与在线选举
登录态巡检 Worker
与官方文档对齐的接入路径
下一篇将展开：Webhook 回调在 3 秒 SLA 下的事件分发架构。
