用 docker compose 一键搭建分层解耦的本地电商系统，含网关、认证（keycloak）、商品、订单、搜索（opensearch）、消息（rabbitmq）、通知（mailhog）等自治服务，通过自定义网络互通，配置外置、数据持久化可选，支持健康检查、日志监控与链路追踪。
用 Docker Compose 快速搭建本地单机版企业级全栈电商系统，核心是分层解耦、服务自治、配置外置和网络互通。不追求生产级高可用，但要贴近真实架构逻辑——网关、认证、商品、订单、用户、搜索、库存、通知等模块各司其职，通过 Docker 网络通信，数据持久化可选，启动一键完成。
服务划分与镜像选型：按职责拆，不造轮子
避免从零写代码，优先复用成熟开源组件或轻量定制服务：
- API 网关：用 nginx 或 kong（推荐 nginx，轻量易配），负责路由转发、跨域、限流基础规则
- 认证中心：选用 keycloak（带管理 UI 和 OIDC 支持），或精简版 authelia + Redis
- 核心业务服务：用 Spring Boot/Go/FastAPI 写的最小可行服务（如 /products、/orders），打包为自定义镜像（Dockerfile 基于 openjdk:17-jre-slim 或 golang:1.22-alpine）
- 搜索服务：直接跑 opensearch:2.13（Elasticsearch 兼容替代），预载商品索引模板
- 消息与通知：rabbitmq:3.13-management（开 Web 控制台），订单创建后发 order.created 事件；邮件用 mailhog 拦截测试
- 数据库：PostgreSQL（用户/订单）、MySQL（商品/库存）分库部署，各挂独立 volume；Redis 单例支撑缓存+会话+分布式锁
docker-compose.yml 关键设计：网络、依赖、健康检查
一个 default 自定义网络（bridge 模式）让所有服务互通，用 depends_on + healthcheck 保证启动顺序：
- 数据库加 healthcheck：psql -U ${DB_USER} -d ${DB_NAME} -c "SELECT 1" || exit 1
- 业务服务的 depends_on 指向 db、redis、mq，但需在应用内实现重试逻辑（Compose 不保证服务已就绪）
- 所有服务 expose 端口仅对容器网络开放（如 8080），宿主机只暴露网关（80）和 Keycloak（8081）、MailHog（8025）等调试端口
- 用 env_file 加载 .env 文件统一管理 DB_HOST=postgres、REDIS_URL=redis://redis:6379 等变量，避免硬编码
数据初始化与联调技巧：让系统“活”起来
首次启动不是单纯 up，而是分步触发初始化：
- postgres 启动后自动执行 /docker-entrypoint-initdb.d/*.sql 初始化表结构（用 volumes 挂载 SQL 脚本）
- Keycloak 通过 KEYCLOAK_IMPORT 环境变量加载 realm.json，预置 client、user、role
- 商品服务启动时调用 OpenSearch API 创建 index template 并 bulk 导入 mock 商品数据（用 curl + wait-for-it.sh 等待 ES 就绪）
- 前端用 Vite/React 打包静态资源，Nginx 镜像中 COPY 进去，反向代理到 /api/* 到后端网关
调试与可观测性：本地也要看得清
单机环境更要快速定位问题：
- 所有服务启用 logging.driver: "json-file" + max-size，便于 docker logs 查看
- 加一个 prometheus:2.47 和 grafana:10.2，业务服务暴露 /actuator/prometheus（Spring）或 /metrics（Go），配好 dashboard
- 用 jaegertracing/all-in-one:1.49 收集链路追踪，服务间调用加 OpenTelemetry SDK
- 关键接口用 curl 或 Postman 测试：登录获取 token → 调商品列表 → 下单 → 查订单 → 检查 MailHog 是否收到通知
不复杂但容易忽略：环境变量命名统一、volume 路径用绝对路径、SQL 初始化脚本注意字符集、OpenSearch 的 discovery.type=single-node。跑通一次后，整个拓扑就固化为可版本化、可分享的 compose 项目。
