IoT DC3

简体中文

Languages
English

简体中文

Languages
English

主题

环境变量详解 ​

IoT DC3 有两套环境变量文件，读取者完全不同：根目录 .env 给 Docker Compose 做插值，dc3/env/dev.env(.sh) 给本地 Java 进程。读完这页，你能分清哪个变量该写进哪个文件、localhost 端口与容器内端口为何不一样，以及生产前必须改掉的两个密钥默认值。

你在这里：已经从源码本地开发或用 Compose 起栈。下一步看部署模式与镜像源了解整套栈如何拉起。

为什么有两套文件 ​

同一个变量名（如 POSTGRES_HOST），在容器里和在你笔记本上的 Java 进程里，含义不一样。容器之间靠 Compose 网络上的服务名（dc3-postgres）互访；而你本地 IDE 里跑的 Java 进程在宿主机上，只能通过 Compose 发布到宿主机的端口（如 localhost:35432）连进去。两套文件就是为这两条互不重叠的路径准备的——混用会让本地进程去连一个解析不了的容器名，或让容器去连一个它根本看不到的 localhost。

文件读取者用途注入方式
.env.exampleDocker Compose 模板复制为根目录 .env，定义镜像仓库、镜像标签、发布端口Compose 变量插值
.envDocker Compose本机未跟踪配置，供 dc3/docker-compose*.yml 插值Compose 变量插值
dc3/env/dev.envIDE（EnvFile 插件）本地 Java 进程环境变量，不带 exportIDE EnvFile 插件读取
dc3/env/dev.env.shShell本地 Java 进程环境变量，带 export，用 source 加载Shell 环境注入

根 .env 不会注入本地 Java 进程

根目录 .env 只服务 Docker Compose，不会自动注入到本地 IDE/命令行启动的 Java 进程。本地源码运行必须用 dc3/env/dev.env(.sh)，让进程指向 Compose 发布在 localhost 上的依赖端口。在根 .env 里写 POSTGRES_HOST=localhost 也不会改变任何容器的运行时环境。

两条互不注入的路径 ​

下图说明两套文件如何沿各自路径生效。关键是这两条路径互不交叉：Compose 不读 dev.env.sh，本地 Java 进程也不自动读根 .env。

host 端口与 internal 端口的对应关系，是理解这张图的核心：

依赖host（本地进程用）internal（容器互访用）
PostgreSQLlocalhost:35432dc3-postgres:5432
RabbitMQ AMQPlocalhost:35672dc3-rabbitmq:5672
EMQX MQTTlocalhost:31883dc3-emqx:1883（约定值）

怎么用 ​

Compose 起栈 ​

先从模板创建本地 .env，再用 make（底层是 podman compose）拉起：

bash
cp .env.example .env
make up-db && make up-optional && make up-dev
bash
cp .env.example .env
podman compose -f dc3/docker-compose-dev.yml config --quiet

根 .env 的变量用于 compose 文件插值，例如镜像与发布端口：

yaml
image: ${DC3_IMAGE_REGISTRY:-pnoker}/dc3-gateway:${DC3_IMAGE_TAG:-2026.6}
ports:
  - "${DC3_BIND_HOST:-127.0.0.1}:${DC3_GATEWAY_PORT:-8000}:8000"

Compose 不会把 .env 里每个变量都注入每个容器——只有 compose 文件通过 environment、env_file 显式引用的变量才会进入容器。

本地源码运行 ​

从命令行启动 Java 进程前先 source：

bash
source dc3/env/dev.env.sh

不加载时，本地进程会回退到容器内服务名（dc3-postgres、dc3-rabbitmq、dc3-center-manager）或默认端口，从而连不上本机依赖。JetBrains IDEA 用户改用 dc3/env/dev.env（同样内容、无 export）：安装 EnvFile 插件 → 在 Run Configuration 启用 EnvFile → 添加 dc3/env/dev.env。不要把 .env.example 直接当作 IDEA 环境变量文件——它是 Compose 模板，不是 Java 运行时配置。

按场景分组的关键变量 ​

下面按"为某个场景实际需要"的角度分组列出关键变量。完整长表在文末 ::: details 折叠，这里只列你会真正改动或排错时查的那些。变量的 Scope 三类含义：Runtime（本地或容器内 Java 进程都读）、Compose only（仅根 .env 给 Compose）、Per-process（单服务覆盖）。

