官方文档：GeWe API - GeWe API｜微信 API 开发文档

一、业务痛点与技术背景

微信自动化故障常表现为「用户说没回，日志却一片安静」。根因多是：

• 回调丢了但没有 Ingress 指标

• 发送 API 成功但业务没记投递单

• 多 appid 混部，告警无法定位账号

• 审计缺失，出事故无法追责到 Token/操作者

需要建立Logs · Metrics · Traces · Audit四位一体，覆盖从 Webhook 到 GeWe API 的全路径。

二、核心架构设计与数据流转

Ingress / Gateway / Worker / GeWeClient │ 结构化日志 (JSON) ▼ Log Agent → Loki / ELK │ Metrics → Prometheus → Grafana │ TraceId 贯穿 → OpenTelemetry │ Audit Event → 不可篡改存储 (对象锁 / WORM)

相关联 ID：trace_id→client_msg_id→appid→newMsgId。

三、关键代码与配置示例

3.1 结构化日志规范

{ "ts": "2026-03-29T08:01:02.123Z", "level": "info", "service": "gewe-outbound", "trace_id": "9f2c...", "appid": "wx_xxx", "client_msg_id": "ord_888", "event": "send_text_ok", "latency_ms": 842, "peer_hash": "sha256:ab12", "api_code": 0 }

注意：peer_hash用哈希，避免日志池散落明文 wxid；必要时另建受限审计库存明文。

3.2 OpenTelemetry 包裹 GeWe Client

import { trace, SpanStatusCode } from "@opentelemetry/api"; const tracer = trace.getTracer("gewe-client"); export async function geweInvoke(path: string, body: any) { return tracer.startActiveSpan(`gewe.${path}`, async (span) => { span.setAttribute("gewe.appid", body.appid ?? ""); span.setAttribute("gewe.client_msg_id", body.client_msg_id ?? ""); const start = Date.now(); try { const res = await http.post(path, body); span.setAttribute("gewe.api_code", res.data?.code ?? res.data?.ret); metrics.sendLatency.observe(Date.now() - start); return res.data; } catch (e: any) { span.setStatus({ code: SpanStatusCode.ERROR, message: e.message }); metrics.sendFail.inc({ path }); throw e; } finally { span.end(); } }); }

3.3 Prometheus 关键指标

gewe_webhook_ingest_total{result="ok|dedupe|error"} gewe_webhook_ack_latency_seconds_bucket gewe_outbound_queue_depth{appid,priority} gewe_send_total{appid,kind,result} gewe_send_latency_seconds{appid} gewe_node_online{appid} gewe_risk_decision_total{decision} gewe_breaker_open{appid}

3.4 Grafana 告警规则示例

groups: - name: gewe rules: - alert: GeWeWebhookAckSlow expr: histogram_quantile(0.99, sum(rate(gewe_webhook_ack_latency_seconds_bucket[5m])) by (le)) > 2 for: 5m labels: { severity: page } annotations: summary: "Webhook ACK p99 > 2s，存在丢回调风险" - alert: GeWeNodeOffline expr: gewe_node_online == 0 for: 3m labels: { severity: page } - alert: GeWeSendFailRate expr: sum(rate(gewe_send_total{result="fail"}[5m])) / sum(rate(gewe_send_total[5m])) > 0.1 for: 10m

3.5 审计事件模型

CREATE TABLE gewe_audit ( id BIGSERIAL PRIMARY KEY, ts TIMESTAMPTZ NOT NULL, actor VARCHAR(128) NOT NULL, -- user/system/token_id action VARCHAR(64) NOT NULL, -- send_text/add_friend/set_callback appid VARCHAR(64), client_msg_id VARCHAR(64), decision VARCHAR(32), detail JSONB NOT NULL ); CREATE INDEX ON gewe_audit (appid, ts DESC);

四、生产环境避坑与安全风控

1. ACK 延迟是最高优先级告警：超过 3s 直接丢消息（官方约束）。

2. 日志不要打印完整回调 Body 到低权限系统（含聊天内容）。

3. 控台变更审计：回调 URL、Token 轮换必须记 actor。

4. 拨测：定时用测试号互发，合成监控比纯指标更早发现通道问题。

5. 容量：队列深度按 appid 展示，避免全局平均掩盖单号堆积。

6. 配置与字段说明见文首官方文档。

五、本篇交付清单

• 四位一体可观测模型

• 日志字段 / Trace 包裹 / 指标集

• 关键告警规则

• 审计表结构