基于SpringAI的智能平台基座开发-（二）

智能平台基座前置文档（环境搭建专项指南）

一、文档核心目标

本指南为小白提供"一步一操作"的环境搭建方案，完成后可获得智能平台基座运行所需的完整环境（含容器化工具、数据库、AI模型服务等）。核心目标：

掌握Docker与Docker Compose的安装配置（环境搭建基础）；
完成MySQL、Redis、Milvus、Ollama核心服务的容器化部署；
学会环境验证方法，确保每个服务正常运行；
解决环境搭建中常见问题，避开小白易踩坑点。

重要提示：环境搭建的核心原则是"容器化部署"（所有服务通过Docker运行），无需单独手动安装复杂软件，降低配置难度。建议按文档顺序逐步操作，每完成一个步骤先验证，再进行下一步。

二、前置准备：明确系统要求与工具清单

2.1 操作系统要求

推荐使用以下系统（兼容性最佳），避免因系统版本问题导致部署失败：

Windows：Windows 10 专业版/企业版（需开启Hyper-V）、Windows 11 任意版本；
Mac：macOS 10.15+（Intel芯片/M1/M2芯片均可）；
Linux：Ubuntu 20.04 LTS、CentOS 7+（适合有基础的用户，小白优先选Windows/Mac）。

2.2 必备工具与资源

提前准备以下工具，避免操作中中断：

网络环境：稳定的互联网（需下载Docker镜像，建议带宽≥10Mbps）；
终端工具：Windows用"命令提示符（CMD）"或"PowerShell"，Mac用"终端"；
文本编辑器：记事本、VS Code（推荐，可高亮配置文件语法，下载地址：https://code.visualstudio.com/）；
辅助工具（可选）：Windows需提前开启Hyper-V（后续步骤会讲），Mac无需额外工具。

三、第一步：安装Docker与Docker Compose（核心基础）

Docker是容器化部署的核心工具，Docker Compose用于管理多个容器，两者必须先安装完成。以下分Windows、Mac系统分别讲解（Linux系统可参考附录）。

3.1 Windows系统安装步骤

开启Hyper-V（关键前置步骤）：
- 按下Win+R键，输入"control"打开控制面板；
- 选择"程序→程序和功能→启用或关闭Windows功能"；
- 找到"Hyper-V"，勾选所有子选项，点击"确定"；
- 系统会提示重启电脑，点击"立即重启"（必须重启生效）。
下载Docker Desktop：
- 访问Docker官网下载：https://www.docker.com/products/docker-desktop/；
- 点击"Download for Windows"，等待安装包下载完成（约500MB）。
安装Docker Desktop：
- 双击下载的安装包（Docker Desktop Installer.exe）；
- 默认勾选"Use WSL 2 instead of Hyper-V"（若未勾选则手动勾选），点击"OK"；
- 等待安装完成，点击"Close and restart"（再次重启电脑）。
验证安装是否成功：
- 重启后，桌面会出现"Docker Desktop"图标，双击打开（首次启动可能需要1-2分钟）；
- 打开"命令提示符（CMD）"，输入以下2个命令，若均显示版本信息则安装成功：
命令1：docker --version（查看Docker版本）

命令2：docker-compose --version（查看Docker Compose版本）

3.2 Mac系统安装步骤

下载Docker Desktop：
- 访问Docker官网下载：https://www.docker.com/products/docker-desktop/；
- 点击"Download for Mac"，根据芯片类型选择（Intel芯片直接下载，Apple芯片点击"Download for Mac (Apple Chip)"）。
安装Docker Desktop：
- 将下载的.dmg文件拖到"应用程序"文件夹中；
- 打开"应用程序"，找到"Docker"并双击启动（首次启动可能需要授权，点击"打开"即可）。
验证安装是否成功：
- 打开"终端"，输入以下2个命令，若均显示版本信息则安装成功：
命令1：docker --version

命令2：docker-compose --version

3.3 小白常见问题解决

问题1：Windows启动Docker提示"Hyper-V未启用"？

解决：重新执行3.1.1步骤，确保Hyper-V所有子选项都勾选，重启电脑后再试。

问题2：Mac启动Docker提示"权限不足"？

解决：打开"系统设置→隐私与安全性"，找到"开发者工具"，允许Docker访问，再重启Docker。

问题3：输入docker命令提示"不是内部或外部命令"？

解决：重启终端工具，若仍无效则重启电脑，确保Docker Desktop已正常启动（桌面右下角/顶部有Docker图标）。

四、第二步：通过Docker Compose部署核心服务

核心服务包括MySQL、Redis、Milvus、Ollama，我们通过一个docker-compose.yml配置文件统一管理，实现"一键启动所有服务"。

4.1 准备配置文件

创建一个专门的环境文件夹（方便管理）：
- Windows：在桌面创建"smart-platform-env"文件夹；
- Mac：在桌面创建"smart-platform-env"文件夹。
创建docker-compose.yml文件：
- 打开VS Code（或记事本），新建一个空白文件；
- 复制以下完整配置代码到文件中（注意：不要修改代码格式，尤其是缩进）；
- 将文件保存到"smart-platform-env"文件夹中，文件名必须为"docker-compose.yml"（后缀为.yml，不是.txt）。

完整配置代码（直接复制使用）：

yaml 复制代码

