基于 Docker 的 Milvus + Redis 本地开发环境部署完全指南

前言

在当今 AI 应用开发中，向量数据库与高速缓存已经成为不可或缺的基础设施组件。Milvus 作为业界领先的开源向量数据库，为相似度搜索、推荐系统、RAG（检索增强生成）等场景提供了高性能的向量检索能力；而 Redis 凭借其基于内存的高速读写特性，广泛应用于会话缓存、状态管理、消息队列等场景。

然而，手动编译和配置这些数据库服务往往涉及复杂的依赖管理和环境配置，对于开发者而言门槛较高。Docker 容器化技术的出现彻底改变了这一局面------通过一条命令即可在本地拉起完整的数据库服务，真正实现了"一次配置，处处运行"。

本文将以实战为导向，从零开始手把手带你完成以下目标：

• 深入理解 Milvus 与 Redis 在 AI 系统架构中的定位与作用
• 掌握 Docker Desktop 的安装与环境配置
• 使用 Docker Compose 一键编排并部署 Milvus 和 Redis
• 通过 Python SDK 完成服务的连接验证与基本操作
• 了解常见问题的排查与解决思路

无论你是刚接触容器化技术的新手，还是需要快速搭建本地开发环境的 AI 工程师，本文都能为你提供一份可落地的完整指南。

---

目录

• 一、整体架构认知
  • 1.1 系统架构全景
  • 1.2 各组件职责解析
  • 1.3 数据流转流程
• 二、前置条件准备
  • 2.1 硬件要求
  • 2.2 软件要求
  • 2.3 端口规划
• 三、安装 Docker Desktop
  • 3.1 Docker 运行原理简述
  • 3.2 Windows 安装步骤
  • 3.3 macOS 安装步骤（Intel / Apple Silicon）
  • 3.4 验证安装
• 四、配置 Docker Compose 文件
  • 4.1 创建项目目录
  • 4.2 编写 docker-compose.yml
  • 4.3 配置文件逐行解析
• 五、启动服务
  • 5.1 拉取镜像并启动容器
  • 5.2 验证容器运行状态
  • 5.3 查看服务日志
• 六、验证 Milvus 服务
  • 6.1 安装 Python SDK
  • 6.2 连接测试
  • 6.3 创建集合与向量插入示例
  • 6.4 向量相似度搜索示例
• 七、验证 Redis 服务
  • 7.1 安装 Python 客户端
  • 7.2 连接测试
  • 7.3 常用数据结构操作示例
• 八、停止与清理服务
• 九、常见问题及解决方法
• 十、参考资源

---

一、整体架构认知

1.1 系统架构全景

在一个典型的 AI 应用系统中，Milvus、Redis 和 Docker 各自承担着不同的职责，共同构成一个高效的数据服务层。整体架构关系如下：

┌─────────────────────────────────────────────────────┐
│                   AI 应用层（Python）                  │
│         推荐系统 / RAG / 图像检索 / 语义搜索           │
└──────────┬──────────────────────────┬───────────────┘
           │                          │
           ▼                          ▼
   ┌──────────────┐          ┌──────────────┐
   │    Milvus     │          │    Redis      │
   │  向量数据库    │          │   缓存/状态    │
   │  端口: 19530  │          │  端口: 6379   │
   └──────┬───────┘          └──────┬───────┘
          │                         │
          ▼                         ▼
   ┌──────────────┐          ┌──────────────┐
   │  Etcd + MinIO │          │   AOF 持久化  │
   │  元数据 + 存储  │          │   数据持久化   │
   └──────────────┘          └──────────────┘
           │                         │
           └────────────┬────────────┘
                        │
                        ▼
              ┌──────────────────┐
              │   Docker Engine   │
              │  容器编排与运行时   │
              └──────────────────┘

1.2 各组件职责解析

Milvus ------ 向量检索引擎

Milvus 是由 Zilliz 公司开发并开源的向量数据库，专门用于存储、索引和检索大规模向量数据。在 AI 系统中，它承担以下核心功能：

• 向量索引构建：支持多种索引类型（如 IVF_FLAT、HNSW、IVF_PQ 等），根据数据规模和精度需求灵活选择
• 相似度搜索：支持欧氏距离（L2）、内积（IP）、余弦相似度（COSINE）等多种度量方式
• 混合查询：支持标量过滤 + 向量搜索的组合查询，满足复杂业务逻辑
• 水平扩展：支持分布式部署，可处理十亿级别的向量数据

典型应用场景：RAG 系统中的文档检索、电商商品以图搜图、推荐系统中的相似用户/物品匹配、音频/视频指纹识别等。

Redis ------ 高速缓存与状态存储

Redis（Remote Dictionary Server）是一款基于内存的键值存储系统，以其极高的读写性能著称。在 AI 系统中，它通常承担：

