sino-mci/AGENTS.md

Sino-MCI 项目约定

本文件用于固定开发/部署时的关键操作，避免反复踩坑。

1. Java 与 Maven

• 必须使用 JDK 21：/Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home
• 项目已配置 Maven Toolchain，必须在 backend/ 目录下执行完整 reactor 构建：

  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：

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 容器挂载的是哪个卷

docker inspect -f '{{ range .Mounts }}{{ if eq .Destination "/var/lib/mysql" }}{{ .Name }}{{ end }}{{ end }}' mci-mysql

查看所有 sino-mci 相关卷

docker volume ls | grep sino-mci

历史 infrastructure_* 卷

早期用 -p infrastructure 启动过，留下以下卷，目前未被使用：

• infrastructure_mci-mysql-data
• infrastructure_mci-seaweedfs-data
• infrastructure_channel-service-data

如需迁移/核对其中的数据，请先停止当前 mci-mysql，再临时挂载该卷启动容器查询，查完立即恢复。

4. 常用命令

# 查看服务状态
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 快速切换本地/远程基础设施

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

# 后端
./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 影响）

# 只启动基础设施
./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 新增环境/自定义地址

复制任意一份模板后修改：

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. 切换环境：

   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 调试

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 调试

cd channel-service
source .venv/bin/activate
python -m app.main

MCI_SERVER_URL 从 .env 加载，指向后端地址。