AI微服务底座向导式安装实战：Ollama+Qdrant+Dify+网关一键部署

我一直觉得，AI 应用开发里最劝退人的环节不是写代码，而是搭环境。你想做一个带知识库问答的智能体，背后要跑模型推理、向量检索、应用编排，再来个 API 网关做统一入口，这一整套微服务底座手动配下来，光依赖冲突和版本不兼容就能耗掉一整个下午。所以我一直琢磨，能不能把这套底座做成向导式安装，让一个零基础的人跟着界面点几下，10 分钟就能从裸机跑起一套能用的 AI 微服务底座。

这篇文章要聊的，就是我用向导式安装思路落地的一套 AI 微服务底座。它把 Ollama（模型推理）、Qdrant（向量数据库）、Dify（应用编排）和 API 网关全部编排进 Docker Compose，再通过一个 Web 安装向导自动完成环境检测、参数配置、配置生成和一键部署。整个过程不需要手写 docker-compose，不需要记一堆命令，打开浏览器按提示走完六个步骤就能看到服务健康检查全部通过。适合三类人：刚入门想本地跑 AI 应用的开发者、要给团队快速搭内部 AI 服务的运维或后端同学，以及想在公司内网私有化部署一套 AI 中台的技术负责人。

1. 项目整体设计与思路拆解

1.1 先拆清楚什么是“AI 微服务底座”

很多朋友一听到“微服务底座”就以为是 K8s、Istio 那一套，其实在 AI 应用这个场景里，底座的核心是四件事：模型推理、知识存储、应用编排、统一入口。模型推理负责跑大模型，知识存储负责把文档向量化并支持检索，应用编排负责把“模型+知识+工具调用”串成业务能力，统一入口负责让外部系统以标准 API 的方式调用整套能力。

打个比方，这就像开一家餐厅。后厨是模型推理服务，负责出菜；冰箱和仓库是向量数据库，负责存食材（知识）；前台点单系统是应用编排层，负责把顾客需求转成后厨能执行的订单；而门迎就是 API 网关，所有客人从同一个门进来。没有这套底座，你的 AI 应用就是一个个孤岛，模型只能聊天、知识库只能检索，无法组合成真正可用的业务系统。

底座这个词的重点在于“可复用”。搭建一次之后，上层任何 AI 应用都可以通过 API 接入，不用再重新部署模型和向量库。这也是我坚持微服务拆分而不是做成单体应用的原因——模型推理要 GPU，向量库要内存，编排层要 CPU，三者资源需求完全不同，拆开才能独立扩缩容。

1.2 为什么必须做向导式安装

我最早做这套底座的时候是纯手动部署，踩过的坑那叫一个多。Ollama 版本要 0.1.3x 以上，Qdrant 的镜像 tag 要和 client 版本匹配，Dify 依赖 PostgreSQL 和 Redis 两个中间件，网关的 upstream 配置写错一个斜杠就 502。这套东西我闭着眼睛能配，但换一个人来，光看部署文档就得看一个小时，中间还要理解一堆“为什么要这样”的背景知识。

向导式安装的本质，是把这些踩坑经验固化成交互流程。用户不需要知道 Qdrant 为什么要用 volume 挂载数据，不需要理解 Dify 的 init 容器为什么要等 PostgreSQL 就绪，只需要在界面里选择“我要装知识库问答”，向导就会自动生成正确的配置组合。这样做的好处有三个：

• 降低门槛。用户只面对业务层面的选择（模型选哪个、知识库放哪、端口多少），基础设施层的事交给向导处理。
• 消除不确定性。手动部署最大的问题是“配置对不对没人知道”，向导在生成配置后可以做预检，提前发现端口冲突、资源不足、镜像拉不到等问题。
• 可复制。相同配置可以在多台机器上重复部署，非常适合给团队或者客户批量交付。

我见过太多“照着教程一步步配，最后跑不起来”的情况，问题几乎都出在环境差异上：有人 Docker 是 19.03 的老版本，有人内存只有 8G，有人 GPU 驱动没装。向导式安装把这些差异全部变成启动前的检测项，不合格直接提示，而不是等你跑到第五步才报错。

1.3 技术选型与取舍背后的考量

选型永远是架构设计里最纠结的部分。我最终定的组合是 Ollama + Qdrant + Dify + APISIX，安装向导用 FastAPI + React 实现。这套组合并不是性能最强的，但它是落地效率最高的。选型时我做了几组对比：

