warden-dev

Warden Agent 技能

Warden 是用于 docker-compose 的本地封装工具，可自动配置 DNS（dnsmasq）、反向代理（Traefik）和 Web 邮件（Mailpit）。项目 .env 文件用于生成临时的 docker-compose.yml。使用 warden env config 预览。

快速开始

warden env-init myproject magento2   # Initialize project
warden svc up -d                     # Start global services (Traefik, DNS, Mailpit)
warden env up -d                     # Start project containers
warden shell                        # Interactive shell in php-fpm

环境生命周期

命令	用途	示例
warden env-init	初始化新项目	warden env-init mystore magento2
warden env up	启动环境	warden env up -d
warden env down	停止环境	warden env down
warden env config	预览 docker-compose	warden env config
warden env ps	列出容器	warden env ps
warden env pull	拉取镜像	warden env pull
warden env logs -f nginx	持续查看日志	warden env logs -f nginx
warden env exec php-fpm bash	进入容器执行命令	warden env exec php-fpm bash

数据库操作

命令	用途	示例
warden db connect	交互式连接 MySQL	warden db connect
warden db import	导入 SQL 转储文件	参见下方模式
warden db dump	导出数据库	warden db dump > backup.sql
warden db upgrade	升级 MariaDB/MySQL	warden db upgrade

导入模式（大型转储文件推荐使用）：

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	启动全局服务
warden svc down	停止全局服务
warden svc ps	列出全局服务
warden status	列出正在运行的环境

文件同步（macOS）

命令	用途
warden sync start	启动 Mutagen 同步
warden sync monitor	监控同步状态
warden sync flush	刷新同步
warden sync reset	重置同步

Redis / Valkey

warden redis              # Interactive Redis CLI
warden redis FLUSHALL      # Execute command
warden valkey              # Valkey (Redis alternative)

环境类型

支持：magento2、magento1、laravel、symfony、wordpress、drupal、shopware、cakephp、local。参见 references/environments.md。

关键 .env 变量

项目 .env 控制服务和版本。完整参考请参见 references/env-variables.md。

变量	说明
WARDEN_ENV_NAME	唯一的项目标识符
WARDEN_ENV_TYPE	环境类型
TRAEFIK_DOMAIN	基础域名（默认：{name}.test）
PHP_VERSION	PHP 版本（7.4、8.1–8.4）
WARDEN_DB、WARDEN_REDIS 等	服务开关（1/0）
MYSQL_DISTRIBUTION_VERSION	MariaDB/MySQL 版本

服务名称映射

.env 变量	容器名称
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）。

服务	URL
Traefik Dashboard	https://traefik.warden.test
Web 邮件（Mailpit）	https://webmail.warden.test
Portainer	https://portainer.warden.test
phpMyAdmin	https://phpmyadmin.warden.test

**电子邮件（Mailpit）：**无需配置 SMTP。Warden 会将 sendmail 路由到 Mailpit。所有邮件都可在 https://webmail.warden.test 查看。

框架兼容性

针对“匹配 Magento 2.4.8 要求”的请求：

1. 搜索官方文档中的系统要求
2. 映射到 .env：PHP → PHP_VERSION，数据库 → MYSQL_DISTRIBUTION_VERSION 等
3. 使用匹配的版本更新 .env

Agent 行为示例

**生成服务表：**读取 .env，将 WARDEN_* 变量映射为服务状态，并输出表格（服务 | 状态 | 版本）。

**验证 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 服务器名称 {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 – 工作流示例