CoreC

主题

完整示例 ​

本页给出一份可直接使用的 CoreC 配置文件，每个段落附带注释说明。可将其作为 config.yaml 启动核心：

bash
./corec -c config.yaml

TIP

完整文件见仓库根目录 config.example.yaml。本页在其基础上补充了逐段讲解。

配置总览 ​

CoreC 配置采用 YAML，顶层段如下：

段作用必填对应文档
node拓扑自动发现（节点身份、上游订阅）否链式核心 → 自动发现
global核心全局设置（日志、API、引擎调优）否全局配置
drivers南向采集驱动列表否驱动配置
transports北向传输通道列表（mqtt / http / notify）否传输配置
rules数据路由与处理规则否规则配置
rule-providers外部规则集提供者（RULE-SET:name 委托）否规则配置
rule-groups命名子规则组（SUB-RULE:name 委托）否规则配置
derived-tags派生标签（表达式计算的 KPI）否派生标签配置

空配置 / Idle 模式

drivers 与 transports 均非必填。CoreC 支持以仅含 global.api 的最小配置启动（idle 模式），再通过 Dashboard 从零配置全部业务。启动时若无数据源或无传输，日志会输出非阻塞告警（no data source configured / no transport configured），引擎以空管线安全运行。详见下方"空配置 / Idle 模式"小节。

INFO

node 段是可选的。省略时所有自动发现功能关闭。设置 node.id 后，MQTT 传输省略的 topic-template、command-topic 会自动生成；显式设置 data-topic 时省略的 parser 自动补全。

完整配置文件 ​

yaml
# ============================================================
# CoreC 配置示例
# 工业数据采集核心
# ============================================================

# ---------- 全局设置 ----------
global:
  log-level: info                    # 日志级别：debug/info/warn/warning/error/silent
  api:
    listen: 0.0.0.0:9090             # 管理 API 监听地址（未设置则不启用 API）
    secret: "corec-secret-token"     # 鉴权令牌（listen 设置时必填，至少 8 字符）
  engine:
    data-bus-size: 8192              # 内部数据通道容量
    # workers: 0                     # 处理协程数（0 = NumCPU，默认）
    shutdown-timeout: 30s            # 优雅关停超时
    error-throttle-window: 10s       # 错误日志抑制窗口
    default-tag-interval: 1s         # 标签未设 interval 时的回退周期
    on-bad-quality: mark-and-publish # 坏质量数据处理策略
    stale-threshold: 30s             # 数据陈旧判定阈值
    write-retry-count: 3             # 写入指令重试次数
  buffer:                            # 离线持久化缓冲（可选）
    enabled: false
    path: /var/lib/corec/buffer      # 缓冲文件目录（enabled=true 时必填）
    max-size: 10000                  # 缓冲批次最大数量（超出驱逐最旧）

# ============================================================
# 南向驱动
# 支持: modbus-tcp, modbus-rtu, modbus-rtuovertcp, modbus-udp,
#       modbus-rtuoverudp, modbus-tls, s7, opcua
# ============================================================
drivers:
  # ---------- 1. Modbus TCP 驱动 (PLC / 传感器网关) ----------
  - name: plc-modbus                 # 驱动实例名，全局唯一
    type: modbus-tcp                 # 协议类型
    settings:
      host: 192.168.1.100            # 设备 IP
      port: 502                      # Modbus 标准端口
      slave-id: 1                    # 从站地址 (Modbus unit id)
      timeout: 3s                    # 读写超时
      retry: 3                       # 失败重试次数
    tags:
      - name: temperature            # 标签名
        address: "40001"             # 保持寄存器 0
        type: float32                # 数据类型
        group: sensors               # 分组
        interval: 1s                 # 采集周期
        deadband: 0.2                # 死区过滤，变化 <0.2 不输出
      - name: pressure
        address: "40003"             # 保持寄存器 2
        type: float32
        group: sensors
        interval: 1s
      - name: pump_status
        address: "00001"             # 线圈 0
        type: bool
        group: actuators
        interval: 2s

  # ---------- 2. Siemens S7 驱动 (S7-200 / S7-300 / S7-400 / S7-1200 / S7-1500) ----------
  - name: siemens-s7-300
    type: s7
    settings:
      host: 192.168.1.200
      port: 102                      # ISO-on-TCP 端口
      rack: 0                        # 机架号
      slot: 2                        # S7-300 用 2，S7-1200/1500 用 1
      timeout: 3s
    tags:
      - name: reactor_temp
        address: "DB1.DBD0"          # DB1 双字 0 (Float32)
        type: float32
        group: reactor
        interval: 500ms
      - name: motor_speed
        address: "DB1.DBW4"          # DB1 字 4 (Uint16)
        type: uint16
        group: motors
        interval: 1s
      - name: emergency_stop
        address: "I0.0"              # 输入位 0.0
        type: bool
        group: safety
        interval: 200ms

  # ---------- 3. OPC UA 客户端驱动 (SCADA / MES / OPC 服务器) ----------
  - name: opc-server
    type: opcua
    settings:
      endpoint: "opc.tcp://192.168.1.50:4840"   # OPC UA 端点
      mode: polling                  # polling 或 subscription
      timeout: 5s
    tags:
      - name: conveyor_speed
        address: "ns=2;s=Conveyor.Speed"        # 命名空间+字符串 NodeId
        type: float64
        group: conveyor
        interval: 1s
      - name: batch_count
        address: "ns=1;i=1001"       # 命名空间+数字 NodeId
        type: uint32
        group: production
        interval: 2s