我重点说一下为什么没上 K8s。很多朋友一听微服务就说“那你得上 K8s 啊”，但在这套底座的落地场景里，大多数是单机或者三五台机器的小集群，用 K8s 等于杀鸡用牛刀——光装集群就要半天，还要维护 etcd、kubelet 这些组件。Docker Compose 用声明式 YAML 描述六个服务之间的关系，一条命令拉起，对于 10 分钟跑起来的诉求来说是最优解。如果你后续真的要扩到多节点，Compose 配置也能比较平滑地迁移到 Docker Swarm 甚至 K8s。

2. 核心细节解析与实操要点

2.1 底座包含的组件与职责划分

这套底座一共编排了七个容器，每个容器干一件事，职责边界非常清晰。首先是 Ollama 容器，负责模型加载和推理，默认监听 11434 端口。它会把模型文件存放在挂载目录里，保证容器重建后模型不丢。其次是 Qdrant 容器，负责向量存储和相似度检索，监听 6333（API）和 6334（gRPC），数据目录同样用 volume 持久化。

然后是 Dify 容器组，严格来说它不是一个容器，而是 api、worker 和 web 三个容器的组合。api 处理 REST API 请求，worker 消费异步任务（比如文档解析、索引构建），web 是用户操作界面。Dify 依赖 PostgreSQL 存储业务数据、Redis 做缓存和队列，所以底座里还包含了这两个中间件容器。最后是 APISIX 网关容器，监听 80 端口，把所有内部服务统一暴露出去，配上密钥校验和速率限制。

这里有个容易忽略的点：Ollama 默认只监听容器内部的 11434，要让 Dify 或者其他服务访问它的模型能力，需要在 docker-compose 里把 Ollama 加入 Dify 所在的网络，同时把宿主机的 11434 端口映射出来，方便直接用 curl 调试。我在向导里默认做了双向映射——既加入内部网络供服务间调用，也暴露宿主机端口供开发者直连。

资源占用方面，Ollama 跑 7B 量级模型大概需要 6~8GB 内存，Qdrant 空载大约占 200MB，Dify 全家桶加中间件合计 2GB 左右。所以整套路底座的最低配置是 12GB 内存，建议 16GB 起步。磁盘方面，底座程序本身只占 3GB（镜像），但模型文件才是大头——7B 模型量化后大概 4.7GB，14B 模型接近 9GB，还要预留知识库向量化的存储空间，所以建议预留 50GB 以上。

2.2 向导式安装的流程设计

这一版向导我设计了六个步骤，每一步只让用户做一个决定，避免信息过载。第一步是环境检测，向导自动检查 Docker 版本、Compose 插件、CPU 核数、内存大小、磁盘剩余空间和 GPU 是否可用，不合格的项会标红并给出修复建议。第二步是组件选择，用户按需勾选要安装的模块，默认全选，但可以去掉 API 网关或者只装模型推理。

第三步是模型选择。这一步我把 Ollama 官方模型库里适合中文场景的几个模型列成下拉框，用户选一个，比如 qwen2.5:7b，向导会在生成配置时写入自动拉取和启动模型的命令。第四步是存储配置，用户指定模型目录、向量库数据目录和 Dify 数据目录的宿主机路径。这里我加了强校验——如果路径已存在且非空，会提示是否复用，避免误覆盖。

第五步是网络配置，包括对外服务端口、API 网关的密钥和是否启用 HTTPS。最后一步是预览与部署，向导把前面所有选项渲染成完整的 docker-compose.yml，展示给用户确认，点“开始部署”后执行拉镜像、起容器、初始化数据库、拉模型，并在进度条下方实时滚动日志。整个过程部署完成后，向导会做一次全链路健康检查，返回每个服务的 HTTP 状态码和响应时间。

这套流程设计最核心的一个细节是“状态可恢复”。如果部署到一半失败（比如拉镜像超时），重启向导时会先读取已生成的 compose 文件，跳过已经成功的步骤，只重试失败的动作，而不是让你从第一步重新开始。这个容错机制我后面还会细讲。

2.3 部署前的资源评估与前置检查

别觉得向导能检测就万事大吉，有些问题机器本身检测不出来，需要你自己先想清楚。比如 CPU 指令集，Ollama 的某些模型在新版本里要求 CPU 支持 AVX2，五年前的旧机器可能就带不动。再比如 GPU，如果你的机器有 NVIDIA 显卡，必须先装好驱动和 NVIDIA Container Toolkit，向导检测到 GPU 设备但跑不了推理，原因基本都在这里。

内存方面有一个很容易被忽视的点：Ollama 除了要加载模型权重的内存，还有上下文窗口（context window）的额外开销。默认 2048 上下文时 7B 模型大约额外占 1GB，如果你在 Dify 里把上下文调到 8192，额外内存会涨到 4GB 以上。所以向导里环境检测的“内存合格线”我定在 16GB，最低 12GB 可以装但只能跑小模型。

