im-system/DEVELOPMENT.md

开发指南

本文档说明如何在本地搭建并运行 im-system。

环境要求

• JDK 21（后端 toolchain 锁定；需本机安装，或由 Gradle 自动下载）
• Gradle 9.6+（仅首次生成 wrapper 需要）
• Node.js 20.19+
• pnpm 11+
• Kafka（可选，见下文）

后端

首次初始化

仓库不含 Gradle wrapper，首次需用本机 Gradle 生成（生成后应 commit 进仓库）：

cd backend
gradle wrapper --gradle-version 9.6.1

之后一律使用 ./gradlew，不再依赖本机 Gradle。

启动三个服务

cd backend
./gradlew :gateway:bootRun      # 网关，http://localhost:8080
./gradlew :im-service:bootRun   # 主服务，http://localhost:8081
./gradlew :log-service:bootRun  # 日志服务，http://localhost:8082

• 三个服务需分终端启动（或加 & 后台运行）。
• 依赖 Kafka 的功能（im-service 发日志 → log-service 消费）需先启动 Kafka；只跑网关转发可暂不起 Kafka。

前端

cd frontend
pnpm install

启动

pnpm --filter @im-system/admin dev    # 管理后台，http://localhost:5173
pnpm --filter @im-system/app dev      # 聊天 App，http://localhost:1420

构建与检查

pnpm -r build          # 全量构建
pnpm type-check        # 全量类型检查

服务通信

• Gateway 统一入口与路由：/api/im/** → im-service，/api/log/** → log-service。
• im-service 通过 Kafka 向 topic im-logs 发送日志消息。
• log-service 监听同一 topic（consumer group log-service）消费并落库。
• 前端 dev 阶段：admin 的 /api 代理到 localhost:8080（gateway）；app 直连后端地址。

配置项

项目	位置	默认值
Kafka 地址	各服务 application.yml 的 KAFKA_BOOTSTRAP_SERVERS	localhost:9092
后端端口	各 application.yml 的 server.port	8080 / 8081 / 8082
前端端口	各 vite.config.ts 的 server.port	5173 / 1420
gateway 路由	gateway/src/main/resources/application.yml 的 spring.cloud.gateway.routes	/api/im/**、/api/log/**

常见问题

• Gradle Unresolved reference：每个子项目脚本需独立声明 plugins {}，根脚本只集中钉版本（apply false）。避免在根 subprojects {} 里用 apply(plugin=...) + 静态访问器（implementation、kotlin 等），否则脚本编译期无法解析。
• Kafka 连接失败：确认 Kafka 已启动，bootstrap-servers 正确（默认 localhost:9092）。
• 端口占用：8080/8081/8082、5173、1420。改端口见上表。