# ============================================================
# 北向传输
# 支持: mqtt, http, notify
# ============================================================
transports:
  # ---------- 1. MQTT 云端传输 (发布 + 可选命令回写) ----------
  - name: cloud-mqtt
    type: mqtt
    settings:
      broker: tcp://broker.emqx.io:1883        # Broker 地址
      client-id: factory-edge-01               # 客户端 ID（需唯一）
      qos: 1                                   # 服务质量等级
      topic-template: "factory/{{.Driver}}/{{.Group}}/{{.Tag}}"  # 发布主题模板
      # 命令回写需成对配置（缺 command-secret 时传输拒绝启动）：
      # command-topic: "factory/commands/#"     # 订阅命令主题（支持通配符）
      # command-secret: ${COREC_COMMAND_SECRET} # 命令 HMAC-SHA256 认证密钥
    batch-size: 50                             # 单批最大点数
    flush-interval: 1s                         # 定时刷新间隔

  # ---------- 2. HTTP Webhook / REST 推送 (MES / 数据湖 API) ----------
  - name: mes-http-push
    type: http
    settings:
      url: "http://localhost:8080/api/v1/telemetry"   # 上游 API
      method: POST                                     # HTTP 方法
      headers:
        Authorization: "Bearer mes-secret-key"         # 鉴权头
      timeout: 3s                                      # 请求超时
    batch-size: 100
    flush-interval: 5s

# ============================================================
# 规则
# 按 priority 升序求值 (数值越小 = 优先级越高)
# 动作: forward, drop, alert, transform, mirror
# ============================================================
rules:
  # ---------- 1. 高温告警 -> 告警到云 MQTT，然后继续正常转发 ----------
  - name: high-temp-alert
    match: "tag == 'temperature' && value > 95"
    action: alert
    target: cloud-mqtt
    priority: 1
    continue: true              # 告警后继续评估，数据仍会流入下方兜底规则

  # ---------- 2. 急停 -> 高优先级告警 ----------
  - name: emergency-stop-alert
    match: "tag == 'emergency_stop' && value == true"
    action: alert
    target: cloud-mqtt
    priority: 2

  # ---------- 3. 安全与反应器数据 -> 镜像到 MQTT 与 MES 双通道 ----------
  - name: reactor-mirror
    match: "group == 'reactor'"
    action: mirror
    targets:
      - cloud-mqtt
      - mes-http-push
    priority: 10

  # ---------- 4. 兜底：其余全部转发到 MES HTTP ----------
  - name: default-catch-all
    match: "ALL"
    action: forward
    target: mes-http-push
    priority: 999

分段讲解 ​

global 段 ​

yaml
global:
  log-level: info
  api:
    listen: 0.0.0.0:9090
    secret: "corec-secret-token"
  engine:
    data-bus-size: 8192
    # workers: 0                     # 0 = NumCPU（默认）
    shutdown-timeout: 30s
    default-tag-interval: 1s
配置点说明
log-level: info生产推荐级别，排障时临时切 debug
api.listen管理 API 监听所有网卡的 9090 端口（未设置则不启用）
api.secretlisten 设置时必填，客户端以 Bearer 令牌鉴权
engine.data-bus-size内部数据通道容量 8192
engine.workers规则管道处理协程数
engine.default-tag-interval标签未设 interval 时的回退采集周期
engine.on-bad-quality坏质量数据处理策略（publish/drop/mark-and-publish/alert）
engine.stale-threshold数据陈旧判定阈值，超过此时间未更新的值标记 is_stale
engine.write-retry-count写入指令失败重试次数，耗尽后进入死信队列
buffer.enabled启用离线缓冲后，传输失败时数据落盘待回放

详见 全局配置。

drivers 段 ​

示例配置了三种典型驱动：

