80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
# 开发指南
|
||
|
||
本文档说明如何在本地搭建并运行 im-system。
|
||
|
||
## 环境要求
|
||
|
||
- **JDK 21**（后端 toolchain 锁定；需本机安装，或由 Gradle 自动下载）
|
||
- **Gradle 9.6+**（仅首次生成 wrapper 需要）
|
||
- **Node.js 20.19+**
|
||
- **pnpm 11+**
|
||
- **Kafka**（可选，见下文）
|
||
|
||
## 后端
|
||
|
||
### 首次初始化
|
||
|
||
仓库不含 Gradle wrapper，首次需用本机 Gradle 生成（生成后应 commit 进仓库）：
|
||
|
||
```bash
|
||
cd backend
|
||
gradle wrapper --gradle-version 9.6.1
|
||
```
|
||
|
||
之后一律使用 `./gradlew`，不再依赖本机 Gradle。
|
||
|
||
### 启动三个服务
|
||
|
||
```bash
|
||
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。
|
||
|
||
## 前端
|
||
|
||
```bash
|
||
cd frontend
|
||
pnpm install
|
||
```
|
||
|
||
### 启动
|
||
|
||
```bash
|
||
pnpm --filter @im-system/admin dev # 管理后台，http://localhost:5173
|
||
pnpm --filter @im-system/app dev # 聊天 App，http://localhost:1420
|
||
```
|
||
|
||
### 构建与检查
|
||
|
||
```bash
|
||
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。改端口见上表。
|