# 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 原始事件池时的期望字段参考。