Skip to content

AGENTS.md

Latest commit

 

History

History
348 lines (292 loc) · 17.5 KB

AGENTS.md

File metadata and controls

348 lines (292 loc) · 17.5 KB
Raw

AI Agent 指南 - PHP-Stack 项目

本文档旨在帮助 AI Agent 快速理解 php-stack 项目的架构设计、代码规范及开发模式。

🏗️ 架构概览

项目采用 Tauri v2 典型的分层架构：

  • Frontend (UI 层): 位于根目录 src/。使用 Vue 3 + TypeScript。
    • App.vue: 主入口，包含侧边栏导航和全局状态管理（如 Docker 可用性、日志流）。
    • style.css: 集成了 Tailwind CSS v4。
  • Backend (逻辑层): 位于 src-tauri/src/。使用 Rust。
    • docker/: 封装 Docker 交互逻辑。
      • manager.rs: 使用 bollard 处理容器列表、启停逻辑。
      • mirror.rs: 处理 Docker 和 PHP 镜像源切换。
    • engine/: 核心业务引擎。
      • env_parser.rs: .env 文件解析器与格式化器（v0.1.0）
      • config_generator.rs: 可视化配置生成器（v0.1.0，含模板释放 resolve_template_dir/copy_template_file）
      • mirror_manager.rs: 统一镜像源管理器（v0.1.0）
      • backup_manifest.rs: 备份清单数据模型（v0.1.0）
      • backup_engine.rs: 增强备份引擎（v0.1.0）
      • restore_engine.rs: 恢复引擎（v0.1.0，zip-slip 防护/回滚包）
      • version_manifest.rs: 服务版本清单管理器（v0.2.0）
      • user_override_manager.rs: 用户版本覆盖管理器（v0.2.0，entry_kind: override/custom）
      • mirror_config_manager.rs: 用户镜像源配置管理器（v0.2.0）
      • workspace_manager.rs: 工作目录管理器（v0.3.0）
      • config_extractor.rs: 运行时配置提取（Phase 3，docker create+cp 提取默认配置）
      • mirror_config.rs: 镜像源配置（向后兼容）
      • site_manager.rs / user_config.rs / backup_options_store.rs: 站点定义 / 用户配置 / 备份选项持久化
    • commands/: 暴露给前端的 #[tauri::command] 接口，按业务域拆分为子模块。
      • mod.rs: 模块声明、re-export 所有命令。
      • paths.rs: 路径解析单一模块（project_root / app_config_dir / log_file）。
      • docker.rs: 容器 CRUD 操作（check_docker、list/start/stop/restart_container）。
      • env_config.rs: 环境配置生成、应用、启动/重启/停止环境。
      • mirror.rs: 镜像源预设管理、自定义配置、连接测试。
      • backup.rs: 备份创建、恢复预览/验证/执行、路径转换。
      • workspace.rs: 工作区管理、版本映射查询、用户覆盖、日志导出。
      • app.rs: 应用信息与更新相关命令。
    • lib.rs: 插件注册与指令分发中心。
    • logging.rs / macros.rs: 三层日志系统与 app_log! / ui_log! 宏。

✅ v0.1.0 已完成功能

1. 可视化环境配置（EnvConfigPage）

  • 需求覆盖: 需求 1.1-1.9
  • 实现状态: ✅ 完成
  • 核心功能:
    • GUI 界面选择服务类型（PHP、MySQL、Redis、Nginx）及版本
    • 端口配置与实时冲突检测
    • PHP 扩展多选配置
    • 自动生成 .env 文件和 docker-compose.yml
    • 保留用户自定义变量
    • 支持多 PHP 版本独立服务

2. 统一镜像源管理（MirrorPanel）

  • 需求覆盖: 需求 2.1-2.7
  • 实现状态: ✅ 完成
  • 核心功能:
    • 5 个预设方案（阿里云、清华、腾讯云、中科大、官方默认）
    • 4 类镜像源独立配置（Docker Registry、APT、Composer、NPM）
    • 连接测试功能（3 秒超时）
    • 一键应用预设或单独配置

