Spring AI Alibaba Copilot 项目使用指南

Spring AI Alibaba Copilot 项目使用指南

---

一、项目介绍

1.1 是什么

AI 编码助手（Alibaba Copilot） 是基于 Spring AI Alibaba 框架构建的智能编码助手，集成 MCP（Model Context Protocol）工具协议，支持项目分析、代码生成、智能编辑、项目脚手架等能力。通过自然语言交互，帮助开发者快速完成各类编程任务。

1.2 技术架构

技术	说明
Spring Boot 3.4.5	应用框架
Spring AI 1.1.2 / Spring AI Alibaba 1.1.2	AI 集成框架，支持多种 LLM
MCP Client	Model Context Protocol 客户端
AspectJ	AOP 切面，用于工具调用监控
MyBatis-Plus / Dynamic-Datasource	数据访问与多数据源
Sa-Token	权限认证（JWT）
Milvus / Redis / MySQL	向量库 / 缓存 / 关系库
Jackson / Java Diff Utils	JSON 处理 / 文件差异比较

1.3 系统要求

• Java 17+ 、Maven 3.6+
• Node.js 20+ （前端 ui-react）
• MySQL 8.0+ （默认库名 spring_ai_copilot）
• Redis （单机 127.0.0.1:6379，强依赖）
• Milvus 2.5.x （端口 19530，强依赖；可用云端 Zilliz Cloud 替代）
• 阿里云通义千问 API Key（或 OpenAI/DeepSeek 兼容 Key）

1.4 项目结构

spring-ai-alibaba-copilot/
├── copilot-admin/          # 启动入口（端口 6039）
├── copilot-modules/        # 业务模块
│   ├── copilot-conversation/   # 对话管理
│   ├── copilot-context/        # 上下文分析（含对话/知识库 Hook）
│   ├── copilot-knowledge/      # 知识库（向量存储/RAG）
│   └── copilot-prompt/         # 提示词管理
├── copilot-common/         # 通用工具
└── ui-react/               # 前端界面（端口 5173）
    ├── src/components/AiChat/  # 聊天组件
    ├── src/components/WeIde/   # IDE 组件
    └── src/api/                # API 接口

---

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

二、安装与环境准备

2.1 依赖中间件

项目运行必须依赖 MySQL、Redis、Milvus（或 Zilliz Cloud） 三类服务。

MySQL / Redis（本机安装或容器）

# Redis（本机未装时可用容器）
docker run -d --name redis -p 6379:6379 redis:7

Milvus 的几种安装方式（任选其一）

前提：Milvus 官方没有 Windows 原生安装包，所有方式都基于 WSL2 或容器运行时。

1. Docker Desktop（WSL2 后端） ------仓库自带 docs/docker/docker-compose-milvus.yml：

   cd d:\test\spring-ai-alibaba-copilot\docs\docker
   docker compose -f docker-compose-milvus.yml up -d

2. Rancher Desktop （Docker Desktop 开源替代，兼容性最佳）------设置引擎为 dockerd (moby) 后，同样执行上面的 compose 命令。

3. WSL2 内原生 Docker Engine ------在 WSL2 Ubuntu 中 apt install docker.io docker-compose-v2，挂载项目目录后执行同一 compose。

4. WSL2 内 standalone 二进制（完全不用 Docker）：

   curl -sfL https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh -o standalone_embed.sh
   bash standalone_embed.sh start

5. Zilliz Cloud（云端托管，推荐，详见第七节）------本地无需安装任何 Milvus 组件。

2.2 初始化数据库

⚠️ README 写的 scripts/sql/init.sql 不存在 ，实际脚本在 docs/scripts/sql/spring_ai_copilot.sql：

mysql -u root -p -e "CREATE DATABASE spring_ai_copilot CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p spring_ai_copilot < docs/scripts/sql/spring_ai_copilot.sql

---

三、配置

3.1 后端核心配置（copilot-admin/src/main/resources/application.yml）

• 服务器 ：端口 6039，context-path /。
• 数据源 ：spring.datasource.dynamic.datasource.master，默认 root/123456，库名 spring_ai_copilot（写死在文件，按需改）。
• AI 模型 ：
  • spring.ai.dashscope.api-key: ${DASHSCOPE_API_KEY}（主对话模型，默认 deepseek-v4-flash）
  • spring.ai.openai（DeepSeek，用于会话压缩）+ spring.ai.openai.embedding（硅基流动 BAAI/bge-large-zh-v1.5，用于知识库向量）