• 会话缓存：缓存频繁查询的结果，减轻 Milvus 的查询压力
• 状态管理：存储用户会话、任务状态、模型推理进度等临时数据
• 速率限制：通过计数器和过期时间实现 API 调用频率限制
• 消息队列：利用 List、Stream 等数据结构实现简单的任务队列
• 特征缓存：缓存常用的 embedding 向量，避免重复计算

Milvus 与 Redis 的协作模式：应用首先查询 Redis 缓存，命中则直接返回；未命中时再查询 Milvus，将结果写回 Redis 后返回给用户。这种"缓存 + 向量数据库"的组合能显著降低延迟并提升吞吐量。

Docker ------ 容器化运行环境

Docker 提供了轻量级的容器虚拟化技术，将 Milvus 和 Redis 及其所有依赖打包为独立的容器，确保：

• 环境一致性：开发、测试、生产环境完全相同，避免"在我机器上能跑"的问题
• 一键部署：通过 Docker Compose 编排文件，一条命令即可启动所有服务
• 资源隔离：各容器独立运行，互不干扰
• 快速销毁：不再需要时，一条命令即可清理所有资源

1.3 数据流转流程

以一个 RAG（检索增强生成）场景为例，展示完整的数据流转过程：

用户提问
  │
  ▼
应用层：文本 → Embedding 模型 → 生成查询向量
  │
  ▼
查询 Redis：是否有缓存的检索结果？
  │
  ├── 命中 → 直接返回缓存结果 → 组装 Prompt → 调用 LLM → 返回答案
  │
  └── 未命中
        │
        ▼
      查询 Milvus：向量相似度搜索 Top-K 相关文档
        │
        ▼
      将检索结果写入 Redis 缓存（设置 TTL）
        │
        ▼
      组装 Prompt（检索到的文档 + 用户问题）→ 调用 LLM → 返回答案

---

二、前置条件准备

2.1 硬件要求

资源	最低要求	推荐配置	说明
内存	8GB	16GB	Milvus 单机模式建议至少 4GB，加上 Redis 和系统开销
磁盘	20GB 可用空间	50GB SSD	Docker 镜像较大，加上数据持久化存储
CPU	2 核	4 核及以上	影响向量索引构建速度

2.2 软件要求

软件	版本要求	用途
Docker Desktop	最新稳定版	容器运行时
Docker Compose	V2（Docker Desktop 自带）	多容器编排
Python	3.8 及以上	验证脚本运行环境
pip	最新版本	Python 包管理器

2.3 端口规划

部署前请确保以下端口未被占用：

服务	端口	协议	说明
Milvus gRPC	19530	TCP	Milvus 主服务端口，Python SDK 默认连接此端口
Milvus Metrics	9091	HTTP	Milvus 健康检查与监控指标端口
Redis	6379	TCP	Redis 数据库服务端口

检查端口占用（Windows PowerShell）：

netstat -ano | findstr "19530"
netstat -ano | findstr "6379"

检查端口占用（macOS / Linux）：

lsof -i :19530
lsof -i :6379

如果端口被占用，可以在后续的 docker-compose.yml 中修改映射端口（如 19531:19530）。

---

三、安装 Docker Desktop

3.1 Docker 运行原理简述

Docker 本质上依赖 Linux 内核特性（如 cgroups、namespace）来实现容器隔离。因此，在非 Linux 系统上运行 Docker 时，底层需要提供一个 Linux 运行环境：

Windows 环境：
  Docker Desktop → WSL2（Windows Subsystem for Linux）→ Linux 内核 → 容器

macOS（Intel）环境：
  Docker Desktop → HyperKit 虚拟机 → Linux 内核 → 容器

macOS（Apple Silicon / M 系列）环境：
  Docker Desktop → Apple Virtualization Framework → Linux ARM64 → 容器

理解这一点很重要------安装 Docker 的本质是：安装 Docker 引擎 + 配置底层 Linux 运行环境。

3.2 Windows 安装步骤

步骤一：启用 WSL2

WSL2 是 Docker Desktop 在 Windows 上运行的必要前提。在安装 Docker 之前，需要先启用 WSL2。

打开 PowerShell（以管理员身份运行），执行：

wsl --install 

该命令会自动完成以下操作：

• 启用"适用于 Linux 的 Windows 子系统"功能
• 启用"虚拟机平台"功能
• 下载并安装最新的 Linux 内核
• 将 WSL2 设为默认版本
• 安装默认的 Linux 发行版（Ubuntu）

执行完成后，重启计算机。

重启后，系统会自动打开 Ubuntu 终口，要求你设置用户名和密码（这是 Linux 子系统的登录凭据，随意设置即可）。

注意 ：如果你的系统版本较旧（Windows 10 1903 以下），可能需要手动下载 WSL2 Linux 内核更新包：https://aka.ms/wsl2kernel