3. 环境备份（BackupPage）

  • 需求覆盖: 需求 3.1-3.8, 6.1-6.4
  • 实现状态: ✅ 完成
  • 核心功能:
    • ZIP 格式备份包，包含 manifest.json
    • 打包 .env、docker-compose.yml、services/ 配置、.user-config/（镜像源/版本覆盖/站点等；不含备份页 UI 偏好 backup.json）
    • 可选：按站点相对路径的本地配置文件、全树、日志
    • SHA256 文件完整性校验
    • Tauri 事件进度通知
    • 部分失败容错处理
    • ⚠️ 数据库导出（mysqldump）尚未实现，属待完善项

4. 环境恢复（RestorePage）

  • 需求覆盖: 需求 4.1-4.10
  • 实现状态: ✅ 完成（自动改写冲突端口尚未做，见「待完善功能」）
  • 核心功能:
    • 备份包预览（manifest 解析、文件统计、端口冲突检测与建议端口）
    • SHA256 完整性验证
    • 路径遍历防护（zip-slip，恶意备份包整体拒绝）
    • 配置文件、项目文件、SQL 文件还原（SQL 导入执行待完善）
    • 站点宿主机路径跨机覆写
    • 恢复前自动回滚包 + 明细结果
    • 进度通知与错误汇总

5. 基础设施模块

  • env_parser.rs: .env 文件可靠读写，保留注释和空行（Property 9, 10）
  • backup_manifest.rs: Manifest 序列化/反序列化（Property 11, 12）
  • 测试覆盖: 后端单元测试 + 4 个集成测试（backup_restore、config_generation、workspace_commands、docker_manager）+ 前端组件测试（Vitest）

✅ v0.2.0 / v0.3.0 新增功能

1. 前端国际化（i18n）

  • 中/英双语支持，运行时动态切换（vue-i18n）
  • 用户可见日志统一为英文短句，并带 info/warn/error 等级（关于页可过滤面板显示）

2. 主题预设系统

  • 自动 / 明亮 / 暗黑三种模式，全组件适配

3. 工作区与版本管理

  • workspace_manager.rs: 多工作区切换，配置持久化到 workspace.json（app_data_dir）
  • version_manifest.rs: 服务版本清单（PHP/MySQL/Redis/Nginx）查询与推荐版本
  • user_override_manager.rs: 用户镜像覆盖（override）与完整自定义条目（custom）
  • mirror_config_manager.rs: 用户镜像源配置持久化

4. 跨平台权限映射（v0.3.1）

  • PUID/PGID 用户映射，解决 Docker 挂载目录权限问题

5. 其他改进

  • 自定义下拉选择组件（CustomSelect），支持搜索过滤和键盘导航
  • 后端命令按业务域拆分（docker/env_config/mirror/backup/workspace/app + paths）
  • GitHub Actions 多平台自动发布工作流
  • 环境启动逻辑重构，流式日志输出

✅ v0.4.0 新增功能

1. Nginx 站点管理

  • site_manager.rs + 环境配置页站点面板：多站点 server_name、挂载路径、public_dir、绑定 PHP/Nginx 服务
  • 生成托管 Nginx conf 与 compose 卷映射；元数据 .user-config/sites.json

2. 跨机恢复与备份增强

  • 恢复预览支持站点路径覆写；备份选项持久化（.user-config/backup.json）
  • 按站点相对路径打包本地配置；可选全树；manifest 记录站点路径元数据

3. 自定义版本映射

  • entry_kind: override | custom；映射表「编辑」/「新增」；custom 进入环境配置下拉
  • 与 L1 sync-version-manifest、L2 ConfigExtractor 分层正交

4. 用户配置收纳与关于页

  • 工作区用户文件统一 .user-config/
  • 关于页：日志等级、导出、检查更新（tauri-plugin-updater + GitHub Releases）

