# dev-docker

**Repository Path**: github-29082639/dev-docker

## Basic Information

- **Project Name**: dev-docker
- **Description**: 面向 macOS的本地开发框架：一套“核心服务”（Nginx 反向代理 / 两套 MySQL / Redis）+ 多个“项目服务”（每个项目自带 PHP-FPM 与 Nginx），通过共享外部网络 `web` 协同工作。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-28
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dev-docker 框架文档（PHP 本地开发）

面向 macOS/Linux 的本地开发框架：一套“核心服务”（**Traefik** 入口网关 / 两套 MySQL / Redis / PostgreSQL / MongoDB）+ 多个“项目服务”（每个项目自带 PHP-FPM 与 Nginx），通过共享外部网络 `web` 协同工作。

该文档全面说明架构设计、目录结构、模块交互、使用示例、API 参考与维护规范，确保与代码实现基本一致。

---

## 目录（Contents）

- 概览与设计理念
- 架构与交互图
- 目录结构与约定
- 快速开始与典型场景
- 核心模块说明（core）
- 项目模块说明（projects）
- API 参考（服务/网络/环境变量）
- 维护与版本说明（文档同步机制）
- 故障排除与技巧
- 参考资料与附录

---

## 概览与设计理念

- 分层设计：将“公共基础设施”（入口网关、数据库、缓存）与“具体项目容器”分离，提升复用与可维护性。
- **声明式路由**：核心入口使用 **Traefik**，通过各项目容器上的 **Docker labels** 声明 `Host` 规则与后端端口；新增域名或项目时**无需**修改核心单一 Nginx 文件或手动维护 `upstream` 容器名。
- 共享网络：所有容器加入外部网络 `web`，实现跨 Compose 项目的稳定互通。
- 简单即可靠：默认仅暴露本机端口用于开发，数据持久化使用 Docker 卷。

---

## 架构与交互图

```
[Browser] -- Host: yourproj.local --> [Traefik :80]
                                 |--> 项目 nginx:80（由 labels 匹配）

Project (projects/<name>)
  ├─ nginx (expose:80)  <-- Traefik 按 Host 转发 HTTP
  └─ php-fpm (9000)     <-- 项目内 nginx fastcgi_pass php:9000

Core services (core)
  ├─ MySQL 5.7 (3306)   <-- 宿主 :3306
  ├─ MySQL 8.0 (3307)   <-- 宿主 :3307
  ├─ PostgreSQL (5432)
  ├─ Redis (6379)       <-- 别名: redis
  └─ MongoDB (27017)

Shared external network: web
```

Mermaid（如编辑器支持）：

```mermaid
flowchart LR
  B[Browser: yourproj.local] --> T[Traefik :80]
  T -->|Docker labels| N[Project Nginx]
  N -->|fastcgi_pass| F[Project PHP-FPM]
  F -->|DB| M57[(MySQL 5.7:3306)]
  F -->|DB| M80[(MySQL 8.0:3307)]
  F -->|DB| PG[(Postgres:5432)]
  F -->|Cache| R[(Redis:6379)]
  F -->|DB| MG[(MongoDB:27017)]
```

---

## 目录结构与约定

实际代码结构（与仓库一致）：

```
core/                      # 公共服务（Traefik / 数据库 / 缓存）
  ├─ .env                  # MySQL/Postgres/Mongo 等默认环境变量示例
  ├─ docker-compose.yml    # traefik、mysql5、mysql8、redis、postgres、mongo 与外部网络 web
  ├─ traefik.yml           # Traefik 静态配置（入口、Docker 提供者）
  ├─ pg-init/              # Postgres 可选初始化脚本（如有）
  └─ clear-proxy.sh        # 清理系统与 Docker 代理配置（macOS）

projects/                  # 每个子目录是一个可独立运行的项目
  ├─ Example/              # 模板示例（php + nginx）
  ├─ chaowan/              # 实际项目示例
  ├─ lilie/ wuliu/ xiaoma/ # 其他示例项目
  └─ README.md             # 项目目录使用说明与模板指南

README.md                  # 框架文档（本文件）
```

说明：请使用 `core/.env` 管理数据库相关变量。

---

## 快速开始与典型场景

前置要求：安装 Docker Desktop 或 OrbStack（含 docker compose v2），确保本机端口 `80/3306/3307/5432/6379/27017` 空闲。

1) 创建外部网络并启动核心服务：

```
docker network create web   # 若已存在可跳过
cd core
docker compose up -d
```

2) 启动一个项目（以自建 `yourproj` 为例，或复制 `projects/Example`）：

```
cd ../projects/yourproj
docker compose up -d
```

3) **接入入口网关**：在项目的 **`nginx` 服务**上配置 Traefik labels（`traefik.enable=true`、`traefik.docker.network=web`、`Host(...)` 规则、`loadbalancer.server.port=80` 等）。详见 `projects/README.md` 中的完整片段。

修改后执行：

```
docker compose up -d
```

Traefik 会监听 Docker 事件并更新路由，一般**无需**重启 `core` 中的 Traefik。

4) 本地域名解析：

```
sudo sh -c 'echo "127.0.0.1 yourproj.local" >> /etc/hosts'
```

5) 访问站点：

```
http://yourproj.local
```

常见场景：

