mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-08-30 12:45:32 +08:00
refactor(stack): 删除 stack.json，README 改为模板使用指南
- 删除 source/stack/stack.json（与 README 模式表重复，无实际用途） - README 新增使用方式说明：可直接用，推荐复制后自定义 （admin:update 只更新原始模板，不覆盖开发者副本） - 同步清理 ulthon-deploy-environment.md 和 ulthon-update-workflow SKILL.md 中对 stack.json 的引用 - ulthon-deploy-environment.md 补充记录义务规则： 智能体应确认 project-dev-runtime-deploy.md 是否已记录运行方式， 必须包含命令执行方式（容器内 vs 宿主机）
This commit is contained in:
augushong
@@ -24,5 +24,17 @@
|
||||
- 模式目录内的 `docker-compose.yaml` 是该模式的栈定义，bind mount 通常指向仓库根目录。
|
||||
- 在容器外执行 `php think`：`docker compose -f source/stack/<mode>/docker-compose.yaml exec <service> php think ...`，或在模式目录内 `docker compose exec <service> php think ...`。
|
||||
- 示例：`docker compose -f source/stack/docker-dev/docker-compose.yaml exec ulthon_admin php think tools:http:call`。
|
||||
- **可用模式**见 `source/stack/stack.json` 与 `source/stack/README.md`（default / docker-serve / docker-dev / docker-dev-sync / full / author 等）。
|
||||
- **可用模式**见 `source/stack/README.md`（default / docker-serve / docker-dev / docker-dev-sync / full / author 等）。
|
||||
- **判断技巧**：如果不确定当前是否处于容器内，看 `pwd` 是否在仓库根、根目录有无 `Dockerfile`、`docker ps` 是否有相关容器在跑。容器内执行 `php think` 不需要前缀。
|
||||
|
||||
## 记录义务
|
||||
|
||||
当开发者确定/选择了项目的运行方式（无论是否使用框架预设的 stack 模式），智能体应当确认 `.agents/rules/project-dev-runtime-deploy.md` 中是否已记录该选择。如果未记录或内容仍为模板占位符，提醒开发者补充或协助填写。
|
||||
|
||||
记录内容不限定格式，开发者用一两句话写清楚"本项目用 xxx 方式运行"即可，无需详细参数列表。但必须包含一个关键信息：**命令执行方式**——即 `php think` 等命令应当在哪里执行。例如：
|
||||
|
||||
- Docker 模式：命令在容器内执行（`docker compose exec <service> php think ...`），不是宿主机直接 `php think`
|
||||
- 宿主机模式：命令直接在仓库根目录执行
|
||||
- 宝塔/其他：按实际环境的执行路径记录
|
||||
|
||||
目的是让后续会话中的智能体能从规则文件快速了解项目的实际运行方式和命令执行入口，而不需要重新询问或猜测。
|
||||
|
||||
@@ -30,7 +30,7 @@ description: "指导 AI agent 协助开发者使用 php think admin:update 同
|
||||
- **default 模式（宿主机直接执行）**：仓库根目录**没有** `docker-compose.yaml`，`source/stack/` 目录不存在或为空。所有 `php think` 命令直接在宿主机执行，不做转换。
|
||||
- **Docker 模式（需容器前缀）**：仓库根目录**存在** `docker-compose.yaml`，或 `source/stack/<mode>/` 目录下存在 Docker 编排文件。所有 `php think` 命令前缀改为 `docker compose exec ulthon_admin`。
|
||||
|
||||
> 可用 `Get-ChildItem source\stack -Directory`（PowerShell）或 `ls source/stack/`（Linux）列出 `source/stack/` 下的所有 mode 子目录；纯文档性质的 `source/stack/stack.json` 仅作历史参考，不再作为权威依据。
|
||||
> 可用 `Get-ChildItem source\stack -Directory`（PowerShell）或 `ls source/stack/`（Linux）列出 `source/stack/` 下的所有 mode 子目录。
|
||||
|
||||
### 3.2 确认代码已提交
|
||||
|
||||
|
||||
@@ -1,40 +1,59 @@
|
||||
# Stack 模式目录规范（B-route 工作流）
|
||||
# Stack 模式目录
|
||||
|
||||
本目录维护多种部署/运行模式的独立栈定义。B-route 工作流下，每个模式是 `source/stack/` 下一个独立子目录，**不再覆盖仓库根目录**：使用某个模式时 `cd` 进对应目录运行 `docker compose up -d` 即可。
|
||||
本目录维护多种部署/运行模式的独立栈定义。每个模式是 `source/stack/` 下一个独立子目录。
|
||||
|
||||
## 工作流
|
||||
## 使用方式
|
||||
|
||||
1. 默认基线（default）：仓库根目录直接 `php think run`，根目录无 Docker 文件。
|
||||
2. 选择某个 Docker 模式：`cd source/stack/<mode>` 后 `docker compose up -d`，bind mount 指向仓库根目录。
|
||||
3. 模式目录内执行命令：在该目录用 `docker compose exec <service> php think ...`，或在仓库根目录用 `docker compose -f source/stack/<mode>/docker-compose.yaml exec <service> php think ...`。
|
||||
模式目录可以直接使用，也推荐复制一份出来自定义：
|
||||
|
||||
## 目录结构
|
||||
**直接使用**：`cd source/stack/docker-dev && docker compose up -d`
|
||||
|
||||
- `source/stack/stack.json`：全局清单，记录 `default_mode` 与 `modes` 元数据，供人与工具查阅可用模式。
|
||||
- `source/stack/default/`：默认行为基线目录（`php think run`，纯 PHP 内置服务器，不依赖 Docker）。
|
||||
- `source/stack/<mode>/`：具体模式目录，内含该模式独立的 `docker-compose.yaml` 及配套文件（如 Dockerfile、nginx 配置、env 示例等）。
|
||||
**复制后自定义**（推荐）：
|
||||
|
||||
```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） |
|
||||
| `docker-dev` | Docker 开发模式（nginx + php-fpm + MySQL + Redis + phpMyAdmin + Xdebug） |
|
||||
| `docker-dev-sync` | Docker 开发模式 - Windows I/O 优化（rsync 同步，避免 bind mount 慢速问题） |
|
||||
| `full` | 完整服务栈（规划中），从 PHP 镜像从头构建 |
|
||||
| `author` | 框架作者维护工具（基础镜像构建、发布脚本等） |
|
||||
|
||||
> `author` 为框架作者专用，使用者一般不需要。
|
||||
|
||||
## default 目录规则（强约束）
|
||||
|
||||
- `source/stack/default/` 必须与代码库默认行为一致。
|
||||
- 默认行为为 `php think run`（ThinkPHP 内置服务器），不依赖 Docker。
|
||||
- 当默认行为文件变更时（如 `.gitea/workflows/build-and-deploy.yml`），必须同步更新 `default` 目录对应文件。
|
||||
- 该规则通过目录维护规范与代码评审保障，不作为运行时阻断条件。
|
||||
- `source/stack/default/` 必须与代码库默认行为一致（`php think run`，不依赖 Docker）
|
||||
- 默认行为相关文件变更时，必须同步更新 `default` 目录对应文件
|
||||
- 该规则通过目录维护规范与代码评审保障，不作为运行时阻断条件
|
||||
|
||||
## 可用模式
|
||||
## 基础镜像
|
||||
|
||||
| 模式 | 启动方式 | 说明 |
|
||||
|------|----------|------|
|
||||
| `default` | 仓库根目录 `php think run` | 默认基线，无 Docker 文件，宿主机直接跑 |
|
||||
| `docker-serve` | `cd source/stack/docker-serve && docker compose up -d` | Docker 部署模式（基于基础镜像，nginx + php-fpm） |
|
||||
| `docker-dev` | `cd source/stack/docker-dev && docker compose up -d` | Docker 开发模式（nginx + php-fpm + MySQL + Redis + phpMyAdmin + Xdebug） |
|
||||
| `docker-dev-sync` | `cd source/stack/docker-dev-sync && docker compose up -d` | Docker 开发模式 - Windows I/O 优化（rsync 同步，避免 bind mount 慢速问题） |
|
||||
| `full` | `cd source/stack/full && docker compose up -d` | 完整服务栈（规划中），从 PHP 镜像从头构建 |
|
||||
| `author` | `cd source/stack/author` | 框架作者维护工具（基础镜像构建、发布脚本等） |
|
||||
|
||||
> 历史 `base-build` 模式已并入 `author`。
|
||||
|
||||
## 基础镜像说明
|
||||
|
||||
- `author/docker/Dockerfile.base` 为基础镜像构建文件，属于作者维护范围。
|
||||
- 推荐标签策略：`latest` + 时间戳（如 `20260424120000`）。
|
||||
- `author/docker/Dockerfile.base` 为基础镜像构建文件，属于作者维护范围
|
||||
- 推荐标签策略：`latest` + 时间戳（如 `20260424120000`）
|
||||
|
||||
@@ -1,29 +0,0 @@
|
||||
{
|
||||
"schema_version": 2,
|
||||
"modes": {
|
||||
"default": {
|
||||
"description": "代码库默认行为基线（php think run）",
|
||||
"category": "user"
|
||||
},
|
||||
"docker-serve": {
|
||||
"description": "Docker 部署模式（基于基础镜像，nginx+php-fpm）",
|
||||
"category": "user"
|
||||
},
|
||||
"docker-dev": {
|
||||
"description": "Docker 开发模式（nginx+php-fpm+MySQL+Redis+phpMyAdmin+Xdebug）",
|
||||
"category": "user"
|
||||
},
|
||||
"docker-dev-sync": {
|
||||
"description": "Docker 开发模式 - Windows I/O 优化（rsync 同步，避免 bind mount 慢速问题）",
|
||||
"category": "user"
|
||||
},
|
||||
"full": {
|
||||
"description": "完整服务栈构建模式（规划含 MySQL/Redis 等完整中间件，当前与 docker-serve 接近，后续完善）",
|
||||
"category": "user"
|
||||
},
|
||||
"author": {
|
||||
"description": "基础镜像 + 应用构建模式（框架作者工具）",
|
||||
"category": "author"
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user