步骤二：下载并安装 Docker Desktop

1. 1.访问 Docker 官方网站：https://www.docker.com/products/docker-desktop
2. 2.点击 Download for Windows 下载安装包
3. 3.双击运行下载的 .exe 安装程序
4. 4.在安装向导中，确保勾选 Use WSL 2 instead of Hyper-V（推荐）
5. 5.点击 OK 开始安装，等待安装完成
6. 6.安装完成后，点击 Close and restart 重启电脑（如果提示）

步骤三：首次启动配置

1. 1.从开始菜单或桌面快捷方式启动 Docker Desktop
2. 2.等待右下角系统托盘出现 Docker 图标（鲸鱼图标），图标不再上下浮动时表示启动完成
3. 3.首次启动可能要求你登录 Docker Hub 账号（可跳过，不影响本地使用）

步骤四：配置镜像加速器（推荐）

由于 Docker Hub 的服务器在海外，国内拉取镜像可能较慢。建议配置国内镜像加速器。

点击 Docker Desktop 右上角 齿轮图标（Settings） → Docker Engine，在 JSON 配置中添加：

{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://docker.m.daocloud.io"
  ]
}

点击 Apply & Restart 使配置生效。

3.3 macOS 安装步骤（Intel / Apple Silicon）

步骤一：下载对应版本

1. 1.访问 Docker 官方网站：https://www.docker.com/products/docker-desktop
2. 2.根据你的 Mac 芯片类型选择下载版本：
   • Apple Silicon（M1 / M2 / M3 / M4） ：选择 Mac with Apple Chip
   • Intel ：选择 Mac with Intel Chip

如何查看芯片类型：点击左上角 → 关于本机 → 查看"芯片"信息。

步骤二：安装

1. 1.打开下载的 .dmg 文件
2. 2.将 Docker 图标拖入 Applications 文件夹
3. 3.打开 Applications 文件夹，双击 Docker 图标启动

步骤三：首次启动

1. 1.系统可能弹出安全提示，点击 打开 确认
2. 2.输入 macOS 登录密码授权安装（Docker 需要安装网络和文件系统相关组件）
3. 3.等待菜单栏出现 Docker 图标，图标不再上下浮动时表示启动完成

步骤四：配置镜像加速器（推荐）

点击菜单栏 Docker 图标 → Settings（设置） → Docker Engine，添加镜像加速器配置（同 Windows 步骤）。

3.4 验证安装

无论 Windows 还是 macOS，安装完成后打开终端（Windows 使用 PowerShell，macOS 使用 Terminal），执行以下命令验证：

# 检查 Docker 引擎版本
docker --version

预期输出（版本号可能不同）：

Docker version 27.x.x, build xxxxxxx 

# 检查 Docker Compose 版本
docker compose version

预期输出：

Docker Compose version v2.x.x 

# 运行测试容器
docker run hello-world

如果看到 "Hello from Docker!" 的欢迎信息，说明 Docker Desktop 安装成功且运行正常。

---

四、配置 Docker Compose 文件

4.1 创建项目目录

选择一个磁盘空间充足的目录，创建专用的项目文件夹：

Windows（PowerShell）：

mkdir C:\milvus_redis
cd C:\milvus_redis

macOS / Linux（Terminal）：

mkdir -p ~/milvus_redis
cd ~/milvus_redis

该目录将用于存放 Docker Compose 配置文件以及所有服务的持久化数据。

4.2 编写 docker-compose.yml

在项目目录下创建 docker-compose.yml 文件：

Windows：

New-Item -Path . -Name "docker-compose.yml" -ItemType "File" 

macOS / Linux：

touch docker-compose.yml 

使用任意文本编辑器（VS Code、Notepad++、Vim 等）打开该文件，写入以下内容：

version: '3.5'

# =====================================================
# Milvus + Redis 本地开发环境
# Redis 密码: 1234
# =====================================================

services:
  # ---------- Etcd：Milvus 元数据存储 ----------
  etcd:
    container_name: milvus-etcd
    image: quay.io/coreos/etcd:v3.5.5
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_ENABLE_V2=true
    volumes:
      - ./volumes/etcd:/etcd/data
    command: >-
      etcd
      -advertise-client-urls=http://127.0.0.1:2379
      -listen-client-urls http://0.0.0.0:2379
      --data-dir /etcd/data

  # ---------- MinIO：Milvus 对象存储 ----------
  minio:
    container_name: milvus-minio
    image: minio/minio:RELEASE.2023-03-20T20-16-18Z
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    volumes:
      - ./volumes/minio:/minio/data
    command: minio server /minio/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

  # ---------- Milvus Standalone：向量数据库主服务 ----------
  standalone:
    container_name: milvus-standalone
    image: milvusdb/milvus:v2.4.4
    command: ["milvus", "run", "standalone"]
    environment:
      - ETCD_ENDPOINTS=etcd:2379
      - MINIO_ADDRESS=minio:9000
    volumes:
      - ./volumes/milvus:/var/lib/milvus
    ports:
      - "19530:19530"    # gRPC 服务端口
      - "9091:9091"      # Metrics / 健康检查端口
    depends_on:
      - etcd
      - minio

  # ---------- Redis：缓存与状态存储 ----------
  redis:
    container_name: milvus-redis
    image: redis:7.2
    restart: always
    ports:
      - "6379:6379"
    volumes:
      - ./volumes/redis:/data
    command: redis-server --requirepass 1234 --appendonly yes

