第二章 从零到一：JetLinks社区版物联网平台开发环境实战搭建

1. 环境准备：你的开发机需要哪些“食材”？

在开始动手搭建JetLinks的开发环境之前，我们得先看看厨房里有什么，还缺什么。这就像做一道大菜，你得先把食材和调料备齐。对于物联网平台开发来说，我们的“食材”就是一系列必须的软件和工具。别担心，我会带你一样一样地准备，确保你每一步都走得稳稳当当。

首先，你得有一台电脑，操作系统我推荐使用Windows 10/11或者Ubuntu 20.04/22.04 LTS，这是目前最主流、兼容性最好的环境。如果你是Mac用户，大部分步骤也是通用的，只是在一些命令行操作上略有不同，我会特别指出来。接下来，我们需要准备几个核心的“大件”：Java开发环境、数据库、缓存和搜索引擎。JetLinks社区版后端是基于Java开发的，所以Java是必须的。我强烈建议你安装JDK 17，这是JetLinks官方推荐且经过充分测试的版本。别用太老的JDK 8，也别急着上最新的JDK 21，以免遇到一些未知的兼容性问题。你可以去Oracle官网或者更推荐使用OpenJDK的发行版，比如Adoptium的Temurin。安装好后，记得在命令行里输入java -version和javac -version来确认版本是否正确。

数据库方面，JetLinks默认支持PostgreSQL，但国内很多团队更习惯用MySQL。为了减少大家的学习成本，我们这篇实战指南就选择MySQL 8.0作为我们的数据库。你可以在MySQL官网下载社区版安装包，记得安装时设置一个你自己能记住的root密码。另一个必不可少的组件是Redis，它用来做缓存和会话存储，能极大提升平台性能。Redis的安装非常简单，从官网下载最新稳定版，解压后几条命令就能跑起来。最后是Elasticsearch，它是JetLinks用来存储设备上报的时序数据和日志搜索的引擎，版本上我建议使用7.10.x或7.17.x这类与JetLinks兼容性好的版本，避免使用最新的8.x版本，因为驱动和API可能有变动。除了这些，像Maven（项目管理工具）、Node.js（前端环境）、Git（代码管理）也是必备的，我会在接下来的具体步骤里告诉你如何检查和安装它们。

2. 后端项目：拉取代码与核心配置实战

好了，基础环境就绪，我们现在正式进入JetLinks的核心地带——后端项目的搭建。这个过程就像组装一台精密的仪器，每一步的配置都关系到最终能否成功启动。我会把我自己踩过的坑和验证过的经验都分享给你，让你少走弯路。

2.1 获取源代码：从GitHub还是Gitee？

JetLinks的社区版代码托管在GitHub上，考虑到国内网络访问GitHub有时不太稳定，官方也在Gitee（码云）上设置了镜像仓库。我的建议是：优先使用Gitee，速度会快很多，体验也更顺畅。打开你的终端（Windows用PowerShell或CMD，Linux/Mac用Terminal），找一个你喜欢的目录，比如D:\Projects或者~/projects，然后执行克隆命令。这里我以Gitee为例：

git clone https://gitee.com/jetlinks/jetlinks-community.git cd jetlinks-community

克隆完成后，别急着切分支。我们先看看有哪些可用的版本。使用git tag命令可以列出所有历史版本标签。对于新手上路，我强烈建议你选择最新的稳定版，比如v2.1.0。切换到这个标签能保证你使用的代码是经过充分测试的，避免开发中的“坑”。切换命令如下：

git checkout v2.1.0

完成这一步，你的本地就有了一个和远程仓库一模一样、且版本确定的JetLinks社区版后端代码库了。接下来，我们打开这个项目，看看它的结构。用你顺手的IDE（IntelliJ IDEA、Eclipse或VS Code）打开项目根目录。你会看到好几个模块，对于初次搭建，我们只需要关注jetlinks-standalone这个模块。它是一个“全家桶”式的启动模块，把平台核心、规则引擎、设备网关等必要组件都打包在一起了，非常适合我们本地开发调试。这个模块下的src/main/resources/application.yml文件，就是我们接下来要重点“料理”的配置文件。

2.2 解剖application.yml：关键配置项详解

application.yml这个文件就像是整个平台的大脑，控制着所有组件的连接和行为。原始文章里提到了几处修改，我这里会展开讲得更细，告诉你为什么这么改，以及如果不改会怎样。首先用你的编辑器打开这个文件。

数据库配置：从PostgreSQL切换到MySQL默认配置是连接PostgreSQL的，我们需要把它改成MySQL。找到r2dbc配置段（R2DBC是响应式数据库连接驱动）。你需要修改url、username和password。这里有个关键点：你需要提前在MySQL里手动创建一个名为jetlinks的空数据库。JetLinks会在首次启动时自动创建所有表结构，但不会帮你创建数据库本身。配置示例如下：

