前言

在上一篇文章中，我们完成了 WSL2 环境配置和 Milvus 向量数据库的部署。真正的企业级系统，不能只有业务代码和数据库，**“可观测性”和“性能优化”**同样是基础设施的重要拼图。

这一次，我们将继续完善项目架构，把 Redis 缓存、Prometheus 监控 和 Grafana 仪表盘 整合进 docker-compose.yml 中。

配置环境的过程从来都不是一帆风顺的——我在这次整合中遇到了网络冲突、容器权限错误、WSL2 端口转发失效等典型的工程问题。本文将完整记录这些问题的排查与修复全过程，希望能帮你少走弯路。

---

一、在 docker-compose 中追加新服务

我们目前使用的是 Milvus 官方提供的单机版 docker-compose.yml（v2.4.23），它包含 etcd、minio 和 standalone 三个服务。现在，我们需要打开该文件，在 services: 块的末尾追加以下三个组件：

YAML

  redis:
    container_name: lite-rag-redis
    image: redis/redis-stack-server:latest
    ports:
      - "6379:6379"
    volumes:
      - ./volumes/redis:/data
    networks:
      - milvus

  prometheus:
    container_name: lite-rag-prometheus
    image: prom/prometheus:latest
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
      - ./volumes/prometheus:/prometheus
    ports:
      - "9090:9090"
    networks:
      - milvus

  grafana:
    container_name: lite-rag-grafana
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    volumes:
      - ./volumes/grafana:/var/lib/grafana
    networks:
      - milvus

同时，为了防止后续的网络冲突，我们需要在**文件最末尾（与 services 平级）**显式定义自定义网络：

YAML

networks:
  milvus:
    name: milvus

💡 预先排雷：在启动服务之前，务必先在宿主机创建好数据卷所需的目录，避免 Docker 用 root 权限自动创建导致后续报错：

Bash

mkdir -p volumes/redis volumes/prometheus volumes/grafana

---

二、创建 Prometheus 配置文件

我们需要告诉 Prometheus 去哪里抓取监控指标。新建并编辑配置文件 monitoring/prometheus.yml：

YAML

global:
  scrape_interval: 15s

scrape_configs:
  # 抓取后续要编写的 FastAPI 应用指标
  - job_name: 'fastapi'
    static_configs:
      - targets: ['host.docker.internal:8000']
      
  # 抓取 Milvus 数据库指标
  - job_name: 'milvus'
    static_configs:
      - targets: ['milvus-standalone:9091']

配置说明：host.docker.internal 是 Docker 提供的一个特殊 DNS 域名，用于从容器内部访问宿主机的网络。因为后续我们的 FastAPI 应用将直接运行在宿主机的 8000 端口（方便打断点调试），所以这里配置为指向宿主机。

---

三、踩坑实录：网络与权限问题排查

准备好配置后，我满怀信心地执行了 docker compose up -d，结果迎面撞上两个经典报错。

🚨 坑一：网络冲突问题

报错现象：

Plaintext

service "grafana" refers to undefined network milvus: invalid compose project

原因分析：

之前启动官方编排文件时，Docker Compose 已经自动在后台创建了一个带默认项目前缀的 milvus 网络。现在我们手动在文件末尾显式定义了 networks:，导致新旧网络配置发生了冲突。

解决方案：

清理旧网络并重新启动。

Bash

# 1. 停止所有容器
docker compose down
# 2. 删除冲突的网络（忽略不存在的报错）
docker network rm milvus 2>/dev/null || echo "网络已不存在"
# 3. 重新启动
docker compose up -d

🚨 坑二：挂载目录权限被拒绝

报错现象：

容器虽然启动了，但浏览器无法访问 Prometheus 和 Grafana。查看日志发现：

• Prometheus: open /prometheus/queries.active: permission denied

• Grafana: GF_PATHS_DATA='/var/lib/grafana' is not writable

原因分析：

我们在宿主机创建的 volumes/ 目录属于当前用户（甚至有可能是之前误用 sudo 创建的 root 归属）。而容器内的服务出于安全考虑，是以非特权用户运行的（Prometheus 使用 nobody，Grafana 使用 UID 472），因此没有权限向宿主机目录写入数据。

解决方案：