驱动协议设备关键设置
plc-modbusModbus TCP192.168.1.100slave-id: 1，保持寄存器与线圈混采
siemens-s7-300S7192.168.1.200slot: 2（S7-300），DB / I 区寻址
opc-serverOPC UA192.168.1.50mode: polling，字符串与数字 NodeId

TIP

注意各驱动标签的 interval 差异：安全相关量（emergency_stop）用 200ms 高频采集，普通量用 1s–2s，避免无谓的通信开销。

详见 驱动配置。

transports 段 ​

传输协议目标特点
cloud-mqttMQTTEMQX Broker主题按 驱动/分组/标签 分层；命令回写为可选能力（需成对配置 command-topic + command-secret）
mes-http-pushHTTP本地 MES APIBearer 鉴权，大批量低频率推送
yaml
topic-template: "factory/{{.Driver}}/{{.Group}}/{{.Tag}}"
# 实际渲染：factory/plc-modbus/sensors/temperature

详见 传输配置。

rules 段 ​

规则按 priority 升序求值，本例的路由策略为：

优先级规则命中条件动作
1high-temp-alert温度 > 95alert → cloud-mqtt，continue: true 后继续评估
2emergency-stop-alert急停触发alert → cloud-mqtt
10reactor-mirror反应器分组mirror → cloud-mqtt + mes-http-push
999default-catch-all全部forward → mes-http-push

高温点先触发告警，再由 continue: true 继续匹配，最终落入 default-catch-all 转发到 MES——告警与正常转发互不抢占。

WARNING

第 4 条 default-catch-all 是兜底规则。未匹配任何规则的数据点会被丢弃，因此务必保留一条 match: "ALL" 的低优先级规则。

详见 规则配置。

启动与验证 ​

将上述配置保存为 config.yaml，启动核心：

bash
./corec -c config.yaml

验证管理 API 可达：

bash
# 查看驱动列表
curl -H "Authorization: Bearer corec-secret-token" \
     http://localhost:9090/drivers

# 查看传输状态
curl -H "Authorization: Bearer corec-secret-token" \
     http://localhost:9090/transports

预期返回各驱动与传输的运行状态 JSON。更多接口见 API 参考。

INFO

若日志出现驱动 error 状态，请依次检查：设备网络可达性、slave-id / slot / endpoint 正确性、防火墙端口放行。

空配置 / Idle 模式 ​

CoreC 支持以空配置或仅含 global.api 的最小配置启动——无需任何 driver、transport 或 rule。引擎以空管线安全运行（scheduler 空转、处理 worker 阻塞在空数据总线、readiness 探针空载时返回 ready），运维随后通过 Dashboard 从零搭建全部业务配置。

最小配置 ​

config.example.yaml 的活动内容即为最小配置（其余示例全部注释掉）：

yaml
global:
  log-level: info
  api:
    listen: 0.0.0.0:9090
    secret: ${COREC_API_SECRET}    # ≥8 字符

启动：

bash
COREC_API_SECRET=change-me-please ./corec -c config.example.yaml

启动告警 ​

以上最小配置启动时，日志会输出两条非阻塞告警（WARN 级别，不影响启动）：

text
WARN no data source configured — running in idle mode; add a driver, an inbound transport (mqtt data-topic / http webhook-addr), or enable auto-discovery with node.subscribe via the Dashboard
WARN no transport configured — running in idle mode; add a northbound transport via the Dashboard

若连 global.api.listen 也未设置（完全空配置），还会额外输出一条控制面告警（control plane (global.api.listen) not configured ...）。

这些告警同时出现在 Dashboard 的日志流（/logs WebSocket）中，提示运维当前核心处于 idle 模式。

经 Dashboard 配置 ​

启动后打开 Dashboard 并连接到该实例的 API（http://<host>:9090，使用 api.secret 认证）。随后可通过：

  • 配置中心：编辑完整 YAML 并 PUT /configs 热重载；
  • 驱动 / 传输 / 规则向导：逐个添加实体，向导会在合并到工作配置后做本地校验（存在性校验已降级为非阻塞告警，不再阻止"先加第一个驱动"等鸡生蛋场景）。

每次 PUT /configs 应用一个仍无数据源 / 无传输的配置时，服务端会再次输出 idle 告警；一旦配置了数据源与传输，告警消失，核心进入正常采集状态。

INFO

api.secret 在 api.listen 设置时仍为硬性必填且不少于 8 字符——这是安全不变量，不因 idle 模式而放宽。其余硬校验（名称唯一、类型已注册、tag 字段合法、规则 target 引用等）同样保持不变。

Released under the MIT License.

Copyright © 2026 CoreC