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 或容器运行时。

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

Rancher Desktop（Docker Desktop 开源替代，兼容性最佳）——设置引擎为dockerd (moby)后，同样执行上面的 compose 命令。
WSL2 内原生 Docker Engine——在 WSL2 Ubuntu 中apt install docker.io docker-compose-v2，挂载项目目录后执行同一 compose。

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

curl-sfLhttps://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh-ostandalone_embed.shbashstandalone_embed.sh start

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 默认激活devprofile，仅用于把@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。

五、使用示例

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

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

知识库功能依赖向量库可用；若 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，已修改两处：

copilot-modules/copilot-knowledge/.../config/MilvusVectorStoreConfig.java
- 新增token、secure配置项；
- 构建ConnectParam时，若配置token则自动withToken(...)并强制withSecure(true)，本地无 token 时行为不变。
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 接入步骤

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

设置环境变量（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"# 嵌入模型仍需（知识库必须）

启动后端：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正确。

企业官网建设流程全解析