在开发环境下，最快的方法是赋予目录全局读写权限。

Bash

# 删除可能被 root 锁定的旧目录
sudo rm -rf volumes/prometheus volumes/grafana
# 重新以当前普通用户身份创建
mkdir -p volumes/prometheus volumes/grafana
# 设置 777 权限（允许任意用户读写）
chmod 777 volumes/prometheus volumes/grafana
# 重新启动这两个异常的服务
docker compose restart prometheus grafana

⚠️ 生产环境警告：开发阶段用 chmod 777 没问题，但在生产环境中，应通过 Docker 的 user: "1000:1000" 指令或在宿主机设置 chown 472:472 来进行严格的权限控制。

---

四、服务整体验证

执行 docker compose ps，此时应该看到 6 个服务全部处于 Up 状态（Milvus 组件会带有 (healthy) 标识）。

容器名	服务组件	宿主机端口	验证方式
milvus-standalone	Milvus 主服务	19530, 9091	Python 客户端连接验证
milvus-minio	MinIO	9000, 9001	浏览器访问或 curl 健康端点
milvus-etcd	etcd	2379-2380	间接通过 Milvus 状态验证
lite-rag-redis	Redis	6379	docker exec -it lite-rag-redis redis-cli ping (应返回 PONG)
lite-rag-prometheus	Prometheus	9090	浏览器访问 http://localhost:9090
lite-rag-grafana	Grafana	3000	浏览器访问 http://localhost:3000

💡 附加坑位：WSL2 localhost 转发失效

如果上述端口在 Linux 终端用 curl 测试正常，但 Windows 浏览器却无法通过 localhost:9090 打开页面，这通常是 WSL2 的端口转发机制卡死了。

解决办法：

打开 Windows PowerShell（管理员），执行以下命令彻底重启 WSL，然后重新启动 Docker 容器即可：

PowerShell

wsl --shutdown

(或者直接通过 ip addr show eth0 获取 WSL2 的真实 IP 地址并在浏览器中访问。)

---

五、最终状态复测：Milvus 连通性

基础设施就绪后，我们再次通过 Python 客户端确认核心数据库的状态。

Python

from pymilvus import connections, utility

connections.connect(host='localhost', port='19530')
print(f"✅ 连接成功！Milvus 版本: {utility.get_server_version()}")
print(f"📦 所有集合: {utility.list_collections()}")

预期输出：

Plaintext

✅ 连接成功！Milvus 版本: v2.4.23
📦 所有集合: []

📌 注意事项：如果你看网上老教程用 curl localhost:19530/health 来测试 Milvus，大概率会收到 404 报错。这是因为 v2.4.x 版本已更改了该 HTTP 端点，直接用 Python SDK 测试才是最准的。

---

六、踩坑清单速览

为你总结本次部署的核心排雷清单：

现象 / 报错	根本原因	一针见血的解决方案
undefined network milvus	Compose 中新旧网络配置冲突	先 docker network rm milvus 再 up
Prometheus/Grafana 频繁重启	宿主机数据卷挂载目录权限不足	对 volumes 子目录执行 chmod 777
Windows 浏览器无法访问页面	WSL2 的 localhost 网络转发崩溃	PowerShell 执行 wsl --shutdown 重启子系统
镜像拉取超时或卡住	Docker Hub 国内连接被阻断	配置阿里云/DaoCloud 等国内镜像源加速
/health 端点返回 404	Milvus 高版本移除了该默认端点	使用 PyMilvus 客户端进行代码连接测试

---

七、下一步计划

至此，我们的项目已经拥有了一个包含缓存、存储和可观测性的企业级微服务基础设施。地基打完，接下来就要开始盖楼了！

下一篇文章，我们将正式进入 RAG 系统的核心业务开发阶段：

1. 配置 Python 虚拟环境与 PyTorch（GPU 版）。

2. 下载本地化的 BGE Embedding 模型并封装为 Python 模块。

3. 编写文档解析与向量化入库脚本。

4. 设计 Milvus Collection Schema，实现数据的初次灌入。

完整的项目代码后续我会同步到 GitHub，欢迎持续关注。

本文是【从0到1搭建企业级RAG系统】系列的第二篇，如果你在实践过程中遇到任何环境问题，欢迎在评论区留言交流！