5. 运行时配置提取（Phase 3）

  • 应用配置前镜像存在性检测 / 拉取确认 / docker create + cp 提取默认配置

🛠️ 开发规范

Rust 后端

  1. 错误处理: 统一使用 Result<T, String> 或 Result<T, Box<dyn Error>>。暴露给前端的 Command 必须将错误转换为 String。
  2. 异步处理: 涉及 Docker 或文件 IO 的操作必须使用 async/await。
  3. 测试:
    • 单元测试：放在源文件内的 #[cfg(test)] mod tests { ... } 模块中
    • 集成测试：放在 src-tauri/tests/integration/ 目录下
    • 解析/生成类纯函数应抽为可直接测试的函数，测试必须包含真断言（禁止 assert!(true) 占位）
    • 安全或回归类测试建议标注：// Feature: {feature}, Property: {描述}
    • 运行测试：cargo test；CI 同时执行 cargo fmt --check 与 cargo clippy --all-targets -- -D warnings
  4. 模块注册:
    • 新增引擎模块需在 engine/mod.rs 中声明 pub mod xxx;
    • 新增命令子模块需在 commands/mod.rs 中声明并 re-export
    • 新增的 #[tauri::command] 函数需在 lib.rs 的 invoke_handler 中注册

Vue 前端

  1. 状态管理: 目前使用 ref 和 reactive 进行局部状态管理。
  2. 样式: 严格遵循 Tailwind CSS v4 规范。在组件内使用 @apply 时必须在 <style scoped> 中声明 @reference "tailwindcss";。
  3. 交互: 所有后端调用必须经过 invoke 封装，并处理 loading 和 error 状态。
  4. 类型定义: 前端 TypeScript 类型需与 Rust 后端的 Serialize/Deserialize 结构体对应，定义在 src/types/ 目录下。
  5. 测试:
    • 测试框架: Vitest + @vue/test-utils
    • 测试位置: 与被测试代码同级目录下的 __tests__/ 文件夹
    • 文件命名: {模块名}.spec.ts
    • 运行测试：npm run test 或 npm run test:run
    • 详细规范参见：DEV.md 第 6 节「测试规范」

📋 关键模块逻辑

1. 容器识别

系统仅识别以 ps- 为前缀的容器。

  • 过滤逻辑位于 src-tauri/src/docker/manager.rs。

2. Env_File 解析器（v0.1.0 新增）

  • 位置：src-tauri/src/engine/env_parser.rs
  • 功能：可靠读写 .env 文件，保留注释和空行
  • 特性：
    • 支持带引号的值（单引号/双引号）
    • 支持行内注释（#）
    • 支持空行和纯注释行
    • 往返一致性保证（parse → format → parse）

3. 配置生成器（v0.1.0 新增）

  • 位置：src-tauri/src/engine/config_generator.rs
  • 功能：根据 GUI 输入生成 .env 和 docker-compose.yml
  • 特性：
    • 端口冲突检测
    • 保留用户自定义变量
    • 使用 ${VAR} 插值语法生成 Compose 文件
    • 创建 dnmp 风格的目录结构（services/、data/、logs/）

4. 统一镜像源管理（v0.1.0 新增）

  • 位置：src-tauri/src/engine/mirror_manager.rs
  • 功能：统一管理 Docker、APT、Composer、NPM 镜像源
  • 特性：
    • 5 个预设方案
    • 单个类别独立配置
    • 3 秒超时连接测试

5. 备份引擎（v0.1.0 增强）

  • 位置：src-tauri/src/engine/backup_engine.rs
  • 功能：生成包含 manifest 的 ZIP 备份包
  • 特性：
    • SHA256 文件完整性校验
    • 打包 .env、docker-compose.yml、services/ 配置、用户自定义配置
    • 可选：项目文件（glob 模式）、日志
    • Tauri 事件进度通知
    • 部分失败容错处理