• 向量库 ：spring.ai.vectorstore.milvus.*（host/port/token/secure/database/collection/dimension）。
• Redis / Redisson ：127.0.0.1:6379。
• 应用自定义 ：app.workspace（工作目录 ./workspace）、app.security.approval-mode、app.conversation.summarization、app.mcp。
• Sa-Token ：默认 timeout: 604800（7 天），token-prefix: Bearer。

注意：application.yml 中 spring.profiles.active: local，仓库无 application-local.yml，不会报错（所有配置都在主文件）。Maven 默认激活 dev profile，仅用于把 @logging.level@ 占位符替换为 DEBUG。

3.2 必须设置的环境变量

application.yml 用 ${...} 引用以下变量，未设置会导致启动失败：

$env:DASHSCOPE_API_KEY = "sk-xxxx"     # 必需：主对话模型
$env:OPENAI_API_KEY    = "sk-xxxx"     # 建议：会话压缩（DeepSeek）
$env:SILICONFLOW_API_KEY = "sk-xxxx"   # 建议：嵌入模型（知识库/RAG 必须）
# Milvus / Zilliz（详见第七节的 Zilliz 配置）
$env:MILVUS_HOST  = "localhost"        # 或 Zilliz Endpoint
$env:MILVUS_PORT  = "19530"            # 或 Zilliz 443
$env:MILVUS_TOKEN = ""                 # 本地留空；Zilliz 填 API Key
$env:MILVUS_SECURE = "false"

3.3 前端配置（ui-react）

• 默认 .env.local 不设置时，Vite 代理 /api、/auth、/admin → http://localhost:6039（vite.config.ts）。

• 如需直连后端，复制 .env.example 为 .env.local：

  APP_BASE_URL=http://localhost:6039

• 开发服务器已配置 Cross-Origin-Embedder-Policy / Opener-Policy（WebContainer 需要）。

---

四、启动

4.1 启动后端

⚠️ 关键坑 ：logging.level 用的是 Maven 资源占位符 @logging.level@，只有经过 Maven 构建/运行才会被替换。直接用 IDE 运行 CopilotApplication.main 会报 "Could not resolve placeholder"，必须用 Maven 启动：

mvn clean install -DskipTests
mvn spring-boot:run -pl copilot-admin

看到 (♥◠‿◠)ﾉﾞ Alibaba Copilot启动成功 即成功。后端地址 http://localhost:6039。

4.2 启动前端

cd ui-react
pnpm install
pnpm run dev

前端地址 http://localhost:5173。

4.3 访问与登录

浏览器打开 http://localhost:5173，默认账号 admin / admin123。WebContainer（在线编码/运行）需 Chrome/Edge。

---

五、使用示例

典型开发流程（基于模块能力）：

1. 登录进入工作台 ：使用 admin/admin123 登录，进入对话（AiChat）或 IDE（WeIde）界面。
2. 自然语言对话编程 ：在对话中描述需求（如"生成一个 Spring Boot 用户管理模块"），由 copilot-conversation 管理多轮会话，copilot-context 做项目上下文分析，调用 LLM + MCP 工具完成代码生成与智能编辑。
3. 会话压缩 ：长对话超过 max-tokens-before-summary: 4000 时自动压缩，保留最近 messages-to-keep: 20 条。
4. 知识库 / RAG 增强 ：在 copilot-knowledge 模块上传代码或文档，系统经嵌入模型（BAAI/bge-large-zh-v1.5）向量化后存入 Milvus，对话时通过 KnowledgeContextHook 做语义检索，实现"基于项目私有知识的问答"。
5. 项目脚手架：基于分析结果生成项目结构与脚手架代码。

知识库功能依赖向量库可用；若 Milvus 不可达，配置类会自动降级为 NoOpVectorStore，应用照常启动，仅知识库/RAG 不可用。

---

六、应用场景

• AI 结对编程：自然语言生成/修改代码、智能补全。
• 项目分析与理解：扫描代码库、生成结构说明与依赖关系。
• 私有知识问答（RAG）：把团队文档/代码库接入向量库，基于私有上下文回答。
• 项目脚手架生成：依据需求快速搭建工程骨架。
• 企业内代码助手平台：基于 Sa-Token 的多用户权限、会话隔离与审计。