安全密钥（Runtime） ​

两个密钥是平台的身份根。它们自带默认值仅为方便首次启动，绝不可带进生产。

变量默认值用途
DC3_SECURITY_KEYdc3.security.key.2026.io.github.pnoker鉴权中心生成/校验登录 Token 的签名密钥
AUTH_HMAC_SECRETio.github.pnoker.dc3Gateway 向后端服务签名 X-Auth-Principal 的 HMAC-SHA256 密钥

生产必须改成强随机值，且切勿提交/打印

DC3_SECURITY_KEY 与 AUTH_HMAC_SECRET 自带默认值，生产环境必须改成强随机值，切勿提交进仓库、写入日志或打印真实密钥。当 Spring profile 为 pre/pro 且 AUTH_HMAC_SECRET 为空或仍等于默认值 io.github.pnoker.dc3 时，服务会 fail-fast 抛 IllegalStateException 拒绝启动——这是有意为之的安全闸门，不要绕过。

PostgreSQL（Runtime） ​

本地进程连 localhost:35432；容器内连 dc3-postgres:5432。POSTGRES_SCHEMA 只在单服务进程里做 schema 覆盖（如 dc3_manager、dc3_data），不要全局设。

变量默认值Scope用途
POSTGRES_HOSTlocalhostRuntime本地用 localhost，容器内用 dc3-postgres
POSTGRES_PORT35432Runtimehost 发布端口；internal 为 5432
POSTGRES_USERNAMEdc3Runtime用户名
POSTGRES_PASSWORDdc3dc3dc3Runtime密码
POSTGRES_DBdc3Runtime数据库名
POSTGRES_SCHEMA(未设)Per-process单服务 schema 覆盖
DC3_POSTGRES_PORT35432Compose only容器发布到宿主机的端口

RabbitMQ（Runtime） ​

AMQP host 端口 35672，internal 5672。开启 TLS 时内部端口切到 5671。

变量默认值Scope用途
RABBITMQ_HOSTlocalhostRuntime本地 localhost，容器内 dc3-rabbitmq
RABBITMQ_PORT35672RuntimeAMQP host 端口；internal 5672
RABBITMQ_USERNAMEdc3Runtime用户名
RABBITMQ_PASSWORDdc3dc3dc3Runtime密码
RABBITMQ_VIRTUAL_HOSTdc3Runtimevirtual host
RABBITMQ_SSL_ENABLEDfalseRuntime启用 TLS（true 时走 5671）
DC3_RABBITMQ_PORT35672Compose onlyAMQP 发布端口
DC3_RABBITMQ_MANAGEMENT_PORT15672Compose only管理界面发布端口

EMQX / MQTT（Runtime） ​

MQTT broker host 端口 31883。EMQX 还发布 WebSocket、Dashboard 等多个端口，详见折叠长表。

变量默认值Scope用途
MQTT_BROKER_HOSTlocalhostRuntimebroker 主机
MQTT_BROKER_PORT31883Runtimebroker 端口（EMQX 发布；internal 约 1883）
MQTT_USERNAMEdc3Runtime用户名
MQTT_PASSWORDdc3dc3dc3Runtime密码
DC3_EMQX_MQTT_PORT31883Compose onlyMQTT 发布端口
DC3_EMQX_DASHBOARD_PORT18083Compose onlyDashboard 发布端口

gRPC / facade（Runtime） ​

中心服务之间通过 facade 互联。分布式部署默认 DC3_FACADE_MODE=grpc，本地进程用 CENTER_*_HOST 指到 localhost。

变量默认值Scope用途
CENTER_AUTH_HOSTlocalhostRuntime鉴权中心主机
CENTER_MANAGER_HOSTlocalhostRuntime管理中心主机
CENTER_DATA_HOSTlocalhostRuntime数据中心主机
CENTER_AGENTIC_HOSTlocalhostRuntime智能中心主机
DC3_FACADE_MODEgrpcRuntimefacade 协议模式
DC3_FACADE_GRPC_DEADLINE_MS3000RuntimegRPC 单次请求 deadline，0 关闭客户端 deadline

网关与服务端口（Compose only） ​

