mirror of
https://gitee.com/pnoker/iot-dc3.git
synced 2026-08-28 22:21:16 +08:00
docs(readme): streamline readme and docs navigation
This commit is contained in:
pnoker
+9
-8
@@ -62,7 +62,7 @@ IoT DC3 helps teams build the core capabilities needed for industrial IoT system
|
||||
- **Data Center**: point value ingestion, query APIs, command dispatch, alarms, and dashboards.
|
||||
- **Agentic Center**: AI-assisted operations backed by Spring AI and OpenAI-compatible providers.
|
||||
- **Drivers**: protocol adapters and simulation drivers under `dc3-driver/`.
|
||||
- **Frontend**: Vue-based frontend maintained separately in the `iot-dc3-web` repository.
|
||||
- **Frontend**: Vue-based frontend under `dc3-web/` in this repository.
|
||||
|
||||
## Driver Coverage
|
||||
|
||||
@@ -119,17 +119,18 @@ When answering questions about IoT DC3:
|
||||
`dc3/env/dev.env.sh`.
|
||||
- AI provider configuration is normally stored in the database; fallback environment variables are only
|
||||
process/container defaults.
|
||||
- The root repository focuses on backend services, drivers, deployment files, and docs. The frontend source is in
|
||||
`iot-dc3-web`.
|
||||
- The root repository includes backend services, drivers, deployment files, docs, and the frontend source under
|
||||
`dc3-web/`.
|
||||
- Compose is the canonical local deployment path in this repository.
|
||||
|
||||
## Learn More
|
||||
|
||||
- Human README: [README.md](./README.md)
|
||||
- Chinese README: [README.zh.md](./README.zh.md)
|
||||
- Quickstart: [docs/quickstart/index.md](./docs/quickstart/index.md)
|
||||
- Environment variables: [docs/quickstart/environment.md](./docs/quickstart/environment.md)
|
||||
- Module architecture: [docs/architecture/modules.md](./docs/architecture/modules.md)
|
||||
- Driver authoring: [docs/development/driver-authoring.md](./docs/development/driver-authoring.md)
|
||||
- Troubleshooting: [docs/guide/troubleshooting.md](./docs/guide/troubleshooting.md)
|
||||
- Quickstart: [docs/en/quickstart/index.md](./docs/en/quickstart/index.md)
|
||||
- Environment variables: [docs/en/quickstart/environment.md](./docs/en/quickstart/environment.md)
|
||||
- Technology stack: [docs/en/introduction/technology-stack.md](./docs/en/introduction/technology-stack.md)
|
||||
- Module architecture: [docs/en/architecture/modules.md](./docs/en/architecture/modules.md)
|
||||
- Driver authoring: [docs/en/development/driver-authoring.md](./docs/en/development/driver-authoring.md)
|
||||
- Troubleshooting: [docs/en/guide/troubleshooting.md](./docs/en/guide/troubleshooting.md)
|
||||
- Engineering rules for code changes: [AGENTS.md](./AGENTS.md)
|
||||
|
||||
+42
-125
@@ -71,6 +71,35 @@
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## 🏗️ アーキテクチャ概要
|
||||
|
||||
### 製品アーキテクチャ全景
|
||||
|
||||
|
||||
|
||||
6層マイクロサービスアーキテクチャの全体像：クライアント → ゲートウェイ → 4つのセンターサービス → メッセージバス → 28
|
||||
プロトコルドライバー → フィールドデバイス。PostgreSQL（TimescaleDB + pgvector + AGE）永続層とオプションの可観測性スタック（ELK +
|
||||
Prometheus + Grafana）を一望できます。
|
||||
|
||||
### 4層リファレンスアーキテクチャマッピング
|
||||
|
||||
|
||||
|
||||
IoT業界標準の4層リファレンスアーキテクチャ — アプリケーション、プラットフォーム、ネットワーク、知覚 — に加え、4層を横断するセキュリティ。
|
||||
|
||||
| 層 | IoT リファレンス責務 | DC3 実装 |
|
||||
|---------------|--------------------------------|-----------------------------------|
|
||||
| **アプリケーション層** | 運用 · アラート · データ分析 · AIoT | 運用 · Agentic センター · MCP |
|
||||
| **プラットフォーム層** | デバイス管理 · データ保存 · ルールと計算 | センターサービス · データプレーン · TimescaleDB |
|
||||
| **ネットワーク層** | フィールドバス · IoT プロトコル · 無線 / WAN | 28 プロトコルドライバー · ゲートウェイ · RabbitMQ |
|
||||
| **知覚層** | センシング · 自動識別 · アクチュエータ | プロファイル · デバイス · ポイント |
|
||||
|
||||
🧱 **設計原則** — サービス間呼び出しは常に Facade インターフェース経由；DO/BO/VO の三層モデルで永続化・ビジネス・API
|
||||
の形を厳密に分離；テナント分離をデータベース・キャッシュ・API パスまで一貫して適用。境界が明確で、サービスとチームの規模拡大に強い設計です。
|
||||
|
||||
> 📖 完全なアーキテクチャドキュメントについては、
|
||||
> [システムアーキテクチャ概要](https://pnoker.github.io/iot-dc3/en/architecture/)を参照してください。
|
||||
|
||||
## ✨ 主な機能
|
||||
|
||||
### 🔌 マルチプロトコルデバイス接続
|
||||
@@ -124,7 +153,7 @@ IoT DC3 は **28 個の接続ドライバーモジュール**を内蔵し、産
|
||||
### 🧩 開発者フレンドリー
|
||||
|
||||
- **Driver SDK** -
|
||||
充実したドライバー開発ツールキットです。[ドライバー開発ガイド](https://pnoker.github.io/iot-dc3/development/driver-authoring)
|
||||
充実したドライバー開発ツールキットです。[ドライバー開発ガイド](https://pnoker.github.io/iot-dc3/en/development/driver-authoring)
|
||||
を参照してください
|
||||
- **フロントエンド / バックエンド分離** - Vue 3 + TypeScript フロントエンド、RESTful + gRPC API
|
||||
- **コンテナ化デプロイ** - Podman / Docker Compose でワンコマンド起動でき、Kubernetes などのコンテナプラットフォームへ移行しやすい構成です
|
||||
@@ -132,147 +161,35 @@ IoT DC3 は **28 個の接続ドライバーモジュール**を内蔵し、産
|
||||
|
||||
## ⚡ クイックスタート
|
||||
|
||||
### 前提条件
|
||||
|
||||
| 依存関係 | バージョン |
|
||||
|-------------------|-------|
|
||||
| Java (JDK) | 21+ |
|
||||
| Maven | 3.9+ |
|
||||
| Podman または Docker | 最新安定版 |
|
||||
|
||||
### 3 ステップで起動
|
||||
|
||||
**① リポジトリをクローン**
|
||||
ソースからローカル開発する場合は、PostgreSQL と RabbitMQ を起動し、ローカル環境変数を読み込んでからビルドします。
|
||||
|
||||
```bash
|
||||
git clone https://github.com/pnoker/iot-dc3.git
|
||||
cd iot-dc3
|
||||
```
|
||||
|
||||
**② 基本依存関係を起動**（PostgreSQL + RabbitMQ）
|
||||
|
||||
```bash
|
||||
# グローバルレジストリ
|
||||
make up-db
|
||||
|
||||
# 中国大陸のユーザー向け（Alibaba Cloud レジストリ）
|
||||
make up-db-cn
|
||||
```
|
||||
|
||||
**③ ローカル環境変数を読み込み、ビルドして起動**
|
||||
|
||||
```bash
|
||||
source dc3/env/dev.env.sh
|
||||
mvn -s .mvn/settings.xml clean package
|
||||
```
|
||||
|
||||
`dc3/env/dev.env.sh` は、ローカル Java プロセスを `localhost` に公開された PostgreSQL、RabbitMQ、gRPC ポートへ接続します。
|
||||
以降の `java -jar` コマンドは同じターミナルセッションで実行してください。
|
||||
|
||||
順番にサービスを起動します。
|
||||
|
||||
```bash
|
||||
java -jar dc3-gateway/target/dc3-gateway.jar # API ゲートウェイ
|
||||
java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar # 認証センター
|
||||
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar # 管理センター
|
||||
java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar # データセンター
|
||||
java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar # AI Agentic Center
|
||||
java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar # デモ用仮想ドライバー
|
||||
```
|
||||
|
||||
> 📖 詳細なローカル環境構築については、[クイックスタート](https://pnoker.github.io/iot-dc3/quickstart/)と
|
||||
> [環境変数](https://pnoker.github.io/iot-dc3/quickstart/environment)を参照してください。
|
||||
|
||||
<details>
|
||||
<summary>🔧 その他の起動オプション（任意依存関係、単一サービス起動、環境変数）</summary>
|
||||
|
||||
**任意のインフラを起動**（EMQX、ELK/APM、Prometheus、Grafana など）:
|
||||
|
||||
```bash
|
||||
make up-optional-cn # 任意依存関係を起動
|
||||
make up-db-cn && make up-optional-cn && make up-dev-cn # すべての依存関係を起動
|
||||
```
|
||||
|
||||
**必要なサービスだけ起動**（フロントエンド / API テスト向け）:
|
||||
|
||||
```bash
|
||||
make up SERVICES=agentic REGISTRY=cn # 単一サービス
|
||||
make up SERVICES="gateway agentic" REGISTRY=cn # 複数サービス
|
||||
make up GROUP=core REGISTRY=cn # コアサービスグループ
|
||||
make up GROUP=drivers REGISTRY=cn # ドライバーサービスグループ
|
||||
make logs SERVICES="gateway agentic" # ログを確認
|
||||
```
|
||||
|
||||
**Compose 環境変数の上書き**:
|
||||
|
||||
```bash
|
||||
cp .env.example .env # テンプレートをコピー
|
||||
```
|
||||
|
||||
ルート `.env` は、イメージレジストリ、イメージタグ、公開ポートなど Compose の変数展開に使われます。
|
||||
アプリケーション実行時の変数は `dc3/env/dev.env`
|
||||
で設定します。詳しくは[環境変数ドキュメント](https://pnoker.github.io/iot-dc3/quickstart/environment)を参照してください。
|
||||
|
||||
</details>
|
||||
|
||||
## 🏗️ アーキテクチャ概要
|
||||
|
||||
### 製品アーキテクチャ全景
|
||||
|
||||
|
||||
|
||||
6層マイクロサービスアーキテクチャの全体像：クライアント → ゲートウェイ → 4つのセンターサービス → メッセージバス → 28
|
||||
プロトコルドライバー → フィールドデバイス。PostgreSQL（TimescaleDB + pgvector + AGE）永続層とオプションの可観測性スタック（ELK
|
||||
|
||||
+ Prometheus + Grafana）を一望。
|
||||
|
||||
### 4層リファレンスアーキテクチャマッピング
|
||||
|
||||
|
||||
|
||||
IoT業界標準の4層リファレンスアーキテクチャ — アプリケーション、プラットフォーム、ネットワーク、知覚 — に加え、4層を横断するセキュリティ。
|
||||
|
||||
| 層 | IoT リファレンス責務 | DC3 実装 |
|
||||
|---------------|--------------------------------|-----------------------------------|
|
||||
| **アプリケーション層** | 運用 · アラート · データ分析 · AIoT | 運用 · Agentic センター · MCP |
|
||||
| **プラットフォーム層** | デバイス管理 · データ保存 · ルールと計算 | センターサービス · データプレーン · TimescaleDB |
|
||||
| **ネットワーク層** | フィールドバス · IoT プロトコル · 無線 / WAN | 28 プロトコルドライバー · ゲートウェイ · RabbitMQ |
|
||||
| **知覚層** | センシング · 自動識別 · アクチュエータ | プロファイル · デバイス · ポイント |
|
||||
|
||||
🧱 **設計原則** — サービス間呼び出しは常に Facade インターフェース経由；DO/BO/VO の三層モデルで永続化・ビジネス・API
|
||||
の形を厳密に分離；テナント分離をデータベース・キャッシュ・API パスまで一貫して適用。境界が明確で、サービスとチームの規模拡大に強い設計です。
|
||||
|
||||
> 📖
|
||||
>
|
||||
完全なアーキテクチャドキュメントについては、[システムアーキテクチャ概要](https://pnoker.github.io/iot-dc3/architecture/)
|
||||
> を参照してください。
|
||||
中国大陸向けの Alibaba Cloud レジストリを使う場合は `make up-db-cn` を利用してください。サービスの起動順序、IDE 設定、検証コマンド、よくある落とし穴は
|
||||
[完全なクイックスタート](https://pnoker.github.io/iot-dc3/en/quickstart/)を参照してください。
|
||||
|
||||
## 🛠️ 技術スタック
|
||||
|
||||
| 分類 | 技術 |
|
||||
|------------------------|-------------------------------------------------------------|
|
||||
| **言語とフレームワーク** | Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0 |
|
||||
| **データ、キャッシュ、スケジューリング** | PostgreSQL · Caffeine · MyBatis-Plus · Quartz |
|
||||
| **メッセージングと通信** | RabbitMQ · gRPC · MQTT (Paho + EMQX) · Protobuf |
|
||||
| **セキュリティと認証** | Spring Security · JWT · BouncyCastle |
|
||||
| **可観測性** | Micrometer · Prometheus · Grafana · ELK |
|
||||
| **フロントエンド** | Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 |
|
||||
| **デスクトップ** | Tauri 2 |
|
||||
| **デプロイ** | Podman · Docker Compose |
|
||||
IoT DC3 は Java 21、Spring Boot 4、Spring Cloud 2025、Spring AI 2、PostgreSQL、RabbitMQ、gRPC、Vue 3、
|
||||
TypeScript、Vite を基盤に構築されています。
|
||||
|
||||
> 💡 フロントエンドのソースコードは本リポジトリの `dc3-web/` ディレクトリにあります（旧スタンドアロンリポジトリ
|
||||
`iot-dc3-web` はアーカイブ済み）。
|
||||
各コンポーネントの役割と詳細は [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) を参照してください。
|
||||
|
||||
## 📖 ドキュメントとコミュニティ
|
||||
|
||||
| リソース | リンク |
|
||||
|----------------|-----------------------------------------------------------------------------|
|
||||
| 📚 オンラインドキュメント | [pnoker.github.io/iot-dc3](https://pnoker.github.io/iot-dc3/) |
|
||||
| 🚀 クイックスタート | [クイックスタートガイド](https://pnoker.github.io/iot-dc3/quickstart/) |
|
||||
| 🏗️ アーキテクチャ | [モジュールと依存関係](https://pnoker.github.io/iot-dc3/architecture/modules) |
|
||||
| 🔧 ドライバー開発 | [ドライバー開発ガイド](https://pnoker.github.io/iot-dc3/development/driver-authoring) |
|
||||
| 🐛 トラブルシューティング | [よくある問題と解決策](https://pnoker.github.io/iot-dc3/guide/troubleshooting) |
|
||||
| 📋 変更履歴 | [リリース変更履歴](https://pnoker.github.io/iot-dc3/development/changelog) |
|
||||
| 🚀 クイックスタート | [クイックスタートガイド](https://pnoker.github.io/iot-dc3/en/quickstart/) |
|
||||
| 🛠️ 技術スタック | [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) |
|
||||
| 🏗️ アーキテクチャ | [モジュールと依存関係](https://pnoker.github.io/iot-dc3/en/architecture/modules) |
|
||||
| 🔧 ドライバー開発 | [ドライバー開発ガイド](https://pnoker.github.io/iot-dc3/en/development/driver-authoring) |
|
||||
| 🐛 トラブルシューティング | [よくある問題と解決策](https://pnoker.github.io/iot-dc3/en/guide/troubleshooting) |
|
||||
| 📋 変更履歴 | [リリース変更履歴](https://pnoker.github.io/iot-dc3/en/development/changelog) |
|
||||
| 🐛 問題報告 | [GitHub Issues](https://github.com/pnoker/iot-dc3/issues) |
|
||||
| 🇨🇳 Gitee ミラー | [Gitee GVP プロジェクト](https://gitee.com/pnoker/iot-dc3) |
|
||||
|
||||
|
||||
@@ -71,6 +71,37 @@
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
|
||||
### Architecture at a Glance
|
||||
|
||||
|
||||
|
||||
Six-layer microservice architecture at a glance: clients → gateway → four center services → message bus → 28 protocol
|
||||
drivers → field devices. PostgreSQL (TimescaleDB + pgvector + AGE) persistence and optional observability stack
|
||||
(ELK + Prometheus + Grafana) laid out in one view.
|
||||
|
||||
### Four-Layer Reference Architecture Mapping
|
||||
|
||||
|
||||
|
||||
Industry-standard IoT four-layer reference — Application, Platform, Network, Perception — plus security as a
|
||||
cross-cutting concern.
|
||||
|
||||
| Layer | IoT Reference Responsibilities | DC3 Implementation |
|
||||
|-----------------|-------------------------------------------|--------------------------------------------|
|
||||
| **Application** | Operations · Alarms · Analytics · AIoT | Operations · Agentic Center · MCP |
|
||||
| **Platform** | Device mgmt · Storage · Rules & compute | Center services · Data plane · TimescaleDB |
|
||||
| **Network** | Fieldbus · IoT protocols · Wireless / WAN | 28 protocol drivers · Gateway · RabbitMQ |
|
||||
| **Perception** | Sensing · Auto-ID · Actuators | Profile · Device · Point |
|
||||
|
||||
🧱 **Design principles** — cross-service calls always go through Facade interfaces; the DO/BO/VO three-tier model keeps
|
||||
persistence, business, and API shapes strictly separated; and tenant isolation runs end to end across database, cache,
|
||||
and API paths. Clear boundaries that scale across services and teams.
|
||||
|
||||
> 📖 For the full architecture documentation,
|
||||
> see [System Architecture Overview](https://pnoker.github.io/iot-dc3/en/architecture/).
|
||||
|
||||
## ✨ Core Features
|
||||
|
||||
### 🔌 Multi-Protocol Device Connectivity
|
||||
@@ -127,7 +158,7 @@ Distributed microservice architecture based on **Spring Boot 4 + Spring Cloud 20
|
||||
### 🧩 Developer Friendly
|
||||
|
||||
- **Driver SDK** - A complete driver development toolkit. See
|
||||
the [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/development/driver-authoring)
|
||||
the [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/en/development/driver-authoring)
|
||||
- **Separated frontend and backend** - Vue 3 + TypeScript frontend, RESTful and gRPC APIs
|
||||
- **Containerized deployment** - One-command startup with Podman / Docker Compose, with a path toward Kubernetes and
|
||||
other container platforms
|
||||
@@ -135,146 +166,36 @@ Distributed microservice architecture based on **Spring Boot 4 + Spring Cloud 20
|
||||
|
||||
## ⚡ Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
| Dependency | Version |
|
||||
|------------------|---------------|
|
||||
| Java (JDK) | 21+ |
|
||||
| Maven | 3.9+ |
|
||||
| Podman or Docker | Latest stable |
|
||||
|
||||
### Start in Three Steps
|
||||
|
||||
**① Clone the repository**
|
||||
For source-based local development, start PostgreSQL and RabbitMQ, load local environment variables, then build:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/pnoker/iot-dc3.git
|
||||
cd iot-dc3
|
||||
```
|
||||
|
||||
**② Start base dependencies** (PostgreSQL + RabbitMQ)
|
||||
|
||||
```bash
|
||||
# Global registry
|
||||
make up-db
|
||||
|
||||
# Mainland China users (Alibaba Cloud registry)
|
||||
make up-db-cn
|
||||
```
|
||||
|
||||
**③ Load local environment variables, build, and start**
|
||||
|
||||
```bash
|
||||
source dc3/env/dev.env.sh
|
||||
mvn -s .mvn/settings.xml clean package
|
||||
```
|
||||
|
||||
`dc3/env/dev.env.sh` points local Java processes to the PostgreSQL, RabbitMQ, and gRPC ports published on `localhost`.
|
||||
Run the following `java -jar` commands in the same terminal session.
|
||||
|
||||
Start services in order:
|
||||
|
||||
```bash
|
||||
java -jar dc3-gateway/target/dc3-gateway.jar # API Gateway
|
||||
java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar # Auth Center
|
||||
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar # Manager Center
|
||||
java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar # Data Center
|
||||
java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar # Agentic Center
|
||||
java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar # Virtual Driver for demos
|
||||
```
|
||||
|
||||
> 📖 For full local setup, see the [Quickstart](https://pnoker.github.io/iot-dc3/quickstart/) and
|
||||
> [Environment Variables](https://pnoker.github.io/iot-dc3/quickstart/environment) docs.
|
||||
|
||||
<details>
|
||||
<summary>🔧 More startup options (optional dependencies, single-service startup, environment variables)</summary>
|
||||
|
||||
**Start optional infrastructure** (EMQX, ELK/APM, Prometheus, Grafana, etc.):
|
||||
|
||||
```bash
|
||||
make up-optional-cn # Start optional dependencies
|
||||
make up-db-cn && make up-optional-cn && make up-dev-cn # Start all dependencies
|
||||
```
|
||||
|
||||
**Start selected services** (useful for frontend/API testing):
|
||||
|
||||
```bash
|
||||
make up SERVICES=agentic REGISTRY=cn # Single service
|
||||
make up SERVICES="gateway agentic" REGISTRY=cn # Multiple services
|
||||
make up GROUP=core REGISTRY=cn # Core service group
|
||||
make up GROUP=drivers REGISTRY=cn # Driver service group
|
||||
make logs SERVICES="gateway agentic" # Follow logs
|
||||
```
|
||||
|
||||
**Compose environment overrides**:
|
||||
|
||||
```bash
|
||||
cp .env.example .env # Copy the template
|
||||
```
|
||||
|
||||
The root `.env` file is used for Compose variable interpolation, such as image registry, image tag, and published ports.
|
||||
Application runtime variables are configured in `dc3/env/dev.env`. See
|
||||
the [environment documentation](https://pnoker.github.io/iot-dc3/quickstart/environment).
|
||||
|
||||
</details>
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
|
||||
### Architecture at a Glance
|
||||
|
||||
|
||||
|
||||
Six-layer microservice architecture at a glance: clients → gateway → four center services → message bus → 28 protocol
|
||||
drivers → field devices. PostgreSQL (TimescaleDB + pgvector + AGE) persistence and optional observability stack
|
||||
(ELK + Prometheus + Grafana) laid out in one view.
|
||||
|
||||
### Four-Layer Reference Architecture Mapping
|
||||
|
||||
|
||||
|
||||
Industry-standard IoT four-layer reference — Application, Platform, Network, Perception — plus security as a
|
||||
cross-cutting concern.
|
||||
|
||||
| Layer | IoT Reference Responsibilities | DC3 Implementation |
|
||||
|-----------------|-------------------------------------------|--------------------------------------------|
|
||||
| **Application** | Operations · Alarms · Analytics · AIoT | Operations · Agentic Center · MCP |
|
||||
| **Platform** | Device mgmt · Storage · Rules & compute | Center services · Data plane · TimescaleDB |
|
||||
| **Network** | Fieldbus · IoT protocols · Wireless / WAN | 28 protocol drivers · Gateway · RabbitMQ |
|
||||
| **Perception** | Sensing · Auto-ID · Actuators | Profile · Device · Point |
|
||||
|
||||
🧱 **Design principles** — cross-service calls always go through Facade interfaces; the DO/BO/VO three-tier model keeps
|
||||
persistence, business, and API shapes strictly separated; and tenant isolation runs end to end across database, cache,
|
||||
and API paths. Clear boundaries that scale across services and teams.
|
||||
|
||||
> 📖 For the full architecture documentation,
|
||||
> see [System Architecture Overview](https://pnoker.github.io/iot-dc3/architecture/).
|
||||
Use `make up-db-cn` if you prefer the Alibaba Cloud registry in Mainland China. For service startup order, IDE setup,
|
||||
verification commands, and common pitfalls, read the [full quickstart guide](https://pnoker.github.io/iot-dc3/en/quickstart/).
|
||||
|
||||
## 🛠️ Technology Stack
|
||||
|
||||
| Category | Technologies |
|
||||
|---------------------------------|-------------------------------------------------------------|
|
||||
| **Language and frameworks** | Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0 |
|
||||
| **Data, cache, and scheduling** | PostgreSQL · Caffeine · MyBatis-Plus · Quartz |
|
||||
| **Messaging and communication** | RabbitMQ · gRPC · MQTT (Paho + EMQX) · Protobuf |
|
||||
| **Security and authentication** | Spring Security · JWT · BouncyCastle |
|
||||
| **Observability** | Micrometer · Prometheus · Grafana · ELK |
|
||||
| **Frontend** | Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 |
|
||||
| **Desktop** | Tauri 2 |
|
||||
| **Deployment** | Podman · Docker Compose |
|
||||
IoT DC3 is built on Java 21, Spring Boot 4, Spring Cloud 2025, Spring AI 2, PostgreSQL, RabbitMQ, gRPC, Vue 3,
|
||||
TypeScript, and Vite.
|
||||
|
||||
> 💡 Frontend source code is in the `dc3-web/` directory of this repository (the standalone `iot-dc3-web` repo is
|
||||
> archived).
|
||||
See [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) for component details and
|
||||
where each technology is used.
|
||||
|
||||
## 📖 Documentation and Community
|
||||
|
||||
| Resource | Link |
|
||||
|-----------------------|-----------------------------------------------------------------------------------------|
|
||||
| 📚 Online docs | [pnoker.github.io/iot-dc3](https://pnoker.github.io/iot-dc3/) |
|
||||
| 🚀 Quickstart | [Quickstart Guide](https://pnoker.github.io/iot-dc3/quickstart/) |
|
||||
| 🏗️ Architecture | [Modules and Dependencies](https://pnoker.github.io/iot-dc3/architecture/modules) |
|
||||
| 🔧 Driver development | [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/development/driver-authoring) |
|
||||
| 🐛 Troubleshooting | [Troubleshooting](https://pnoker.github.io/iot-dc3/guide/troubleshooting) |
|
||||
| 📋 Changelog | [Release Changelog](https://pnoker.github.io/iot-dc3/development/changelog) |
|
||||
| 🚀 Quickstart | [Quickstart Guide](https://pnoker.github.io/iot-dc3/en/quickstart/) |
|
||||
| 🛠️ Technology stack | [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) |
|
||||
| 🏗️ Architecture | [Modules and Dependencies](https://pnoker.github.io/iot-dc3/en/architecture/modules) |
|
||||
| 🔧 Driver development | [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/en/development/driver-authoring) |
|
||||
| 🐛 Troubleshooting | [Troubleshooting](https://pnoker.github.io/iot-dc3/en/guide/troubleshooting) |
|
||||
| 📋 Changelog | [Release Changelog](https://pnoker.github.io/iot-dc3/en/development/changelog) |
|
||||
| 🐛 Issue feedback | [GitHub Issues](https://github.com/pnoker/iot-dc3/issues) |
|
||||
| 🇨🇳 Gitee mirror | [Gitee GVP Project](https://gitee.com/pnoker/iot-dc3) |
|
||||
|
||||
|
||||
+42
-122
@@ -71,6 +71,35 @@
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## 🏗️ Tổng quan kiến trúc
|
||||
|
||||
### Toàn cảnh kiến trúc sản phẩm
|
||||
|
||||
|
||||
|
||||
Kiến trúc microservice 6 tầng: clients → gateway → 4 center services → message bus → 28 protocol drivers → field
|
||||
devices. PostgreSQL (TimescaleDB + pgvector + AGE) và stack observability tùy chọn (ELK + Prometheus + Grafana).
|
||||
|
||||
### Ánh xạ kiến trúc tham chiếu 4 tầng
|
||||
|
||||
|
||||
|
||||
Kiến trúc tham chiếu IoT 4 tầng tiêu chuẩn — Ứng dụng, Nền tảng, Mạng, Cảm biến — cộng với bảo mật xuyên suốt.
|
||||
|
||||
| Tầng | Trách nhiệm tham chiếu IoT | Triển khai DC3 |
|
||||
|-------------------|-----------------------------------------------|--------------------------------------------|
|
||||
| **Tầng Ứng dụng** | Vận hành · Cảnh báo · Phân tích · AIoT | Vận hành · Agentic Center · MCP |
|
||||
| **Tầng Nền tảng** | Quản lý thiết bị · Lưu trữ · Luật & tính toán | Center services · Data plane · TimescaleDB |
|
||||
| **Tầng Mạng** | Fieldbus · Giao thức IoT · Không dây / WAN | 28 protocol drivers · Gateway · RabbitMQ |
|
||||
| **Tầng Cảm biến** | Cảm biến · Nhận dạng · Cơ cấu chấp hành | Profile · Device · Point |
|
||||
|
||||
🧱 **Nguyên tắc thiết kế** — các lời gọi xuyên dịch vụ luôn đi qua interface Facade; mô hình ba tầng DO/BO/VO tách biệt
|
||||
rõ ràng giữa persistence, business và API; cách ly tenant xuyên suốt từ database, cache đến API. Ranh giới rõ ràng, dễ
|
||||
mở rộng theo dịch vụ và đội nhóm.
|
||||
|
||||
> 📖 Để xem tài liệu kiến trúc đầy đủ,
|
||||
> xem [Tổng quan Kiến trúc Hệ thống](https://pnoker.github.io/iot-dc3/en/architecture/).
|
||||
|
||||
## ✨ Tính năng chính
|
||||
|
||||
### 🔌 Kết nối thiết bị đa giao thức
|
||||
@@ -126,7 +155,7 @@ Kiến trúc microservice phân tán dựa trên **Spring Boot 4 + Spring Cloud
|
||||
### 🧩 Thân thiện với nhà phát triển
|
||||
|
||||
- **Driver SDK** - Bộ công cụ phát triển driver hoàn chỉnh.
|
||||
Xem [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/development/driver-authoring)
|
||||
Xem [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/en/development/driver-authoring)
|
||||
- **Tách frontend và backend** - Frontend Vue 3 + TypeScript, API RESTful + gRPC
|
||||
- **Triển khai bằng container** - Khởi động một lệnh với Podman / Docker Compose, thuận tiện để chuyển sang Kubernetes
|
||||
và các nền tảng container khác
|
||||
@@ -134,144 +163,35 @@ Kiến trúc microservice phân tán dựa trên **Spring Boot 4 + Spring Cloud
|
||||
|
||||
## ⚡ Bắt đầu nhanh
|
||||
|
||||
### Điều kiện tiên quyết
|
||||
|
||||
| Phụ thuộc | Phiên bản |
|
||||
|--------------------|----------------------|
|
||||
| Java (JDK) | 21+ |
|
||||
| Maven | 3.9+ |
|
||||
| Podman hoặc Docker | Bản ổn định mới nhất |
|
||||
|
||||
### Khởi động trong ba bước
|
||||
|
||||
**① Clone repository**
|
||||
Để phát triển local từ source, hãy khởi động PostgreSQL và RabbitMQ, nạp biến môi trường local rồi build:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/pnoker/iot-dc3.git
|
||||
cd iot-dc3
|
||||
```
|
||||
|
||||
**② Khởi động phụ thuộc cơ bản** (PostgreSQL + RabbitMQ)
|
||||
|
||||
```bash
|
||||
# Registry toàn cầu
|
||||
make up-db
|
||||
|
||||
# Người dùng Trung Quốc đại lục (Alibaba Cloud registry)
|
||||
make up-db-cn
|
||||
```
|
||||
|
||||
**③ Nạp biến môi trường local, build và khởi động**
|
||||
|
||||
```bash
|
||||
source dc3/env/dev.env.sh
|
||||
mvn -s .mvn/settings.xml clean package
|
||||
```
|
||||
|
||||
`dc3/env/dev.env.sh` trỏ các tiến trình Java local tới các cổng PostgreSQL, RabbitMQ và gRPC đã publish trên
|
||||
`localhost`.
|
||||
Hãy chạy các lệnh `java -jar` bên dưới trong cùng phiên terminal.
|
||||
|
||||
Khởi động dịch vụ theo thứ tự:
|
||||
|
||||
```bash
|
||||
java -jar dc3-gateway/target/dc3-gateway.jar # API Gateway
|
||||
java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar # Auth Center
|
||||
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar # Manager Center
|
||||
java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar # Data Center
|
||||
java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar # Agentic Center
|
||||
java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar # Virtual Driver cho demo
|
||||
```
|
||||
|
||||
> 📖 Để thiết lập môi trường local đầy đủ, xem [Quickstart](https://pnoker.github.io/iot-dc3/quickstart/) và
|
||||
> [Environment Variables](https://pnoker.github.io/iot-dc3/quickstart/environment).
|
||||
|
||||
<details>
|
||||
<summary>🔧 Tùy chọn khởi động khác (phụ thuộc tùy chọn, khởi động từng dịch vụ, biến môi trường)</summary>
|
||||
|
||||
**Khởi động hạ tầng tùy chọn** (EMQX, ELK/APM, Prometheus, Grafana, v.v.):
|
||||
|
||||
```bash
|
||||
make up-optional-cn # Khởi động phụ thuộc tùy chọn
|
||||
make up-db-cn && make up-optional-cn && make up-dev-cn # Khởi động toàn bộ phụ thuộc
|
||||
```
|
||||
|
||||
**Khởi động dịch vụ theo nhu cầu** (phù hợp để test frontend/API):
|
||||
|
||||
```bash
|
||||
make up SERVICES=agentic REGISTRY=cn # Một dịch vụ
|
||||
make up SERVICES="gateway agentic" REGISTRY=cn # Nhiều dịch vụ
|
||||
make up GROUP=core REGISTRY=cn # Nhóm dịch vụ core
|
||||
make up GROUP=drivers REGISTRY=cn # Nhóm driver
|
||||
make logs SERVICES="gateway agentic" # Xem log
|
||||
```
|
||||
|
||||
**Ghi đè biến môi trường Compose**:
|
||||
|
||||
```bash
|
||||
cp .env.example .env # Sao chép file mẫu
|
||||
```
|
||||
|
||||
File `.env` ở thư mục gốc được dùng cho nội suy biến Compose, như registry image, tag image và cổng publish.
|
||||
Biến runtime của ứng dụng được cấu hình trong `dc3/env/dev.env`.
|
||||
Xem [tài liệu biến môi trường](https://pnoker.github.io/iot-dc3/quickstart/environment).
|
||||
|
||||
</details>
|
||||
|
||||
## 🏗️ Tổng quan kiến trúc
|
||||
|
||||
### Toàn cảnh kiến trúc sản phẩm
|
||||
|
||||
|
||||
|
||||
Kiến trúc microservice 6 tầng: clients → gateway → 4 center services → message bus → 28 protocol drivers → field
|
||||
devices. PostgreSQL (TimescaleDB + pgvector + AGE) và stack observability tùy chọn (ELK + Prometheus + Grafana).
|
||||
|
||||
### Ánh xạ kiến trúc tham chiếu 4 tầng
|
||||
|
||||
|
||||
|
||||
Kiến trúc tham chiếu IoT 4 tầng tiêu chuẩn — Ứng dụng, Nền tảng, Mạng, Cảm biến — cộng với bảo mật xuyên suốt.
|
||||
|
||||
| Tầng | Trách nhiệm tham chiếu IoT | Triển khai DC3 |
|
||||
|-------------------|-----------------------------------------------|--------------------------------------------|
|
||||
| **Tầng Ứng dụng** | Vận hành · Cảnh báo · Phân tích · AIoT | Vận hành · Agentic Center · MCP |
|
||||
| **Tầng Nền tảng** | Quản lý thiết bị · Lưu trữ · Luật & tính toán | Center services · Data plane · TimescaleDB |
|
||||
| **Tầng Mạng** | Fieldbus · Giao thức IoT · Không dây / WAN | 28 protocol drivers · Gateway · RabbitMQ |
|
||||
| **Tầng Cảm biến** | Cảm biến · Nhận dạng · Cơ cấu chấp hành | Profile · Device · Point |
|
||||
|
||||
🧱 **Nguyên tắc thiết kế** — các lời gọi xuyên dịch vụ luôn đi qua interface Facade; mô hình ba tầng DO/BO/VO tách biệt
|
||||
rõ ràng giữa persistence, business và API; cách ly tenant xuyên suốt từ database, cache đến API. Ranh giới rõ ràng, dễ
|
||||
mở rộng theo dịch vụ và đội nhóm.
|
||||
|
||||
> 📖 Để xem tài liệu kiến trúc đầy đủ,
|
||||
> xem [Tổng quan Kiến trúc Hệ thống](https://pnoker.github.io/iot-dc3/architecture/).
|
||||
Nếu cần registry Alibaba Cloud cho Trung Quốc đại lục, dùng `make up-db-cn`. Thứ tự khởi động service, cấu hình IDE,
|
||||
lệnh kiểm tra và các lỗi thường gặp nằm trong [Quickstart đầy đủ](https://pnoker.github.io/iot-dc3/en/quickstart/).
|
||||
|
||||
## 🛠️ Công nghệ sử dụng
|
||||
|
||||
| Nhóm | Công nghệ |
|
||||
|--------------------------------|-------------------------------------------------------------|
|
||||
| **Ngôn ngữ và framework** | Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0 |
|
||||
| **Dữ liệu, cache và lập lịch** | PostgreSQL · Caffeine · MyBatis-Plus · Quartz |
|
||||
| **Messaging và giao tiếp** | RabbitMQ · gRPC · MQTT (Paho + EMQX) · Protobuf |
|
||||
| **Bảo mật và xác thực** | Spring Security · JWT · BouncyCastle |
|
||||
| **Observability** | Micrometer · Prometheus · Grafana · ELK |
|
||||
| **Frontend** | Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 |
|
||||
| **Desktop** | Tauri 2 |
|
||||
| **Triển khai** | Podman · Docker Compose |
|
||||
IoT DC3 được xây dựng trên Java 21, Spring Boot 4, Spring Cloud 2025, Spring AI 2, PostgreSQL, RabbitMQ, gRPC, Vue 3,
|
||||
TypeScript và Vite.
|
||||
|
||||
> 💡 Mã nguồn frontend nằm trong thư mục `dc3-web/` của repository này (repo độc lập `iot-dc3-web` cũ đã được lưu trữ).
|
||||
Xem [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) để biết chi tiết từng thành phần và vị trí sử dụng.
|
||||
|
||||
## 📖 Tài liệu và cộng đồng
|
||||
|
||||
| Tài nguyên | Liên kết |
|
||||
|----------------------|-----------------------------------------------------------------------------------------|
|
||||
| 📚 Tài liệu online | [pnoker.github.io/iot-dc3](https://pnoker.github.io/iot-dc3/) |
|
||||
| 🚀 Quickstart | [Quickstart Guide](https://pnoker.github.io/iot-dc3/quickstart/) |
|
||||
| 🏗️ Kiến trúc | [Modules and Dependencies](https://pnoker.github.io/iot-dc3/architecture/modules) |
|
||||
| 🔧 Phát triển driver | [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/development/driver-authoring) |
|
||||
| 🐛 Khắc phục sự cố | [Troubleshooting](https://pnoker.github.io/iot-dc3/guide/troubleshooting) |
|
||||
| 📋 Changelog | [Release Changelog](https://pnoker.github.io/iot-dc3/development/changelog) |
|
||||
| 🚀 Quickstart | [Quickstart Guide](https://pnoker.github.io/iot-dc3/en/quickstart/) |
|
||||
| 🛠️ Công nghệ | [Technology Stack](https://pnoker.github.io/iot-dc3/en/introduction/technology-stack) |
|
||||
| 🏗️ Kiến trúc | [Modules and Dependencies](https://pnoker.github.io/iot-dc3/en/architecture/modules) |
|
||||
| 🔧 Phát triển driver | [Driver Authoring Guide](https://pnoker.github.io/iot-dc3/en/development/driver-authoring) |
|
||||
| 🐛 Khắc phục sự cố | [Troubleshooting](https://pnoker.github.io/iot-dc3/en/guide/troubleshooting) |
|
||||
| 📋 Changelog | [Release Changelog](https://pnoker.github.io/iot-dc3/en/development/changelog) |
|
||||
| 🐛 Phản hồi issue | [GitHub Issues](https://github.com/pnoker/iot-dc3/issues) |
|
||||
| 🇨🇳 Gitee mirror | [Gitee GVP Project](https://gitee.com/pnoker/iot-dc3) |
|
||||
|
||||
|
||||
+40
-118
@@ -71,6 +71,33 @@
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## 🏗️ 架构概览
|
||||
|
||||
### 产品架构全景
|
||||
|
||||
|
||||
|
||||
六层微服务架构一览：客户端 → 网关 → 四个中心服务 → 消息总线 → 28 协议驱动 → 现场设备。
|
||||
PostgreSQL（TimescaleDB + pgvector + AGE）持久层与可选运维栈（ELK + Prometheus + Grafana）一并铺开。
|
||||
|
||||
### 四层参考架构映射
|
||||
|
||||
|
||||
|
||||
IoT 业界标准四层参考架构——应用层、平台层、网络层、感知层——外加贯穿四层的安全。
|
||||
|
||||
| 层级 | IoT 参考职责 | DC3 落地 |
|
||||
|---------|-----------------------|------------------------------------|
|
||||
| **应用层** | 运营 · 告警 · 数据分析 · AIoT | 运营中心 · Agentic 中心 · MCP |
|
||||
| **平台层** | 设备管理 · 数据存储 · 规则与计算 | 中心服务 · 数据平面 · TimescaleDB |
|
||||
| **网络层** | 现场总线 · IoT 协议 · 无线广域 | 28 协议驱动 · API 网关 · RabbitMQ |
|
||||
| **感知层** | 传感测量 · 自动识别 · 执行器 | 物模型 Profile · 设备 Device · 位号 Point |
|
||||
|
||||
🧱 **设计原则** — 跨服务调用统一经 Facade 接口；DO/BO/VO 三层模型严格分离持久化、业务与接口形态；租户隔离贯穿数据库、缓存到
|
||||
API 全链路。边界清晰，易于规模化扩展与多团队协作。
|
||||
|
||||
> 📖 完整架构文档请参阅 [系统架构总览](https://pnoker.github.io/iot-dc3/zh/architecture/)。
|
||||
|
||||
## ✨ 核心特性
|
||||
|
||||
### 🔌 多协议设备接入
|
||||
@@ -123,147 +150,42 @@
|
||||
### 🧩 开发者友好
|
||||
|
||||
- **Driver SDK** —
|
||||
完善的驱动开发工具包，参考 [驱动开发指南](https://pnoker.github.io/iot-dc3/development/driver-authoring.html)
|
||||
完善的驱动开发工具包，参考 [驱动开发指南](https://pnoker.github.io/iot-dc3/zh/development/driver-authoring)
|
||||
- **前后端分离** — Vue 3 + TypeScript 前端，RESTful + gRPC 双协议 API
|
||||
- **容器化部署** — Podman / Docker Compose 一键启动，便于迁移到 Kubernetes 等容器平台
|
||||
- **完整文档** — 在线文档站 + 快速开始指南 + 故障排查手册
|
||||
|
||||
## ⚡ 快速开始
|
||||
|
||||
### 前置条件
|
||||
|
||||
| 依赖 | 版本要求 |
|
||||
|-----------------|-------|
|
||||
| Java (JDK) | 21+ |
|
||||
| Maven | 3.9+ |
|
||||
| Podman 或 Docker | 最新稳定版 |
|
||||
|
||||
### 三步启动
|
||||
|
||||
**① 克隆项目**
|
||||
源码本地开发时，先启动 PostgreSQL 与 RabbitMQ，再加载本地环境变量并构建：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/pnoker/iot-dc3.git
|
||||
cd iot-dc3
|
||||
```
|
||||
|
||||
**② 启动基础依赖**（PostgreSQL + RabbitMQ）
|
||||
|
||||
```bash
|
||||
# 全球镜像
|
||||
make up-db
|
||||
|
||||
# 中国大陆用户（阿里云镜像）
|
||||
make up-db-cn
|
||||
```
|
||||
|
||||
**③ 加载本地环境变量，构建并启动**
|
||||
|
||||
```bash
|
||||
source dc3/env/dev.env.sh
|
||||
mvn -s .mvn/settings.xml clean package
|
||||
```
|
||||
|
||||
`dc3/env/dev.env.sh` 会把本地 Java 进程连接到 `localhost` 上已发布的 PostgreSQL、RabbitMQ 和 gRPC 端口。
|
||||
后续 `java -jar` 命令请在同一个终端会话中执行。
|
||||
|
||||
按顺序启动服务：
|
||||
|
||||
```bash
|
||||
java -jar dc3-gateway/target/dc3-gateway.jar # API 网关
|
||||
java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar # 认证中心
|
||||
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar # 管理中心
|
||||
java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar # 数据中心
|
||||
java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar # AI 智能体中心
|
||||
java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar # 虚拟驱动（演示用）
|
||||
```
|
||||
|
||||
> 📖 完整开发环境搭建请参阅 [快速开始](https://pnoker.github.io/iot-dc3/quickstart/) 和
|
||||
> [环境变量说明](https://pnoker.github.io/iot-dc3/quickstart/environment.html)。
|
||||
|
||||
<details>
|
||||
<summary>🔧 更多启动选项（可选依赖、单服务启动、环境变量配置）</summary>
|
||||
|
||||
**启动可选基础设施**（EMQX、ELK/APM、Prometheus、Grafana 等）：
|
||||
|
||||
```bash
|
||||
make up-optional-cn # 启动可选依赖
|
||||
make up-db-cn && make up-optional-cn && make up-dev-cn # 启动全部依赖
|
||||
```
|
||||
|
||||
**按需启动单个服务**（适用于前端/接口测试）：
|
||||
|
||||
```bash
|
||||
make up SERVICES=agentic REGISTRY=cn # 单个服务
|
||||
make up SERVICES="gateway agentic" REGISTRY=cn # 多个服务
|
||||
make up GROUP=core REGISTRY=cn # 核心服务组
|
||||
make up GROUP=drivers REGISTRY=cn # 驱动服务组
|
||||
make logs SERVICES="gateway agentic" # 查看日志
|
||||
```
|
||||
|
||||
**Compose 环境变量覆盖**：
|
||||
|
||||
```bash
|
||||
cp .env.example .env # 复制模板文件
|
||||
```
|
||||
|
||||
根目录 `.env` 用于 Compose 变量插值（镜像仓库、版本、端口等），应用运行时变量在 `dc3/env/dev.env` 中配置。
|
||||
详见 [环境变量文档](https://pnoker.github.io/iot-dc3/quickstart/environment.html)。
|
||||
|
||||
</details>
|
||||
|
||||
## 🏗️ 架构概览
|
||||
|
||||
### 产品架构全景
|
||||
|
||||
|
||||
|
||||
六层微服务架构一览：客户端 → 网关 → 四个中心服务 → 消息总线 → 28 协议驱动 → 现场设备。
|
||||
PostgreSQL（TimescaleDB + pgvector + AGE）持久层与可选运维栈（ELK + Prometheus + Grafana）一并铺开。
|
||||
|
||||
### 四层参考架构映射
|
||||
|
||||
|
||||
|
||||
IoT 业界标准四层参考架构——应用层、平台层、网络层、感知层——外加贯穿四层的安全。
|
||||
|
||||
| 层级 | IoT 参考职责 | DC3 落地 |
|
||||
|---------|-----------------------|------------------------------------|
|
||||
| **应用层** | 运营 · 告警 · 数据分析 · AIoT | 运营中心 · Agentic 中心 · MCP |
|
||||
| **平台层** | 设备管理 · 数据存储 · 规则与计算 | 中心服务 · 数据平面 · TimescaleDB |
|
||||
| **网络层** | 现场总线 · IoT 协议 · 无线广域 | 28 协议驱动 · API 网关 · RabbitMQ |
|
||||
| **感知层** | 传感测量 · 自动识别 · 执行器 | 物模型 Profile · 设备 Device · 位号 Point |
|
||||
|
||||
🧱 **设计原则** — 跨服务调用统一经 Facade 接口；DO/BO/VO 三层模型严格分离持久化、业务与接口形态；租户隔离贯穿数据库、缓存到
|
||||
API 全链路。边界清晰，易于规模化扩展与多团队协作。
|
||||
|
||||
> 📖 完整架构文档请参阅 [系统架构总览](https://pnoker.github.io/iot-dc3/architecture/)。
|
||||
中国大陆网络环境可改用 `make up-db-cn`。服务启动顺序、IDEA 配置、验证命令和常见坑请阅读
|
||||
[完整快速开始](https://pnoker.github.io/iot-dc3/zh/quickstart/)。
|
||||
|
||||
## 🛠️ 技术栈
|
||||
|
||||
| 分类 | 技术 |
|
||||
|--------------|-------------------------------------------------------------|
|
||||
| **语言与框架** | Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0 |
|
||||
| **数据、缓存与调度** | PostgreSQL · Caffeine · MyBatis-Plus · Quartz |
|
||||
| **消息与通信** | RabbitMQ · gRPC · MQTT (Paho + EMQX) · Protobuf |
|
||||
| **安全与认证** | Spring Security · JWT · BouncyCastle |
|
||||
| **可观测性** | Micrometer · Prometheus · Grafana · ELK |
|
||||
| **前端** | Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 |
|
||||
| **桌面端** | Tauri 2 |
|
||||
| **部署** | Podman · Docker Compose |
|
||||
IoT DC3 基于 Java 21、Spring Boot 4、Spring Cloud 2025、Spring AI 2、PostgreSQL、RabbitMQ、gRPC、Vue 3、
|
||||
TypeScript 与 Vite 构建。
|
||||
|
||||
> 💡 前端源码在本仓库 `dc3-web/` 目录（原独立仓库 `iot-dc3-web` 已归档）。
|
||||
完整组件说明与适用位置请看 [技术栈](https://pnoker.github.io/iot-dc3/zh/introduction/technology-stack)。
|
||||
|
||||
## 📖 文档与社区
|
||||
|
||||
| 资源 | 链接 |
|
||||
|-----------|------------------------------------------------------------------------------|
|
||||
| 📚 在线文档 | [pnoker.github.io/iot-dc3](https://pnoker.github.io/iot-dc3/) |
|
||||
| 🚀 快速开始 | [快速开始指南](https://pnoker.github.io/iot-dc3/quickstart/) |
|
||||
| 🏗️ 架构说明 | [模块与依赖](https://pnoker.github.io/iot-dc3/architecture/modules.html) |
|
||||
| 🔧 驱动开发 | [驱动开发指南](https://pnoker.github.io/iot-dc3/development/driver-authoring.html) |
|
||||
| 🐛 故障排查 | [常见问题与解决方案](https://pnoker.github.io/iot-dc3/guide/troubleshooting.html) |
|
||||
| 📋 变更日志 | [版本更新记录](https://pnoker.github.io/iot-dc3/development/changelog.html) |
|
||||
| 🚀 快速开始 | [快速开始指南](https://pnoker.github.io/iot-dc3/zh/quickstart/) |
|
||||
| 🛠️ 技术栈 | [技术栈说明](https://pnoker.github.io/iot-dc3/zh/introduction/technology-stack) |
|
||||
| 🏗️ 架构说明 | [模块与依赖](https://pnoker.github.io/iot-dc3/zh/architecture/modules) |
|
||||
| 🔧 驱动开发 | [驱动开发指南](https://pnoker.github.io/iot-dc3/zh/development/driver-authoring) |
|
||||
| 🐛 故障排查 | [常见问题与解决方案](https://pnoker.github.io/iot-dc3/zh/guide/troubleshooting) |
|
||||
| 📋 变更日志 | [版本更新记录](https://pnoker.github.io/iot-dc3/zh/development/changelog) |
|
||||
| 🐛 问题反馈 | [GitHub Issues](https://github.com/pnoker/iot-dc3/issues) |
|
||||
| 🇨🇳 码云镜像 | [Gitee GVP 最有价值开源项目](https://gitee.com/pnoker/iot-dc3) |
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ const PILLARS: ReadonlyArray<Pillar> = [
|
||||
navKey: 'pillar.overview', landing: 'introduction',
|
||||
paths: ['introduction', 'quickstart'], activeMatch: '^/(zh|en)/(introduction|quickstart)/',
|
||||
groups: [
|
||||
{key: '', items: [['introduction'], ['introduction/concepts'], ['introduction/paths']]},
|
||||
{key: '', items: [['introduction'], ['introduction/concepts'], ['introduction/paths'], ['introduction/technology-stack']]},
|
||||
{
|
||||
key: 'group.objects-data',
|
||||
items: [['introduction/concepts/profile'], ['introduction/concepts/device'], ['introduction/concepts/driver'], ['introduction/concepts/point'], ['introduction/concepts/point-value']]
|
||||
|
||||
@@ -104,7 +104,7 @@ mind when writing integration tests for executable modules like drivers.
|
||||
|
||||
## Frontend test commands
|
||||
|
||||
The frontend (`iot-dc3-web/`) uses pnpm + Vitest (unit/api/component/view) and Playwright (E2E), independent of the
|
||||
The frontend (`dc3-web/`) uses pnpm + Vitest (unit/api/component/view) and Playwright (E2E), independent of the
|
||||
backend:
|
||||
|
||||
::: code-group
|
||||
|
||||
@@ -80,6 +80,8 @@ For how each hop works and why it's designed that way, see [Architecture](/en/ar
|
||||
- **Frontend**: Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 (source in `dc3-web/` directory of this repo;
|
||||
the standalone `iot-dc3-web` repo is archived)
|
||||
|
||||
See [Technology Stack](./introduction/technology-stack) for the full breakdown.
|
||||
|
||||
## License
|
||||
|
||||
IoT DC3 is open source under the [AGPL-3.0 License](https://github.com/pnoker/iot-dc3/blob/release/LICENSE-AGPL.txt).
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Technology Stack
|
||||
---
|
||||
|
||||
# Technology Stack
|
||||
|
||||
This page summarizes the main technologies IoT DC3 currently runs on and recommends for local development. Treat
|
||||
`pom.xml`, `dc3-web/package.json`, and `docs/package.json` as the source of truth for exact versions; the README keeps
|
||||
only a short reader-facing summary.
|
||||
|
||||
## Backend and Center Services
|
||||
|
||||
| Area | Technologies | Purpose |
|
||||
|------|--------------|---------|
|
||||
| Language and frameworks | Java 21 · Spring Boot 4 · Spring Cloud 2025 | Runtime foundation for the gateway, center services, and driver processes |
|
||||
| AI integration | Spring AI 2.0 | Agentic Center integration with OpenAI-compatible providers, Tool Calling, and MCP workflows |
|
||||
| Web and API | Spring WebFlux · Spring Security · springdoc-openapi | HTTP APIs, authentication and authorization, and aggregated API docs |
|
||||
| Service collaboration | gRPC · Protobuf · Facade interfaces | Strongly typed contracts between center services |
|
||||
| Build | Maven 3.9+ | Multi-module build, tests, packaging, and dependency version management |
|
||||
|
||||
## Data, Messaging, and Scheduling
|
||||
|
||||
| Area | Technologies | Purpose |
|
||||
|------|--------------|---------|
|
||||
| Primary storage | PostgreSQL | Business data, tenants, resources, device models, and runtime data |
|
||||
| Time-series and extensions | TimescaleDB · AGE · pgvector | Point history, graph capabilities, and vector capabilities |
|
||||
| ORM / data access | MyBatis-Plus | Persistence access and paginated queries at the DO layer |
|
||||
| Message bus | RabbitMQ | Asynchronous point value reports, command dispatch, and buffering between drivers and the data center |
|
||||
| Cache and scheduling | Caffeine · Quartz | In-process caching, scheduled jobs, and task orchestration |
|
||||
|
||||
## Frontend, Docs, and Automation
|
||||
|
||||
| Area | Technologies | Purpose |
|
||||
|------|--------------|---------|
|
||||
| Web frontend | Vue 3 · TypeScript 6 · Vite 8 · Element Plus | Management console under `dc3-web/` |
|
||||
| Visualization | AntV G2/G6 | Dashboard charts and relationship visualizations |
|
||||
| Docs site | VitePress · Mermaid | The current `docs/` site, architecture diagrams, and flow diagrams |
|
||||
| CLI automation | TypeScript · pnpm · Vitest | Sibling `dc3-cli/` project, a Gateway-oriented command-line client |
|
||||
| Container deployment | Podman · Docker Compose | Local dependencies, dev stack, app stack, and optional observability stack |
|
||||
|
||||
## Continue Reading
|
||||
|
||||
- [Local Development from Source](../quickstart/) — start dependencies, load environment variables, build, and verify
|
||||
- [Frontend Development](../frontend/) — running, structure, and test commands for `dc3-web/`
|
||||
- [System Architecture Overview](../architecture/) — how the gateway, centers, drivers, message bus, and storage work together
|
||||
- [Module Map](../architecture/modules) — Maven modules, deployable units, and dependencies
|
||||
@@ -87,12 +87,11 @@ The table below is a reference index. For how to use each entry point, see its o
|
||||
| Swagger UI | `http://localhost:8000/swagger-ui.html` | Browse the gateway-aggregated API in development (usually disabled in production) |
|
||||
| Direct-connect debugging per center | Auth `8300` / Manager `8400` / Data `8500` / Agentic `8600` | When debugging a single center, connect straight to its HTTP port, bypassing the gateway |
|
||||
| MCP / OAuth entry | `POST /mcp`, `GET /.well-known/oauth-protected-resource` | For AI Agents to reach MCP tools over OAuth 2.1 (both at the gateway root, not under `/api/v3`); see [Agentic Center](../ai/agentic) |
|
||||
| Web UI | The frontend source lives in the separate `iot-dc3-web` repository | The graphical interface; its backend calls go through the Gateway too |
|
||||
| Web UI | The frontend source lives under `dc3-web/` in this repository | The graphical interface; its backend calls go through the Gateway too |
|
||||
|
||||
::: info The Web UI is not in this repository
|
||||
This repository (`iot-dc3`) holds the backend and the docs only. The graphical interface is the Vue frontend project in
|
||||
the separate `iot-dc3-web` repository, and it calls the same set of APIs through the Gateway. This manual describes
|
||||
operations in terms of API calls and curl. The matching UI entry points map one-to-one.
|
||||
::: info The Web UI uses the same API entry point
|
||||
The graphical interface lives under `dc3-web/` in this repository and calls the same set of APIs through the Gateway.
|
||||
This manual describes operations in terms of API calls and curl. The matching UI entry points map one-to-one.
|
||||
:::
|
||||
|
||||
## From login to a single command: the minimal runnable example
|
||||
|
||||
@@ -22,7 +22,7 @@ build toolchain plus a container runtime.
|
||||
- **JDK 21** — the platform requires Java 21. Compiling on a lower version fails outright.
|
||||
- **Maven 3.9+** — the repository ships `.mvn/settings.xml` and a parallel-build configuration; use it for multi-module
|
||||
packaging.
|
||||
- **pnpm** — both the `iot-dc3-web` frontend and `dc3-cli` use pnpm (not npm or yarn). Skip this for backend-only work.
|
||||
- **pnpm** — both the `dc3-web/` frontend and sibling `dc3-cli/` use pnpm (not npm or yarn). Skip this for backend-only work.
|
||||
- **Podman** — every container operation in this repository uses `podman` (`make` defaults to `podman compose`).
|
||||
|
||||
## Why These Five Steps
|
||||
|
||||
@@ -9,6 +9,7 @@
|
||||
"introduction": "Overview",
|
||||
"introduction/concepts": "Core Concepts",
|
||||
"introduction/paths": "Choose Your Path",
|
||||
"introduction/technology-stack": "Technology Stack",
|
||||
"introduction/concepts/profile": "Profile",
|
||||
"introduction/concepts/device": "Device",
|
||||
"introduction/concepts/driver": "Driver",
|
||||
|
||||
@@ -9,6 +9,7 @@
|
||||
"introduction": "总览",
|
||||
"introduction/concepts": "核心概念",
|
||||
"introduction/paths": "按角色选择路径",
|
||||
"introduction/technology-stack": "技术栈",
|
||||
"introduction/concepts/profile": "物模型",
|
||||
"introduction/concepts/device": "设备",
|
||||
"introduction/concepts/driver": "驱动",
|
||||
|
||||
@@ -91,7 +91,7 @@ dc3-coverage/target/site/jacoco-aggregate/index.html
|
||||
|
||||
## 前端测试命令
|
||||
|
||||
前端（`iot-dc3-web/`）用 pnpm + Vitest（单元/接口/组件/视图）与 Playwright（E2E），与后端独立：
|
||||
前端（`dc3-web/`）用 pnpm + Vitest（单元/接口/组件/视图）与 Playwright（E2E），与后端独立：
|
||||
|
||||
::: code-group
|
||||
|
||||
|
||||
@@ -77,6 +77,8 @@ RabbitMQ 异步解耦。
|
||||
- **前端**：Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6（源码在本仓库 `dc3-web/` 目录，原独立仓库
|
||||
`iot-dc3-web` 已归档）
|
||||
|
||||
完整说明见 [技术栈](./introduction/technology-stack)。
|
||||
|
||||
## 开源协议
|
||||
|
||||
IoT DC3 基于 [AGPL-3.0 License](https://github.com/pnoker/iot-dc3/blob/release/LICENSE-AGPL.txt)
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: 技术栈
|
||||
---
|
||||
|
||||
# 技术栈
|
||||
|
||||
这页汇总 IoT DC3 当前推荐和运行中的主要技术选型。精确版本以仓库内的 `pom.xml`、`dc3-web/package.json` 和
|
||||
`docs/package.json` 为准；README 只保留面向新读者的摘要。
|
||||
|
||||
## 后端与中心服务
|
||||
|
||||
| 范围 | 技术 | 用途 |
|
||||
|------|------|------|
|
||||
| 语言与框架 | Java 21 · Spring Boot 4 · Spring Cloud 2025 | 网关、四个中心服务与驱动进程的运行基础 |
|
||||
| AI 集成 | Spring AI 2.0 | Agentic Center 接入 OpenAI-compatible provider、Tool Calling 与 MCP 工作流 |
|
||||
| Web 与 API | Spring WebFlux · Spring Security · springdoc-openapi | HTTP API、认证鉴权、聚合 API 文档 |
|
||||
| 服务协作 | gRPC · Protobuf · Facade 接口 | 中心服务之间的强类型调用契约 |
|
||||
| 构建 | Maven 3.9+ | 多模块构建、测试、打包和依赖版本管理 |
|
||||
|
||||
## 数据、消息与调度
|
||||
|
||||
| 范围 | 技术 | 用途 |
|
||||
|------|------|------|
|
||||
| 主存储 | PostgreSQL | 业务数据、租户、资源、设备模型与运行数据 |
|
||||
| 时序与扩展 | TimescaleDB · AGE · pgvector | 位号历史、图能力和向量能力扩展 |
|
||||
| ORM / 数据访问 | MyBatis-Plus | DO 层持久化访问与分页查询 |
|
||||
| 消息总线 | RabbitMQ | 驱动与数据中心之间的异步值上报、命令下发与削峰 |
|
||||
| 缓存与调度 | Caffeine · Quartz | 进程内缓存、定时任务与调度 |
|
||||
|
||||
## 前端、文档与自动化
|
||||
|
||||
| 范围 | 技术 | 用途 |
|
||||
|------|------|------|
|
||||
| Web 前端 | Vue 3 · TypeScript 6 · Vite 8 · Element Plus | `dc3-web/` 下的管理控制台 |
|
||||
| 可视化 | AntV G2/G6 | 仪表盘图表与关系可视化 |
|
||||
| 文档站 | VitePress · Mermaid | 当前 `docs/` 文档站、架构图和流程图 |
|
||||
| CLI 自动化 | TypeScript · pnpm · Vitest | sibling `dc3-cli/` 项目，面向 Gateway 的命令行客户端 |
|
||||
| 容器部署 | Podman · Docker Compose | 本地依赖、开发栈、应用栈和可选观测栈 |
|
||||
|
||||
## 继续阅读
|
||||
|
||||
- [从源码本地开发](../quickstart/) — 启动依赖、加载环境变量、构建与验证
|
||||
- [前端开发](../frontend/) — `dc3-web/` 的运行、目录和测试命令
|
||||
- [系统架构总览](../architecture/) — 网关、中心服务、驱动、消息总线和存储如何协作
|
||||
- [模块地图](../architecture/modules) — Maven 模块、部署单元和依赖关系
|
||||
@@ -70,11 +70,10 @@ flowchart LR
|
||||
| Swagger UI | `http://localhost:8000/swagger-ui.html` | 开发环境查看网关聚合后的 API（生产环境一般关闭） |
|
||||
| 各中心直连调试 | Auth `8300` / Manager `8400` / Data `8500` / Agentic `8600` | 单独调试某个中心时直连其 HTTP 端口，绕过网关 |
|
||||
| MCP / OAuth 入口 | `POST /mcp`、`GET /.well-known/oauth-protected-resource` | 供 AI Agent 经 OAuth 2.1 访问 MCP 工具（均在网关根路径，不经 `/api/v3`），见 [Agentic 中心](../ai/agentic) |
|
||||
| Web UI | 前端源码在独立的 `iot-dc3-web` 仓库 | 图形化操作界面，后端接口同样通过 Gateway 访问 |
|
||||
| Web UI | 前端源码在本仓库 `dc3-web/` 目录 | 图形化操作界面，后端接口同样通过 Gateway 访问 |
|
||||
|
||||
::: info Web UI 不在本仓库
|
||||
本仓库（`iot-dc3`）只含后端与文档；图形界面是独立的 `iot-dc3-web` 仓库里的 Vue 前端工程，它通过 Gateway 调用同一套 API。本手册以
|
||||
API / curl 为准描述操作，UI 上的对应入口与之一一对应。
|
||||
::: info Web UI 与 API 共用同一入口
|
||||
图形界面位于本仓库 `dc3-web/` 目录，通过 Gateway 调用同一套 API。本手册以 API / curl 为准描述操作，UI 上的对应入口与之一一对应。
|
||||
:::
|
||||
|
||||
## 从登录到一条命令：最小可跑示例
|
||||
|
||||
@@ -18,7 +18,7 @@ JDK/构建工具，外加一个容器运行时。
|
||||
|
||||
- **JDK 21** —— 平台强制 Java 21，低版本编译会直接失败。
|
||||
- **Maven 3.9+** —— 仓库内置 `.mvn/settings.xml` 与并行构建配置；多模块打包用它。
|
||||
- **pnpm** —— 前端 `iot-dc3-web` 与 `dc3-cli` 都用 pnpm（不要用 npm/yarn）。仅做后端开发可跳过。
|
||||
- **pnpm** —— 前端 `dc3-web/` 与同级目录 `dc3-cli/` 都用 pnpm（不要用 npm/yarn）。仅做后端开发可跳过。
|
||||
- **Podman** —— 本仓库容器操作一律用 `podman`（`make` 默认 `podman compose`）。
|
||||
|
||||
## 在 JetBrains IDEA 中开发
|
||||
|
||||
Reference in New Issue
Block a user