# Stack 模式目录

本目录维护多种部署/运行模式的独立栈定义。每个模式是 `source/stack/` 下一个独立子目录。

## 使用方式

模式目录可以直接使用，也推荐复制一份出来自定义：

**直接使用**：`cd source/stack/docker-dev && docker compose up -d`

**复制后自定义**（推荐）：

```bash
# 复制一份模板
cp -r source/stack/docker-dev source/stack/docker-dev-myproject

# 修改副本中的端口、服务配置等
# （如 compose 的 name、ports、volumes 等）

# 运行副本
cd source/stack/docker-dev-myproject && docker compose up -d
```

复制后自定义的好处：

- 框架更新（`admin:update`）只更新原始模板，不覆盖你的副本
- 可以基于同一个模板创建多个实例（如 dev / test 分开跑）
- 端口、服务配置等自定义不污染框架原始模板

## 启动与命令执行

1. `cd source/stack/<mode>`
2. `docker compose up -d`（首次会自动 build）
3. 在模式目录内执行命令：`docker compose exec <service> php think ...`
4. 或在仓库根目录：`docker compose -f source/stack/<mode>/docker-compose.yaml exec <service> php think ...`

## 可用模板

| 模式 | 说明 |
|------|------|
| `default` | 默认基线，仓库根目录 `php think run`，无 Docker 文件 |
| `docker-serve` | Docker 部署模式（基于基础镜像，nginx + php-fpm + XHProf） |
| `docker-dev` | Docker 开发模式（nginx + php-fpm + MySQL + Redis + phpMyAdmin + Xdebug + XHProf） |
| `docker-dev-sync` | Docker 开发模式 - Windows I/O 优化（rsync 同步，避免 bind mount 慢速问题） + XHProf |
| `full` | 完整服务栈（规划中），从 PHP 镜像从头构建 + XHProf |
| `author` | 框架作者维护工具（基础镜像构建、发布脚本等） |

> `author` 为框架作者专用，使用者一般不需要。

## XHProf 性能分析（可选）

docker-dev / docker-dev-sync / docker-serve / full 模式内置了 XHProf 性能分析能力，默认不启用，完全不影响现有行为。采集数据存储在 MySQL 中（PDO 方式），docker-dev / docker-dev-sync 开箱即用；docker-serve / full 需配置 XHGUI_PDO_DSN 环境变量指向可用的 MySQL。

### 启用方式

```bash
# 在模式目录中，加 --profile xhprof 启动
cd source/stack/docker-dev
XHPROF_ENABLE=true docker compose --profile xhprof up -d
```

或者在 `.env` 中设置 `XHPROF_ENABLE=true`，然后：

```bash
docker compose --profile xhprof up -d
```

### 查看性能报告

浏览器打开 `http://localhost:8142`，输入 Basic Auth 用户名密码（默认 `admin` / `xhgui123`）。

### 认证配置

通过环境变量覆盖默认密码（在 `.env` 或 docker-compose 命令行设置）：

```env
XHGUI_AUTH_USER=myuser
XHGUI_AUTH_PASS=mypassword
```

### 存储配置

默认使用 PDO MySQL 存储（复用 docker-dev 的 MySQL）。通过环境变量自定义：

```env
XHGUI_PDO_DSN=mysql:host=mysql;dbname=ulthon;charset=utf8mb4
XHGUI_PDO_USER=root
XHGUI_PDO_PASS=root
```

docker-serve / full 模式没有内置 MySQL，需要设置 `XHGUI_PDO_DSN` 指向可用的 MySQL 实例。

### 手动触发采集

默认 1% 采样率。需要强制采集某个请求时，浏览器请求带 cookie `_profiler=1`。

### 端口说明

| 端口 | 服务 | 说明 |
|------|------|------|
| 8142 | XHGui | 性能分析报告界面 |

### 默认行为

不加 `--profile xhprof` 时，XHGui 服务不启动，行为与未集成 XHProf 完全一致。

## default 目录规则（强约束）

- `source/stack/default/` 必须与代码库默认行为一致（`php think run`，不依赖 Docker）
- 默认行为相关文件变更时，必须同步更新 `default` 目录对应文件
- 该规则通过目录维护规范与代码评审保障，不作为运行时阻断条件

## 基础镜像

- `author/docker/Dockerfile.base` 为基础镜像构建文件，属于作者维护范围
- 推荐标签策略：`latest` + 时间戳（如 `20260424120000`）