网关是唯一对外 HTTP 入口（8000）。各中心 HTTP/gRPC 发布端口如下；SERVER_PORT/GRPC_SERVER_PORT 仅在本地同时跑多个服务、需要错开端口时作单进程覆盖。

变量默认值Scope用途
DC3_GATEWAY_PORT8000Compose only网关 HTTP 发布端口（入口）
DC3_AUTH_PORT8300Compose only鉴权中心 HTTP
DC3_MANAGER_PORT8400Compose only管理中心 HTTP
DC3_DATA_PORT8500Compose only数据中心 HTTP
DC3_AGENTIC_PORT8600Compose only智能中心 HTTP
DC3_AUTH_GRPC_PORT9300Compose only鉴权中心 gRPC
DC3_MANAGER_GRPC_PORT9400Compose only管理中心 gRPC
DC3_DATA_GRPC_PORT9500Compose only数据中心 gRPC
DC3_LISTENING_VIRTUAL_TCP_PORT6270Compose onlyListening Virtual 驱动 TCP 发布
DC3_LISTENING_VIRTUAL_UDP_PORT6271Compose onlyListening Virtual 驱动 UDP 发布
SERVER_PORT(未设)Per-process单服务 HTTP 端口覆盖
GRPC_SERVER_PORT(未设)Per-process单中心 gRPC 端口覆盖

DC3_LISTENING_VIRTUAL_*_PORT 是宿主机发布端口

DC3_LISTENING_VIRTUAL_TCP_PORT/DC3_LISTENING_VIRTUAL_UDP_PORT 是 Compose 发布到宿主机的端口；进程内部端口用 TCP_PORT/UDP_PORT（Per-process），两者别混。

Agentic / AI（Runtime） ​

仅当 dc3_model_provider 没有配置可用提供方时，才回退到这组 AGENTIC_FALLBACK_OPENAI_*。会话记忆默认关闭。

变量默认值用途
AGENTIC_FALLBACK_OPENAI_BASE_URLhttps://api.openai.comfallback OpenAI 兼容 API 地址
AGENTIC_FALLBACK_OPENAI_API_KEY(空)fallback API key（端点需鉴权时填）
AGENTIC_FALLBACK_OPENAI_MODELgpt-4ofallback 模型名
AGENTIC_FALLBACK_OPENAI_TEMPERATURE0.7采样温度（0.0–2.0）
AGENTIC_FALLBACK_OPENAI_MAX_TOKENS2048最大输出 token
AGENTIC_MEMORY_SCHEMA_INITneverSpring AI JDBC 记忆表初始化模式（always/never/create_if_not_exists）
AGENTIC_MEMORY_ENABLEDfalse是否启用持久化会话记忆
AGENTIC_TOOL_CALLING_ENABLEDtrue是否启用工具调用
AGENTIC_MEMORY_MAX_MESSAGES50每个对话窗口保留的最大消息数
AGENTIC_ATTACHMENT_STORAGE_PATHdc3/data/agentic/attachments附件存储路径

AGENTIC_MEMORY_SCHEMA_INIT 的建表绑定以代码为准

AGENTIC_MEMORY_SCHEMA_INIT 默认 never，意在控制记忆表初始化模式。但该变量经 compose 注入容器后，仓库内未见 application*.yml 把它绑定到 Spring AI 的 initialize-schema；记忆表实际由 initdb 脚本预建。是否真能通过设为 always 触发自动建表，请以代码为准，不要当成已接线的可用开关。

真实 API key 不进文档/日志/提交历史

AGENTIC_FALLBACK_OPENAI_API_KEY 等敏感值绝不能写入文档、日志或提交历史。正式提供方应配置在 dc3_model_provider 表，fallback 仅作兜底。

表中默认值取自 .env.example，与代码内回退默认不一致

上表 AGENTIC_MEMORY_ENABLED（false）、AGENTIC_ATTACHMENT_STORAGE_PATH（dc3/data/agentic/attachments）取自 .env.example——走 cp .env.example .env + source 路径时会被显式注入这些值。但 application-agentic.yml 的代码内回退默认不同（未设环境变量时记忆默认开启、附件路径为 dc3/data/upload/agentic/attachment）。不走 .env.example 路径时以代码为准。

