Spring AI Alibaba Copilot 项目使用指南

Spring AI Alibaba Copilot 项目使用指南一、项目介绍1.1 是什么AI 编码助手Alibaba Copilot是基于 Spring AI Alibaba 框架构建的智能编码助手集成 MCPModel Context Protocol工具协议支持项目分析、代码生成、智能编辑、项目脚手架等能力。通过自然语言交互帮助开发者快速完成各类编程任务。1.2 技术架构技术说明Spring Boot 3.4.5应用框架Spring AI 1.1.2 / Spring AI Alibaba 1.1.2AI 集成框架支持多种 LLMMCP ClientModel Context Protocol 客户端AspectJAOP 切面用于工具调用监控MyBatis-Plus / Dynamic-Datasource数据访问与多数据源Sa-Token权限认证JWTMilvus / Redis / MySQL向量库 / 缓存 / 关系库Jackson / Java Diff UtilsJSON 处理 / 文件差异比较1.3 系统要求Java 17、Maven 3.6Node.js 20前端ui-reactMySQL 8.0默认库名spring_ai_copilotRedis单机 127.0.0.1:6379强依赖Milvus 2.5.x端口 19530强依赖可用云端 Zilliz Cloud 替代阿里云通义千问 API Key或 OpenAI/DeepSeek 兼容 Key1.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:7Milvus 的几种安装方式任选其一前提Milvus 官方没有 Windows 原生安装包所有方式都基于 WSL2 或容器运行时。Docker DesktopWSL2 后端——仓库自带docs/docker/docker-compose-milvus.ymlcd d:\test\spring-ai-alibaba-copilot\docs\docker docker compose-f docker-compose-milvus.yml up-dRancher DesktopDocker Desktop 开源替代兼容性最佳——设置引擎为dockerd (moby)后同样执行上面的 compose 命令。WSL2 内原生 Docker Engine——在 WSL2 Ubuntu 中apt install docker.io docker-compose-v2挂载项目目录后执行同一 compose。WSL2 内 standalone 二进制完全不用 Dockercurl-sfLhttps://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh-ostandalone_embed.shbashstandalone_embed.sh startZilliz Cloud云端托管推荐详见第七节——本地无需安装任何 Milvus 组件。2.2 初始化数据库⚠️ README 写的scripts/sql/init.sql不存在实际脚本在docs/scripts/sql/spring_ai_copilot.sqlmysql-u root-p-eCREATE 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服务器端口6039context-path/。数据源spring.datasource.dynamic.datasource.master默认root/123456库名spring_ai_copilot写死在文件按需改。AI 模型spring.ai.dashscope.api-key: ${DASHSCOPE_API_KEY}主对话模型默认deepseek-v4-flashspring.ai.openaiDeepSeek用于会话压缩spring.ai.openai.embedding硅基流动BAAI/bge-large-zh-v1.5用于知识库向量向量库spring.ai.vectorstore.milvus.*host/port/token/secure/database/collection/dimension。Redis / Redisson127.0.0.1:6379。应用自定义app.workspace工作目录./workspace、app.security.approval-mode、app.conversation.summarization、app.mcp。Sa-Token默认timeout: 6048007 天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 false3.3 前端配置ui-react默认.env.local不设置时Vite 代理/api、/auth、/admin→http://localhost:6039vite.config.ts。如需直连后端复制.env.example为.env.localAPP_BASE_URLhttp://localhost:6039开发服务器已配置Cross-Origin-Embedder-Policy/Opener-PolicyWebContainer 需要。四、启动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或 IDEWeIde界面。自然语言对话编程在对话中描述需求如“生成一个 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 CloudZilliz 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.ymlspring.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, 云端鉴权true7.5 注意事项嵌入 Key 不能省Zilliz 只存/检向量向量由硅基流动BAAI/bge-large-zh-v1.5维度 1024生成SILICONFLOW_API_KEY必须配置。维度/集合一致embedding-dimension: 1024collection-name: copilot_knowledgeCOSINE会在 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_PORT443、MILVUS_TOKEN正确。