197 lines
6.0 KiB
Markdown
197 lines
6.0 KiB
Markdown
# Sino-MCI 项目约定
|
||
|
||
> 本文件用于固定开发/部署时的关键操作，避免反复踩坑。
|
||
|
||
## 1. Java 与 Maven
|
||
|
||
- **必须使用 JDK 21**：`/Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home`
|
||
- 项目已配置 Maven Toolchain，**必须在 `backend/` 目录下执行完整 reactor 构建**：
|
||
```bash
|
||
cd /Users/marsal/Projects/sino-project/sino-mci/backend
|
||
mvn clean install -DskipTests
|
||
```
|
||
- **不要**用 `-pl` 单模块编译，会跳过 `.mvn/maven.config` 中的 toolchains 配置，导致编译报 JDK 17 错误。
|
||
- 当前环境 `java -version` 可能显示 JDK 17，但 Maven 会通过 toolchain 自动切换到 JDK 21，无需手动修改 `JAVA_HOME`。
|
||
|
||
## 2. Docker Compose 项目名（重要）
|
||
|
||
Docker Compose 的 `-p` 参数决定容器前缀和命名卷前缀。反复换 `-p` 会产生多个 MySQL 数据卷，导致数据“丢失”的假象。
|
||
|
||
**统一使用项目名 `sino-mci`**：
|
||
|
||
```bash
|
||
cd /Users/marsal/Projects/sino-project/sino-mci
|
||
|
||
# 启动全部基础设施 + 应用
|
||
# 使用 --profile 同时启用 infra 和 app，否则带 profile 的服务不会启动
|
||
docker compose -p sino-mci --profile infra --profile app up -d
|
||
|
||
# 只启动基础设施（MySQL/Redis/RabbitMQ/SeaweedFS）
|
||
docker compose -p sino-mci --profile infra up -d
|
||
|
||
# 只启动应用（mci-server / admin-web / channel-service）
|
||
docker compose -p sino-mci --profile app up -d
|
||
|
||
# 停止整个项目（不删除数据卷）
|
||
docker compose -p sino-mci --profile infra --profile app down
|
||
```
|
||
|
||
- 不带 `-p` 时，项目名默认就是目录名 `sino-mci`，与上面等价。
|
||
- **不要**再使用 `-p infrastructure` 或其他名字启动，避免产生新的数据卷。
|
||
|
||
## 3. 数据卷
|
||
|
||
当前项目使用的命名卷：
|
||
|
||
- `sino-mci_mci-mysql-data`
|
||
- `sino-mci_mci-seaweedfs-data`
|
||
- `sino-mci_channel-service-data`
|
||
|
||
### 检查当前 MySQL 容器挂载的是哪个卷
|
||
|
||
```bash
|
||
docker inspect -f '{{ range .Mounts }}{{ if eq .Destination "/var/lib/mysql" }}{{ .Name }}{{ end }}{{ end }}' mci-mysql
|
||
```
|
||
|
||
### 查看所有 sino-mci 相关卷
|
||
|
||
```bash
|
||
docker volume ls | grep sino-mci
|
||
```
|
||
|
||
### 历史 `infrastructure_*` 卷
|
||
|
||
早期用 `-p infrastructure` 启动过，留下以下卷，**目前未被使用**：
|
||
|
||
- `infrastructure_mci-mysql-data`
|
||
- `infrastructure_mci-seaweedfs-data`
|
||
- `infrastructure_channel-service-data`
|
||
|
||
如需迁移/核对其中的数据，请先停止当前 `mci-mysql`，再临时挂载该卷启动容器查询，查完立即恢复。
|
||
|
||
## 4. 常用命令
|
||
|
||
```bash
|
||
# 查看服务状态
|
||
docker compose -p sino-mci ps
|
||
|
||
# 查看 mci-server 日志
|
||
docker logs -f mci-server --tail 100
|
||
|
||
# 进入 MySQL
|
||
docker exec -it mci-mysql mysql -uroot -proot sino_mci
|
||
|
||
# 进入 Redis
|
||
docker exec -it mci-redis redis-cli
|
||
|
||
# 重新构建 mci-server 镜像（先执行 mvn clean install -DskipTests）
|
||
docker compose -p sino-mci --profile app build mci-server
|
||
```
|
||
|
||
## 5. 环境变量与快速切换环境
|
||
|
||
项目使用 `.env` 统一管理 MySQL、Redis、RabbitMQ、SeaweedFS 以及应用服务的连接地址。
|
||
|
||
### 5.1 快速切换本地/远程基础设施
|
||
|
||
```bash
|
||
cd /Users/marsal/Projects/sino-project/sino-mci
|
||
|
||
# 方案 A：连接本机 localhost 上的基础设施（默认）
|
||
cp .env.local .env
|
||
|
||
# 方案 B：连接远程基础设施（如 192.168.1.173）
|
||
cp .env.remote .env
|
||
```
|
||
|
||
`.env` 文件不会被提交（已加入 `.gitignore`），可以按需要随时切换。
|
||
|
||
### 5.2 本地启动后端/前端/Channel Service
|
||
|
||
```bash
|
||
# 后端
|
||
./scripts/run-local.sh backend
|
||
|
||
# 前端
|
||
./scripts/run-local.sh frontend
|
||
|
||
# Channel Service
|
||
./scripts/run-local.sh channel
|
||
```
|
||
|
||
`run-local.sh` 会自动加载项目根目录的 `.env`，并把 `MYSQL_HOST`、`REDIS_HOST`、`RABBITMQ_HOST`、`MCI_SERVER_URL`、`VITE_API_BASE_URL` 等变量注入到对应进程中。
|
||
|
||
### 5.3 Docker Compose 启动（不受 .env 中 host 影响）
|
||
|
||
```bash
|
||
# 只启动基础设施
|
||
./scripts/local-up.sh
|
||
|
||
# 启动基础设施 + 应用服务
|
||
./scripts/local-up.sh --with-apps
|
||
```
|
||
|
||
`local-up.sh` 会自动把 host 覆盖为 Docker 容器名（`mci-mysql`、`mci-redis`、`mci-rabbitmq`、`mci-server`），因此无论 `.env` 中是 `localhost` 还是远程 IP，容器内部都能正确互联。
|
||
|
||
### 5.4 手动执行 docker compose 的注意事项
|
||
|
||
若直接运行 `docker compose` 命令，容器会使用当前 `.env` 中的 `MYSQL_HOST` 等变量。请确保 `.env` 中的 host 对容器可访问，或改用 `local-up.sh` 启动。
|
||
|
||
### 5.5 默认账号
|
||
|
||
- MySQL root 密码：`root`（仅本地/内网开发使用）
|
||
- 平台管理员：`superadmin` / `admin123`
|
||
|
||
### 5.6 新增环境/自定义地址
|
||
|
||
复制任意一份模板后修改：
|
||
|
||
```bash
|
||
cp .env.local .env
|
||
# 编辑 .env 中的 MYSQL_HOST、REDIS_HOST、RABBITMQ_HOST、MCI_SERVER_URL、VITE_API_BASE_URL
|
||
```
|
||
|
||
## 6. 本地调试（IDE）
|
||
|
||
### 6.1 后端 Spring Boot 调试
|
||
|
||
1. 切换环境：
|
||
```bash
|
||
cd /Users/marsal/Projects/sino-project/sino-mci
|
||
cp .env.local .env # 连接本地 docker-compose 基础设施
|
||
# 或 cp .env.remote .env # 连接远程基础设施（如 192.168.1.173）
|
||
```
|
||
|
||
2. 在 IntelliJ IDEA 中创建 Run Configuration：
|
||
- **Main class**: `com.sino.mci.server.MciServerApplication`
|
||
- **Active profiles**: `dev`
|
||
- **Environment variables**: 填入 `.env` 中的关键变量，例如：
|
||
```
|
||
MYSQL_HOST=localhost;REDIS_HOST=localhost;RABBITMQ_HOST=localhost;MYSQL_PORT=3306;MYSQL_ROOT_PASSWORD=root;MYSQL_DATABASE=sino_mci;MYSQL_USER=root;REDIS_PORT=6379;RABBITMQ_DEFAULT_USER=guest;RABBITMQ_DEFAULT_PASS=guest;RABBITMQ_AMQP_PORT=5672
|
||
```
|
||
|
||
> 也可安装 EnvFile / .env 插件让 IDE 自动加载 `.env`。
|
||
|
||
3. 启动 Debug，访问 `http://localhost:8080/msg-platform`。
|
||
|
||
### 6.2 前端 Vite 调试
|
||
|
||
```bash
|
||
cd admin-web
|
||
npm run dev
|
||
```
|
||
|
||
代理目标由 `VITE_API_BASE_URL` 决定（定义在 `.env` 中）：
|
||
- `.env.local`：指向 `http://localhost:8080`
|
||
- `.env.remote`：指向 `http://192.168.1.173:8080`
|
||
|
||
### 6.3 Channel Service 调试
|
||
|
||
```bash
|
||
cd channel-service
|
||
source .venv/bin/activate
|
||
python -m app.main
|
||
```
|
||
|
||
`MCI_SERVER_URL` 从 `.env` 加载，指向后端地址。
|