mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-08-30 12:45:32 +08:00
143 lines
6.2 KiB
Markdown
143 lines
6.2 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 性能分析能力，默认不启用，完全不影响现有行为。
|
||
|
||
### 推荐路径：本地文件落盘 + 后台查看（默认）
|
||
|
||
采集数据以 jsonl 文件按天落盘到容器内目录，由后台导入定时任务增量读取写入数据库，最终在后台管理界面查看性能报告。无需启动任何额外服务。
|
||
|
||
```
|
||
请求
|
||
└─ auto_prepend_file(xhprof-bootstrap.php)
|
||
└─ php-profiler 采集（XHPROF_ENABLE 总闸 + cookie _profiler=1 强制 + 1% 采样）
|
||
└─ 落盘 {XHPROF_FILE_DIR}/runs-{Ymd}.jsonl（默认 /var/www/html/runtime/xhprof，按天分文件）
|
||
└─ 后台导入定时任务增量读取入库（读同一 XHPROF_FILE_DIR，导完的整天文件自动删除）
|
||
└─ 后台管理界面查看性能报告
|
||
```
|
||
|
||
启用方式（默认即为 file 落盘，无需额外 profile）：
|
||
|
||
```bash
|
||
cd source/stack/docker-dev
|
||
XHPROF_ENABLE=true docker compose up -d
|
||
```
|
||
|
||
相关环境变量：
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| XHPROF_ENABLE | false | 采集总开关，true 开启 |
|
||
| XHPROF_SAVER | file | 落盘方式：file（文件落盘）/ upload（推送 XHGui）/ stack（双写） |
|
||
| XHPROF_FILE_DIR | 空 | jsonl 落盘目录，空时容器内 `/var/www/html/runtime/xhprof`；采集与导入共用此变量 |
|
||
| XHGUI_UPLOAD_URL | 空 | XHGui 上传地址，仅 upload / stack 模式使用 |
|
||
| XHGUI_UPLOAD_TOKEN | ulthon-admin-xhprof | 上传令牌，仅 upload / stack 模式使用 |
|
||
|
||
### 手动触发采集
|
||
|
||
默认 1% 采样率。需要强制采集某个请求时，浏览器请求带 cookie `_profiler=1`。
|
||
|
||
### 可选：XHGui 独立可视化服务
|
||
|
||
XHGui 已降级为可选服务（独立 profile），只负责实时可视化，不参与默认采集链路。需要时以 `--profile xhgui` 启动，并推荐配合 stack 双写：
|
||
|
||
```bash
|
||
cd source/stack/docker-dev
|
||
XHPROF_ENABLE=true XHPROF_SAVER=stack XHGUI_UPLOAD_URL=<XHGui上传地址> docker compose --profile xhgui up -d
|
||
```
|
||
|
||
- `XHPROF_SAVER=stack`：文件落盘与 XHGui 推送同时写（SaverFactory 递归双写），落盘数据不丢，XHGui 实时可看
|
||
- `XHGUI_UPLOAD_URL` 为空时不会推送；`XHPROF_SAVER=stack` 且该地址为空时，bootstrap 记录警告并自动降级为 file 单写（防静默丢数据）
|
||
- `XHPROF_SAVER=upload`（只推送 XHGui 不落盘）为旧行为，兼容保留，不推荐
|
||
|
||
浏览器打开 `http://localhost:8142` 查看，Basic Auth 默认 `admin` / `xhgui123`，通过 `XHGUI_AUTH_USER` / `XHGUI_AUTH_PASS` 覆盖。
|
||
|
||
XHGui 存储使用 PDO MySQL。docker-dev / docker-dev-sync 复用栈内 MySQL；docker-serve / full 没有内置 MySQL，需配置 `XHGUI_PDO_DSN` 指向可用的 MySQL 实例：
|
||
|
||
```env
|
||
XHGUI_PDO_DSN=mysql:host=mysql;dbname=ulthon;charset=utf8mb4
|
||
XHGUI_PDO_USER=root
|
||
XHGUI_PDO_PASS=root
|
||
```
|
||
|
||
### 端口说明
|
||
|
||
| 端口 | 服务 | 说明 |
|
||
|------|------|------|
|
||
| 8142 | XHGui | 可选的性能分析报告界面（需 `--profile xhgui`） |
|
||
|
||
### 迁移说明（profiles 更名，破坏性变更）
|
||
|
||
XHGui 服务的 compose profile 已由 `xhprof` 更名为 `xhgui`，采集开关与 XHGui 界面彻底解耦：
|
||
|
||
- 旧命令 `docker compose --profile xhprof up -d` 不再启动 XHGui，请改用 `--profile xhgui`
|
||
- 现在只需 `XHPROF_ENABLE=true` 即可采集（默认文件落盘），无需任何 profile
|
||
- 旧栈若依赖 upload 直推 XHGui，需显式设置 `XHPROF_SAVER=upload` 或改用推荐的 file / stack 模式
|
||
|
||
### 部署注记
|
||
|
||
bootstrap 的落盘方式切换与后台导入定时任务是配套变更，须同批上线：若采集端已切换为默认 file 落盘而后台导入任务未部署，落盘文件将无人消费、持续增长。
|
||
|
||
### 默认行为
|
||
|
||
`XHPROF_ENABLE=false`（默认）时不采集，行为与未集成 XHProf 完全一致；不加 `--profile xhgui` 时 XHGui 服务不启动。
|
||
|
||
## default 目录规则（强约束）
|
||
|
||
- `source/stack/default/` 必须与代码库默认行为一致（`php think run`，不依赖 Docker）
|
||
- 默认行为相关文件变更时，必须同步更新 `default` 目录对应文件
|
||
- 该规则通过目录维护规范与代码评审保障，不作为运行时阻断条件
|
||
|
||
## 基础镜像
|
||
|
||
- `author/docker/Dockerfile.base` 为基础镜像构建文件，属于作者维护范围
|
||
- 推荐标签策略：`latest` + 时间戳（如 `20260424120000`）
|