磁盘检测也有讲究。我见过有人把模型目录放在系统盘，跑几天硬盘满了系统直接崩溃。向导会提醒模型目录和数据目录不要放在根分区，最好是独立的数据盘或挂载卷。检测逻辑里我加了一个“目录所在分区剩余空间”的检查，而不是只看当前目录的空闲空间，这两个值在跨分区挂载时差别很大。运行df -h 目录路径可以很方便地确认。

3. 实操过程与核心环节实现

3.1 环境准备：Docker 与基础依赖

在跑向导之前，需要先把基础的运行时环境准备好。我用的是 Ubuntu 22.04 服务器，内核版本 5.15，以下命令都是在这个环境验证过的。第一步安装 Docker Engine 和 Compose 插件，如果之前没装过 Docker，可以执行官方脚本一键安装：

curl -fsSL https://get.docker.com | sh

装完确认版本，Docker Engine 需要在 24.0 以上，因为老版本对 Compose v2 的支持不完整。确认命令：

docker --version docker compose version

我实测下来 Docker 27.x 一切正常，Compose v2.24 以上功能完整。然后建议把当前用户加入 docker 组，省得每次敲sudo docker：

sudo usermod -aG docker $USER newgrp docker

这里有一个重要提醒：如果服务器在国内，Docker Hub 的镜像拉取速度经常让人崩溃。向导里面有配置镜像加速的选项，也可以在/etc/docker/daemon.json里手动指定加速源并重启 Docker。配置完可以用docker info查看 Registry Mirrors 是否生效。镜像加速是合规操作，放心用。

GPU 支持方面，如果你的服务器有 NVIDIA 显卡，需要额外安装 NVIDIA Container Toolkit。装好后在向导的环境检测页面能看到 GPU 型号和显存大小。如果看不到，大概率是 toolkit 没装或者驱动版本太旧。

3.2 获取安装包并启动向导

环境就绪后，把向导项目包拷贝到服务器上。我这里为了演示方便，直接把向导做成一个 Docker 镜像，启动后访问http://服务器IP:8080就能打开安装界面：

docker run -d --name ai-base-installer \ -p 8080:80 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /opt/ai-base:/data \ registry.example.com/ai-base-installer:latest

注意两个挂载：/var/run/docker.sock是让向导有权限调用宿主机 Docker 来创建容器，这是实现“一键部署”的关键；/opt/ai-base是向导的数据目录，生成的配置、日志和预检报告都存在这里。第一次启动后打开浏览器进入向导首页，界面会先展示一个“环境兼容性总览”，绿色的项越多，后面的部署越顺畅。

启动向导之前建议先做个干净环境检查，把 80、443、8080、11434 这些端口能关的关掉，避免部署阶段端口冲突。如果 80 被 Nginx 占了，在向导的“网络配置”步骤里改成 8081 就行。

3.3 向导逐步配置实操

我按实际走一遍流程，让大家知道每一步怎么填。第一步环境检测，正常情况下所有项目都是绿色。如果 Docker 版本这一项标红，向导会给出两个按钮：一个是“查看修复命令”，一个是“重新检测”。修复命令其实就是官方安装脚本，复制执行后回来点重新检测就行。

第二步组件选择，这里默认全选。我建议首次体验全选，跑通之后再考虑裁剪。如果只要模型推理和知识库，可以取消 Dify 组件，这样能省掉 PostgreSQL 和 Redis 两个容器，对低配机器来说很友好。

第三步模型选择，下拉框里列出几个常见模型及其大小：qwen2.5:7b（约 4.7GB）、qwen2.5:14b（约 9GB）、llama3.1:8b（约 4.7GB）、bge-m3（约 1.2GB，纯向量化模型不做对话）。对话场景我推荐 qwen2.5:7b，中文表现好，显存 6GB 就能跑。如果机器只有 CPU，选 qwen2.5:7b 的 q4_K_M 量化版也能跑，就是生成速度慢一些，大概每秒 3~5 个 token。

第四步存储配置，向导会根据当前磁盘情况给出默认路径/opt/ai-base/models、/opt/ai-base/qdrant_storage、/opt/ai-base/dify_data。我的建议是这些目录不要放在根分区，而是放到/data这种独立挂载点下面。填完点“检查路径”，向导会验证目录是否可写、空间是否充足。