批处理（Runtime） ​

MQTT 与位号值各有一组"数量阈值 + 间隔"参数，由 Quartz 定时按 interval（秒）把累积缓冲一次性刷出，speed = count / interval。

变量默认值用途
MQTT_BATCH_SPEED100MQTT 批量大小阈值（条/批）
MQTT_BATCH_INTERVAL5MQTT 批处理间隔（秒）
POINT_BATCH_SPEED100位号值批量大小阈值
POINT_BATCH_INTERVAL5位号值批处理间隔（秒）

镜像源（Compose only） ​

中国大陆网络可把 REGISTRY 设为 cn 走阿里云镜像。注意：Makefile 读 REGISTRY，Compose 插值读 DC3_IMAGE_REGISTRY，两者各管一段。

变量默认值用途
REGISTRYautoMakefile 镜像源选择器（仅接受 auto/global/cn，其它值会报错）
DC3_IMAGE_REGISTRYpnoker镜像命名空间
DC3_IMAGE_TAG2026.6所有服务/依赖镜像标签
DC3_BIND_HOST127.0.0.1发布端口绑定地址（0.0.0.0 对外）

可观测性（Compose only / Runtime） ​

可选栈（EMQX、ELK、Prometheus、Grafana）通过 make up-optional 拉起，端口与 JVM 参数如下。

变量默认值Scope用途
GF_SERVER_ROOT_URLhttp://localhost:3000RuntimeGrafana 对外 root URL
DC3_GRAFANA_PORT3000Compose onlyGrafana 发布端口
DC3_KIBANA_PORT5601Compose onlyKibana 发布端口
DC3_ES_JAVA_OPTS-Xms512m -Xmx512mRuntimeElasticsearch JVM 堆
DC3_LS_JAVA_OPTS-Xms256m -Xmx256mRuntimeLogstash JVM 堆
APM_AGENT_ENABLEfalseRuntime是否启用 Java APM agent
完整变量参考（折叠）

Security & Authentication（Runtime） ​

变量默认值用途
DC3_SECURITY_KEYdc3.security.key.2026.io.github.pnoker登录 Token 签名密钥
AUTH_HMAC_SECRETio.github.pnoker.dc3X-Auth-Principal HMAC-SHA256 密钥

PostgreSQL ​

变量默认值Scope
POSTGRES_HOSTlocalhostRuntime
POSTGRES_PORT35432Runtime
POSTGRES_USERNAMEdc3Runtime
POSTGRES_PASSWORDdc3dc3dc3Runtime
POSTGRES_DBdc3Runtime
POSTGRES_SCHEMA(未设)Per-process
DC3_POSTGRES_PORT35432Compose only

RabbitMQ ​

变量默认值Scope
RABBITMQ_HOSTlocalhostRuntime
RABBITMQ_PORT35672Runtime
RABBITMQ_USERNAMEdc3Runtime
RABBITMQ_PASSWORDdc3dc3dc3Runtime
RABBITMQ_VIRTUAL_HOSTdc3Runtime
RABBITMQ_MQTT_EXCHANGEdc3.e.mqttRuntime
RABBITMQ_SSL_ENABLEDfalseRuntime
RABBITMQ_SSL_ALGORITHMTLSRuntime
RABBITMQ_SSL_VALIDATE_SERVER_CERTIFICATEfalseRuntime
RABBITMQ_SSL_VERIFY_HOSTNAMEfalseRuntime
RABBITMQ_CONTAINER_PORT5672Runtime
DC3_RABBITMQ_PORT35672Compose only
DC3_RABBITMQ_TLS_PORT35671Compose only
DC3_RABBITMQ_MANAGEMENT_PORT15672Compose only

EMQX / MQTT ​

变量默认值Scope
MQTT_BROKER_HOSTlocalhostRuntime
MQTT_BROKER_PORT31883Runtime
MQTT_USERNAMEdc3Runtime
MQTT_PASSWORDdc3dc3dc3Runtime
MQTT_BATCH_SPEED100Runtime
MQTT_BATCH_INTERVAL5Runtime
DC3_EMQX_WS_PORT38083Compose only
DC3_EMQX_WSS_PORT38084Compose only
DC3_EMQX_MQTT_PORT31883Compose only
DC3_EMQX_MQTTS_PORT38883Compose only
DC3_EMQX_DASHBOARD_PORT18083Compose only