r2dbc: url: r2dbc:mysql://localhost:3306/jetlinks?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai username: root # 替换成你的MySQL用户名 password: your_password # 替换成你的MySQL密码

紧接着，往下翻找到easyorm配置段，这里是ORM框架的配置，必须和上面的数据库类型对应上：

easyorm: default-schema: jetlinks dialect: mysql # 关键！必须从默认的postgresql改为mysql

如果这里不改dialect，启动时就会报一堆SQL语法错误，因为PostgreSQL和MySQL的SQL方言有不少差异。

Redis配置：连接你的缓存服务Redis的配置相对简单。找到redis配置段，把host和port改成你本地Redis服务的地址和端口。如果你的Redis设置了密码，还需要添加password配置项。lettuce.pool.max-active这个参数表示连接池最大连接数，本地开发保持默认或调小一点（比如32）都行，生产环境再根据压力调整。

redis: host: 127.0.0.1 port: 6379 # password: 如果你的Redis有密码，取消注释并填写 lettuce: pool: max-active: 32 max-wait: 5s

Elasticsearch配置：内嵌还是外置？这是新手最容易困惑的地方。JetLinks提供了两种模式：内嵌模式和外置模式。

• 内嵌模式 (embedded: true)：JetLinks会自己启动一个内置的Elasticsearch进程。这是最推荐给本地开发、测试、个人学习使用的模式，一键启动，无需额外安装和配置ES服务。你只需要确保data-path指向的目录有写入权限即可。配置很简单：

  elasticsearch: embedded: enabled: true >elasticsearch: embedded: enabled: false spring: elasticsearch: uris: http://localhost:9200 # 你的ES服务地址 # username: elastic # 如果ES开启了安全认证 # password: your_es_password

  我实测下来，对于只是想快速跑起来看看效果的开发者，强烈建议先用内嵌模式，能避开很多网络连接、版本兼容的麻烦。

2.3 启动与验证：看到日志才算成功

配置保存好后，我们就可以启动项目了。在IDE里，找到jetlinks-standalone模块下的org.jetlinks.community.standalone.JetLinksApplication这个类，直接运行它的main方法。如果你习惯用命令行，可以在项目根目录下执行：

mvn clean compile -DskipTests cd jetlinks-standalone mvn spring-boot:run

启动过程会输出大量日志，你需要耐心等待并观察。成功的标志是最后看到类似这样的日志：

Started JetLinksApplication in 25.456 seconds (JVM running for 26.789)

并且没有持续刷新的错误信息。启动过程中，你会看到它自动创建数据库表、初始化内嵌ES等操作。第一次启动可能会慢一些，因为要下载依赖和初始化数据。启动成功后，打开浏览器，访问http://localhost:8848/（8848是默认端口），如果能看到一个简单的页面或者接口文档（比如Swagger UI），说明后端服务已经正常启动了。记得把这个地址记下来，等下配置前端要用到。

3. 前端项目：Vue版界面搭建与联调

后端服务跑起来了，我们还需要一个操作界面来管理设备、查看数据。JetLinks提供了新旧两个前端，旧版基于Ant Design Pro（React），新版是基于Vue 3 + Vite + Ant Design Vue的。毫无疑问，我们选择更现代、性能更好的Vue新版进行搭建。

3.1 获取与准备前端代码

和后台类似，前端代码我们也从Gitee镜像克隆，速度更快：

git clone https://gitee.com/jetlinks/jetlinks-ui-vue.git cd jetlinks-ui-vue

同样，我们也需要切换到与后端匹配的稳定版本标签，比如v2.1.0：

git checkout v2.1.0

进入项目目录后，第一件事是安装依赖。这里官方推荐使用yarn，因为它比npm在依赖管理上更快速、可靠。如果你没有安装yarn，可以先通过npm install -g yarn来安装。然后执行：

yarn install

这个过程会下载所有需要的JavaScript包，取决于你的网络环境，可能需要几分钟。如果遇到网络超时，可以尝试配置淘宝的镜像源：yarn config set registry https://registry.npmmirror.com。

3.2 关键配置：让前端找到后端

前端项目启动前，最重要的一步就是告诉它后端API服务在哪里。这个配置在vite.config.ts文件中。用编辑器打开这个文件，找到server.proxy配置部分。它的作用是在开发环境下，将前端对特定API的请求转发到我们刚刚启动的后端服务上，解决跨域问题。

你需要修改target的值为你后端服务的实际地址。假设你的后端在本地8848端口启动，且没有修改上下文路径，配置应该像这样：

