# 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-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

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

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

---

## 目录（Contents）

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

---

## 概览与设计理念

- 分层设计：将“公共基础设施”（反向代理、数据库、缓存）与“具体项目容器”分离，提升复用与可维护性。
- 显式路由：核心代理采用手动维护的 `nginx.conf` 路由规则，明确域名到项目容器的映射，避免隐式魔法。
- 共享网络：所有容器加入外部网络 `web`，实现跨 Compose 项目的稳定互通。
- 简单即可靠：默认仅暴露本机端口用于开发，数据持久化使用 Docker 卷。

---

## 架构与交互图

```
[Browser] -- Host: yourproj.local --> [Core Nginx Proxy (80)]
                                 |--> upstream yourproj-nginx-1:80

Project (projects/<name>)
  ├─ nginx (expose:80)  <-- proxy forwards HTTP
  └─ php-fpm (9000)     <-- nginx fastcgi_pass php:9000

Core services (core)
  ├─ MySQL 5.7 (3306)   <-- host access :3306
  ├─ MySQL 8.0 (3307)   <-- host access :3307
  └─ Redis (6379)       <-- alias: redis

Shared external network: web
```

Mermaid（如编辑器支持）：

```mermaid
flowchart LR
  B[Browser: yourproj.local] --> P[Core Nginx Proxy]
  P -->|proxy_pass| 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 -->|Cache| R[(Redis:6379 alias redis)]
```

---

## 目录结构与约定

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

```
core/                      # 公共服务（反向代理 / MySQL / Redis）
  ├─ .env                  # MySQL 默认环境变量示例（实际使用）
  ├─ docker-compose.yml    # 定义 proxy/mysql5/mysql8/redis 与外部网络 web
  ├─ nginx.conf            # 手动域名路由（upstream 指向项目 nginx 容器）
  └─ clear-proxy.sh        # 清理系统与 Docker 代理配置（macOS）

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

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

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

---

## 快速开始与典型场景

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

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

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

2) 启动一个项目（以 Example 为例）：

```
cd ../projects/Example
docker compose up -d
docker compose ps  # 记录 nginx 容器名称，如 example-nginx-1
```

3) 接入核心代理（在 `core/nginx.conf` 增加 upstream 与域名匹配）：

```
upstream example-backend { server example-nginx-1:80; }
# 在 server/location 中增加：
if ($host ~* "(^|\.)example\.local$") { set $backend "http://example-backend"; }
```

然后重载代理：

```
cd core && docker compose restart proxy
```

4) 本地域名解析：

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

5) 访问站点：

```
http://example.local
```

常见场景：
- 切换数据库版本：选择连接 `127.0.0.1:3306`（5.7）或 `127.0.0.1:3307`（8.0）。
- 使用 Redis：在容器内直接连接 `redis:6379`（已配置网络别名）。
- 开启 Xdebug：在项目 `php` 服务环境或 `php.ini` 中启用并按 IDE 配置远程调试。

---

## 核心模块说明（core）

- 反向代理（`nginx:alpine`，服务名 `proxy`）
  - 端口：`80`（宿主机）
  - 路由：在 `nginx.conf` 中使用 `upstream` 指向项目的 `nginx` 容器名，并在 `server` 中按域名匹配选择后端。
- 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` 便于跨项目连接

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

---

## 项目模块说明（projects）

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

与核心交互：
- 加入网络 `web` 以被核心代理与其他服务访问
- 通过 `core/nginx.conf` 的 `upstream` → 项目 `nginx` 容器名进行域名路由
- 与 MySQL/Redis 通信：
  - 宿主连接：`127.0.0.1:3306/3307/6379`
  - 容器连接：`host.docker.internal:3306/3307`，Redis 用主机名 `redis:6379`

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

---

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

- 服务名称（core/docker-compose.yml）：`proxy`、`mysql5`、`mysql8`、`redis`
- 外部网络：`web`（需提前 `docker network create web`）
- 环境变量（`core/.env`）：
  - `MYSQL_ROOT_PASSWORD`：MySQL root 密码（默认 `root`）
  - `MYSQL_DATABASE`：启动时创建的数据库名（默认 `dev`）
  - 可选：`MYSQL_USER`、`MYSQL_PASSWORD`（如需普通用户）
- Nginx 核心路由（`core/nginx.conf`）：
  - 在 `http` 段定义 `upstream <project>-backend { server <project>-nginx-1:80; }`
  - 在 `server/location` 中按域名 `if ($host ~* "...")` 选择后端并 `proxy_pass`

---

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

- 版本记录（示例）：
  - Unreleased：文档细化 API 参考、统一术语；核心代理保持手动路由
  - v0.1：确立 core/projects 分层结构；完成 MySQL/Redis 基础服务
- 文档与代码同步机制：
  - 修改 `core/docker-compose.yml` 或 `core/nginx.conf` 后，必须同步更新本 README 与 `projects/README.md`
  - 变更清单模板：
    - 服务名/端口/网络是否变更
    - 环境变量是否新增或改名
    - Nginx 路由规则是否新增/删除/改名（容器名是否变化）
  - 建议在 PR 中包含“文档更新”检查项，保证与实现一致

---

## 故障排除与技巧

- 端口冲突：`lsof -i :80`、`:3306`、`:3307`、`:6379` 检查占用
- 外部网络缺失：`docker network create web`
- 代理 404：检查域名匹配与 `upstream` 指向的容器名是否正确（`docker compose ps`）
- 镜像拉取策略：如设置了 `pull_policy: never`，本地无镜像会失败；可改为 `always` 或预先 `docker pull`
- 清理系统与 Docker 代理（macOS）：
  - 执行 `core/clear-proxy.sh` 清除网络代理与 Docker 客户端代理配置
- 刷新本机 DNS 缓存（macOS）：
  - `sudo dscacheutil -flushcache`

---

## 参考资料与附录

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