6. 恢复引擎（v0.1.0 新增）

  • 位置：src-tauri/src/engine/restore_engine.rs
  • 功能：解析备份包并还原环境
  • 特性：
    • 备份预览（manifest 解析）
    • SHA256 完整性验证
    • 路径遍历防护（zip-slip）
    • 配置文件、项目文件还原（SQL 导入执行待完善；端口冲突仅预览提示、不自动改写）

7. 备份清单（v0.1.0 新增）

  • 位置：src-tauri/src/engine/backup_manifest.rs
  • 功能：记录备份元数据和文件校验和
  • 特性：
    • serde_json 序列化/反序列化
    • 必需字段验证（version、timestamp、services）
    • 往返一致性保证

8. 服务版本清单（v0.2.0 新增）

  • 位置：src-tauri/src/engine/version_manifest.rs
  • 功能：管理 PHP/MySQL/Redis/Nginx 的服务版本清单
  • 特性：
    • 按服务类型查询可用版本
    • 推荐版本查询
    • 版本 ID 校验

9. 用户版本覆盖管理器（v0.2.0 新增）

  • 位置：src-tauri/src/engine/user_override_manager.rs
  • 功能：工作区侧版本覆盖与完整自定义条目（与 sync 清单 / ConfigExtractor 分层）
  • 特性：
    • entry_kind: override — 覆盖已有清单 ID 的 image_tag
    • entry_kind: custom — 新增完整 VersionEntry，进入映射表与环境配置下拉
    • 配置持久化到 .user-config/version_overrides.json（不做旧格式兼容）
    • 与 L1 sync-version-manifest、L2 运行时 docker create 提取正交，互不改写

10. 工作目录管理器（v0.3.0 新增）

  • 位置：src-tauri/src/engine/workspace_manager.rs
  • 功能：管理工作目录配置
  • 特性：
    • 工作目录持久化到 workspace.json
    • 加载/保存工作目录

📚 文档规范

文档体系（精简）

项目刻意不设历史归档目录，文档精简为 5 份常驻文件：

文档 位置 用途
README.md 根目录 项目介绍、用户快速开始
DEV.md 根目录 开发者贡献指南（环境/命令/测试/扩展）
AGENTS.md 根目录 AI Agent 协作规范（本文档）
CHANGELOG.md 根目录 变更记录（Keep a Changelog 格式）
ARCHITECTURE.md docs/ 系统架构、设计决策、核心流程

核心原则:

  • 变更记录 → 更新 CHANGELOG.md 的 [Unreleased] 段
  • 架构级变更 → 更新 docs/ARCHITECTURE.md
  • 面向用户的变更 → 更新 README.md
  • 开发者流程（命令/测试/扩展）→ 更新 DEV.md
  • 过时内容直接删除（git 历史可追溯），不保留 docs/history/ 之类的归档目录

文档编写规范

  1. 命名: 使用英文文件名，单词间用下划线分隔。
  2. 内容: 使用 Markdown，清晰的标题层级，代码示例使用语法高亮。
  3. 语言: 技术文档使用中文；代码注释使用中文；变量名和函数名使用英文。
  4. 更新: 修改代码后及时更新相关文档，保持文档与实现一致（详见「Agent 任务接入建议」）。

🚀 Agent 任务接入建议

如果你被分派了新任务，请遵循以下流程：

  1. 理解 Scope: 确认是前端 UI 调整还是后端 Rust 逻辑变更。
  2. 安全检查: 涉及 Docker 修改的操作应先调用 check_docker 指令。
  3. 权限校验: 若新增了 Tauri 插件调用，请务必更新 src-tauri/capabilities/default.json。
  4. TDD 流程:
    • 优先编写单元测试
    • 解析/生成类逻辑先抽纯函数再测
    • 运行 cargo test 确保所有测试通过
  5. 类型同步: 修改 Rust 数据结构后，同步更新 src/types/ 中的 TypeScript 类型定义。

🗺️ 后续开发重点 (给下个 Agent 的 Tip)