第五步网络配置，API 网关端口默认 80，模型服务端口可选暴露 11434，Dify Web 界面端口 3000，管理后台端口 6333。这里我会把 API 网关的访问密钥设成一串随机密钥，向导会自动生成，你也可以手动改成好记的。HTTPS 选项首次安装先不勾，等后面反代加证书。

第六步预览配置。这一页会把生成的 docker-compose.yml 完整展示出来，你可以看到 Ollama、Qdrant、Dify、APISIX 等服务的定义。确认没问题后点“开始部署”，进度条开始走，右侧日志窗口会实时滚动显示拉镜像、创建网络、启动容器的过程。整个等待时间取决于网络速度，镜像总共 3GB 左右，正常网络下 5~10 分钟能拉完。

3.4 生成配置的关键内容讲解

部署完成后，向导会在数据目录下生成完整的部署产物，核心文件就是docker-compose.yml。我截取几个关键服务配置说明一下，帮你理解向导到底帮你做了什么。

模型服务这一段的重点是资源的reservation和limits。我设置了 GPU 保留和内存上限，避免 Ollama 把宿主机内存吃满：

ollama: image: ollama/ollama:latest container_name: ai-ollama restart: always ports: - "11434:11434" volumes: - /opt/ai-base/models:/root/.ollama deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] healthcheck: test: ["CMD", "ollama", "list"] interval: 30s timeout: 10s retries: 3

Dify 的编排是这套底座里最复杂的，因为它依赖 PostgreSQL 和 Redis，而且 api 容器要等数据库就绪后才启动。我用了一个 init 容器配合脚本来处理依赖关系：

dify-api: image: langgenius/dify-api:0.6.14 container_name: ai-dify-api depends_on: postgres: condition: service_healthy redis: condition: service_healthy environment: DB_HOST: postgres DB_PORT: 5432 DB_USERNAME: dify DB_PASSWORD: ${DIFY_DB_PASSWORD} DB_DATABASE: dify REDIS_HOST: redis REDIS_PORT: 6379 MODE: api volumes: - /opt/ai-base/dify_data:/app/api/storage

这里有个细节：Dify 在首次启动时会自动执行数据库迁移，需要 1~2 分钟，中间如果 API 报 503 是正常的。向导的健康检查模块会等 postgres 的 healthcheck 变成 healthy 后再检查 Dify，避免误报。

APISIX 网关的配置则是把三个服务映射到统一入口，并开启 key-auth 插件：

apisix: image: apache/apisix:3.9.0-centos container_name: ai-apisix ports: - "80:9080" volumes: - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro environment: APISIX_STAND_ALONE: "true"

向导生成的这套配置是经过我反复验证的，直接复制到任何一台相同环境的机器上也能跑。这也是向导式安装的另一个价值：它产出的不是一次性脚本，而是一份可审计、可版本管理的部署资产。

3.5 验证与跑通第一个应用

部署完别急着开心，先做一轮端到端验证，确保每个环节都真的通了。第一步检查容器状态，确认所有容器都在运行且没有反复重启：

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

正常情况下应该看到七个容器状态都是 Up。然后验证模型服务，向 Ollama 发一个请求确认模型已加载并可以对话：

curl http://localhost:11434/api/generate -d '{ "model": "qwen2.5:7b", "prompt": "你好，用一句话介绍你自己", "stream": false }'

模型如果有响应，说明推理链路通了。接着打开 Dify Web 界面（默认 3000 端口），用向导打印的初始管理员账号登录，创建一个应用，选择“聊天助手”，模型提供商选 Ollama，就能直接对话。最后做一个更有代表性的验证——创建一个“知识库问答”应用，上传一份 PDF 文档，等索引构建完成后提问，确认向量检索链路也是通的。

我还习惯用 APISIX 网关注册一个 API 再做一次调用，确认网关转发正常。你在 Dify 应用页面点“API 访问”，复制 API 密钥，然后调用网关地址即可：

curl -X POST http://localhost/v1/chat-messages \ -H "Authorization: Bearer app-xxxxx" \ -H "Content-Type: application/json" \ -d '{"query":"你好","inputs":{},"response_mode":"blocking"}'

如果返回正常回复，那这套 AI 微服务底座就算真正跑起来了，上层应用可以开始接入了。

4. 常见问题与排查技巧实录

4.1 Docker 镜像拉取慢或超时

这是被问得最多的一个问题，现象是部署进度卡在拉镜像阶段，日志显示EOF或者timeout。解决思路很直接——配置镜像加速器。在/etc/docker/daemon.json中配置加速源后重启 Docker，再重新部署。注意改完 daemon.json 要执行systemctl daemon-reload && systemctl restart docker，否则不生效。