- 切换数据库版本：选择连接 `127.0.0.1:3306`（5.7）或 `127.0.0.1:3307`（8.0）；PostgreSQL 使用 `127.0.0.1:5432`。
- 使用 Redis：在容器内直接连接 `redis:6379`（已配置网络别名）。
- 使用 MongoDB：宿主机 `127.0.0.1:27017` 或容器内 `host.docker.internal:27017`（按需）。
- 开启 Xdebug：在项目 `php` 服务环境或 `php.ini` 中启用并按 IDE 配置远程调试。

---

## 核心模块说明（core）

- **Traefik**（`traefik:v3.3`，服务名 `traefik`，容器名 `traefik`）
  - 端口：`80`（宿主机）
  - 只读挂载 `docker.sock` 与 `traefik.yml`；路由由各项目 **labels** 提供，`exposedByDefault: false`。
- MySQL 5.7（服务名 `mysql5`）与 MySQL 8.0（服务名 `mysql8`）
  - 端口映射：`3306:3306`（5.7）、`3307:3306`（8.0）
  - 环境变量：来自 `core/.env`（`MYSQL_ROOT_PASSWORD`、`MYSQL_DATABASE` 等）
  - 数据卷：`mysql_data`、`mysql8_data`
- Redis（服务名 `redis`）
  - 端口映射：`6379:6379`
  - AOF 持久化启用；网络别名 `redis` 便于跨项目连接
- PostgreSQL（服务名 `postgres`，镜像带 pgvector）
  - 端口：`5432:5432`；密码等见 `core/.env` / compose 默认值
- MongoDB（服务名 `mongo`）
  - 端口：`27017:27017`

网络：所有核心服务加入外部网络 `web`，与各项目共享。

---

## 项目模块说明（projects）

每个项目通常包含两个服务：

- `php`：构建自项目 `Dockerfile`（例如 `FROM php:7.4-fpm`），挂载代码到 `/app`
- `nginx`：加载项目的 `nginx.conf`/`default.conf`，`fastcgi_pass php:9000` 代理到 PHP-FPM

与核心交互：

- 加入网络 `web` 以被 Traefik 与其他服务访问
- 在 **`nginx`（或对外 HTTP 的服务）上配置 Traefik labels**，声明域名与后端端口
- 与 MySQL/Redis/Postgres/Mongo 通信：
  - 宿主连接：`127.0.0.1` 对应端口
  - 容器连接：`host.docker.internal` 对应端口；Redis 可用主机名 `redis:6379`

更多项目用法见 `projects/README.md`。

---

## API 参考（服务/网络/环境变量）

- 服务名称（`core/docker-compose.yml`）：`traefik`、`mysql5`、`mysql8`、`redis`、`postgres`、`mongo`
- 外部网络：`web`（需提前 `docker network create web`）
- 环境变量（`core/.env`）示例：
  - `MYSQL_ROOT_PASSWORD`、`MYSQL_DATABASE`：MySQL
  - `POSTGRES_PASSWORD`：PostgreSQL
  - `MONGO_INITDB_ROOT_USERNAME`、`MONGO_INITDB_ROOT_PASSWORD`：MongoDB
  - 可选：`MYSQL_USER`、`MYSQL_PASSWORD`（如需普通 MySQL 用户）
- **Traefik 路由**：在各项目 `docker-compose.yml` 的 labels 中维护，例如：
  - `traefik.enable=true`
  - `traefik.docker.network=web`
  - `traefik.http.routers.<唯一名称>.rule`：使用 `Host()` 与可选的 `HostRegexp()` 匹配域名（详见 `projects/README.md` 示例）
  - `traefik.http.services.<名称>.loadbalancer.server.port=80`

---

## 维护与版本说明（文档同步机制）

- 版本记录（示例）：
  - Unreleased：核心入口由 Nginx 改为 Traefik；文档同步路由方式
  - v0.1：确立 core/projects 分层结构；完成 MySQL/Redis 基础服务
- 文档与代码同步机制：
  - 修改 `core/docker-compose.yml`、`core/traefik.yml` 或各项目 Traefik labels 后，应同步检查本 README 与 `projects/README.md`、`core/README.md`
  - 变更清单模板：
    - 服务名/端口/网络是否变更
    - 环境变量是否新增或改名
    - Traefik 路由/labels 是否新增或冲突（路由器名称全局唯一）

---

## 故障排除与技巧

- 端口冲突：`lsof -i :80`、`:3306`、`:3307`、`:5432`、`:6379`、`:27017` 检查占用
- 外部网络缺失：`docker network create web`
- 入口 404 或无路由：检查项目 labels、`Host` 是否与浏览器一致；`docker compose logs traefik`（在 `core` 目录）
- 镜像拉取策略：如设置了 `pull_policy: never`，本地无镜像会失败；可改为 `always` 或预先 `docker pull`
- 清理系统与 Docker 代理（macOS）：
  - 执行 `core/clear-proxy.sh` 清除网络代理与 Docker 客户端代理配置（与 Traefik **服务名**无关，脚本名中的 proxy 指 **系统 HTTP 代理**）
- 刷新本机 DNS 缓存（macOS）：
  - `sudo dscacheutil -flushcache`

---

## 参考资料与附录

- 核心服务文档：`core/README.md`
- 项目目录指南：`projects/README.md`
- Docker Compose：https://docs.docker.com/compose/
- Traefik：https://doc.traefik.io/traefik/
- Nginx：https://nginx.org/
- MySQL（官方镜像）：https://hub.docker.com/_/mysql
- Redis（官方镜像）：https://hub.docker.com/_/redis
- PostgreSQL / pgvector：https://hub.docker.com/r/pgvector/pgvector
- MongoDB：https://hub.docker.com/_/mongo