从零到一：在Windows上搭建MeterSphere本地开发与调试环境

1. 环境准备从零搭建MeterSphere开发环境第一次在Windows上配置MeterSphere开发环境时我踩了不少坑。这个开源测试平台依赖的中间件比较多包括MySQL、Redis、Kafka和MinIO等需要提前做好规划。建议准备一台配置还不错的Windows电脑至少16GB内存因为同时运行这些服务会比较吃资源。我推荐使用Windows 10或11专业版因为后续可能会用到WSLWindows Subsystem for Linux功能。另外确保你的系统已经安装了最新版本的Git和Docker Desktop这两个工具在后续步骤中会频繁使用。如果你打算完全在Windows原生环境下运行还需要提前安装好Java 17 JDK这是MeterSphere v2.10的硬性要求。2. 获取MeterSphere源码直接从GitHub克隆MeterSphere主仓库是最直接的方式git clone https://github.com/metersphere/metersphere.git不过国内开发者可能会遇到克隆速度慢的问题。我试过几种解决方案最稳定的是使用国内镜像源。比如在git clone命令前加上前缀git clone https://gitclone.com/github.com/metersphere/metersphere.git克隆完成后建议切换到稳定分支。我通常会选择最新的release分支cd metersphere git checkout v2.103. 处理项目依赖MeterSphere有个特殊的依赖项——meterSphere-plugin-sdk需要单独处理。这个SDK包不在公共Maven仓库中需要我们自己构建git clone https://github.com/metersphere/metersphere-plugin-sdk.git cd metersphere-plugin-sdk mvn clean install构建完成后jar包会自动安装到本地Maven仓库。这时再回到MeterSphere主项目执行Maven构建cd ../metersphere mvn clean package -DskipTests第一次构建可能会比较久因为要下载大量依赖。我在北京和上海的机器上都试过有时候会因为网络问题卡住。如果遇到这种情况可以尝试配置阿里云的Maven镜像源。4. 配置文件本地化MeterSphere默认会从/opt/metersphere/conf/目录加载配置这在Windows下显然不适用。我们需要修改几个关键配置文件首先是metersphere.properties找到项目中的src/main/resources/目录复制一份到你的工作目录比如D:\metersphere\conf\。然后修改其中的数据库连接信息spring.datasource.urljdbc:mysql://localhost:3306/metersphere?useUnicodetruecharacterEncodingUTF-8autoReconnecttrueuseSSLfalse spring.datasource.usernameroot spring.datasource.passwordrootredisson.yml也需要类似处理修改Redis连接信息singleServerConfig: password: 123456 address: redis://localhost:6379 database: 05. 中间件安装与配置5.1 MySQL 8.0安装MeterSphere要求MySQL 8.0以上版本。Windows下最简单的安装方式是使用MySQL Installer从官网下载MySQL Community Server安装时选择Server only模式设置root密码为root与配置文件对应创建metersphere数据库CREATE DATABASE metersphere CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;5.2 Redis安装Windows原生运行Redis不太稳定我推荐以下两种方案方案一使用Dockerdocker run --name redis -p 6379:6379 -d redis redis-server --requirepass 123456方案二使用WSL启用WSL并安装Ubuntu在Ubuntu中安装Redissudo apt update sudo apt install redis-server sudo sed -i s/supervised no/supervised systemd/g /etc/redis/redis.conf sudo systemctl restart redis5.3 Kafka部署Kafka在Windows原生环境下运行问题较多建议使用Docker Composeversion: 3 services: zookeeper: image: wurstmeister/zookeeper ports: - 2181:2181 kafka: image: wurstmeister/kafka ports: - 9092:9092 environment: KAFKA_ADVERTISED_HOST_NAME: localhost KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181 KAFKA_CREATE_TOPICS: metersphere:1:1 volumes: - /var/run/docker.sock:/var/run/docker.sock5.4 MinIO配置MinIO可以直接在Windows下运行下载MinIO Windows版创建数据目录比如D:\minio\data启动服务set MINIO_ROOT_USERadmin set MINIO_ROOT_PASSWORDpassword minio.exe server D:\minio\data --console-address :90016. 启动MeterSphere服务所有中间件就绪后就可以启动MeterSphere了。我推荐使用IntelliJ IDEA打开项目配置启动参数-Dspring.config.locationD:\metersphere\conf\metersphere.properties修改application.yml中的服务发现配置eureka: client: serviceUrl: defaultZone: http://localhost:8761/eureka/启动MeterSphereApplication主类第一次启动会比较慢耐心等待直到看到Started MeterSphereApplication日志。如果遇到问题可以检查以下几个方面所有中间件服务是否正常运行配置文件路径是否正确数据库连接信息是否准确端口是否被占用7. 常见问题排查在实际搭建过程中我遇到过几个典型问题数据库连接失败检查MySQL是否允许远程连接确保metersphere数据库已创建字符集为utf8mb4。Redis超时如果使用WSL或Docker注意localhost可能需要替换为实际IP。我在WSL2中遇到过这个问题解决方案是在Windows hosts文件中添加WSL2的IP映射。Kafka连接问题确保Kafka的advertised.listeners配置正确。在Docker环境下需要设置为宿主机的IP。MinIO访问异常检查MinIO的console端口和服务端口是否冲突我遇到过9000端口被占用的情况改成9001就正常了。8. 开发调试技巧成功启动服务后这里分享几个实用的开发技巧前端热部署MeterSphere采用前后端分离架构前端代码在metersphere-web项目里。启动前端开发服务器cd metersphere-web npm install npm run serveAPI调试启动后访问http://localhost:8081这是Swagger UI界面可以方便地测试各个API。日志查看重点监控以下几个日志文件logs/metersphere-app.log应用主日志logs/sql.logSQL语句日志logs/access.logHTTP请求日志配置覆盖开发时经常需要修改配置可以在resources目录下创建application-dev.yml里面的配置会覆盖主配置。