---

七、云端 Zilliz Cloud 介绍与接入

7.1 什么是 Zilliz Cloud

Zilliz Cloud 是 Milvus 的全托管云服务（由 Milvus 原厂提供），开箱即用、免运维，兼容 Milvus API。对本项目而言，它直接替代"自建 Milvus 服务"，只需一个 Endpoint + API Key 即可连接，无需在本机跑 Docker / WSL2 Milvus。

7.2 为什么用云端

• 省去本地安装/运维 Milvus、etcd、minio 的麻烦（尤其 Windows 环境）。
• 弹性扩容、高可用，适合团队与生产。
• 本项目代码已做兼容：本地 Milvus 与云端 Zilliz 用同一套配置，靠环境变量切换。

7.3 代码适配改动（已完成）

为支持 Zilliz 的 Token 鉴权 + TLS，已修改两处：

1. copilot-modules/copilot-knowledge/.../config/MilvusVectorStoreConfig.java

   • 新增 token、secure 配置项；
   • 构建 ConnectParam 时，若配置 token 则自动 withToken(...) 并强制 withSecure(true)，本地无 token 时行为不变。

2. copilot-admin/src/main/resources/application.yml

   • spring.ai.vectorstore.milvus.client 下新增：

     token: ${MILVUS_TOKEN:}
     secure: ${MILVUS_SECURE:false}

   • 默认仍是本地 Milvus，设了 MILVUS_TOKEN 即自动走云端 + TLS。

7.4 接入步骤

1. 注册 Zilliz Cloud ，创建一个 Cluster（免费版 Free 即可），拿到 Endpoint （形如 in01-xxxx.api.gcp-us-west1.zillizcloud.com）。

2. 在 API Keys 页面创建 API Key。

3. 设置环境变量（PowerShell）：

   $env:MILVUS_HOST  = "你的cluster-endpoint"   # 纯域名，不带 https:// 和 :443
   $env:MILVUS_PORT  = "443"
   $env:MILVUS_TOKEN = "你的APIKey"             # Zilliz API Key
   # $env:MILVUS_SECURE = "true"  # 设了 token 会自动 TLS，可省略
   $env:SILICONFLOW_API_KEY = "sk-xxxx"         # 嵌入模型仍需（知识库必须）

4. 启动后端 ：mvn spring-boot:run -pl copilot-admin，日志应出现：

   Milvus 客户端已初始化: 主机=..., 端口=443, 数据库=default, 云端鉴权=true

7.5 注意事项

• 嵌入 Key 不能省 ：Zilliz 只存/检向量，向量由硅基流动 BAAI/bge-large-zh-v1.5（维度 1024）生成，SILICONFLOW_API_KEY 必须配置。
• 维度/集合一致 ：embedding-dimension: 1024 + collection-name: copilot_knowledge + COSINE，会在 Zilliz 上自动建集合，与嵌入模型匹配。
• database ：保持默认 default（免费版通常仅支持 default）。
• 本机依赖变化 ：用 Zilliz 后无需本地/容器 Milvus ，但 MySQL、Redis 仍需。
• 免费版限制：Free 版有 CU/集合数/存储额度，开发联调足够；超量需升级。
• 降级保护 ：Zilliz 连不上时自动降级为 NoOpVectorStore，主流程仍可跑。

---

八、常见问题与排错

• 启动报 "Could not resolve placeholder @logging.level@" ：务必用 mvn spring-boot:run，不要直接 IDE 跑 main。
• 数据库/Redis/Milvus 连接失败 ：确认三服务已启动，地址端口与 application.yml 一致（MySQL 3306、Redis 6379、Milvus 19530 / Zilliz 443）。
• AI 不响应 ：检查 DASHSCOPE_API_KEY 是否有效、deepseek-v4-flash 模型在百炼平台可用；知识库还需 SILICONFLOW_API_KEY 与向量库正常。
• 前端连不上后端 ：确认后端已起；检查是否误设 APP_BASE_URL 导致直连失败，或浏览器 CORS 报错。
• Zilliz 连不上 ：核对 MILVUS_HOST 是否为纯域名（不含协议/端口）、MILVUS_PORT=443、MILVUS_TOKEN 正确。