mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-09-03 06:31:37 +08:00
e0e2580646
在 docker-dev/docker-dev-sync/docker-serve/full 四个模式中集成 XHProf 性能分析能力，默认不启用（--profile xhprof 按需开启），零侵入不改 业务代码和 run.sh。 核心组件： - source/docker/xhprof-bootstrap.php: 采集器初始化（auto_prepend_file） - source/docker/xhgui-config.php: XHGui 认证配置（Basic Auth）+ PDO 存储 - 各 Dockerfile: 安装 PECL xhprof 扩展 + php-profiler 到 /opt/xhprof/ - 各 docker-compose: 新增 xhgui 服务（profiles: xhprof），端口 8142 存储方案：PDO MySQL（复用现有 MySQL），避免 MongoDB PHP 驱动兼容性问题。 docker-dev/docker-dev-sync 开箱即用；docker-serve/full 需配置 XHGUI_PDO_DSN。 认证：HTTP Basic Auth，默认 admin/xhgui123，环境变量可覆盖。 采集控制：XHPROF_ENABLE 环境变量 + cookie _profiler 强制触发 + 1% 采样。 Dockerfile.base 同步新增 xhprof 扩展（框架作者需重建推送基础镜像）。
117 lines
3.9 KiB
Markdown
117 lines
3.9 KiB
Markdown
# 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`）
|