Warden 是一个本地 docker-compose 封装工具，用于管理基于 Docker 的本地开发环境。它自动处理 DNS（dnsmasq）、反向代理（Traefik）和网页邮箱（Mailpit），并根据项目 .env 动态生成 docker-compose.yml。可用 warden env config 预览生成的配置。
【用途】 Warden 面向需要在本地搭建 PHP/Node 项目开发环境的开发者，常用于 Magento、Laravel、Symfony、WordPress、Drupal 等项目。
【主要能力】
- 环境生命周期管理：提供 env-init（初始化新项目）、env up（启动环境）、env down（停止环境）、env config（预览 docker-compose）、env ps（列出容器）、env pull（拉取镜像）、env logs（跟随日志）、env exec（进入容器执行命令）等命令。
- 数据库操作：支持 db connect（交互式 MySQL）、db import（导入 SQL dump）、db dump（导出数据库）、db upgrade（升级 MariaDB/MySQL）。大文件导入推荐使用管道方式，例如 pv dump.sql.gz | gzip -d | warden db import、gzip -dc dump.sql.gz | warden db import 或 warden db import < database.sql。
- Shell 访问：warden shell 提供 PHP-FPM 容器的交互式 Shell（默认 bash）；warden debug 提供启用 Xdebug 的 Shell；warden blackfire 用于 Blackfire 性能分析（如 warden blackfire run php script.php）；warden spx 用于 PHP SPX 分析。使用 Xdebug 调试时应使用 warden debug 而非 warden shell。
- 服务管理：warden svc up -d 启动全局服务、svc down 停止、svc ps 列出全局服务、warden status 列出运行中的环境。
- 文件同步（macOS）：支持 sync start、sync monitor、sync flush、sync reset 管理 Mutagen 同步。
- Redis / Valkey：warden redis 进入交互式 Redis CLI，warden redis FLUSHALL 执行命令；warden valkey 操作 Valkey（Redis 替代）。
【使用方式】 快速开始：warden env-init myproject magento2 初始化项目 → warden svc up -d 启动全局服务 → warden env up -d 启动项目容器 → warden shell 进入 php-fpm 交互式 Shell。 环境类型支持：magento2、magento1、laravel、symfony、wordpress、drupal、shopware、cakephp、local。 关键 .env 变量包括：WARDEN_ENV_NAME（唯一项目标识）、WARDEN_ENV_TYPE（环境类型）、TRAEFIK_DOMAIN（基础域名，默认 {name}.test）、PHP_VERSION（7.4、8.1–8.4）、WARDEN_DB、WARDEN_REDIS 等服务开关（1/0）、MYSQL_DISTRIBUTION_VERSION（MariaDB/MySQL 版本）。服务开关与容器名对应关系：WARDEN_DB=1 对应 db，WARDEN_REDIS=1 对应 redis，WARDEN_OPENSEARCH=1 对应 opensearch，WARDEN_ELASTICSEARCH=1 对应 elasticsearch，WARDEN_VARNISH=1 对应 varnish，WARDEN_RABBITMQ=1 对应 rabbitmq，WARDEN_NGINX=1 对应 nginx，PHP_VERSION 对应 php-fpm 与 php-debug。
【全局服务与 URL】 默认域名为 warden.test，可在 ~/.warden/.env 中通过 WARDEN_SERVICE_DOMAIN 配置。Traefik Dashboard 地址为 https://traefik.warden.test，Webmail（Mailpit）为 https://webmail.warden.test，Portainer 为 https://portainer.warden.test，phpMyAdmin 为 https://phpmyadmin.warden.test。邮件无需 SMTP 配置，Warden 会把 sendmail 路由到 Mailpit，所有邮件可在 https://webmail.warden.test 查看。
【框架兼容性处理】 当需要“匹配 Magento 2.4.8 要求”这类请求时，流程为：检索官方文档中的系统要求 → 映射到 .env（PHP 对应 PHP_VERSION、数据库对应 MYSQL_DISTRIBUTION_VERSION 等）→ 用匹配到的版本更新 .env。
【智能体行为示例】 生成服务表：读取 .env，将 WARDEN_* 变量映射为服务状态，输出表格（Service | Status | Version）。验证 PHP 是否运行：执行 warden env ps，检查 php-fpm、php-debug、php-blackfire。排查站点无法访问：warden svc ps → warden env ps → ping app.{project}.test → warden env logs nginx。Xdebug 不工作：使用 warden debug，核验 IDE server name 为 {project}-docker、端口 9003、XDEBUG_SESSION cookie。
【参考文档】 references/commands.md 完整命令参考、references/environments.md 环境类型、references/env-variables.md .env 变量参考、references/global-services.md 服务 URL 与配置、references/troubleshooting.md 常见问题与解决、examples/workflows.md 工作流示例。