12 KiB
title
| title |
|---|
| 部署模式与镜像源 |
部署模式与镜像源
IoT DC3 用四个 Compose 栈拼出完整环境：db 起依赖、dev 从源码构建、app 拉预构建镜像、optional 叠可观测性。这页讲清每个栈的用途、
make 生命周期命令、以及镜像从哪个仓库拉、对外暴露哪些端口——读完你能挑对栈、选对镜像源、知道生产上该锁哪些口。
四个 Compose 栈各司其职
平台没有"一个大 compose 包打天下"，而是按职责切成四个栈，分别对应 dc3/ 下四个 Compose 文件。它们叠加使用：依赖层先起，应用层再起，可观测层按需加。
db（docker-compose-db.yml）：基础设施层，只有两个容器——dc3-postgres（PostgreSQL + AGE/TimescaleDB/pgvector，承载元数据、时序值、告警、Agentic 会话）和dc3-rabbitmq（数据流/命令流的消息总线）。任何应用栈都依赖它先就绪。dev（docker-compose-dev.yml）：源码构建栈，从本地Dockerfile现场build出dc3-gateway与四个中心（auth/manager/data/agentic）等。给改后端代码、要本地调试的人用；前端不在此栈内，单独pnpm dev起。app（docker-compose.yml）：预构建镜像栈，直接拉远端镜像跑，含前端dc3-web、网关、四个中心、以及一组驱动容器。给评估、演示、生产部署用——不编译、起得快。optional（docker-compose-optional.yml）：可观测性与可选依赖栈，含 EMQX、Elasticsearch/Logstash/Kibana、Prometheus、Grafana、APM 及若干 exporter。按需叠加，不影响核心链路。详见 可观测性。
::: info dev 与 app 的取舍
要改 Java 代码就用 dev（现场构建，改完重 build）；只想把平台跑起来评估或上生产就用 app（拉镜像，最快）。两者用的是同一套
db/optional 依赖栈。
:::
部署拓扑：谁对外、谁只在内网
下图给出四栈如何叠加，以及 ingress 边界——**生产形态（app 栈）只有 dc3-web 和 dc3-driver-listening-virtual 发布到宿主机
**，网关与四个中心都在内部 dc3net 网络里，靠前端反代或内部调用访问，不直接对外。
flowchart TB
subgraph Ingress["对外入口（仅这两个发布到宿主机）"]
Web["前端 dc3-web<br/>(8080 / 8443)"]
LV["监听型驱动 dc3-driver-listening-virtual<br/>(TCP 6270 / UDP 6271)"]
end
subgraph App["app 栈：预构建镜像"]
GW["网关 dc3-gateway<br/>(内部 8000)"]
Auth["鉴权中心 dc3-center-auth"]
Mgr["管理中心 dc3-center-manager"]
Data["数据中心 dc3-center-data"]
Agt["智能中心 dc3-center-agentic"]
Drv["驱动容器组<br/>modbus-tcp / opc-ua / mqtt / ..."]
end
subgraph Dev["dev 栈：源码构建（替代 app）"]
DevBuild["现场 build 网关与四个中心"]
end
subgraph DB["db 栈：基础设施"]
PG[("dc3-postgres<br/>PostgreSQL + Timescale")]
MQ["dc3-rabbitmq<br/>消息总线"]
end
subgraph Opt["optional 栈：可观测性（按需）"]
Obs["EMQX / ELK / Prometheus / Grafana"]
end
Web --> GW
GW --> Auth & Mgr & Data & Agt
Data --> MQ
Drv --> MQ
LV --> Drv
Auth & Mgr & Data & Agt --> PG
App -.依赖.-> DB
Dev -.依赖.-> DB
Opt -.叠加.-> App
::: danger 对外入口只有 web 与 listening-virtual
在 app（生产）栈里，只有 dc3-web（8080/8443）和 dc3-driver-listening-virtual（TCP 6270 / UDP 6271）发布到宿主机端口；网关
8000、四个中心的 HTTP/gRPC 端口、数据库、消息队列一律只在内部网络，不要额外暴露到公网。
注意 dev 栈为方便调试会额外发布网关 8000 与各中心 HTTP 端口（8300/8400/8500/8600）及 auth/manager/data 对应的
gRPC（9300/9400/9500，agentic 无 gRPC server），这是开发便利，不要照搬到生产。所有发布默认绑定 DC3_BIND_HOST=127.0.0.1
（仅本机），需要跨机访问才改成 0.0.0.0，且改之前先收敛端口。
:::
make 生命周期：一套命令操作任意栈
所有栈共用同一组 make 目标，靠变量选择"对哪个栈、哪些服务、用哪个镜像源"。命令都在 iot-dc3/ 目录下跑。
核心生命周期目标：
make build— 构建镜像（dev栈现场编译；app栈一般无需 build）make up— 启动（-d后台）make down— 停止并移除容器（保留数据卷）make config— 渲染并校验 Compose 配置，不实际启动make logs— 跟随日志（-f --tail=200）make reset— ⚠️ down + 删除数据卷，需显式确认（见下方 danger）
选择"操作哪个栈、哪些服务"的变量：
| 变量 | 默认 | 作用 |
|---|---|---|
STACK |
dev |
选栈：db / dev / app / optional |
SERVICES |
（空=全部） | 只操作指定服务，空格分隔，如 SERVICES="gateway agentic" |
GROUP |
（空） | 预定义服务组：center（四个中心）/ core（中心 + 网关）/ drivers（驱动组） |
COMPOSE |
podman compose |
容器运行时（本仓库统一用 podman） |
GROUP 是 SERVICES 的快捷写法——center 展开为 auth manager data agentic，core 再加 gateway，drivers 展开为内置驱动集合。
SERVICES 与 GROUP 可叠加。
::: code-group
# 依赖 → 可观测性 → 源码构建栈
make up STACK=db
make up STACK=optional
make up STACK=dev
make up STACK=db
make up SERVICES="gateway agentic" # 只起网关 + 智能中心
make up GROUP=core # 起四个中心 + 网关
make logs SERVICES="gateway agentic" # 只看这两个的日志
make config STACK=app # 只渲染配置，不启动
make down STACK=dev # 停 dev 栈，保留数据
:::
::: danger reset 会删数据卷
make reset 会执行 down 并删除数据卷——PostgreSQL 里的元数据、时序值、告警全部丢失。它带硬性闸门：必须显式
CONFIRM_RESET_VOLUMES=true 才会执行，否则直接拒绝。
make reset STACK=db CONFIRM_RESET_VOLUMES=true
生产环境慎用。删卷后下次起库会重新跑一遍 initdb 种子脚本（见末节）。 :::
镜像源：REGISTRY 选仓库，DC3_IMAGE_TAG 选版本
镜像从哪个仓库拉由 REGISTRY 决定，它在 make 层把 DC3_IMAGE_REGISTRY（Compose 实际读的命名空间）解析出来：
REGISTRY |
解析出的 DC3_IMAGE_REGISTRY |
适用 |
|---|---|---|
auto（默认） |
读环境/.env 里的 DC3_IMAGE_REGISTRY，未设则 pnoker |
自定义私有仓库或沿用 .env |
global |
pnoker（Docker Hub） |
海外/通用网络 |
cn |
registry.cn-beijing.aliyuncs.com/dc3（阿里云） |
中国大陆，拉取更快 |
传入其它值会直接报错 Unsupported REGISTRY。镜像版本由 DC3_IMAGE_TAG（默认 2026.6）统一控制——所有服务与依赖镜像共用同一个
tag，生产建议钉死具体版本而非 latest。
::: code-group
make up STACK=db REGISTRY=global
make up STACK=app REGISTRY=global
make up STACK=db REGISTRY=cn
make up STACK=app REGISTRY=cn
:::
举例：在 cn 下，网关镜像解析为 registry.cn-beijing.aliyuncs.com/dc3/dc3-gateway:2026.6；在 global 下则是
pnoker/dc3-gateway:2026.6。完整镜像清单见末节折叠的命令参考。
::: warning Makefile 用 REGISTRY，Compose 用 DC3_IMAGE_REGISTRY
两个名字别混。REGISTRY=auto|global|cn 是 make 的选择器，它负责把对应的 DC3_IMAGE_REGISTRY 命名空间注入 Compose；直接跑
podman compose 时要自己设 DC3_IMAGE_REGISTRY。
:::
起栈后：种子数据与对外验证
app/dev 栈起来后，平台已可用。验证对外入口最直接的方式是走前端 dc3-web（默认 http://127.0.0.1:8080）。若要从命令行打
API，需经网关——但网关在 app 栈不对外，通常在 dev 栈（发布 8000）下验证。登录是两步：先 POST /api/v3/auth/token/salt 取盐，再
POST /api/v3/auth/token/generate 换取 12 小时有效的 token，后续请求带上 X-Auth-Tenant / X-Auth-Login /
X-Auth-Token 三个鉴权头。
# 仅在网关对外的 dev 栈下可用；值均为示例，按你的租户/账号替换
# 1) 取盐（公开）
curl -s -X POST http://127.0.0.1:8000/api/v3/auth/token/salt \
-H 'Content-Type: application/json' \
-d '{"tenant":"default","name":"dc3"}'
# → 返回 5 分钟有效的盐字符串（示例）
# 2) 用盐对密码哈希后换取 token（公开），返回 12 小时有效的访问令牌
curl -s -X POST http://127.0.0.1:8000/api/v3/auth/token/generate \
-H 'Content-Type: application/json' \
-d '{"tenant":"default","name":"dc3","salt":"<上一步返回>","password":"<哈希后密码>"}'
数据库首次在空数据卷上启动时，dc3-postgres 入口会按文件名顺序执行 initdb 下的 7 个种子脚本，一次性建好库结构与基础数据：
| 顺序 | 脚本 | 内容 |
|---|---|---|
| 00 | 00-iot-dc3-extensions.sql |
启用扩展 |
| 01 | 01-iot-dc3-common.sql |
公共表 |
| 02 | 02-iot-dc3-auth.sql |
菜单、资源、用户、角色、OAuth/MCP |
| 03 | 03-iot-dc3-data.sql |
运行时数据：告警、通知、规则 |
| 04 | 04-iot-dc3-manager.sql |
实体管理：设备、驱动、位号、模板 |
| 05 | 05-iot-dc3-history.sql |
时序超表（hypertable） |
| 06 | 06-iot-dc3-agentic.sql |
会话、消息、附件 |
::: warning 种子脚本只在空库首次跑
这些脚本仅在数据卷为空时执行一次。卷里已有数据时不会重跑，改了 SQL 也不会自动生效——要重新种子，得先
make reset ... CONFIRM_RESET_VOLUMES=true 清卷（会丢数据）。
:::
::: danger 生产 secrets 必须随机
.env.example 里的 DC3_SECURITY_KEY、AUTH_HMAC_SECRET，以及 POSTGRES_PASSWORD / RABBITMQ_PASSWORD（默认
dc3dc3dc3）都是公开的弱默认值，仅供本地。生产部署前必须替换为强随机值。
其中 AUTH_HMAC_SECRET 带 fail-fast 保护：当 Spring profile 命中 pre 或 pro、而密钥为空或仍等于默认
io.github.pnoker.dc3 时，服务启动直接抛 IllegalStateException
拒绝起来。各密钥含义见 环境变量详解。
:::
完整命令与镜像参考
下面折叠的是 dc3/doc/USAGE.md 的完整原文，列出所有 make 快捷命令与每个服务在 Docker Hub / 阿里云两套仓库的镜像坐标，作为操作时的速查表。
::: details 展开完整命令与镜像清单
:::