# ---------- 网络配置 ----------
networks:
  default:
    name: milvus-network

4.3 配置文件逐行解析

下面对关键配置项进行逐一说明，帮助你理解每一行的作用：

Etcd 服务

配置项	说明
image: quay.io/coreos/etcd:v3.5.5	Etcd 官方镜像，v3.5.5 是经过 Milvus 官方验证的稳定版本
ETCD_AUTO_COMPACTION_MODE=revision	按修订版本号自动压缩历史数据，防止存储无限增长
ETCD_AUTO_COMPACTION_RETENTION=1000	保留最近 1000 个修订版本
ETCD_QUOTA_BACKEND_BYTES=4294967296	设置后端存储配额为 4GB（4 × 1024³）
ETCD_ENABLE_V2=true	启用 Etcd V2 API（Milvus 内部需要）
volumes: ./volumes/etcd:/etcd/data	将 Etcd 数据持久化到本地目录

MinIO 服务

配置项	说明
image: minio/minio:RELEASE.2023-03-20T20-16-18Z	MinIO 是一个 S3 兼容的对象存储，Milvus 用它存储索引文件和日志
MINIO_ACCESS_KEY / MINIO_SECRET_KEY	MinIO 的访问凭据，开发环境使用默认值 minioadmin
healthcheck	定期检查 MinIO 是否健康，确保 Milvus 启动时 MinIO 已就绪

Milvus Standalone 服务

配置项	说明
image: milvusdb/milvus:v2.4.4	Milvus 官方单机版镜像，该镜像兼容 x86_64 和 ARM64 架构
command: ["milvus", "run", "standalone"]	以单机模式运行（适合开发测试，生产环境可部署分布式集群）
ETCD_ENDPOINTS=etcd:2379	告诉 Milvus 去哪里找 Etcd（Docker Compose 内部 DNS 自动解析）
MINIO_ADDRESS=minio:9000	告诉 Milvus 去哪里找 MinIO
ports: 19530:19530	将 Milvus 的 gRPC 端口映射到宿主机，供外部应用连接
ports: 9091:9091	Metrics 端口，可用于 Prometheus 监控或健康检查
depends_on	确保 Etcd 和 MinIO 先于 Milvus 启动

Redis 服务

配置项	说明
image: redis:7.2	Redis 7.2 官方镜像，支持多架构（x86_64 / ARM64）
restart: always	容器意外退出后自动重启，保证服务可用性
command: redis-server --requirepass 1234 --appendonly yes	设置密码为 1234，并启用 AOF 持久化（每次写操作都追加到日志文件）
volumes: ./volumes/redis:/data	将 Redis 数据持久化到本地目录

安全提醒 ：--requirepass 设置的密码 1234 仅适用于本地开发环境。生产环境务必使用强密码，并通过 Docker Secrets 或环境变量文件管理敏感信息。

网络配置

networks:
  default:
    name: milvus-network

所有服务将加入名为 milvus-network 的自定义网络，容器之间可以通过服务名（如 etcd、minio、standalone、redis）直接互相访问，无需关心具体的 IP 地址。

---

五、启动服务

5.1 拉取镜像并启动容器

在项目目录下打开终端，执行：

docker compose up -d 

参数说明：

• up：创建并启动所有定义的容器
• -d：以守护进程（后台）模式运行

首次执行时，Docker 需要从远程仓库拉取所有镜像，输出类似如下：

[+] Running 5/5
 ✔ Network milvus-network   Created                                    0.1s
 ✔ Container milvus-etcd    Healthy                                   12.3s
 ✔ Container milvus-minio   Healthy                                   15.6s
 ✔ Container milvus-standalone Started                                 18.2s
 ✔ Container milvus-redis   Started                                    5.1s

镜像拉取说明：完整的镜像总大小约 2-3GB，首次拉取可能需要 5-20 分钟，取决于你的网络带宽。后续启动会直接使用本地缓存的镜像，秒级启动。

5.2 验证容器运行状态

docker ps 

正常情况下应该看到 4 个容器均处于 Up 状态：