已完成的功能（v0.1.0 ~ v0.4.0）

✅ 环境可视化配置 - 完整实现需求 1.1-1.9，支持多 PHP 版本独立服务 ✅ 统一镜像源管理 - 完整实现需求 2.1-2.7 ✅ 环境备份 - 完整实现需求 3.1-3.8, 6.1-6.4（数据库 dump 除外） ✅ 环境恢复 - 完整实现需求 4.1-4.10（含预览端口冲突检测、站点路径覆写、回滚包） ✅ 前端国际化（i18n） - 中/英双语，运行时切换 ✅ 主题预设 - 自动/明亮/暗黑三种模式 ✅ 工作区与版本管理 - 多工作区、版本清单、override/custom ✅ 跨平台权限映射 - PUID/PGID 用户映射 ✅ Nginx 站点管理 - 多站点挂载与托管 conf ✅ 关于页与自动更新 - 日志等级/导出、GitHub Releases 更新 ✅ 测试框架 - 单元测试 + 集成测试 + 组件测试

当前版本定位（v0.4.0）

核心定位: PHP-Stack v0.4.0 是一个环境配置管理与迁移工具，专注于：

  • ✅ 可视化配置生成（替代手动编辑 .env 和 docker-compose.yml）
  • ✅ Nginx 多站点挂载与托管 conf
  • ✅ 镜像源统一管理（加速国内开发体验）
  • ✅ 环境备份与恢复（含跨机路径重映射）
  • ✅ 国际化与主题（中英双语 + 明暗主题）
  • ✅ 工作区与版本管理（清单 + 用户 override/custom）
  • ✅ 关于页与自动更新

不包含的功能（未来版本可能考虑）:

  • ❌ 软件管理中心（多版本一键安装/拉取编排）— 镜像需用户本地具备或在应用配置时确认拉取
  • ❌ 数据库自动 dump / SQL 自动导入 — 当前可手动备份数据库文件或自行 mysqldump

设计理念:

  • 轻量级: 专注于配置管理和环境迁移，不做复杂的容器编排
  • 透明性: 生成的配置文件完全可见可编辑，不隐藏任何细节
  • 兼容性: 与 dnmp 等项目保持兼容，便于团队协作

待完善功能

恢复时自动改写冲突端口（中优先级）

  • 当前状态：恢复预览读取 manifest.services 端口映射，用本机 TcpListener 绑定探测占用；冲突时在预览页展示服务/占用端口/建议端口
  • 说明：恢复仍写入备份包原配置，不自动改写端口；启动前用户可手动改 .env 或停止占用进程
  • 未做：恢复时按建议端口自动改写 .env / compose（设计稿中的 port_overrides）

数据库备份/恢复（低优先级）

  • 目标：完善备份/恢复引擎中的数据库导出与导入
  • 当前状态：备份不导出数据库（BackupOptions 无 include_database），恢复仅提取 SQL 文件到本地、不执行导入
  • 待完善：
    • 完整的 mysqldump 执行（使用 bollard exec API）
    • SQL 导入执行（mysql client 或 bollard exec）
    • 事务性恢复（失败时回滚）
  • 优先级: 低（当前版本可使用手动方式备份/恢复数据库）

发布流水线签名密钥

  • 自动更新已完成（tauri-plugin-updater + GitHub Releases）；正式发版流水线需配置 TAURI_SIGNING_PRIVATE_KEY 签名密钥

开发建议

  1. 稳定优先: v0.4.x 重点是稳定性、站点/版本映射体验与发版质量
  2. Bug 修复: 优先处理用户反馈的问题和边界情况
  3. 性能优化: 大文件备份的流式处理已落地；可评估增量备份
  4. 文档同步: 变更进 CHANGELOG、架构进 ARCHITECTURE、过时直接删（见「文档规范」）
  5. 测试补全: 继续补全前端组件测试与后端集成测试；清单相关断言避免硬编码「最新 ID」