企业官网建设流程全解析

简介：JetLinks开源物联网平台v1.20.0源码包，面向物联网应用开发者、计算机专业学生及需要搭建IoT系统的技术团队，可用于设备接入、数据处理与业务逻辑开发等场景，也适合作为毕业设计选题或企业级项目参考。压缩包共665个文件，约29MB，以573个Java源文件为核心，辅以32个XML配置、6个YML与5个properties配置文件，另有pem、p12、jks等证书密钥文件及Dockerfile、mvnw等构建脚本，完整呈现微服务架构下的工程组织方式。平台支持MQTT、HTTP、CoAP等多协议设备接入，内置实时流处理与图形化规则引擎，并提供细粒度权限管理与Web管理界面。已有442人学习下载。通过研读源码，读者可掌握设备模型定义、数据清洗聚合、告警联动等实现思路，理解开源物联网平台的设计取舍，并在此基础上进行二次开发或定制扩展。

1. 从一份 JetLinks v1.20.0 源码包说起：它到底能解决什么问题

如果你正在做物联网方向的毕业设计，或者公司要快速搭一套设备接入与管理平台，大概率会搜到 JetLinks 这个名字。我手上这份JetLinks开源物联网平台 v1.20.0.zip就是它的完整源码包，解压后是一套基于 Java 的、能直接跑起来的物联网中台系统。它解决的核心问题很具体：设备怎么接进来、数据怎么实时处理、规则怎么配置、告警怎么触发，这些物联网项目里最耗时的脏活累活，它已经帮你搭好了骨架。

这份资源适合三类人：一是需要一套可运行系统来写论文、做答辩演示的学生；二是想研究物联网平台架构、看别人怎么设计设备接入层的后端工程师；三是需要私有化部署、不想从零造轮子的团队。它不是玩具 demo，而是一个带前端、后端、规则引擎、时序数据存储的完整工程。接下来我会按「它是什么 → 怎么跑起来 → 怎么改 → 坑在哪」的顺序，把这份源码包拆开讲清楚。

2. 拆包与运行环境：把 v1.20.0 跑起来需要哪些前置条件

2.1 源码包结构与技术栈速览

解压JetLinks开源物联网平台 v1.20.0.zip后，你会看到典型的 Maven 多模块结构。核心模块大致分这几层：jetlinks-community是社区版主工程，jetlinks-manager负责设备与产品管理，jetlinks-network处理 TCP、MQTT、HTTP 等协议接入，jetlinks-rule-engine是规则引擎，前端资源通常单独放在ui或web目录下。整个后端基于 Spring Boot 2.x 体系，响应式编程用 Reactor，设备消息总线走事件驱动模型。

数据库层面，JetLinks 默认依赖 PostgreSQL 做业务数据存储，同时用 Elasticsearch 存设备时序数据和日志。缓存和会话用 Redis。这意味着你本地至少需要准备三个中间件：PostgreSQL、Redis、Elasticsearch。很多新手翻车就翻在这里——只装了 JDK 和 Maven，跑起来发现连不上数据库，控制台一片红。

提示：v1.20.0 对 Elasticsearch 的版本有要求，常见做法是配 7.x 系列，版本不匹配会出现索引模板创建失败。

2.2 环境准备与依赖安装

我一般会先把版本对齐再动手，避免中途返工。下面是我在 Linux 和 macOS 上都验证过的一套基础环境清单：

安装 PostgreSQL 后，需要手动建库和用户。JetLinks 不会自动帮你创建数据库，这一步必须手动执行：

# 进入 PostgreSQL 命令行 psql -U postgres # 创建业务库和用户，密码按自己环境改 CREATE DATABASE jetlinks; CREATE USER jetlinks WITH PASSWORD 'jetlinks123'; GRANT ALL PRIVILEGES ON DATABASE jetlinks TO jetlinks; # 退出 \q

这段 SQL 的逻辑很直白：建一个名为jetlinks的库，再建一个同名用户并授权。参数上唯一要注意的是密码复杂度，JetLinks 配置文件里会明文引用这个密码，所以别用特殊字符，否则 YAML 解析容易出玄学问题。Redis 和 Elasticsearch 一般默认配置就能用，但 Elasticsearch 如果开了安全认证，需要在 JetLinks 配置里同步关闭或填入凭证。

2.3 配置文件修改与首次启动

源码包里通常带一份application.yml或application-dev.yml，位置在jetlinks-community/src/main/resources/下。你需要改的是数据源、Redis、Elasticsearch 三块连接信息。我习惯先复制一份application-dev.yml再改，保留原始文件做对照：

spring: datasource: url: r2dbc:postgresql://127.0.0.1:5432/jetlinks username: jetlinks password: jetlinks123 redis: host: 127.0.0.1 port: 6379 elasticsearch: uris: http://127.0.0.1:9200