CONTAINER ID   IMAGE                              STATUS         NAMES
xxxxxxxxxxxx   redis:7.2                          Up 2 minutes   milvus-redis
xxxxxxxxxxxx   milvusdb/milvus:v2.4.4             Up 2 minutes   milvus-standalone
xxxxxxxxxxxx   minio/minio:RELEASE.2023-03-20...  Up 2 minutes   milvus-minio
xxxxxxxxxxxx   quay.io/coreos/etcd:v3.5.5         Up 2 minutes   milvus-etcd

如果某个容器的 STATUS 显示为 Restarting 或 Exited，说明启动过程中出现了问题，需要查看日志排查原因。

5.3 查看服务日志

当服务启动异常时，可以通过查看容器日志来定位问题：

# 查看 Milvus 日志（实时跟踪）
docker logs -f milvus-standalone

# 查看 Redis 日志
docker logs -f milvus-redis

# 查看 Etcd 日志
docker logs -f milvus-etcd

# 查看 MinIO 日志
docker logs -f milvus-minio

参数 -f 表示实时跟踪日志输出，按 Ctrl + C 退出。

---

六、验证 Milvus 服务

6.1 安装 Python SDK

确保已安装 Python 3.8 或以上版本（可通过 python --version 或 python3 --version 检查），然后安装 Milvus Python SDK：

pip install pymilvus 

如果你的网络环境导致 pip 安装较慢，可以使用国内镜像源：

pip install pymilvus -i https://pypi.tuna.tsinghua.edu.cn/simple 

6.2 连接测试

创建测试脚本 test_milvus.py：

from pymilvus import connections, utility

# 连接到本地 Milvus 服务
connections.connect(host="localhost", port="19530")

# 获取并打印 Milvus 服务端版本
version = utility.get_server_version()
print(f"Milvus 连接成功！服务端版本: {version}")

# 断开连接
connections.disconnect("default")

运行脚本：

python test_milvus.py 

预期输出：

Milvus 连接成功！服务端版本: v2.4.4 

6.3 创建集合与向量插入示例

验证连接成功后，我们进一步演示 Milvus 的核心操作------创建集合（Collection）、插入向量数据。创建脚本 test_milvus_insert.py：

from pymilvus import (
    connections,
    FieldSchema,
    CollectionSchema,
    DataType,
    Collection,
    utility,
)

# ============ 1. 连接 Milvus ============
connections.connect(host="localhost", port="19530")
print("已连接到 Milvus")

# ============ 2. 定义集合 Schema ============
# 字段定义
fields = [
    # 主键字段：自增整数 ID
    FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=True),
    # 向量字段：128 维浮点向量
    FieldSchema(name="embedding", dtype=DataType.FLOAT_VECTOR, dim=128),
    # 标量字段：文本描述
    FieldSchema(name="text", dtype=DataType.VARCHAR, max_length=512),
]

# 创建 Schema
schema = CollectionSchema(fields=fields, description="Milvus 测试集合")

# ============ 3. 创建集合 ============
collection_name = "demo_collection"

# 如果集合已存在则先删除
if utility.has_collection(collection_name):
    Collection(name=collection_name).drop()
    print(f"已删除旧集合: {collection_name}")

collection = Collection(name=collection_name, schema=schema)
print(f"集合 '{collection_name}' 创建成功")

# ============ 4. 插入数据 ============
import random

# 生成 10 条随机测试数据
num_entities = 10
dim = 128

# 随机生成向量数据
vectors = [[random.random() for _ in range(dim)] for _ in range(num_entities)]
# 生成文本描述
texts = [f"这是第 {i} 条测试文本" for i in range(num_entities)]

# 插入数据（id 字段设为 auto_id，不需要手动指定）
insert_result = collection.insert([vectors, texts])
print(f"成功插入 {len(insert_result.primary_keys)} 条数据")

# 刷新集合，确保数据写入（生产环境下 Milvus 会自动刷新）
collection.flush()
print(f"集合中当前实体数量: {collection.num_entities}")

# ============ 5. 创建索引 ============
index_params = {
    "index_type": "IVF_FLAT",   # 索引类型：倒排文件 + 暴力搜索
    "metric_type": "L2",        # 距离度量：欧氏距离
    "params": {"nlist": 128},   # 聚类中心数量
}

collection.create_index(field_name="embedding", index_params=index_params)
print("向量索引创建成功")

# ============ 6. 加载集合到内存 ============
collection.load()
print("集合已加载到内存")

# 清理
connections.disconnect("default")
print("操作完成，连接已断开")

运行：

python test_milvus_insert.py 

预期输出：

已连接到 Milvus
集合 'demo_collection' 创建成功
成功插入 10 条数据
集合中当前实体数量: 10
向量索引创建成功
集合已加载到内存
操作完成，连接已断开

