yunmei
098125164d
架构核对发现 2 处差距，本次补齐： - Kafka 上行支持 SSL/SASL_SSL 双向 mTLS（8.2 服务间 mTLS 边缘网关↔总线） - 网关日志支持结构化 JSON 输出（NFR 可维护：统一日志规范） - 配置示例与 README 验收口径同步更新
68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
# iAOP-Core · 边缘采集网关（Edge Gateway）模板化封装
|
||
|
||
对应 PRD 5.1「① 边缘采集网关」与 NFR 第 9 章。本模块把化工 AI 边缘网关
|
||
改造成**模板化**实现：协议可插拔、采集配置全部外置（点位字典 CSV + YAML），
|
||
严格**只读**采集（DCS / PLC / 称重 / 能源表），Kafka 流式上行，
|
||
断点续传 + 本地 spool 缓存 + 背压保护，并实时统计健康度指标。
|
||
|
||
## 验收口径（PRD 5.1 / 9 章）
|
||
|
||
| 指标 | 目标 | 实现落点 |
|
||
|------|------|----------|
|
||
| 采集 P99 延迟 | ≤ 1.8s（600 点位 1Hz） | `collector/metrics.py` 统计，`engine.py` 调度 |
|
||
| 丢失率 | ≤ 0.02% | `collector/spool.py` 断点续传 + 背压丢弃计数 |
|
||
| 可用性 | ≥ 99.8% | `collector/metrics.py` 轮次成功率 |
|
||
| 安全-网络 | 严格只读、零控制指令；传输 mTLS | 驱动仅只读接口；`upstream/kafka_sink.py` 支持 SSL/SASL_SSL 双向 mTLS |
|
||
| 可维护 | 统一日志规范（结构化 JSON） | `main.py --log-json` 输出结构化 JSON 日志 |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
edge-gateway/
|
||
├── config/gateway.example.yaml # 采集配置外置示例（模板参数化）
|
||
├── point_dict/ # 点位字典：CSV schema + 导入 + 自动校验
|
||
│ ├── schema.py # 字段定义与约束（对齐 PRD 5.1 字段表）
|
||
│ ├── loader.py # CSV → 内存模型
|
||
│ └── validator.py # 校验：缺失字段 / 量纲 / 重复点号 / 采样率
|
||
├── drivers/ # 协议可插拔驱动（只读）
|
||
│ ├── base.py # 驱动抽象基类（唯一入口 read_points）
|
||
│ ├── opcua_driver.py # OPC UA（和利时 DCS 等）
|
||
│ ├── s7_driver.py # 西门子 S7-1200（python-snap7）
|
||
│ ├── modbus_driver.py # Modbus RTU/TCP（PLC / 称重仪表）
|
||
│ ├── weighing_driver.py # 称重终端
|
||
│ └── energy_driver.py # 能源表（电表等）
|
||
├── collector/
|
||
│ ├── engine.py # 周期采集调度引擎（只读 + 背压保护）
|
||
│ ├── spool.py # 本地缓存 + 断点续传（重启重发）
|
||
│ └── metrics.py # 健康度统计（丢失率 / P99 / 可用性）
|
||
├── upstream/kafka_sink.py # Kafka 流式上行（失败重试 + 确认删除 spool）
|
||
├── main.py # 入口：加载配置 → 校验点位 → 启动采集
|
||
└── tests/ # 单元测试（python -m unittest）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 1) 准备点位字典 CSV（字段见 point_dict/schema.py 与 PRD 5.1）
|
||
cp config/point_dict.example.csv /tmp/points.csv
|
||
|
||
# 2) 准备采集配置（复制示例并修改）
|
||
cp config/gateway.example.yaml /tmp/gateway.yaml
|
||
|
||
# 3) 运行（--dry-run 只做配置加载与点位校验，不启动采集）
|
||
python main.py --config /tmp/gateway.yaml --point-dict /tmp/points.csv --dry-run
|
||
|
||
# 4) 正式启动（采集 → spool → Kafka 上行）
|
||
python main.py --config /tmp/gateway.yaml --point-dict /tmp/points.csv
|
||
|
||
# 5) 测试
|
||
python -m unittest discover -s tests
|
||
```
|
||
|
||
## 模板化说明（换行业只改配置，不改代码）
|
||
|
||
- 点位范围 / 采样率 / 量纲：由**点位字典 CSV** 驱动（模板 → 行业点位集）。
|
||
- 协议选型与连接参数：由 `gateway.yaml` 的 `drivers` 段驱动（模板 → 行业协议栈）。
|
||
- Kafka topic 命名：`{template}.{device}.points`，随配置模板变化。
|
||
- 新增协议：实现 `drivers/base.py` 的 `Driver` 子类并注册即可，引擎与上行链路零改动。
|