English: README.en.md
DataAcquisition 是一个基于 .NET 构建的工业级 PLC 数据采集系统。系统采用 WAL-first（写前日志）架构确保数据零丢失，支持 Edge-Central 分布式架构实现多车间集中管理。提供多 PLC 并行采集、条件触发采集、批量读取优化等高级功能，支持配置热更新和实时监控，开箱即用，运维友好。
技术栈：
- 运行时：.NET 10.0
- 数据存储：InfluxDB 2.x（时序数据库）+ Parquet（本地 WAL）
- 监控：Prometheus 指标 + Vue3 可视化界面
- 架构：Edge-Central 分布式架构
| 特性 | 说明 |
|---|---|
| 🔒 数据安全 | WAL-first 架构，所有数据先写入本地 Parquet 文件，确保零丢失 |
| 🔀 多协议支持 | 支持 Mitsubishi（三菱）、Inovance（汇川）、BeckhoffAds（倍福）等 PLC 协议 |
| ⚡ 高性能采集 | 多 PLC 并行采集，批量读取优化，减少网络往返 |
| 🎯 智能采集 | 支持条件触发采集（边沿触发、值变化触发）和持续采集两种模式 |
| 🔄 配置热更新 | JSON 配置文件 + 文件系统监控，修改配置无需重启服务 |
| 📊 实时监控 | Prometheus 指标暴露，Vue3 可视化界面，实时展示系统状态 |
| 💾 双存储策略 | InfluxDB 时序数据库 + Parquet 本地持久化（WAL） |
| 🔁 自动容错 | 网络异常自动重连，数据写入失败自动重试，保证数据完整性 |
系统采用 Edge-Central（边缘-中心）分布式架构，支持多车间、多节点的集中式管理和监控：
┌─────────────────────────────────────────┐
│ Central Web (Vue3) │
│ 可视化界面 / 监控面板 │
└───────────────────┬─────────────────────┘
│ HTTP/API
┌───────────────────▼─────────────────────┐
│ Central API │
│ • 边缘节点注册/心跳管理 │
│ • 遥测数据接入 │
│ • 查询与管理接口 │
│ • Prometheus 指标聚合 │
└───────┬─────────────────────┬───────────┘
│ │
┌─────────────┘ └───────────┐
│ │
┌─────────▼─────────┐ ┌──────────▼────────┐
│ Edge Agent #1 │ │ Edge Agent #N │
│ (Node 1) │ │ (Node N) │
└─────────┬─────────┘ └─────────┬─────────┘
│ │
└──────────────────────────────────────────────┘
每个 Edge Agent 采用分层架构设计，各层职责清晰，确保数据零丢失：
┌────────────────────────────┐ ┌──────────────────────────┐
│ PLC Device │──────▶ │ Heartbeat Monitor Layer │
└────────────────────────────┘ └──────────────────────────┘
│
▼
┌────────────────────────────┐
│ Data Acquisition Layer │
└────────────────────────────┘
│
▼
┌────────────────────────────┐
│ Queue Service Layer │
└────────────────────────────┘
│
▼
┌────────────────────────────┐
│ Storage Layer │
└────────────────────────────┘
│
▼
┌────────────────────────────┐ ┌──────────────────────────────┐
│ WAL Persistence │──────▶ │ Time-Series Database Storage │
└────────────────────────────┘ └──────────────────────────────┘
│ │
▼ │ Write Failed
┌────────────────────────────┐ │
│ Retry Worker │◀────────────────────┘
└────────────────────────────┘
- 数据采集阶段：PLC 设备 →
ChannelCollector（支持条件触发、批量读取优化） - 数据聚合阶段：
LocalQueueService按配置的BatchSize批量聚合数据 - 数据持久化阶段：
- Parquet WAL：立即写入本地 Parquet 文件（写前日志，确保零丢失）
- InfluxDB：同步写入时序数据库（主存储）
- 容错处理阶段：写入成功后删除 WAL 文件；写入失败时保留 WAL 文件，由
RetryWorker定期重试 - 数据上报阶段：可选地将数据上报到 Central API（用于集中式管理和监控）
- 节点注册阶段：Edge Agent 启动时自动向 Central API 注册节点信息（EdgeId、AgentBaseUrl、Hostname）
- 心跳上报阶段：周期性发送心跳信息（默认间隔 10 秒），包含队列积压量、错误信息等状态
- 遥测数据上报阶段：批量上报采集的时序数据到 Central API（可选功能）
- 监控查询阶段：Central Web 前端通过 Central API 查询各边缘节点的状态、指标和日志
DataAcquisition/
├── src/DataAcquisition.Application/ # 应用层 - 接口定义
│ ├── Abstractions/ # 核心接口抽象
│ └── PlcRuntime.cs # PLC 运行时
├── src/DataAcquisition.Contracts/ # 契约层 - 对外 DTO/协议模型
├── src/DataAcquisition.Domain/ # 领域层 - 核心模型
│ └── Models/ # 数据模型
├── src/DataAcquisition.Infrastructure/ # 基础设施层 - 实现
│ ├── Clients/ # PLC 客户端实现
│ ├── DataAcquisitions/ # 数据采集服务
│ ├── DataStorages/ # 数据存储服务
│ └── Metrics/ # 指标收集
├── src/DataAcquisition.Edge.Agent/ # Edge Agent - 车间侧采集后台 + 指标 + 本地 API
│ ├── Configs/ # 设备配置文件
│ └── Controllers/ # 管理 API 控制器
├── src/DataAcquisition.Central.Api/ # Central API - 中心侧 API（边缘注册/心跳/数据接入、查询与管理）
├── src/DataAcquisition.Central.Web/ # Central Web - 纯前端（Vue CLI / Vue3），通过 /api 访问 Central API
├── src/DataAcquisition.Simulator/ # PLC 模拟器 - 用于测试
│ ├── Simulator.cs # 模拟器核心逻辑
│ ├── Program.cs # 程序入口
│ └── README.md # 模拟器文档
└── DataAcquisition.sln # 解决方案文件
想要快速开始使用系统？请查看 快速开始指南，该指南提供了从零开始的完整步骤，包括：
- 环境要求和安装步骤
- InfluxDB 配置说明
- 设备配置文件创建
- 系统启动和验证
- 使用 PLC 模拟器进行测试
提示: 如果你是第一次使用，建议按照 快速开始指南 的步骤操作。如果你已经熟悉系统，可以直接查看 配置说明 和 API 使用示例。
项目提供了独立的 PLC 模拟器（DataAcquisition.Simulator），可以模拟三菱 PLC 的行为，用于测试数据采集功能，无需真实的 PLC 设备。
cd src/DataAcquisition.Simulator
dotnet run- ✅ 模拟三菱 PLC（MelsecA1EServer）
- ✅ 自动更新心跳寄存器（D100）
- ✅ 模拟 7 个传感器指标（温度、压力、电流、电压、光栅位置、伺服速度、生产序号）
- ✅ 支持条件采集测试（生产序号触发）
- ✅ 交互式命令控制（set/get/info/exit）
- ✅ 实时数据显示
- 启动模拟器：
cd src/DataAcquisition.Simulator
dotnet run-
配置测试设备：
在
src/DataAcquisition.Edge.Agent/Configs/目录创建TEST_PLC.json（参考src/DataAcquisition.Simulator/README.md中的完整配置示例） -
启动采集系统：
dotnet run --project src/DataAcquisition.Edge.Agent
dotnet run --project src/DataAcquisition.Central.Api
cd src/DataAcquisition.Central.Web
npm install
npm run serve- 观察数据采集：
- 访问 http://localhost:3000 查看中心 UI（Edges/Metrics/Logs）
- 访问 http://localhost:8000/metrics 查看中心 API 自身指标页面
- 检查 InfluxDB 中的
sensor和productionmeasurement
详细说明请参考：src/DataAcquisition.Simulator/README.md
根据你的使用场景，选择合适的文档阅读路径：
如果你是第一次使用本系统，建议按以下顺序阅读：
-
快速开始指南 - 从零开始，快速上手系统
- 环境要求和安装步骤
- 系统配置和启动
- 使用 PLC 模拟器测试
-
配置说明 - 了解如何配置系统
- 设备配置文件详解
- 应用配置说明
- 配置示例和使用场景
-
常见问题 - 遇到问题时的参考
- 常见问题解答
- 故障排查指南
- 配置验证方法
如果你已经熟悉系统，需要日常使用和维护：
如果你想深入了解系统架构和实现：
-
核心模块文档 - 了解系统核心模块
- PLC 客户端实现
- 通道采集器
- 数据存储服务
-
数据处理流程 - 理解数据流转过程
- 正常处理流程
- 异常处理机制
- 数据一致性保证
-
设计理念 - 了解系统设计思想
- WAL-first 架构
- 模块化设计
- 分布式架构
详细的配置说明请参考：配置文档
| 配置类型 | 位置 | 说明 |
|---|---|---|
| 设备配置 | src/DataAcquisition.Edge.Agent/Configs/*.json |
每个 PLC 设备对应一个 JSON 配置文件 |
| Edge Agent 配置 | src/DataAcquisition.Edge.Agent/appsettings.json |
应用层配置（数据库、API 等） |
| 配置热更新 | 自动检测 | 支持配置文件修改后自动热加载，无需重启服务 |
设备配置示例：
{
"IsEnabled": true,
"PlcCode": "PLC01",
"Host": "192.168.1.100",
"Port": 502,
"Type": "Mitsubishi",
"HeartbeatMonitorRegister": "D100",
"HeartbeatPollingInterval": 5000,
"Channels": [
{
"Measurement": "sensor",
"ChannelCode": "PLC01C01",
"EnableBatchRead": true,
"BatchReadRegister": "D6000",
"BatchReadLength": 10,
"BatchSize": 10,
"AcquisitionInterval": 100,
"AcquisitionMode": "Always",
"DataPoints": [
{
"FieldName": "temperature",
"Register": "D6000",
"Index": 0,
"DataType": "short",
"EvalExpression": "value / 100.0"
}
]
}
]
}我们欢迎各种形式的贡献！请参考以下步骤：
- Fork 本项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
# 克隆项目
git clone https://github.com/liuweichaox/DataAcquisition.git
# 安装依赖
dotnet restore
# 运行测试
dotnet test
# 构建项目
dotnet build- 遵循 .NET 编码规范
- 使用有意义的命名
- 添加必要的 XML 注释
- 编写单元测试
本项目采用 MIT 许可证 - 详见 LICENSE 文件。
感谢以下开源项目：
- .NET - 强大的开发平台
- InfluxDB - 高性能时序数据库
- Prometheus - 监控系统
- Vue.js - 渐进式 JavaScript 框架
如有问题或建议，请提交 Issue 或通过 Pull Request 贡献代码！
