任务执行1-19

doc/Syslog-Trap接入与重放.md

@@ -0,0 +1,87 @@
+# Syslog-Trap 接入与重放
+
+## 接入目标
+
+`logs` 服务负责接收 Syslog 与 SNMP Trap，按字典和规则解析后写入 `logs_events`，并通过 `logs_alert_outbox` 异步转发到 `alert` 的原始事件池：
+
+```text
+Syslog / Trap -> logs_events -> logs_alert_outbox -> Alert/v1/raw-events/ingest
+```
+
+转发使用 `X-Internal-Key`，配置来自 `AlertForward.internal_key`。解析成功的事件 `parse_status=parsed`，未命中字典或规则的事件仍保存原始报文，并以 `parse_status=unparsed` 入队，便于规则调整后重放。
+
+## 部署配置
+
+`logs` 当前内置 UDP 接收器：
+
+```yaml
+Ingest:
+  syslog_listen_addr: "0.0.0.0:5140"
+  trap_listen_addr: "0.0.0.0:1620"
+  rule_refresh_secs: 30
+
+AlertForward:
+  enabled: true
+  base_url: "http://127.0.0.1:18080"
+  internal_key: "change-me"
+  default_policy_id: 1
+```
+
+生产环境如需标准端口 `514/162`，建议由 systemd socket、firewalld rich rule、iptables REDIRECT 或外层采集网关转发到非特权端口。TCP Syslog 接入建议在网关层启用 TCP listener，再转发到 UDP 或调用后续 HTTP ingest 入口；开启 TCP 时必须保留原始来源 IP 和 trace ID。
+
+## 字典与规则
+
+Trap 字典字段：
+
+- `vendor`：厂商，例如 `H3C`。
+- `oid`：精确 Trap OID。
+- `oid_prefix`：OID 前缀，兼容旧字典。
+- `name` / `title`：展示名称。
+- `severity_mapping_json`：级别映射 JSON。
+- `parse_expression`：解析 varbind 的表达式或正则。
+
+Syslog 规则字段：
+
+- `source_match`：来源 IP、主机名或原始行子串。
+- `message_regex`：消息正文正则。
+- `severity_mapping_json`：按正则映射平台级别。
+- `resource_uid_extract_regex`：提取 `resource_uid`，优先使用命名分组 `resource_uid`。
+
+示例 Syslog：
+
+```text
+<189>Jun 24 10:00:01 h3c-core-01 IFNET/4/LINK_DOWN: Interface GigabitEthernet1/0/1 is down, resource_uid=network:h3c-core-01
+```
+
+示例 H3C Trap OID：
+
+```text
+1.3.6.1.6.3.1.1.5.3
+```
+
+## 未解析队列与重放
+
+未解析事件仍写入 `logs_events`，并创建 outbox payload：
+
+- `source_type=syslog` 或 `trap`
+- `parse_status=unparsed`
+- `raw_payload` 保存原始报文或 varbind 摘要
+
+重放接口：
+
+```http
+POST /Logs/v1/entries/{id}/replay
+Authorization: Bearer <jwt>
+```
+
+成功响应会返回新的 `outbox_id`。重放 payload 使用 `parse_status=replayed`，并带上 `labels.replay_of_log_event_id`，前端可在“日志查询 -> 重放结果”中查看发送结果，失败任务可人工重试。
+
+## Smoke 样例
+
+输出 H3C Syslog 与 Trap 示例载荷：
+
+```powershell
+C:\Users\27105\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe scripts\test_alert_receive_smoke.py --print-log-samples
+```
+
+这些样例用于准备 UDP/TCP 接收器 smoke 数据，也可作为联调 alert 原始事件池时的期望字段参考。