注意这里用的是r2dbc而不是传统的 JDBC 驱动，这是 JetLinks 响应式架构的一部分。如果你只改了 JDBC 配置，启动时会发现数据源根本没生效。改完配置后，在项目根目录执行 Maven 构建：

# 跳过测试加速构建，首次构建会下载大量依赖 mvn clean package -DskipTests # 构建完成后启动主类，通常位于 jetlinks-community 模块 java -jar jetlinks-community/target/jetlinks-community.jar --spring.profiles.active=dev

启动日志里如果看到Netty started on port 8080和Started JetLinksApplication，说明后端起来了。前端部分如果是分离的，进入ui目录执行npm install && npm run serve，然后浏览器访问对应端口。第一次启动会比较慢，因为要初始化数据库表结构和 Elasticsearch 索引模板，耐心等日志刷完。

3. 设备接入与规则引擎：从模拟设备到告警触发

3.1 设备接入模型与 MQTT 模拟上报

JetLinks 的设备接入围绕「产品」和「设备」两个概念展开。产品定义了一类设备的物模型——也就是属性、事件、功能；设备是产品的实例，持有唯一 ID 和密钥。要验证平台是否正常工作，最直接的方式是模拟一台 MQTT 设备上报数据。JetLinks 内置了 MQTT 服务端，默认端口在配置里可以查到，常见是 1883 或 8081 映射。

我一般用 Python 的paho-mqtt库写一个最小上报脚本，比用现成的调试工具更可控：

import paho.mqtt.client as mqtt import json import time # 连接 JetLinks 内置 MQTT 服务，client_id 用设备 ID client = mqtt.Client(client_id="device-001") client.username_pw_set("device-001", "你的设备密钥") client.connect("127.0.0.1", 1883, 60) # 上报属性消息，主题格式遵循 JetLinks 约定 payload = { "timestamp": int(time.time() * 1000), "properties": { "temperature": 26.5, "humidity": 60.2 } } client.publish("/device-001/properties/report", json.dumps(payload)) client.disconnect()

这段代码的关键参数有三个：client_id必须和平台上注册的设备 ID 一致，否则会被拒绝连接；username_pw_set里的密钥在设备详情页可以重置；主题/device-001/properties/report是 JetLinks 默认的属性上报格式，如果你在平台上改了主题约定，这里要同步改。跑通之后，在平台设备详情页能看到实时属性值刷新，说明接入链路是通的。

3.2 规则引擎配置与告警落地

设备数据进来之后，下一步是让它产生业务价值。JetLinks 的规则引擎支持可视化编排，你可以理解为一套「当设备数据满足某条件时，执行某动作」的流程。常见场景是温度超过阈值触发告警。在规则引擎里新建一条规则，触发方式选「设备属性上报」，条件配置为temperature > 30，动作选「发送告警」或「调用 HTTP 接口」。

配置过程中有几个参数容易设错。一是「去重间隔」，如果不设，设备每秒上报一次、温度持续超标，你会被重复告警淹没。我一般设 60 秒，同一设备同一规则一分钟内只触发一次。二是「数据窗口」，规则引擎支持滑动窗口聚合，比如统计最近 5 分钟平均值再判断，这个在配置界面里叫「窗口配置」，不启用就是逐条判断。三是动作里的「模板变量」，告警内容里引用设备属性要用${properties.temperature}这种占位符，写错变量名不会报错，但告警内容会是空的，这个坑我踩过。

规则保存后是即时生效的，不需要重启服务。你可以用上面的 Python 脚本把温度改成 35 再上报一次，观察告警列表里是否出现记录。如果没触发，先检查规则状态是不是「已启动」，再看设备上报的消息是否真的进入了规则引擎——有时候 MQTT 连上了但主题不对，消息根本没被平台解析。

3.3 时序数据存储与查询验证

JetLinks 把设备属性数据写入 Elasticsearch，按设备 ID 和时间分索引。你可以在平台的「设备日志」或「时序数据」页面直接查，也可以走 REST API 验证。常见做法是调/api/device/instance/{deviceId}/properties/_query这类接口，传时间范围和属性名。返回结果里如果能看到你刚才上报的temperature和humidity，说明整条链路——接入、解析、存储——全部打通。

这里有个细节值得注意：Elasticsearch 的索引是按天或按月滚动的，如果你查的时间范围跨了索引边界，而索引还没创建，会返回空。这不是数据丢了，而是查询条件没命中。我一般会先查最近一小时，确认有数据后再扩大范围。另外，如果 Elasticsearch 磁盘水位超过阈值，会进入只读模式，新数据写不进去但也不报错，表现就是平台上看不到最新数据。遇到这种情况，去 Elasticsearch 节点上执行GET _cluster/health看是不是read_only_allow_delete，是的话清理磁盘或调水位线。

