官方文档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)相关联 IDtrace_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 Clientimport { 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{resultok|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{resultfail}[5m])) / sum(rate(gewe_send_total[5m])) 0.1 for: 10m3.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);四、生产环境避坑与安全风控ACK 延迟是最高优先级告警超过 3s 直接丢消息官方约束。日志不要打印完整回调 Body 到低权限系统含聊天内容。控台变更审计回调 URL、Token 轮换必须记 actor。拨测定时用测试号互发合成监控比纯指标更早发现通道问题。容量队列深度按 appid 展示避免全局平均掩盖单号堆积。配置与字段说明见文首官方文档。五、本篇交付清单四位一体可观测模型日志字段 / Trace 包裹 / 指标集关键告警规则审计表结构