export default defineConfig({ server: { proxy: { '/api/': { target: 'http://localhost:8848/', // 重点：改成你的后端地址 changeOrigin: true, }, '/jetlinks/': { target: 'http://localhost:8848/', changeOrigin: true, } } } })

这个配置意味着，当前端代码中请求/api/device时，Vite开发服务器会自动将这个请求转发到http://localhost:8848/api/device。这样，前端和后端就联通起来了。

3.3 编译启动与登录

配置保存后，就可以启动前端开发服务器了。在项目根目录下运行：

yarn dev

如果一切顺利，命令行会输出Local: http://localhost:5173/这样的信息（Vite默认使用5173端口）。此时，打开浏览器访问http://localhost:5173，你就能看到JetLinks的登录界面了。

默认的超级管理员账号是admin，密码也是admin。输入后点击登录，如果成功进入系统主界面，看到设备管理、规则引擎等菜单，那么恭喜你，前后端联调成功！整个JetLinks社区版开发环境就已经完整地运行在你的本地机器上了。你可以试着创建一个模拟设备，体验一下从设备接入、数据上报到数据可视化的完整流程，感受一下这个开源物联网平台的强大功能。

4. 避坑指南：常见问题与解决思路

搭建过程很少有一帆风顺的，尤其是第一次接触这么多组件。我把我和同事们常遇到的几个“坑”以及解决办法整理出来，你遇到问题时可以先来这里找找思路。

问题一：后端启动报数据库连接错误

• 现象：日志中抛出Connection refused或Unknown database ‘jetlinks’等异常，然后启动失败。
• 排查：
  1. MySQL服务是否启动？在终端运行mysql -u root -p看能否进入MySQL命令行。
  2. 数据库创建了吗？登录MySQL后，执行SHOW DATABASES;查看是否存在jetlinks库。如果没有，执行CREATE DATABASE jetlinks CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;创建它。
  3. 配置信息对吗？仔细检查application.yml中的url、username、password，特别是IP、端口和数据库名。密码有特殊字符的，可能需要URL编码。
  4. MySQL用户权限？确保你配置的用户（如root）有从本地（localhost）连接并操作jetlinks数据库的权限。

问题二：Redis连接失败

• 现象：启动日志提示无法连接Redis，或报RedisConnectionFailureException。
• 排查：
  1. 运行redis-cli ping，如果返回PONG说明Redis服务正常，否则需要启动Redis服务。
  2. 检查application.yml中Redis的host和port是否与你的Redis服务配置一致。
  3. 如果Redis设置了密码，务必在配置文件中添加password项。
  4. 如果是Windows系统，确保你以管理员身份启动了Redis服务器。

问题三：Elasticsearch相关错误

• 现象：启动时卡在Elasticsearch初始化，或报版本不兼容、端口被占用等错误。
• 排查：
  1. 端口冲突：内嵌ES默认用9200端口。如果这个端口被其他程序（比如你自己安装的ES服务）占用，就会失败。可以通过netstat -ano | findstr :9200(Windows) 或lsof -i:9200(Linux/Mac) 查看并结束占用进程，或者修改application.yml中的elasticsearch.embedded.port为其他端口，如9201。
  2. 文件权限：内嵌ES需要写入data-path指定的目录。确保当前运行Java进程的用户对该目录有读写权限。
  3. 内存不足：ES比较吃内存。如果启动时JVM内存不足，可以尝试在启动命令中添加参数调大内存，例如-Xms512m -Xmx1024m。

问题四：前端能打开但登录失败或页面空白

• 现象：前端页面能访问，但点击登录没反应，或登录后页面空白，浏览器控制台（F12）报网络错误（404或500）。
• 排查：
  1. 代理配置错误：这是最常见的原因。再次确认vite.config.ts中的target地址是否精确地指向了正在运行的后端服务（http://localhost:8848）。确保后端服务确实在运行。
  2. 后端跨域设置：虽然Vite代理解决了开发环境的跨域，但如果直接打包部署，可能需要后端配置CORS。社区版默认已配置，如果遇到问题，可以检查后端application.yml中jetlinks.cors相关配置。
  3. 浏览器缓存：尝试打开浏览器无痕模式，或强制刷新（Ctrl+F5）页面。

问题五：依赖下载慢或失败无论是Maven依赖还是Yarn的npm包，在国内都可能遇到网络问题。

• Maven：可以配置阿里云镜像。编辑Maven安装目录下conf/settings.xml文件，在<mirrors>标签内添加：

  <mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>

• Yarn/NPM：如前所述，配置淘宝镜像：yarn config set registry https://registry.npmmirror.com。

把这些常见问题处理好，你的JetLinks开发环境基本上就非常稳固了。接下来，你就可以基于这个本地环境，开始阅读代码、调试功能、开发自己的设备协议接入或者业务插件了。记住，搭建环境是第一步，也是最重要的一步，地基打牢了，后面盖房子才快。