docker/awesome-compose · 上手攻略

仓库：docker/awesome-compose
链接：https://github.com/docker/awesome-compose
分类：DevOps / Docker / Docker Compose
作者：Jay
更新：2026-07-13

这是什么

docker/awesome-compose 是 Docker 官方维护的 Docker Compose 范例合集，收录了大量生产级别的多容器应用配置示例。每个示例都是一个独立目录，内含 compose.yaml 描述服务拓扑，配有独立 README 说明结构和使用方法。

官方定位明确：仅适用于本地开发环境，不适用于生产部署。

简单说：你想跑一个 FastAPI + PostgreSQL + Redis 的本地开发栈？来这里抄作业，改改版本号就能用。

解决什么问题

从零搭环境耗时：每个项目都要手写 docker-compose.yaml，版本、网络、卷挂载都要查文档。awesome-compose 提供了经过验证的模板。
服务集成配置不熟：把 Nginx、PostgreSQL、Redis、Prometheus 等常见服务组合起来时，网络怎么互通、卷怎么挂载、环境变量怎么传，示例里有标准答案。
不知道最佳实践：官方维护的示例代表了 Docker 官方推荐的做法，有参考价值。

快速安装

前提条件

Windows 或 macOS： 安装 Docker Desktop（已内置 docker compose）。

Linux： 先装 Docker，再装 Docker Compose。

验证安装：

docker compose version
# Docker Compose version v2.x.x

快速上手任意示例

# 克隆仓库（可选，也可以只复制单个示例目录）
git clone https://github.com/docker/awesome-compose.git
cd awesome-compose

# 进入某个示例目录，例如 FastAPI
cd fastapi

# 启动所有服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 停止并清理
docker compose down

核心用法

示例总览

多服务集成类（推荐）

示例	说明
`django/`	Django + PostgreSQL + Nginx
`flask/`	Flask + PostgreSQL
`fastapi/`	FastAPI + PostgreSQL
`angular/`	Angular + Nginx（WebAssembly 支持）
`vuejs/`	VueJS + Nginx
`nextcloud-postgres/`	Nextcloud + PostgreSQL
`nextcloud-redis-mariadb/`	Nextcloud + Redis + MariaDB
`prometheus-grafana/`	Prometheus + Grafana 监控栈
`gitea-postgres/`	Gitea Git 服务 + PostgreSQL
`pihole-cloudflared-DoH/`	Pi-hole DNS + cloudflared DoH
`traefik-golang/`	Traefik 反向代理 + Go 应用
`plex/`	Plex 媒体服务器
`portainer/`	Portainer 容器管理面板
`wireguard/`	WireGuard VPN 服务
`minecraft/`	Minecraft 服务器
`wordpress-mysql/`	WordPress + MySQL

�wasm 图标表示该示例支持 Docker+WASM。

单服务类

apache-php/ — 经典 LAMP 中的 PHP 部分
sparkjava/ — SparkJava 微框架

常用 compose.yaml 结构解读

以 FastAPI 示例为例（参考官方 README 推断）：

# compose.yaml（示例结构）
services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/mydb
    depends_on:
      - db
      - redis
    volumes:
      - ./app:/app

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

启动命令：

docker compose up -d       # 后台启动
docker compose up          # 前台看日志
docker compose down        # 停止并移除容器（保留卷）
docker compose down -v     # 停止并删除卷（数据丢失）
docker compose restart     # 重启所有服务
docker compose exec app python -c "import myapp"  # 在 app 容器里执行命令

服务依赖与启动顺序

depends_on 只保证容器启动顺序，不保证服务就绪。用 healthcheck 配合：

services:
  db:
    image: postgres:15-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 5s
      timeout: 5s
      retries: 5

  app:
    depends_on:
      db:
        condition: service_healthy

数据持久化

数据存在命名卷（named volume）里，容器删除后不丢失：

docker compose down          # 卷保留
docker compose down -v       # 删除卷
docker volume ls             # 查看所有卷

典型适用场景

场景	推荐示例
快速起一个 Web + DB 开发环境	`fastapi/` / `flask/` / `django/`
自建 Git 服务	`gitea-postgres/`
本地监控栈（熟悉 Prometheus/Grafana）	`prometheus-grafana/`
私有网盘	`nextcloud-postgres/`
广告/跟踪器屏蔽（DNS 层）	`pihole-cloudflared-DoH/`
媒体中心	`plex/`
VPN 组网	`wireguard/`

坑与注意

⚠️ 非生产用途：官方 README 明确说明所有示例仅用于本地开发，不要直接部署到生产环境。生产部署需要考虑数据安全、镜像签名、资源限制、网络隔离等额外配置。
版本号固定问题：示例中的镜像版本（如 postgres:15-alpine）可能随时间推移有新版本。如果遇到兼容性问题，检查 Docker Hub 上对应镜像的最新稳定版本。
端口冲突：示例默认端口（如 5432 PostgreSQL、6379 Redis）可能与本地已有服务冲突。修改 compose.yaml 中的 ports 映射： ```yaml ports:
- "5433:5432" # 把主机的 5433 映射到容器的 5432 ```
数据卷权限：Linux 上某些镜像（尤其是 PostgreSQL）以特定用户运行，宿主机直接修改卷内文件可能导致权限问题。避免在容器外直接操作卷内容。
Docker Desktop 和 Linux 行为差异：macOS 的 Docker Desktop 运行在虚拟机里，文件性能比 Linux 原生慢，数据库等 IO 密集型场景可能感知到延迟。
Windows 路径换行符：在 Windows 上 clone 仓库，换行符可能变成 CRLF，导致 shell 脚本执行异常。推荐在 WSL2 里运行 Docker，或者 clone 后 git config --global core.autocrlf input。
网络隔离：默认所有服务在同一个 default 网络里，可以通过 docker network ls 查看。如需网络隔离，参考 Docker Compose 网络文档自行添加自定义网络。

与同类对比

维度	docker/awesome-compose	Dploy.app / Coolify	Portainer 模板	自定义 yaml
覆盖范围	官方维护的常见组合	一键部署流行应用	可视化容器管理	无限制
更新频率	依赖官方维护	活跃	视社区贡献	按需更新
定制化	中等（需修改 yaml）	低（一键部署）	低	高
学习价值	✅ 高（可看标准写法）	❌	❌	✅ 高
适用场景	本地开发参考	快速建站	可视化管理	生产复杂架构

awesome-compose 最大价值：它是 Docker 官方的"标准答案"，每个 compose.yaml 都代表官方推荐写法，是学习 Docker Compose 语法的最佳参考库之一。

一句话推荐结论

想要快速搭建本地开发环境、参考 Docker Compose 最佳实践？直接来这里找对应模板，改改版本和端口就能跑，节省大量查文档时间。但切记——这只是本地开发参考，生产部署必须在此基础上加固。