IoT DC3 这个项目最早是我做设备接入平台选型时挖到的。当时团队需要一个能快速跑起来的 Spring Cloud 物联网框架既要能管设备又要能收 MQTT 数据还得有现成的存储链路。翻了好几个开源项目DC3 给我的印象最直接它不是一堆代码堆在一起的单体应用而是正经的微服务划分网关、认证、管理、数据、监控各司其职中间件也是业界常用的一套。说白了这就是一套能本地跑起来、能二次开发的 Spring Cloud 物联网脚手架。我把它完整部署到本地的过程说实话不算太轻松。中间件多、服务多、配置链路长踩了不少坑。所以这篇文章我想原原本本把整套流程记录下来从架构认知讲到环境准备从源码编译讲到 Compose 编排再把遇到过的典型问题整理成排查清单。适合刚入行想做 IoT 平台的 Java 工程师也适合拿微服务做毕设、做内部项目的同学还有手里有设备数据想快速验证接入方案的从业者。照着走完你至少能得到一套能登录、能建产品、能收 MQTT 数据的 DC3 环境。1. 先把 DC3 看明白项目定位与部署价值1.1 DC3 能干什么核心能力拆解从功能模块看DC3 不是一个大而全的商业物联网平台而是一个基础框架核心能力可以总结成三块设备接入与设备管理、数据采集与存储、平台基础能力。设备接入层面DC3 主推的是 MQTT 协议接入。你在平台上创建产品、创建设备然后设备通过 MQTT 往指定 topic 上报数据平台侧的 data 服务负责消费消息解析后落库。整个过程跑通之后你就能在自己的业务里做设备状态监控、数据转发、告警之类的事情。它还预留了驱动扩展的思路不同协议可以在驱动层适配这也是很多人在选型时看上它的原因。数据存储层面DC3 用了 MySQL、MongoDB、InfluxDB 三个数据库组合。MySQL 存平台元数据比如产品模型、设备列表、租户信息MongoDB 用来存设备上报的非结构化消息内容InfluxDB 单独存时序数据适合做指标趋势分析。Redis 在这里主要做缓存RabbitMQ 承担服务间的消息解耦。这套技术选型不算花哨但很务实每个中间件定位清晰对初学者来说反而更容易理解。1.2 为什么要本地部署一套 DC3很多人在网上看过 DC3 的演示截图觉得功能也就那样。但演示和亲手跑起来完全是两回事。本地部署的价值至少有四点。第一理解微服务架构。DC3 的模块划分非常典型gateway 做统一入口、auth 做认证、manager 管业务、data 管数据、monitor 做监控。你把这套服务全部启动起来观察它们之间怎么注册、怎么调用、怎么通信比看十篇架构文章都管用。当你在 Nacos 控制台上看到服务列表一个个出现的时候对“服务注册与发现”这个概念基本就通了。第二为二次开发打基础。你要给 DC3 加驱动、改协议解析、对接自己的业务系统光看代码是不行的必须有本地能跑的环境改完代码立刻验证。没有本地环境所有改动都是空谈。第三验证部署可行性。工作中经常要帮团队评估一个框架能不能落地。本地部署一遍端口、内存、依赖、启动顺序这些坑都会暴露出来你心里就有底了。文章后面记录的踩坑内容基本就是我当初真实趟过一遍的结果。第四学习中间件组合。DC3 依赖的中间件种类多MySQL、Redis、MongoDB、InfluxDB、RabbitMQ、Nacos 全都有。平时你可能只接触其中一两个部署 DC3 等于把这些中间件一次性全用起来对整个技术栈的认知会完整很多。2. 架构与依赖部署之前必须知道的事2.1 微服务骨架和模块职责DC3 的项目仓库是典型的多模块 Maven 工程顶层会有 dc3-common 这类公共模块放通用的工具类、实体类、Feign 接口定义。业务相关的服务我部署过的版本里核心有这么几个dc3-register注册中心相关封装在 Docker 部署里对应的就是 Nacos 容器dc3-gatewayAPI 网关基于 Spring Cloud Gateway是前端和外部请求的统一入口dc3-auth认证服务负责用户登录、Token 颁发与校验dc3-manager管理服务产品管理、设备管理、租户管理等平台核心业务dc3-data数据服务消费设备上报消息负责数据解析、存储和对外查询dc3-monitor监控服务基于 Spring Boot Admin展示各服务的运行状态你不需要记死每个服务的内部代码但要理解一条链路请求从客户端进来先到 gateway由 gateway 鉴权并转发要业务数据就去 manager设备数据上报走 data 链路。服务之间通过 OpenFeign 做内部调用注册中心统一协调。整体结构就是很标准的 Spring Cloud 微服务写法如果你做过相关项目看这套代码会非常亲切。有一点要注意dc3-register 这个模块在不同版本里的形态可能不一样有的版本用独立的 Nacos 容器有的版本会通过这个模块启动内嵌 Nacos。部署的时候以你拉到的仓库文档为准不用在这上面花太多时间纠结你只要知道注册中心是 Nacos 就够了。2.2 中间件选型和数据流DC3 依赖的中间件比较多本地部署前最好先列一个清单知道谁是干嘛的否则后面启动报错你都不知道该查谁。中间件默认端口在 DC3 中的角色MySQL3306平台元数据如产品、设备、租户、用户表Redis6379缓存部分会话信息与认证数据MongoDB27017设备上报消息的原始存储InfluxDB8086时序数据存储适合指标趋势分析RabbitMQ5672、15672服务间消息解耦设备数据流转Nacos8848服务注册与配置中心数据流的逻辑大致是这样设备通过 MQTT 上报消息平台把原始消息写入 MongoDB同时解析出需要的字段写入 InfluxDB管理端和 API 层要查询设备状态、历史数据时分别从 MySQL 拿元数据、从 InfluxDB 拿时序数据、从 MongoDB 拿原始记录。RabbitMQ 在这个过程中负责削峰解耦避免上报高峰把业务服务冲垮。在本地部署时这些中间件跑不跑得起来、配置对不对直接决定后面服务能不能正常启动。所以我的建议是别急着把平台服务编排上去先把中间件逐个跑起来确认健康了再上平台服务。这个顺序特别重要尤其是第一次部署能帮你把问题范围缩小一大半。3. 安装前的环境准备JDK、Docker 与源码拉取3.1 本地环境清单与版本选择先说说我实际使用的环境。DC3 是基于 Java 8 和 Spring Boot 2.x 这一版技术栈做的所以 JDK 必须用 1.8不要为了追新去用 JDK 11 或 17否则编译期就可能出现各种版本兼容问题。我一开始图省事装了 JDK 17结果 Maven 编译直接报错换回 JDK 8 后一路顺畅。Maven 建议 3.6 以上Git 肯定要装。Docker 这块Windows 和 macOS 用 Docker DesktopLinux 直接装 Docker Engine记得把 Docker Compose 插件配好。前端项目 dc3-web 是 Vue 技术栈如果你打算本地跑前端调试需要 Node.js建议装 14.x 或 16.x 的 LTS 版本。如果只想要一个能用的后台可以把前端构建产物放到 Nginx 里或者直接用 dev server 起一个开发环境这个后面专门说。还有一项是端口规划。DC3 全家桶涉及的端口至少包括 3306、6379、27017、8086、5672、15672、8848再加上网关、各个服务和前端的端口。本地部署前先检查一遍端口占用情况Windows 上可以用netstat -ano | findstr 端口Linux 上可以用ss -lntp | grep 端口有冲突的先处理别等启动报错才回来找。3.2 源码获取与仓库结构说明DC3 的主仓库在 GitHub项目地址是iot-dc3/dc3拉取命令很常规git clone https://github.com/iot-dc3/dc3.git cd dc3前端仓库是独立的叫iot-dc3/dc3-web需要单独拉git clone https://github.com/iot-dc3/dc3-web.git拉下来之后先看仓库根目录的 README 和docker-compose.yml。版本不同目录结构和脚本多少会有差异。我部署的时候发现仓库里既有完整的 Compose 编排也有每个服务单独的 Dockerfile甚至有些模块带直接构建脚本。多花十分钟读 README比盲目执行一堆命令靠谱得多。另外国内拉取依赖容易慢Maven 的settings.xml里建议配置国内镜像仓库这个属于常规操作关键字搜“Maven 阿里云镜像”就能找到配置方式。网络环境下我踩过几次依赖下载超时配完镜像基本就稳了。4. 从源码到可运行的镜像编译与构建4.1 Maven 多模块编译DC3 是多模块工程第一次编译建议在根目录直接执行mvn clean package -Dmaven.test.skiptrue这里-Dmaven.test.skiptrue很重要它跳过测试编译和测试执行既能省时间也能避开部分测试用例需要外部中间件环境的问题。整个项目模块多第一次编译下载依赖会花不少时间耐心等只要网络正常、JDK 版本对一般都能过。编译完成后各个服务的可执行 jar 包会生成在各自模块的target目录。你可以选择直接用java -jar启动比如java -jar dc3-manager/target/dc3-manager.jar但本地部署更推荐用 Docker因为中间件多Docker 能统一管理生命周期。不过有一点要注意直接用 jar 启动和用 Docker 启动配置文件的生效位置不一样。用 jar 启动时Nacos 地址、数据库地址这些配置默认会去找localhost而在容器里可能通过环境变量注入不同的地址。这个细节在外面部署的时候特别容易把人绕晕第 5 节我会展开说。4.2 构建 Docker 镜像的两种方式DC3 的镜像构建我实际中用过两条路。第一条是用仓库自带的 Dockerfile 手动构建。比如构建 manager 服务docker build -t dc3-manager:latest ./dc3-manager第二条是直接用 Compose 里配置的公共镜像。有些版本为了简化流程会在docker-compose.yml里直接写镜像地址这样你就不用本地构建了docker compose pull直接拉镜像就能跑。两条路各有利弊。手动构建能保证镜像和本地代码一致适合你要改代码的场景拉公共镜像最省事但拿到的可能不是最新代码。我的建议是第一步先用公共镜像把环境跑通确认没有版本兼容问题后再决定要不要本地构建镜像。这样能把环境的坑和代码的坑分开排查效率高很多。5. 使用 Docker Compose 搭建本地环境5.1 基础中间件先启动DC3 对中间件的依赖前面已经列过表了。正式跑平台服务之前先把基础设施组件启动起来。如果你拉到的仓库里有单独的docker-compose-infra.yml直接用docker compose -f docker-compose-infra.yml up -d如果没有拆分文件就手动挑出 mysql、redis、mongodb、influxdb、rabbitmq、nacos 这些容器单独启动docker compose up -d mysql redis mongodb influxdb rabbitmq nacos启动之后别急着下一步先确认每个容器都健康。用docker ps看状态等 Nacos 的 8848 端口能访问控制台了再继续。MySQL 和 MongoDB 第一次初始化可能要花一点时间尤其 Nacos 自己要连 MySQL启动顺序上通常放在 MySQL 之后。实操提示第一次部署千万别把所有容器一把梭全部用up -d拉起先中间件后服务能帮你省下大量排查时间。同时启动的话经常是平台服务早就起来了Nacos 还没就绪然后服务注册失败你还要回头倒日志找原因。5.2 启动平台核心服务基础设施就绪后再启动平台服务。命令类似docker compose up -d dc3-auth dc3-manager dc3-data dc3-gateway dc3-monitor平台服务起来之后建议用docker compose logs -f dc3-manager这样的命令盯着日志。健康的服务标准是在 Nacos 控制台的服务列表里能看到对应服务并且服务状态显示正常。这个阶段最容易翻车的是服务之间互相调不通。常见原因有几个容器内部网络问题比如配置里localhost指到了容器自己身上数据库或 Nacos 的地址写的是容器名但 Compose 网络没连通再就是服务启动顺序错乱A 服务启动时调 B 服务的 Feign 接口B 还没注册上。这些问题在第 7 节排查部分我会逐个说。5.3 前端项目启动与访问入口后端起来之后要访问管理界面还得把前端项目跑起来。前端是独立的dc3-web仓库我本地用 dev server 最省事cd dc3-web npm install npm run dev默认开发服务器一般跑在http://localhost:8080它会通过代理把 API 请求转发到后端的网关地址。如果前端页面能打开但接口全报 404 或者跨域第一件事就是去查前端配置文件里的代理目标和后端的网关地址对不对。还有一种方式是用 Nginx 部署前端构建产物适合模拟生产环境。执行npm run build把dist目录丢给 Nginx再把/api之类的路径反向代理到网关端口。这种方式更接近上线状态但本地调试还是 dev server 改起来快。登录后台时默认账号密码每个版本可能不一样。我看到过 admin / admin也见过初始化 SQL 里写的其他值。最靠谱的办法是去仓库里搜初始化 SQL比如dc3.sql直接在里面查用户表的初始记录。第一次登录成功后第一件事建议先改密码虽然是本地环境但养成习惯没坏处。6. 部署成功后的验证与体验6.1 服务健康检查如果你按前面的步骤操作完现在应该有一套完整的 DC3 在本地跑着。我的建议是先做一轮健康检查别急着登后台。执行docker ps确认所有容器都是 Up 状态没有反复重启的打开 Nacos 控制台http://localhost:8848/nacos看服务列表里有没有注册上所有平台服务打开监控服务的 Spring Boot Admin 界面看各个服务的内存、线程、健康状态用 curl 或者浏览器直接访问网关的健康检查接口确认网关本身正常这几项里Nacos 控制台的服务列表最直观。看到所有服务都亮着说明注册中心这条链路没问题剩下的就是业务功能验证了。6.2 第一次登录和设备接入实战登录后台后建议按“产品、设备、数据上报、数据查询”的顺序走一遍。先创建一个产品定义好产品模型再在产品下注册一个测试设备拿到设备标识然后找一个 MQTT 客户端工具比如 MQTTX以设备身份往平台接入 topic 推送数据。推送之后去后台的数据管理页或者直接查 InfluxDB看数据有没有落库。如果能看到数据恭喜你整套链路已经通了。这一步的体验比什么架构图都实在你能亲眼看到一条设备消息从 MQTT 进来到 MongoDB、InfluxDB 各存一份再到前端页面展示出来。这个端到端跑通的感觉能帮你把前面所有模块和中间件串成一张图。实际测试时我建议先用固定字段的 JSON 消息别上来就搞复杂的自定义协议。先把链路调通再去研究模型定义和解析规则这样排查问题的时候能缩小范围不会眉毛胡子一把抓。7. 踩坑记录本地部署常见问题排查7.1 端口占用与调整本地环境最常见的坑就是端口被占。Windows 上经常是 3306 被本机 MySQL 占了8080 被其他 Web 服务占了。处理办法是在 Compose 文件里改宿主机映射端口比如ports: - 3307:3306但要注意改端口不能只改 Compose。平台服务的配置里如果写死了数据库连接串你也得同步改成新端口否则容器里面连的还是 3306宿主机上却没有 3306。这类配置串联问题排查时要顺着连接关系一层层找别改了一个地方就以为完事了。7.2 内存不足导致容器反复退出DC3 全家桶的容器数量不少就算只跑基础功能全部加起来对内存也有一定要求。我实测下来至少要给 Docker 分配 6G 以上的内存才比较稳8G 更从容。如果你发现容器起来又挂、挂完又起或者服务日志里出现内存溢出相关字眼基本上就是内存不够。Windows 的 Docker Desktop 可以在 Settings 的资源选项里调内存和 CPULinux 上注意检查一下 swap 空间。这个问题看着低级实际翻车率非常高尤其是 16G 内存的电脑不开 Docker 还好一开全家桶直接卡成 PPT。7.3 Nacos 启动失败与服务注册超时Nacos 本身依赖 MySQL 存储配置和数据所以它的启动顺序必须在 MySQL 之后。如果 Nacos 一直启动失败先去 Nacos 的日志里看有没有数据库连接报错确认初始化脚本有没有执行。另外平台服务注册超时也很常见。解决方案很简单等 Nacos 完全就绪再启动服务或者在 Compose 里给服务加depends_on和健康检查条件。但要注意depends_on只是容器层面的依赖不能完全保证 Nacos 内部初始化完成所以看日志、看健康检查仍然是最稳妥的做法。7.4 前端页面打开但接口报错前端能打开但数据加载不出来十有八九是代理配置问题。拿 Vue dev server 来说vue.config.js里的代理目标必须指到网关的真实地址。我遇到过一种情况前端的代理指向了localhost:8080但那台机器上 8080 被别的服务占着网关实际跑在 8081结果页面一直在转圈。排查套路是先在浏览器 F12 里看请求地址和返回状态再顺着地址去查网关、查网关转发的目标服务逐层定位。跨域问题同理后端网关如果没开对应的跨域配置前端接口一样会挂。还有一个很隐蔽的坑服务全部启动成功后第一次登录没问题过一会儿再操作就提示 Token 失效或者权限不足。这种情况通常和 Redis 有关认证信息存在 Redis 里如果 Redis 里的数据被清了或者配置的 Redis 库序号和认证服务启动时初始化用的库不一致就会出现这种时好时坏的诡异现象。遇到这类问题我一般会先把 Redis 清干净同时检查各服务配置里的 Redis db 序号是否一致。为了便于快速定位我把几个高频问题整理成了一张速查表现象大概率原因处理建议容器起来又退出内存不足调大 Docker 内存检查是否有 OOM 日志Nacos 启动失败数据库未就绪或初始化脚本没执行等 MySQL 健康后再启动 Nacos查 Nacos 日志服务注册不上启动顺序或容器网络问题等 Nacos 就绪确认 Compose 网络连通前端接口 404代理目标或网关实际端口不一致检查vue.config.js代理和网关监听端口登录后 Token 反复失效Redis 库序号错乱或数据被清核对各服务 Redis db 配置清理后重启最后说点实际的。整个 DC3 本地部署流程走完之后我个人最大的收获不是能把平台跑起来而是通过它把 Spring Cloud 微服务这套东西完整串了一遍。以前看概念服务注册、网关转发、Feign 调用、配置中心都是一个个孤立的知识点亲手把 DC3 从源码部署起来之后这些概念突然就串成了一条线。如果你也在学 Spring Cloud 或者想做物联网平台强烈建议不要只看文档找个开源项目把它在自己电脑上跑起来改几行代码加一个设备比什么教程都管用。还有个实用小经验部署这套环境如果中途失败了别急着删了重来先去看容器日志绝大多数问题日志里都有明确线索。我踩过的坑里大概有七成都是自己没看日志、凭感觉改配置反而越改越乱。稳一点一步步来DC3 本地跑通并不难。