6.4 向量相似度搜索示例

在上一步插入数据的基础上，执行向量相似度搜索。创建脚本 test_milvus_search.py：

import random
from pymilvus import connections, Collection

# ============ 1. 连接并加载集合 ============
connections.connect(host="localhost", port="19530")

collection = Collection("demo_collection")
collection.load()

# ============ 2. 构造查询向量 ============
dim = 128
# 随机生成一个查询向量（实际应用中由 Embedding 模型生成）
query_vector = [[random.random() for _ in range(dim)]]

# ============ 3. 执行相似度搜索 ============
search_params = {
    "metric_type": "L2",
    "params": {"nprobe": 10},  # 搜索时探查的聚类中心数
}

results = collection.search(
    data=query_vector,           # 查询向量
    anns_field="embedding",      # 搜索的向量字段
    param=search_params,
    limit=5,                     # 返回最相似的 Top 5
    output_fields=["text"],      # 同时返回文本字段
)

# ============ 4. 打印搜索结果 ============
print("=== 向量相似度搜索结果 ===\n")
for i, hits in enumerate(results):
    print(f"查询向量 {i + 1} 的搜索结果:")
    for rank, hit in enumerate(hits):
        print(f"  Top {rank + 1}: ID={hit.id}, "
              f"距离={hit.distance:.4f}, "
              f"文本=\"{hit.entity.get('text')}\"")

# ============ 5. 清理 ============
collection.release()
connections.disconnect("default")
print("\n搜索完成")

运行：

python test_milvus_search.py 

预期输出（向量和距离为随机值，具体数值会不同）：

=== 向量相似度搜索结果 ===

查询向量 1 的搜索结果:
  Top 1: ID=4567890123, 距离=12.3456, 文本="这是第 7 条测试文本"
  Top 2: ID=4567890120, 距离=13.0123, 文本="这是第 3 条测试文本"
  Top 3: ID=4567890125, 距离=13.4567, 文本="这是第 9 条测试文本"
  Top 4: ID=4567890119, 距离=13.8901, 文本="这是第 2 条测试文本"
  Top 5: ID=4567890121, 距离=14.2345, 文本="这是第 4 条测试文本"

搜索完成

---

七、验证 Redis 服务

7.1 安装 Python 客户端

pip install redis 

使用国内镜像源：

pip install redis -i https://pypi.tuna.tsinghua.edu.cn/simple 

7.2 连接测试

创建脚本 test_redis.py：

import redis

# 连接到 Redis（注意：docker-compose.yml 中设置了密码 1234）
client = redis.Redis(
    host="localhost",
    port=6379,
    password="1234",          # 与 docker-compose.yml 中 --requirepass 一致
    decode_responses=True,    # 自动将 bytes 解码为字符串
)

# 测试连接
print(f"Redis 连接状态: {'正常' if client.ping() else '异常'}")

# 写入数据
client.set("test_key", "Hello, Redis!")

# 读取数据
value = client.get("test_key")
print(f"Redis 读写测试: test_key = {value}")

# 设置带过期时间的键（10 秒后自动删除）
client.setex("temp_key", 10, "这条数据 10 秒后消失")
ttl = client.ttl("temp_key")
print(f"temp_key 剩余生存时间: {ttl} 秒")

# 清理测试数据
client.delete("test_key")
client.delete("temp_key")
print("测试数据已清理")

运行：

python test_redis.py 

预期输出：

Redis 连接状态: 正常
Redis 读写测试: test_key = Hello, Redis!
temp_key 剩余生存时间: 10 秒
测试数据已清理

常见错误 ：如果连接时报错 redis.exceptions.AuthenticationError，说明密码不正确。请检查 docker-compose.yml 中 --requirepass 的值是否与 Python 脚本中的 password 参数一致。

7.3 常用数据结构操作示例

Redis 支持丰富的数据结构，以下是在 AI 项目中常用的几种操作示例。创建脚本 test_redis_datatypes.py：

import redis
import json

client = redis.Redis(
    host="localhost",
    port=6379,
    password="1234",
    decode_responses=True,
)

# ========== 1. String：缓存 Embedding 结果 ==========
# 将向量查询结果缓存，设置 5 分钟过期
search_result = {
    "query": "什么是向量数据库？",
    "top_docs": ["文档A", "文档B", "文档C"],
    "scores": [0.95, 0.87, 0.82],
}
client.setex("cache:search:query_001", 300, json.dumps(search_result))
cached = json.loads(client.get("cache:search:query_001"))
print(f"缓存的搜索结果: {cached['top_docs']}")
print(f"缓存命中分数: {cached['scores']}\n")