如果你使用向导时环境检测提示 Docker 版本低于 24.0，我建议直接升级，不要心存侥幸。老版本 Docker 对 Compose v2 的支持是半残的，很可能出现docker compose命令不存在的情况。升级方式就是重跑官方安装脚本，数据不会丢。

4.2 模型下载失败或速度极慢

Ollama 拉取模型是从官方源走的，网络状况不好时会下载失败。解决办法不使用 Ollama 的拉取命令，而是从国内模型社区手动下载模型文件，再放到模型目录里。具体做法是：

# 1. 在 ModelScope 下载 GGUF 格式的模型文件 # 2. 将文件放到 /opt/ai-base/models 对应目录 # 3. 重启 Ollama 容器让模型注册生效 docker restart ai-ollama

这里要注意文件名和目录结构必须符合 Ollama 的命名规范，否则模型不会出现在列表里。最稳妥的方式是用 Ollama 创建 Modelfile 从本地文件构建模型：

FROM /path/to/qwen2.5-7b-instruct-q4_K_M.gguf

然后执行ollama create qwen2.5:7b -f Modelfile注册模型。这样能绕开所有网络问题，部署时间完全可控。

4.3 GPU 设备无法使用

如果部署向导使用的是 GPU 优化配置，但 Ollama 跑起来特别慢，或者日志里有 und GPU 的报错，先确认 NVIDIA Container Toolkit 是否安装。在宿主机执行：

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

如果命令执行失败，说明容器无法访问 GPU，需要重新安装 toolkit。如果命令成功，再检查 docker-compose 里 GPU 的reservation配置是否写对。注意 NVIDIA 驱动版本要跟 CUDA 兼容，建议驱动版本 535 以上。

4.4 Qdrant 连接被拒绝或检索超时

Dify 配置向量数据库时填了 Qdrant 地址但提示连接失败，通常是两个原因。第一是网络没通，确认 Qdrant 容器和 Dify 容器在同一个 Docker 网络里，用docker network inspect查看。第二是 Qdrant 还没完全启动，它的健康检查接口在/readyz，返回 200 才算就绪。在向导的部署日志里能看到 Qdrant 的启动状态，等它就绪再让 Dify 连接。

还有一种情况是 Dify 对 Qdrant 的 API 版本兼容问题，我的建议是把 Qdrant 镜像固定在 1.9 以上版本，旧版本的部分字段 Dify 读取会报错。升级 Qdrant 时注意备份qdrant_storage目录，避免数据丢失。

4.5 端口冲突导致服务无法启动

安装向导在部署前会做端口预检，但依然可能漏掉少数场景。比如有服务监听了 3000 端口，Dify Web 就起不来。排查方法很简单，先用ss -lntp | grep 端口号查看占用进程，然后在向导的“网络配置”步骤改端口映射即可。有一个经验之谈：Dify Web 我建议映射到一个冷门端口像 23000，因为 3000 端口在开发机上太容易被占用了。

部署遇到问题先不要慌，很多看起来复杂的问题都是小配置导致的。我把常见问题整理成了速查表，方便你对照处理：

4.6 向导中途失败后的恢复策略

我前面提到向导有“状态可恢复”机制，这里展开讲一下。向导会把每一步的执行结果记录到/opt/ai-base/installer/state.json，里面标记了每个步骤是 pending、completed 还是 failed。如果部署中途失败，重新打开向导页面会看到“继续上次部署”的按钮，点击后向导会跳过 completed 的步骤，只执行 pending 和 failed 的。这样就避免了重复拉取已经存在的镜像。

如果部署失败后你想彻底重置，向导首页有“重置环境”按钮，它会执行docker compose down -v并清空数据目录。注意这个操作会删除所有向量数据和模型文件，谨慎使用。我在按钮上加了两层确认，弹窗提示后果，需要手动输入“RESET”才能执行。

说实话，向导式安装这件事，做到后面我发现最难的倒不是技术，而是把你脑中那些“理所当然”的细节全部显性化。比如 Qdrant 要等就绪、Dify 迁移要 1 分钟、Ollama 模型名里不能有斜杠，这些经验不写进逻辑里，别人就会反复踩坑。把经验沉淀成交互流程，让后来者不踩坑，这才是我做这套东西最大的收获。

最后再分享一个实用的小技巧：第一次部署跑通之后，把/opt/ai-base目录整体备份一份，或者提交到 Git 私有仓库。以后再部署新环境，直接用这份配置改几个路径和密钥就能批量复制。如果你后面想把底座升级到多节点，这套 Compose 配置也可以作为 Docker Swarm 或 K8s 的起点。按照这个思路，祝你也早日跑起自己的 AI 底座。