封面图：Docker Compose 编排本地 AI 服务环境
| 文档类型 | 网站发布教程 + SEO 文档 |
| 适用对象 | AI 工具站编辑、独立开发者、内容创作者、运维新手 |
| 核心场景 | Ollama + Open WebUI、n8n、Dify、LocalAI、Flowise、数据库与反向代理 |
| 建议发布分类 | 保姆级教程 / 安装部署教程 / 自动化工作流 |
标题
- Docker Compose 搭建 AI 服务环境教程：新手也能一键部署本地 AI 工具
- 从零搭建 AI 服务环境：用 Docker Compose 部署 Ollama、Open WebUI、n8n、Dify
- 不用反复装环境！Docker Compose 一次管理所有 AI 工具服务
- 本地 AI 工具部署保姆级教程：Docker Compose 从入门到可用
文章摘要
想在一台电脑或 Linux 服务器上同时运行 Ollama、Open WebUI、n8n、Dify、LocalAI、Flowise 等 AI 工具，最容易遇到的问题不是模型不会用，而是端口冲突、依赖混乱、数据丢失和升级困难。Docker Compose 的价值，就是把多个容器服务写进一个 compose.yaml 文件，用一组命令统一启动、停止、升级、查看日志和备份。
这篇教程从 Docker Compose 的安装、目录结构、compose.yaml 写法讲起，逐步演示如何搭建本地 AI 服务环境，并给出适合新手的排错树、备份方案和安全建议。
一、为什么 AI 工具部署更适合用 Docker Compose？
单个 AI 工具可以用 docker run 启动，但一旦涉及 WebUI、模型服务、数据库、缓存、向量库、反向代理、HTTPS，就会变成多服务协作。Docker Compose 正是为“多容器应用”设计的：用 YAML 文件定义 services、networks、volumes、environment 等配置，然后通过 docker compose up -d 统一启动。
| 方式 | 适合场景 | 优点 | 缺点 |
| 直接安装到系统 | 只装一个简单工具 | 容易理解，少一层容器概念 | 污染系统环境，迁移和重装麻烦 |
| docker run | 临时测试单个服务 | 命令直观，启动快 | 参数一多就难维护，无法优雅管理多服务 |
| Docker Compose | AI 服务栈、自托管平台、数据库联动 | 配置可复用，方便升级、备份、迁移 | 需要学习 compose.yaml 基础写法 |
| Kubernetes | 企业级集群和弹性扩缩容 | 高可用、可扩展 | 新手成本高，不适合入门阶段 |
新手建议：本地电脑或一台 VPS/服务器，优先 Docker Compose；只有当服务规模变大、需要弹性伸缩和多节点调度时，再考虑 Kubernetes。
二、部署前准备：电脑、系统与软件要求
Docker 官方文档说明，Docker Desktop 会同时包含 Docker Engine、Docker CLI 和 Docker Compose，是 Windows、macOS 和桌面 Linux 用户最省事的安装方式；Linux 服务器则通常安装 Docker Engine 后，再安装 Docker Compose plugin。
| 环境 | 推荐配置 | 说明 |
| Windows 10/11 | Docker Desktop + WSL2 | 适合本地学习。大体量模型建议把项目放在 Linux 文件系统中，避免挂载性能问题。 |
| macOS | Docker Desktop | Apple Silicon 可运行多数轻量 AI 服务，但 NVIDIA GPU 加速不适用。 |
| Ubuntu/Debian 服务器 | Docker Engine + compose plugin | 生产和长期自托管首选。 |
| NVIDIA GPU 服务器 | Docker Engine + NVIDIA Container Toolkit | 用于 Ollama、LocalAI、vLLM、ComfyUI 等需要 GPU 的场景。 |
| 最低建议 | 2 核 CPU / 4GB 内存 / 30GB 磁盘 | 能跑轻量 Web 服务；大模型和 Dify 等平台建议更高配置。 |
三、安装 Docker Compose 并验证
1. Windows / macOS：安装 Docker Desktop
1. 访问 Docker 官网，下载对应系统的 Docker Desktop。
2. Windows 用户按提示启用 WSL2；安装完成后重启电脑。
3. 打开终端，执行 docker –version 和 docker compose version。
4. 能看到版本号，说明 Docker 和 Compose 都已就绪。
| docker –version docker compose version docker info |
2. Linux 服务器：安装 Compose 插件
如果已经安装 Docker Engine，可以使用发行版软件源安装 Compose plugin。Docker 官方 Linux 插件文档给出的 Ubuntu/Debian 命令如下：
| sudo apt-get update sudo apt-get install docker-compose-plugin docker compose version |
注意：现在推荐使用 docker compose 命令；老版本 docker-compose 属于 standalone legacy 路线，不建议新项目优先使用。
四、先看懂 compose.yaml：新手必须掌握的 8 个字段
Compose 文件建议命名为 compose.yaml 或 docker-compose.yml。新项目优先使用 compose.yaml。下面是 AI 服务部署最常用的字段：
| 字段 | 作用 | AI 部署中的常见用法 |
| services | 定义容器服务 | open-webui、ollama、postgres、redis、n8n 等 |
| image | 指定镜像 | ghcr.io/open-webui/open-webui:main、ollama/ollama 等 |
| ports | 端口映射 | 3000:8080、11434:11434、5678:5678 |
| volumes | 持久化数据 | 模型、数据库、上传文件、配置目录 |
| environment | 环境变量 | API Key、数据库连接、服务地址 |
| env_file | 加载 .env 文件 | 统一管理密码和开关配置 |
| depends_on | 启动顺序依赖 | 让 Web 服务在数据库之后启动 |
| networks | 容器网络 | 让多个服务通过服务名互相访问 |
更安全的做法是把密码、Token、API Key 放在 .env 或 Docker secrets 中，不要直接写死在 compose.yaml 里。Docker 官方也提醒，环境变量可能在日志或调试中泄露，敏感信息更适合使用 secrets。
五、推荐项目目录结构
| ai-stack/ ├─ compose.yaml ├─ .env ├─ data/ │ ├─ open-webui/ │ ├─ ollama/ │ ├─ n8n/ │ └─ postgres/ ├─ backups/ └─ README.md |
- compose.yaml：服务编排主文件。
- .env：端口、密码、模型服务地址等变量。
- data/：持久化数据目录，不要随便删除。
- backups/：升级和迁移前保存备份。
- README.md：记录服务端口、管理员账号、升级步骤。
六、Docker Compose 部署总流程图
图：从机器准备到服务启动、验证和备份的完整流程
七、AI 服务架构图：WebUI、模型、数据库如何协作
图：Docker Compose 管理访问层、应用层、模型层和数据层
八、实战一：Ollama + Open WebUI 本地聊天服务
Open WebUI 官方文档说明，Docker 是多数用户推荐的部署方式，Open WebUI 可连接 Ollama 与 OpenAI-compatible API。下面这个 Compose 示例适合在本地或内网服务器上快速搭建一个 ChatGPT 风格的本地聊天界面。
| services: ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped ports: – “11434:11434” volumes: – ollama:/root/.ollama open-webui: image: ghcr.io/open-webui/open-webui:main container_name: open-webui restart: unless-stopped depends_on: – ollama ports: – “3000:8080” environment: OLLAMA_BASE_URL: http://ollama:11434 volumes: – open-webui:/app/backend/data volumes: ollama: open-webui: |
启动命令：
| docker compose up -d docker compose ps docker compose logs -f open-webui |
访问地址：浏览器打开 http://localhost:3000。首次进入后创建管理员账号，再到 Ollama 中拉取模型。
| docker exec -it ollama ollama pull qwen2.5:7b docker exec -it ollama ollama list |
九、GPU 加速：NVIDIA 显卡服务器怎么配置
如果要让容器使用 NVIDIA GPU，宿主机必须先装好 NVIDIA 驱动，并配置 NVIDIA Container Toolkit。NVIDIA 官方文档给出的 Docker 配置步骤包括执行 nvidia-ctk runtime configure –runtime=docker，然后重启 Docker daemon。
| nvidia-smi sudo nvidia-ctk runtime configure –runtime=docker sudo systemctl restart docker |
Compose 中常见的 GPU 写法如下，具体支持情况取决于镜像和 Docker 版本：
| services: ollama: image: ollama/ollama:latest ports: – “11434:11434” volumes: – ollama:/root/.ollama deploy: resources: reservations: devices: – driver: nvidia count: all capabilities: [gpu] volumes: ollama: |
验证容器是否看到 GPU：
| docker run –rm –gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi |
十、实战二：n8n + PostgreSQL 自动化工作流服务
n8n 官方 Docker 文档提供了 Docker 与 PostgreSQL 自托管路线。生产或长期使用时，建议使用 PostgreSQL，不建议只依赖临时容器文件系统。
| services: postgres: image: postgres:16 restart: unless-stopped environment: POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: ${POSTGRES_DB} volumes: – postgres_data:/var/lib/postgresql/data n8n: image: n8nio/n8n:latest restart: unless-stopped depends_on: – postgres ports: – “5678:5678” environment: DB_TYPE: postgresdb DB_POSTGRESDB_HOST: postgres DB_POSTGRESDB_PORT: 5432 DB_POSTGRESDB_DATABASE: ${POSTGRES_DB} DB_POSTGRESDB_USER: ${POSTGRES_USER} DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD} N8N_HOST: ${N8N_HOST} N8N_PROTOCOL: ${N8N_PROTOCOL} WEBHOOK_URL: ${WEBHOOK_URL} GENERIC_TIMEZONE: Asia/Shanghai volumes: – n8n_data:/home/node/.n8n volumes: postgres_data: n8n_data: |
.env 示例：
| POSTGRES_USER=n8n POSTGRES_PASSWORD=请改成强密码 POSTGRES_DB=n8n N8N_HOST=example.com N8N_PROTOCOL=https WEBHOOK_URL=https://example.com/ |
十一、实战三：Dify 自托管部署路线
Dify 官方文档提供 Docker Compose 快速部署路线，部署前最低硬件要求为 2 核 CPU、4 GiB 内存；在 macOS Docker Desktop 场景中还建议给 Docker 虚拟机分配至少 2 个 vCPU 和 8 GiB 内存。
| LATEST_TAG=$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | \ jq -r .tag_name) git clone –branch “$LATEST_TAG” https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env docker compose up -d |
Dify 服务较多，新手不建议一开始就手写全部 compose.yaml。更稳妥的方式是先用官方 docker 目录跑通，再按实际需要修改 .env、域名、存储、模型供应商和向量数据库。
十二、实战四：LocalAI 作为本地 OpenAI 兼容 API
LocalAI 官方容器文档说明，它支持 Docker、Podman 等 OCI 兼容容器引擎；Quickstart 文档也将其定位为可替代 OpenAI/Anthropic 等接口的本地 REST API。适合把本地模型包装成统一 API，供 n8n、Dify、自写应用调用。
| services: localai: image: localai/localai:latest restart: unless-stopped ports: – “8080:8080” environment: DEBUG: “false” volumes: – ./models:/models – localai_data:/tmp/localai volumes: localai_data: |
启动后可访问 http://localhost:8080，或把 OpenAI SDK 的 base_url 指向 LocalAI 服务地址。
十三、实战五：Flowise 可视化 AI 工作流
Flowise 可用于可视化搭建 Chatflow、Agentflow 和知识库工作流。官方 Docker 说明中，常见步骤是创建 .env 文件、执行 docker compose up -d，然后访问 localhost:3000。
| services: flowise: image: flowiseai/flowise:latest restart: unless-stopped ports: – “3001:3000” environment: PORT: 3000 DATABASE_PATH: /root/.flowise FLOWISE_USERNAME: ${FLOWISE_USERNAME} FLOWISE_PASSWORD: ${FLOWISE_PASSWORD} volumes: – flowise_data:/root/.flowise volumes: flowise_data: |
十四、反向代理与 HTTPS：公网部署必须做
如果 AI 服务只在本机或内网访问，可以先不配置域名。但如果要开放到公网，至少要做三件事：绑定域名、启用 HTTPS、添加登录鉴权。不要把 Open WebUI、n8n、Dify、Flowise 的管理页面裸露在公网端口上。
| 组件 | 作用 | 新手建议 |
| Caddy | 自动 HTTPS 反向代理 | 配置简单，适合新手 |
| Nginx Proxy Manager | 图形化反向代理 | 适合不想手写 Nginx 配置的人 |
| Traefik | 自动发现 Docker 服务 | 适合进阶用户和多服务环境 |
| Cloudflare Tunnel | 不开放服务器端口也能访问 | 适合家用宽带、内网穿透场景 |
| services: caddy: image: caddy:2 restart: unless-stopped ports: – “80:80” – “443:443” volumes: – ./Caddyfile:/etc/caddy/Caddyfile – caddy_data:/data – caddy_config:/config volumes: caddy_data: caddy_config: |
十五、常用运维命令：部署后每天都会用
| 目标 | 命令 |
| 启动服务 | docker compose up -d |
| 停止服务 | docker compose stop |
| 停止并删除容器 | docker compose down |
| 查看状态 | docker compose ps |
| 查看日志 | docker compose logs -f 服务名 |
| 重启单个服务 | docker compose restart 服务名 |
| 拉取新镜像 | docker compose pull |
| 升级并重建 | docker compose up -d –pull always |
| 进入容器 | docker exec -it 容器名 bash |
| 查看磁盘占用 | docker system df |
十六、备份、升级与迁移：别等数据丢了才后悔
Docker Compose 的核心数据通常在 volumes 或绑定目录中。升级前至少备份三类内容：compose.yaml、.env、数据卷/绑定目录。对于 PostgreSQL、MySQL 等数据库，建议用数据库自身的 dump 工具导出。
| # 备份项目配置 tar -czf backups/ai-stack-config-$(date +%F).tar.gz compose.yaml .env # 查看数据卷 docker volume ls # 备份 PostgreSQL 示例 docker exec -t postgres pg_dump -U n8n n8n > backups/n8n-$(date +%F).sql |
升级建议流程：先备份，再 docker compose pull，最后 docker compose up -d。升级后第一时间检查 docker compose ps 和 logs。
十七、常见问题排查树
图：AI 服务用 Docker Compose 部署后的常见报错排查顺序
十八、新手最容易犯的 10 个错误
1. 把密码直接写进 compose.yaml，还上传到 GitHub。
2. 没有使用 volumes，容器删除后数据一起没了。
3. 把数据库、模型、上传文件都放在临时容器层。
4. 公网部署不加 HTTPS、不加登录、不限制端口。
5. 每次出错就重装系统，而不是先看 docker compose logs。
6. Windows 下把大型模型放在慢速挂载目录中，导致加载很慢。
7. 不知道容器内服务名可以互相访问，比如 http://ollama:11434。
8. 盲目升级 latest 镜像，结果和旧配置不兼容。
9. GPU 容器没配置 NVIDIA Container Toolkit，却以为是模型问题。
10. 同一台机器多个服务抢 3000、5678、7860、8080 等常用端口。
十九、FAQ：Docker Compose 搭建 AI 服务常见问答
Q1：Docker Compose 和 Docker Desktop 是一回事吗？
不是。Docker Desktop 是桌面端软件包，通常包含 Docker Engine、CLI 和 Compose；Docker Compose 是用于定义和运行多容器应用的工具。
Q2：新手必须会写 Dockerfile 吗？
不必须。多数 AI 工具已经提供官方镜像，新手先学会 compose.yaml、ports、volumes、environment 即可。
Q3：为什么容器启动了但浏览器打不开？
先看 docker compose ps 是否 Up，再确认 ports 是否映射正确，最后检查防火墙、安全组和服务日志。
Q4：Open WebUI 连接不上 Ollama 怎么办？
在同一个 Compose 网络中，Open WebUI 访问 Ollama 应使用 http://ollama:11434，而不是宿主机的 localhost。
Q5：docker compose down 会删除数据吗？
默认不会删除 named volumes，但 docker compose down -v 会删除 volumes。生产环境不要随便加 -v。
Q6：能不能所有服务都用 latest？
学习阶段可以；生产环境建议固定版本标签，并在升级前备份。
Q7：GPU 加速一定要装 CUDA Toolkit 吗？
容器场景通常更关键的是宿主机 NVIDIA 驱动和 NVIDIA Container Toolkit。很多镜像自带运行所需 CUDA 组件。
Q8：.env 文件能不能提交到仓库？
不建议。可以提交 .env.example，但真实 .env 应加入 .gitignore。
Q9：Dify 为什么比 Open WebUI 更吃资源？
Dify 通常包含 API、Web、Worker、数据库、Redis、向量库等多个服务，资源需求自然更高。
Q10：家用电脑适合长期跑 Docker Compose AI 服务吗？
适合学习和个人使用；长期公网服务更建议 Linux 服务器、稳定电源、备份和监控。
官方参考来源
- Docker Compose 安装概览：https://docs.docker.com/compose/install/
- Docker Compose Linux 插件安装：https://docs.docker.com/compose/install/linux/
- Docker Compose 文件参考：https://docs.docker.com/reference/compose-file/
- Docker Compose secrets：https://docs.docker.com/compose/how-tos/use-secrets/
- NVIDIA Container Toolkit 安装指南：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
- Open WebUI Quick Start：https://docs.openwebui.com/getting-started/quick-start/
- Dify Docker Compose 部署：https://docs.dify.ai/en/self-host/quick-start/docker-compose
- LocalAI 容器安装：https://localai.io/installation/containers/index.html
- n8n Docker 安装：https://docs.n8n.io/hosting/installation/docker/
- Flowise Docker 说明：https://github.com/FlowiseAI/Flowise/blob/main/docker/README.md