# ========== 2. Hash：存储用户会话状态 ==========
session_id = "session:abc123"
client.hset(session_id, mapping={
    "user_id": "user_001",
    "model": "gpt-4",
    "message_count": "0",
    "created_at": "2024-01-01T00:00:00",
})
client.expire(session_id, 3600)  # 1 小时过期

# 递增消息计数
client.hincrby(session_id, "message_count", 1)
session = client.hgetall(session_id)
print(f"用户会话状态: {session}\n")

# ========== 3. List：简单的任务队列 ==========
queue_name = "queue:embedding_tasks"

# 推入 3 个嵌入计算任务
for i in range(3):
    client.rpush(queue_name, json.dumps({"task_id": i, "text": f"待计算文本 {i}"}))

# 模拟消费者取出任务
print("任务队列处理:")
while client.llen(queue_name) > 0:
    task = json.loads(client.lpop(queue_name))
    print(f"  处理任务: {task['task_id']} - {task['text']}")

# ========== 4. Sorted Set：排行榜 / 相似度排名 ==========
leaderboard = "ranking:similar_items"

# 添加物品及其相似度分数
items = [
    ("item_A", 0.95),
    ("item_B", 0.87),
    ("item_C", 0.92),
    ("item_D", 0.78),
    ("item_E", 0.89),
]
for item, score in items:
    client.zadd(leaderboard, {item: score})

# 获取 Top 3 最相似的物品（按分数降序）
top_items = client.zrevrange(leaderboard, 0, 2, withscores=True)
print(f"\nTop 3 相似物品:")
for item, score in top_items:
    print(f"  {item}: {score}")

# ========== 5. 清理所有测试数据 ==========
client.delete("cache:search:query_001", session_id, queue_name, leaderboard)
print("\n所有测试数据已清理")

运行：

python test_redis_datatypes.py 

预期输出：

缓存的搜索结果: ['文档A', '文档B', '文档C']
缓存命中分数: [0.95, 0.87, 0.82]

用户会话状态: {'user_id': 'user_001', 'model': 'gpt-4', 'message_count': '1', 'created_at': '2024-01-01T00:00:00'}

任务队列处理:
  处理任务: 0 - 待计算文本 0
  处理任务: 1 - 待计算文本 1
  处理任务: 2 - 待计算文本 2

Top 3 相似物品:
  item_A: 0.95
  item_C: 0.92
  item_E: 0.89

所有测试数据已清理

---

八、停止与清理服务

当不再需要使用 Milvus 和 Redis 时，可以停止并清理服务。

停止服务（保留数据）：

docker compose down 

该命令会停止并删除所有容器和网络，但本地 volumes/ 目录下的数据仍然保留。下次执行 docker compose up -d 时会重新创建容器并加载已有数据。

停止服务并删除数据（完全清理）：

docker compose down -v 

加上 -v 参数会同时删除 Docker 挂载的卷。但注意，由于我们使用的是 bind mount（直接挂载本地目录），-v 不会删除本地 volumes/ 目录。如需彻底清理：

# 先停止容器 docker compose down  # 删除本地数据目录 # Windows rmdir /s /q C:\milvus_redis\volumes  # macOS / Linux rm -rf ~/milvus_redis/volumes 

仅暂停服务（不删除容器）：

docker compose stop 

暂停后可通过 docker compose start 恢复运行，无需重新创建容器。

常用命令速查：

# 启动所有服务（后台运行）
docker compose up -d

# 停止所有服务
docker compose stop

# 停止并删除容器和网络
docker compose down

# 查看运行中的容器
docker ps

# 查看所有容器（包括已停止的）
docker ps -a

# 进入某个容器内部（调试用）
docker exec -it milvus-redis bash

# 查看容器资源占用
docker stats

---

九、常见问题及解决方法

问题 1：端口被占用

错误表现 ：执行 docker compose up -d 时报错 Bind for 0.0.0.0:19530 failed: port is already allocated

解决方案：

方案 A：找出并关闭占用端口的进程

# Windows
netstat -ano | findstr "19530"
# 找到 PID 后，执行 taskkill /PID <PID> /F

# macOS / Linux
lsof -i :19530
# 找到 PID 后，执行 kill -9 <PID>

方案 B：修改 docker-compose.yml 中的端口映射

ports:
  - "19531:19530"   # 将宿主机端口改为 19531

修改后，Python 脚本中连接时也需要使用新端口：

connections.connect(host="localhost", port="19531") 

问题 2：镜像拉取失败或超时

错误表现 ：Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeout

解决方案：

1. 1.确认网络连接正常
2. 2.配置 Docker 镜像加速器（参见 3.2 节配置镜像加速器部分）
3. 3.尝试手动逐个拉取镜像：

docker pull quay.io/coreos/etcd:v3.5.5
docker pull minio/minio:RELEASE.2023-03-20T20-16-18Z
docker pull milvusdb/milvus:v2.4.4
docker pull redis:7.2

