opensource/iot-dc3
3
0
Fork 0
mirror of https://gitee.com/pnoker/iot-dc3.git synced 2026-11-01 18:51:53 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
develop
iot-dc3/dc3/doc/USAGE.md
T
pnoker 987c96d501 docs(deployment): correct factual errors in DEPLOYMENT.md and USAGE.md 
- driver replicas are per-instance nodes with their own RabbitMQ
  command queues (group=dc3.driver.client, key service.node), not
  workers over shared queues; FAQ now also states Compose/Swarm keep
  protocol drivers at 1 replica (shared driver_data / SQLite outbox)
- fail-fast gate covers AUTH_HMAC_SECRET only; DC3_SECURITY_KEY is
  non-empty-checked, so a weak default still boots
- 6271 is intended as the device UDP channel but every publish site
  omits /udp / protocol: UDP and actually publishes TCP - say so
- k8s scaling note: scaled driver pods are independent nodes, not one
  shared worker pool
- swarm runbook: pushing dependency images is a multi-node requirement,
  a local build is fine on a single node
- USAGE.md: NODE_ENV bullet narrowed to weak AUTH_HMAC_SECRET rejected
2026-08-28 23:56:08 +08:00

145 lines
10 KiB
Markdown
Raw Permalink Blame History

# 📦 Usage
### 🍭 Requirements
> These are the core requirements needed to build and run the application. Make sure to have these tools installed and
> properly configured in your development environment.
- **JDK 21**: Java Development Kit version 21 or higher
- **Maven**: Build automation and dependency management tool
- **Podman or Docker**: Container platform with Compose support for building and running applications
### 🍻 Quick Start
> Choose one of the following container registries:
#### 🦁 Docker Hub
> Global access with standard Docker registry service
```bash
cd iot-dc3
make up-db
make up STACK=app
```
#### 🐱 China Registry
> Optimized registry service for users in mainland China
```bash
cd iot-dc3
make up-db-cn
make up STACK=app REGISTRY=cn
```
> You can also start full workflows or other compose stacks with the same selector, for example:
```bash
make up-db && make up-optional && make up-dev
make up-db-cn && make up-optional-cn && make up-dev-cn
make up-db-cn && make up-optional-cn && make up-app-cn
make up STACK=optional
make up STACK=optional REGISTRY=cn
make logs STACK=dev REGISTRY=global
```
For frontend and API testing, use the service-level shortcuts to start only the modules under test:
```bash
make up-db-cn
make up SERVICES=agentic REGISTRY=cn
make up SERVICES="gateway agentic" REGISTRY=cn
make logs SERVICES="gateway agentic"
make up GROUP=core REGISTRY=cn
make up GROUP=drivers REGISTRY=cn
```
## 🐳 Container
### ⛳ Platform Support
All images are built for multiple platforms:
- `linux/amd64` - For Intel/AMD 64-bit systems
- `linux/arm64` - For ARM 64-bit systems (Apple Silicon, ARM servers)
### 🚥 Version Tags
- `${DC3_IMAGE_TAG}` - Specific version (recommended for production)
- `latest` - Latest stable version (may change)
### 🍉 Images
| Description | Docker Hub | China Registry |
|--------------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------|
| Gateway | `pnoker/dc3-gateway:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-gateway:${DC3_IMAGE_TAG}` |
| Agentic Center | `pnoker/dc3-center-agentic:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-center-agentic:${DC3_IMAGE_TAG}` |
| Auth Center | `pnoker/dc3-center-auth:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-center-auth:${DC3_IMAGE_TAG}` |
| Data Center | `pnoker/dc3-center-data:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-center-data:${DC3_IMAGE_TAG}` |
| Manager Center | `pnoker/dc3-center-manager:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-center-manager:${DC3_IMAGE_TAG}` |
| Single Center | `pnoker/dc3-center-single:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-center-single:${DC3_IMAGE_TAG}` |
| Listening Virtual Driver | `pnoker/dc3-driver-listening-virtual:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-listening-virtual:${DC3_IMAGE_TAG}` |
| Modbus TCP Driver | `pnoker/dc3-driver-modbus-tcp:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-modbus-tcp:${DC3_IMAGE_TAG}` |
| Modbus RTU Driver | `pnoker/dc3-driver-modbus-rtu:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-modbus-rtu:${DC3_IMAGE_TAG}` |
| MQTT Driver | `pnoker/dc3-driver-mqtt:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-mqtt:${DC3_IMAGE_TAG}` |
| OPC DA Driver | `pnoker/dc3-driver-opc-da:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-opc-da:${DC3_IMAGE_TAG}` |
| OPC UA Driver | `pnoker/dc3-driver-opc-ua:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-opc-ua:${DC3_IMAGE_TAG}` |
| Siemens S7 Driver | `pnoker/dc3-driver-plcs7:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-plcs7:${DC3_IMAGE_TAG}` |
| Virtual Driver | `pnoker/dc3-driver-virtual:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-virtual:${DC3_IMAGE_TAG}` |
| BACnet/IP Driver | `pnoker/dc3-driver-bacnet-ip:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-bacnet-ip:${DC3_IMAGE_TAG}` |
| BLE Driver | `pnoker/dc3-driver-ble:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-ble:${DC3_IMAGE_TAG}` |
| CAN Driver | `pnoker/dc3-driver-can:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-can:${DC3_IMAGE_TAG}` |
| CoAP Driver | `pnoker/dc3-driver-coap:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-coap:${DC3_IMAGE_TAG}` |
| DLMS Driver | `pnoker/dc3-driver-dlms:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-dlms:${DC3_IMAGE_TAG}` |
| EtherNet/IP Driver | `pnoker/dc3-driver-ethernet-ip:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-ethernet-ip:${DC3_IMAGE_TAG}` |
| Omron FINS Driver | `pnoker/dc3-driver-fins:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-fins:${DC3_IMAGE_TAG}` |
| HTTP Driver | `pnoker/dc3-driver-http:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-http:${DC3_IMAGE_TAG}` |
| IEC 60870-5-104 Driver | `pnoker/dc3-driver-iec104:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-iec104:${DC3_IMAGE_TAG}` |
| LwM2M Driver | `pnoker/dc3-driver-lwm2m:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-lwm2m:${DC3_IMAGE_TAG}` |
| Mitsubishi MELSEC Driver | `pnoker/dc3-driver-melsec:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-melsec:${DC3_IMAGE_TAG}` |
| MySQL Driver | `pnoker/dc3-driver-mysql:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-mysql:${DC3_IMAGE_TAG}` |
| Oracle Driver | `pnoker/dc3-driver-oracle:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-oracle:${DC3_IMAGE_TAG}` |
| PostgreSQL Driver | `pnoker/dc3-driver-postgresql:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-postgresql:${DC3_IMAGE_TAG}` |
| Serial Driver | `pnoker/dc3-driver-serial:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-serial:${DC3_IMAGE_TAG}` |
| SL651 Driver | `pnoker/dc3-driver-sl651:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-sl651:${DC3_IMAGE_TAG}` |
| SNMP Driver | `pnoker/dc3-driver-snmp:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-snmp:${DC3_IMAGE_TAG}` |
| SQL Server Driver | `pnoker/dc3-driver-sqlserver:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-sqlserver:${DC3_IMAGE_TAG}` |
| TCP/UDP Driver | `pnoker/dc3-driver-tcp-udp:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-tcp-udp:${DC3_IMAGE_TAG}` |
| Zigbee Driver | `pnoker/dc3-driver-zigbee:${DC3_IMAGE_TAG}` | `registry.cn-beijing.aliyuncs.com/dc3/dc3-driver-zigbee:${DC3_IMAGE_TAG}` |
## 🚢 Deployment
> Single-host Compose is only the first of five deployment modes. The full runbook - every
> command, the scaling semantics, and the production hardening checklist - lives in
> [`dc3/doc/DEPLOYMENT.md`](https://github.com/pnoker/iot-dc3/blob/main/dc3/doc/DEPLOYMENT.md).
| Mode | Files | Use for |
|-----------------|------------------------------------------------------|---------------------------------------------|
| Single host | `docker-compose-db.yml` + `docker-compose.yml` | evaluation, demo, small production |
| Compose scaling | `docker-compose-db.yml` + `docker-compose-scale.yml` | replicated services on one host (`--scale`) |
| Docker Swarm | `docker-compose-swarm.yml` | multi-node swarm (`make stack-deploy`) |
| Kubernetes | `dc3/deploy/k8s/` | production Kubernetes (`make k8s-apply`) |
| Helm | `dc3/deploy/helm/dc3/` | GitOps installs (`make helm-install`) |
Facts that hold in every mode:
- **Dependency images** (`dc3-postgres`, `dc3-rabbitmq`) are built locally by the `db` stack and are **not published**
by the release CI. For swarm/k8s/helm, build and push them first
(`DC3_IMAGE_REGISTRY=my.registry/dc3 ./dc3/deploy/k8s/scripts/push-images.sh`) or point the stack at managed services
instead.
- **`dc3-web` is tagged `latest` and full release versions only** - it has no series tag like
`2026.6`. Backend images (gateway, centers, drivers) carry `latest`, the series tag, and the full version. The
deployment configs account for this; pin a full release version for
`dc3-web` when you need reproducible rollouts.
- **DNS names are the contract.** Keep the default service names (`dc3-postgres`,
`dc3-rabbitmq`, `dc3-center-*`, `dc3-gateway`, `dc3-web`) so the images resolve each other, or override
`POSTGRES_HOST`, `RABBITMQ_HOST`, `MQTT_BROKER_HOST`, `CENTER_*_HOST`, and
`APP_API_HOST` to point at services deployed differently.
- **`NODE_ENV` selects the Spring profile** at runtime: `test` (the default in every deployment config) or `pro`
(hardened: OpenAPI/Swagger UI disabled, weak `AUTH_HMAC_SECRET` rejected at startup).
Mode-specific runbooks: `dc3/deploy/k8s/README.md`, `dc3/deploy/helm/dc3/README.md`, and the
`stack-deploy` / `stack-rm` / `k8s-apply` / `k8s-delete` / `helm-install` / `helm-uninstall`
targets in the root `Makefile`.
Reference in New Issue View Git Blame Copy Permalink