version: '3.8'
services:
  # MySQL数据库
  mysql:
    image: mysql:8.0
    container_name: smart-platform-mysql
    ports:
      - "3306:3306"  # 主机端口:容器端口，外部通过3306访问MySQL
    environment:
      MYSQL_ROOT_PASSWORD: root123456  #  root用户密码，可修改
      MYSQL_DATABASE: smart_platform_db  # 自动创建的数据库名
    volumes:
      - mysql-data:/var/lib/mysql  # 数据持久化，重启容器数据不丢失
    restart: always  # 容器异常时自动重启

  # Redis缓存
  redis:
    image: redis:7.2
    container_name: smart-platform-redis
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: always

  # Milvus向量数据库
  milvus:
    image: milvusdb/milvus:v2.4.4
    container_name: smart-platform-milvus
    ports:
      - "19530:19530"  # Milvus核心端口
      - "9091:9091"
    volumes:
      - milvus-data:/var/lib/milvus
    restart: always

  # Ollama本地AI模型
  ollama:
    image: ollama/ollama:latest
    container_name: smart-platform-ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    restart: always
    command: ["serve"]  # 启动Ollama服务

volumes:
  mysql-data:
  redis-data:
  milvus-data:
  ollama-data:

配置说明：上述代码已预设好所有服务的基础配置，小白无需修改。其中"ports"是端口映射（外部通过主机端口访问容器内服务），"environment"是环境变量（如MySQL密码），"volumes"是数据持久化（确保重启服务后数据不丢失）。

4.2 启动所有核心服务

打开终端/CMD，进入"smart-platform-env"文件夹：
- Windows（CMD）：输入命令 cd Desktop\smart-platform-env，按回车；
- Mac（终端）：输入命令 cd ~/Desktop/smart-platform-env，按回车。
执行启动命令：
- 输入命令 docker-compose up -d，按回车；
- 首次执行会自动下载所有服务的镜像（约2-5GB，耗时取决于网络速度），耐心等待，终端会显示"Pull complete"表示下载完成；
- 下载完成后，Docker会自动启动所有容器，终端显示"Done"即启动成功。

4.3 验证服务是否正常运行

每个服务启动后，必须验证是否可用，避免后续开发踩坑。

4.3.1 查看所有容器状态

在终端/CMD输入命令 docker ps，按回车；
若输出结果中，"NAMES"列显示"smart-platform-mysql""smart-platform-redis"等4个容器，且"STATUS"列均为"Up"（运行中），则容器启动成功。

4.3.2 单独验证每个服务

服务名称	验证步骤	验证成功标志
MySQL	1. 终端输入命令：docker exec -it smart-platform-mysql mysql -u root -p；2. 输入密码：root123456（配置文件中预设的），按回车。	进入MySQL命令行（显示"mysql>"提示符）。
Redis	1. 终端输入命令：docker exec -it smart-platform-redis redis-cli；2. 输入命令：ping，按回车。	输出"PONG"。
Milvus	1. 终端输入命令：docker exec -it smart-platform-milvus milvus_cli；2. 输入命令：version，按回车。	输出Milvus版本信息（如v2.4.4）。
Ollama	1. 终端输入命令：docker exec -it smart-platform-ollama ollama run qwen:7b；2. 等待模型拉取完成（约4GB，耗时较久），输入问题："你好"，按回车。	Ollama返回中文回复（如"你好！有什么可以帮到你？"）。

4.4 常用操作命令（必记）

后续管理服务需用到以下命令，记熟这些即可满足基础需求：

启动所有服务：docker-compose up -d（需在smart-platform-env文件夹下执行）；
停止所有服务：docker-compose down；
查看运行中的容器：docker ps；
查看所有容器（含停止的）：docker ps -a；
重启某个服务（如MySQL）：docker restart smart-platform-mysql；
进入容器内部：docker exec -it 容器名命令（如进入Redis：docker exec -it smart-platform-redis redis-cli）。

五、第三步：环境搭建完成后的检查清单

完成所有步骤后，对照以下清单检查，确保环境完全可用：

Docker与Docker Compose已安装成功，能正常执行命令；
docker-compose.yml文件已正确创建，放置在smart-platform-env文件夹；
执行docker-compose up -d后，4个核心服务容器均为"Up"状态；
MySQL能正常登录，Redis能返回PONG，Milvus能显示版本，Ollama能正常对话；
记住常用的容器管理命令（启动、停止、查看状态）。

六、常见问题排查大全（小白必备）

6.1 容器启动失败（STATUS显示Exited）

原因1：端口被占用（如3306端口被其他MySQL占用）；
解决：关闭占用端口的程序，或修改docker-compose.yml中的"ports"（如将3306:3306改为3307:3306），然后重新执行docker-compose up -d。

6.2 镜像下载缓慢或失败

原因1：网络不稳定，或国外镜像源访问慢；
解决：配置Docker国内镜像源（阿里云）：

打开Docker Desktop，进入设置（Windows：Settings，Mac：Preferences）；
找到"Docker Engine"，在配置中添加：

"registry-mirrors": ["https://registry.cn-hangzhou.aliyuncs.com"]

点击"Apply & Restart"，重启Docker后重新下载。

6.3 Ollama模型拉取失败

原因1：网络问题，或模型体积过大（qwen:7b约4GB）；
解决：耐心等待，或更换网络（如连接手机热点），重新执行docker exec -it smart-platform-ollama ollama run qwen:7b。

6.4 无法进入MySQL命令行

原因1：密码输入错误，或容器未启动；
解决：1. 先执行docker ps确认MySQL容器已启动；2. 输入密码时注意区分大小写，配置文件中预设密码为root123456。

七、总结

本指南完成了智能平台基座的核心环境搭建，核心是通过Docker Compose实现"一键部署所有服务"，避免了单独安装每个软件的复杂配置。小白只需按步骤操作，每步验证，就能顺利完成环境搭建。

环境搭建是后续技术学习和开发的基础，确保环境正常后，就可以进入后端、前端等技术的入门学习（如Spring Boot接口开发、Vue3页面搭建）。