拉取完成后再执行 docker compose up -d。

问题 3：Apple Silicon（M 系列芯片）兼容性问题

错误表现 ：容器启动后立即退出，日志中出现 exec format error 或 WARNING: The requested image's platform (linux/amd64) does not match

解决方案：

docker-compose.yml 中使用的镜像版本均支持多架构（包括 ARM64），一般不会有此问题。如遇到个别镜像不兼容的情况：

1. 1.打开 Docker Desktop → Settings → General
2. 2.确保 Use Rosetta for x86_64/amd64 emulation on Apple Silicon 选项已开启（Docker Desktop 4.25+）
3. 3.重启 Docker Desktop 后重新执行 docker compose up -d

问题 4：Milvus 连接失败

错误表现 ：Python 脚本报错 pymilvus.exceptions.MilvusException: <MilvusException: (code=2, message=Fail connecting to server on localhost:19530)>

排查步骤：

# 1. 检查容器是否在运行
docker ps | grep milvus-standalone

# 2. 如果容器不在运行，查看退出原因
docker logs milvus-standalone

# 3. 检查 Milvus 健康状态
curl http://localhost:9091/healthz

# 4. 等待 Milvus 完全启动（首次启动可能需要 30-60 秒）
# 如果 healthz 返回 "OK"，表示服务就绪

注意：Milvus 依赖 Etcd 和 MinIO，如果后两者未就绪，Milvus 会等待并重试。首次启动时请耐心等待约 1 分钟。

问题 5：Redis 认证失败

错误表现 ：redis.exceptions.AuthenticationError: NOAUTH Authentication required.

解决方案：确保 Python 脚本中指定了密码参数：

client = redis.Redis(
    host="localhost",
    port=6379,
    password="1234",  # 必须与 docker-compose.yml 中 --requirepass 的值一致
    decode_responses=True,
)

问题 6：数据未持久化

错误表现：重启容器后，之前写入的数据丢失。

排查步骤：

1. 1.检查 docker-compose.yml 中 Redis 是否配置了 --appendonly yes
2. 2.检查 volumes 挂载路径是否正确：./volumes/redis:/data
3. 3.确保宿主机的 volumes/ 目录有写入权限：

# macOS / Linux
ls -la volumes/
# 确保目录权限为 drwxr-xr-x 或更开放

问题 7：Docker Desktop 启动失败（Windows）

错误表现：Docker Desktop 启动后报错或无法正常运行。

解决方案：

1. 1.确认 WSL2 已正确安装：

   wsl --status

2. 2.确认虚拟化已开启（在 BIOS 中启用 Intel VT-x 或 AMD-V）

3. 3.尝试重置 WSL2：

wsl --shutdown
wsl --unregister docker-desktop
wsl --unregister docker-desktop-data

然后重新启动 Docker Desktop。

---

十、参考资源

资源	地址
Milvus 官方文档	https://milvus.io/docs
Milvus GitHub 仓库	https://github.com/milvus-io/milvus
Milvus Python SDK (pymilvus) 文档	https://milvus.io/api-reference/pymilvus/v2.4.x/About.md
Redis 官方文档	https://redis.io/docs
Redis Python 客户端文档	https://redis-py.readthedocs.io
Docker Desktop 官方文档	https://docs.docker.com/desktop
Docker Compose 文档	https://docs.docker.com/compose
Milvus Docker 镜像（Docker Hub）	https://hub.docker.com/r/milvusdb/milvus
Redis Docker 镜像（Docker Hub）	https://hub.docker.com/_/redis
Etcd 官方文档	https://etcd.io/docs
MinIO 官方文档	https://min.io/docs

---

附录：项目目录结构总览

部署完成后，你的项目目录结构应如下所示：

C:\milvus_redis\               # 或 ~/milvus_redis/
│
├── docker-compose.yml          # Docker Compose 编排文件
│
├── test_milvus.py              # Milvus 连接测试脚本
├── test_milvus_insert.py       # Milvus 插入数据示例
├── test_milvus_search.py       # Milvus 向量搜索示例
├── test_redis.py               # Redis 连接测试脚本
├── test_redis_datatypes.py     # Redis 数据结构操作示例
│
└── volumes/                    # 数据持久化目录（自动生成）
    ├── etcd/                   # Etcd 数据
    ├── minio/                  # MinIO 数据
    ├── milvus/                 # Milvus 数据
    └── redis/                  # Redis 数据

---

最后提醒 ：本文档中使用的 Milvus 版本为 v2.4.4、Redis 版本为 7.2。由于这些开源项目更新较快，建议在实际部署时参考官方文档确认最新稳定版本。如需升级版本，只需修改 docker-compose.yml 中的镜像标签（tag），然后重新执行 docker compose up -d 即可自动拉取新版本镜像并重建容器。