当前位置： 首页 > news >正文

Spring AI Alibaba Copilot 项目使用指南

news 2026/7/17 23:59:02

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.2AI 集成框架，支持多种 LLM
MCP ClientModel Context Protocol 客户端
AspectJAOP 切面，用于工具调用监控
MyBatis-Plus / Dynamic-Datasource数据访问与多数据源
Sa-Token权限认证（JWT）
Milvus / Redis / MySQL向量库 / 缓存 / 关系库
Jackson / Java Diff UtilsJSON 处理 / 文件差异比较

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-sfLhttps://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh-ostandalone_embed.shbashstandalone_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 默认激活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。

五、使用示例

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

  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正确。
http://www.jsqmd.com/news/1209694/

相关文章：

  • 「线上课就是自学」——这句话漏掉了什么
  • 2026年7月劳力士中国专柜官方客户热线最新服务 - 劳力士官方服务中心
  • 每周分享】USB协议波形中的SOF包为何如此设计？令我疑惑不解
  • 2026年7月最新亨得利官方服务项目及价格查询｜服务电话及详细地址权威信息通告 - 亨得利官方博客
  • 真力时中国官方售后服务中心｜服务热线及门店详细地址权威信息声明（2026年7月更新） - 亨得利官方服务中心
  • 鸿蒙 ArkTS 实战：Title Inspiration Machine 从轻量生成到草稿管理完整解析
  • 2026 年更新：仁布比较好的铸铁拍门加工厂哪家专业,打破传统：这门铁门，如何彻底解决噪音和安全问题？ - 领域鉴赏官
  • 微流控技术的核心特征、流体行为优势及其在体外诊断领域的应用展望
  • 积家中国官方售后服务中心｜服务电话及全部地址权威信息公示（2026年7月最新） - 积家官方售后服务中心
  • Linux操作系统1
  • Codex与ChatGPT Work：AI编程助手从原理到700万用户实战
  • 劳力士中国官方售后服务中心｜官方地址及24小时客服电话权威信息公示（2026年7月更新） - 劳力士服务中心
  • 2026广州漏水维修实用攻略｜厨卫、阳台、外墙、屋顶与地下室处理｜常见漏点处理及服务选择 - 盛隆防水
  • AI编程实战：7天零基础开发三个项目
  • Unity 物理系统进阶：重力设置与自定义重力效果
  • 2026 年现阶段，固原有实力的球墨铸铁篦子批发厂家联系电话,别再买！这小物件的秘密，让你的排水系统永不堵塞 - 品质体验官
  • 微信小程序版2048游戏源码（含完整页面结构、核心算法与运行截图）
  • 2026年07月：Q235B工字钢供应厂家实力解析与采购参考 - 甄选服务推荐
  • 2026年7月最新亨得利官方服务项目及价格查询｜维修地址与24小时热线权威信息通告 - 亨得利官方
  • 宝玑中国官方售后服务中心｜官方地址及服务热线权威信息公示（2026年7月最新） - 亨得利钟表维修中心
  • 【Linux运维极简教程】12-性能监控与优化
  • 开源零代码Bot平台：企业AI落地的最后一公里解决方案
  • 2026广州漏水维修实用攻略｜厨卫、阳台、外墙、屋顶与地下室处理｜分场景维修与门店判断方法 - 盛隆防水
  • 2026合肥企业团建包车高性价比高长短途出行服务 全城严筛名单.doc - 资讯在线
  • Oracle点餐系统课设资源包：含建库脚本、数据说明书与Python演示程序
  • 亨得利官方服务项目及价格查询｜地址和维修热线权威信息通知（2026年7月最新） - 亨得利官方
  • 2026年7月最新亨得利官方服务项目及价格查询｜地址及服务电话权威信息公示 - 亨得利官方博客
  • 电商项目微服务拆分实战
  • 鸿蒙 ArkTS 实战：Recipe Rewriter 从轻量生成到草稿管理完整解析
  • SpringBoot+Vue反欺诈平台源码，带用户管理与音视频素材上传功能