gRPC / facade ​

变量默认值Scope
CENTER_AUTH_HOSTlocalhostRuntime
CENTER_MANAGER_HOSTlocalhostRuntime
CENTER_DATA_HOSTlocalhostRuntime
CENTER_AGENTIC_HOSTlocalhostRuntime
DC3_FACADE_MODEgrpcRuntime
DC3_FACADE_GRPC_DEADLINE_MS3000Runtime
DC3_AUTH_GRPC_PORT9300Compose only
DC3_MANAGER_GRPC_PORT9400Compose only
DC3_DATA_GRPC_PORT9500Compose only

HTTP Gateway & 服务端口 ​

变量默认值Scope
DC3_GATEWAY_PORT8000Compose only
DC3_AUTH_PORT8300Compose only
DC3_MANAGER_PORT8400Compose only
DC3_DATA_PORT8500Compose only
DC3_AGENTIC_PORT8600Compose only
SERVER_PORT(未设)Per-process
GRPC_SERVER_PORT(未设)Per-process
DC3_LISTENING_VIRTUAL_TCP_PORT6270Compose only
DC3_LISTENING_VIRTUAL_UDP_PORT6271Compose only
TCP_PORT(未设)Per-process
UDP_PORT(未设)Per-process
GATEWAY_ROUTE_AUTH_TOKEN_URI(未设)Per-process
GATEWAY_ROUTE_AUTH_URI(未设)Per-process
GATEWAY_ROUTE_MANAGER_URI(未设)Per-process
GATEWAY_ROUTE_DATA_URI(未设)Per-process
GATEWAY_ROUTE_AGENTIC_URI(未设)Per-process

Agentic / AI（Runtime） ​

变量默认值
AGENTIC_FALLBACK_OPENAI_BASE_URLhttps://api.openai.com
AGENTIC_FALLBACK_OPENAI_API_KEY(空)
AGENTIC_FALLBACK_OPENAI_MODELgpt-4o
AGENTIC_FALLBACK_OPENAI_TEMPERATURE0.7
AGENTIC_FALLBACK_OPENAI_MAX_TOKENS2048
AGENTIC_MEMORY_SCHEMA_INITnever
AGENTIC_MEMORY_ENABLEDfalse
AGENTIC_MEMORY_MAX_MESSAGES50
AGENTIC_TOOL_CALLING_ENABLEDtrue
AGENTIC_ATTACHMENT_STORAGE_PATHdc3/data/agentic/attachments

批处理 / 镜像 / 可观测性 ​

变量默认值Scope
POINT_BATCH_SPEED100Runtime
POINT_BATCH_INTERVAL5Runtime
REGISTRYautoCompose only
DC3_IMAGE_REGISTRYpnokerCompose only
DC3_IMAGE_TAG2026.6Compose only
DC3_LOG_MAX_SIZE10MCompose only
DC3_LOG_MAX_FILE20Compose only
DC3_BIND_HOST127.0.0.1Compose only
GF_SERVER_ROOT_URLhttp://localhost:3000Runtime
DC3_GRAFANA_PORT3000Compose only
DC3_KIBANA_PORT5601Compose only
DC3_ES_JAVA_OPTS-Xms512m -Xmx512mRuntime
DC3_LS_JAVA_OPTS-Xms256m -Xmx256mRuntime
APM_AGENT_ENABLEfalseRuntime
NODE_ENVdevRuntime

约束与常见误区 ​

  • 改 .env.example 不会影响运行——必须先 cp .env.example .env。
  • dc3/env/dev.env 与根 .env 用途不同，不是同一个文件，别互相复制。
  • 服务发布端口统一用 DC3_*_PORT；进程内部仍用 SERVER_PORT、GRPC_SERVER_PORT 等 Spring Boot 原生命名。
  • Per-process 变量（POSTGRES_SCHEMA、SERVER_PORT、TCP_PORT 等）只作单服务覆盖，不要全局滥用。
  • Compose 应用栈可以用与本地源码不同的 NODE_ENV。

延伸阅读 ​

Released under the AGPL-3.0 License · 基于 AGPL-3.0 协议发布

Copyright © 2017-2026 pnoker