4. 避坑与排查：跑 JetLinks 源码时最容易翻车的五个地方

4.1 启动报「表不存在」或「索引模板创建失败」

现象是启动日志里出现relation "xxx" does not exist或者 Elasticsearch 相关的index_template错误。原因通常是数据库没建对，或者 Elasticsearch 版本不兼容。JetLinks 启动时会自动执行建表脚本，但如果数据库连接用户没有建表权限，脚本会静默失败。解决方法是确认jetlinks用户对jetlinks库有全部权限，并且 Elasticsearch 版本在 7.x 范围内。如果用的是 8.x，需要额外配置兼容头，这个在社区版里没有默认支持。

4.2 MQTT 设备连不上，日志显示认证失败

现象是 Python 脚本报Connection Refused: not authorised。原因一般是设备 ID 或密钥不对，或者设备没有在平台上启用。JetLinks 的设备密钥在创建时只完整显示一次，后面再看是脱敏的。如果你忘了密钥，直接在设备详情页重置，然后用新密钥重连。另一个可能是 MQTT 端口被防火墙拦了，本地测试一般不会，但部署到服务器上很常见。

4.3 规则引擎不触发，条件明明满足了

现象是设备数据在平台上能看到，但规则就是不执行。原因有三个常见方向：规则没启动、条件字段名写错、数据窗口配置导致判断延迟。先看规则列表里的状态开关，再看条件里的属性名是否和物模型里定义的完全一致——大小写敏感。如果用了窗口聚合，数据要等窗口关闭才会进入判断，不是实时的。排查时可以先建一条最简单的规则：无条件，直接发告警，确认动作本身能执行，再逐步加条件。

4.4 前端页面空白或接口 404

现象是后端启动正常，但浏览器打开前端页面一片白，控制台报接口 404。原因是前后端分离部署时，前端配置的 API 地址不对。JetLinks 前端通常有一个环境变量或配置文件指向后端地址，默认可能是localhost:8080，如果你改了后端端口或部署到远程，这里要同步改。另外，如果前端没构建直接拿源码跑，路由模式可能和 Nginx 配置不匹配，刷新页面会 404，这个在部署章节里要特别注意。

4.5 内存溢出或启动极慢

现象是java -jar启动后不久就 OOM，或者构建阶段卡在某个依赖下载上。原因是 JetLinks 模块多、依赖重，默认 JVM 堆内存可能不够。我一般启动时会显式指定内存参数：java -Xms512m -Xmx2048m -jar ...。构建慢则多半是 Maven 中央仓库网络问题，配置国内镜像源能明显改善。如果机器配置有限，可以只启动jetlinks-community模块，其他模块按需引入，不必全量构建。

5. 二次开发切入点：改哪里、怎么验证、我的习惯

当你把平台跑起来之后，真正的价值在于按自己需求改。JetLinks 的扩展点设计得比较清晰，我一般从三个地方入手。第一是协议接入层，如果你想接一种平台不支持的私有协议，在jetlinks-network模块下新建一个 Network 实现类，参考已有的 MQTT 或 TCP 实现，核心是实现消息解码和会话管理两个接口。第二是规则引擎节点，平台内置的动作不够用时，可以实现自定义规则节点，注册到 Spring 容器后会在可视化编排里出现。第三是物模型扩展，如果标准属性类型不满足，可以在管理端配置自定义类型。

验证改动是否生效，我习惯用「最小闭环」法：改完一个点，立刻用模拟设备发一条数据，看它有没有按预期流转。比如改了协议解码，就发一条原始报文，看平台解析出的属性对不对；改了规则节点，就建一条只包含该节点的规则，看动作有没有执行。不要攒一堆改动再一起测，出了问题根本定位不到是哪一层。

还有一个血泪经验：改源码之前先确认你改的模块有没有被其他模块依赖。JetLinks 的模块耦合不算低，改了一个公共类，可能影响好几个服务。我一般会先跑一遍全量测试，虽然慢，但能提前发现编译层面的问题。另外，平台自带的数据库初始化脚本在版本升级时可能有变更，如果你改了表结构，记得把变更脚本单独维护，别直接改原始 SQL 文件，否则下次拉新版本合并时必冲突。

从那以后我每次拿到一份新源码包，都强制走一遍「先跑通默认配置，再改一个最小点验证，最后才动核心逻辑」的流程。这份 JetLinks v1.20.0 的源码包，只要你把 PostgreSQL、Redis、Elasticsearch 三个依赖对齐，跑起来并不难，难的是跑起来之后知道往哪改。希望这份拆解能帮你少走几个弯路，顺利把平台用起来。

本文还有配套的精品资源，点击获取