官方文档平台介绍 - QiWe API企微 API 开发文档一、业务痛点与技术背景SCRM 出问题常被说成「企微又挂了」实则可能是回调 ACK 慢、网关熔断、某 guid 掉线、租户配额打满。没有统一可观测值班只能盲猜。企业场景还强调审计谁用哪个 Token、对哪个客户发了什么类型消息、是否经审批。二、核心架构设计与数据流转Ingress / Gateway / Flow Engine / QiWeClient │ trace_id tenant_id guid ▼ OTel Collector → Tempo/Jaeger Metrics → Prometheus → Grafana Logs → Loki (脱敏) Audit → 专用审计库 (WORM/锁定桶)三、关键代码与配置示例3.1 日志字段标准{ ts: 2026-03-29T12:00:00Z, service: qiwe-gateway, tenant_id: t_10086, guid: g_xxx, trace_id: 4bf9..., client_msg_id: erp_ship_01, method: /msg/sendText, code: 0, latency_ms: 356, chat_type: user, to_hash: sha256:... }3.2 指标集qiwe_webhook_ack_seconds (histogram) qiwe_webhook_events_total{tenant,result} qiwe_outbound_queue_depth{guid,priority} qiwe_doapi_calls_total{method,code} qiwe_device_online{guid} qiwe_flow_instances_active{flow_id} qiwe_risk_blocks_total{reason}3.3 告警- alert: QiWeWebhookRisk expr: histogram_quantile(0.99, rate(qiwe_webhook_ack_seconds_bucket[5m])) 2 for: 3m annotations: { summary: 企微回调 ACK 过慢接近 3s 丢弃线 } - alert: QiWeDeviceOffline expr: qiwe_device_online 0 for: 5m - alert: QiWeDoApiErrorBudget expr: sum(rate(qiwe_doapi_calls_total{code!0}[10m])) / sum(rate(qiwe_doapi_calls_total[10m])) 0.053.4 审计查询示例SELECT ts, actor, method, guid, client_msg_id, code FROM qiwe_audit WHERE tenant_id $1 AND ts BETWEEN $2 AND $3 AND method LIKE /msg/% ORDER BY ts DESC;3.5 合成监控# 每 5 分钟探测号 A → 发文本到探测号 B并期望在 N 秒内收到回调事件 def synthetic_probe(): mid client.send_text(PROBE_GUID, PROBE_TO, fprobe {time.time()}) ok wait_event(matchermid, timeout30) metrics.probe.success(ok)四、生产环境避坑与安全风控聊天正文默认不进通用日志审计库单独授权。多租户面板全局成功率掩盖单租户事故必须可下钻tenant_id。回调配置变更进审计URL 被改是高危事件。仪表盘分层通道健康 / 业务 SOP / AI 质检分开。字段与回调行为以文首官方文档为准。五、本篇交付清单企业可观测四件套指标与告警审计查询合成探测