---
name: env-setup
version: 2.0.0
description: "初始化 PHP Hyperf + Vue 3 双栈开发环境。当需要项目初始化、环境配置或安装依赖时使用。含 Docker Compose 和数据库初始化。"
---

# 🔧 Environment Setup (PHP Hyperf + Vue 3 Dual Stack)

## 触发条件

用户要求初始化项目环境、配置开发工具链、设置环境变量。

## 执行流程

### 1. 检测系统依赖

```bash
echo "=== System Dependencies ==="

# PHP
php -v 2>/dev/null && echo "✅ PHP installed" || echo "❌ PHP not found (need >= 8.1)"

# Swoole
php -m 2>/dev/null | grep -i swoole && echo "✅ Swoole installed" || echo "❌ Swoole not found (need >= 5.0)"

# Composer
composer --version 2>/dev/null && echo "✅ Composer installed" || echo "❌ Composer not found"

# Node.js
node -v 2>/dev/null && echo "✅ Node.js installed" || echo "❌ Node.js not found (need >= 20)"

# npm
npm -v 2>/dev/null && echo "✅ npm installed" || echo "❌ npm not found"

# Docker
docker --version 2>/dev/null && echo "✅ Docker installed" || echo "⚠️ Docker not found (optional for local dev)"

# Docker Compose
docker compose version 2>/dev/null && echo "✅ Docker Compose installed" || echo "⚠️ Docker Compose not found"
```

### 2. 后端初始化 (PHP Hyperf)

```bash
cd Case-Database-Backend

# 安装 PHP 依赖
composer install

# 复制环境变量
if [ ! -f ".env" ] && [ -f ".env.example" ]; then
    cp .env.example .env
    echo "✅ .env created from .env.example"
    echo "⚠️ Please fill in required values: DB_HOST, DB_DATABASE, REDIS_HOST, JWT_SECRET"
fi

# 验证 Hyperf 启动
php bin/hyperf.php start --dry-run 2>/dev/null || php bin/hyperf.php di:init-proxy
```

### 3. 前端初始化 (Vue 3 + Vite)

```bash
for dir in Case-Database-Frontend-user Case-Database-Frontend-admin; do
  echo "=== $dir ==="
  cd $dir
  
  # 安装 Node 依赖
  npm install
  
  # 复制环境变量
  if [ ! -f ".env.local" ] && [ -f ".env.example" ]; then
      cp .env.example .env.local
      echo "✅ .env.local created from .env.example"
  fi
  cd ..
done
```

### 4. 数据库初始化

```bash
cd Case-Database-Backend

# 运行迁移
php bin/hyperf.php migrate

# 运行种子（如有）
php bin/hyperf.php db:seed
```

### 5. Docker Compose 启动（可选）

```bash
# 一键启动全部服务
docker compose up -d

# 验证服务状态
docker compose ps
```

### 6. 初始化工具链

| 工具 | 配置文件 | 前端/后端 |
|------|---------|---------|
| jsconfig | `jsconfig.json` | 前端 |
| ESLint | `.eslintrc.*` / `eslint.config.*` | 前端 |
| Prettier | `.prettierrc` | 前端 |
| Husky | `.husky/` | 全栈 |
| PHPStan | `phpstan.neon` | 后端 |
| PHP CS Fixer | `.php-cs-fixer.php` | 后端 |

### 7. 验证环境

```bash
echo "=== Backend Verification ==="
cd Case-Database-Backend
php -v
composer --version
php bin/hyperf.php --version 2>/dev/null || echo "Run: php bin/hyperf.php start"

echo ""
echo "=== Frontend Verification ==="
for dir in Case-Database-Frontend-user Case-Database-Frontend-admin; do
  echo "=== $dir Verification ==="
  cd $dir
  node -v
  npm -v
  npm run build --dry-run 2>/dev/null || echo "Run: npm run dev"
  cd ..
done

echo ""
echo "=== Services ==="
docker compose ps 2>/dev/null || echo "Docker Compose not running"
```

## 关键环境变量

### 后端 (.env)

| 变量 | 说明 | 示例 |
|------|------|------|
| `APP_NAME` | 应用名称 | `MyApp` |
| `APP_ENV` | 环境 | `dev` / `production` |
| `DB_HOST` | MySQL 主机 | `127.0.0.1` |
| `DB_PORT` | MySQL 端口 | `3306` |
| `DB_DATABASE` | 数据库名 | `myapp` |
| `DB_USERNAME` | 数据库用户 | `root` |
| `DB_PASSWORD` | 数据库密码 | *(Secret)* |
| `REDIS_HOST` | Redis 主机 | `127.0.0.1` |
| `REDIS_PORT` | Redis 端口 | `6379` |
| `JWT_SECRET` | JWT 密钥 | *(auto-generate)* |

### 前端 (.env.local)

| 变量 | 说明 | 示例 |
|------|------|------|
| `VITE_API_BASE_URL` | API 地址 | `http://localhost:9501` |
| `VITE_WS_URL` | WebSocket 地址 | `ws://localhost:9502` |
| `VITE_APP_TITLE` | 应用标题 | `MyApp` |

## 密钥管理最佳实践

### 原则

- **永不硬编码** — 密钥不进入代码仓库
- **运行时注入** — 密钥在部署/启动时注入，不写入磁盘文件
- **最小权限** — 每个服务只拥有必需的密钥访问权限
- **定期轮换** — 密钥和 Token 设置过期时间并定期轮换

### 推荐方案（按场景选择）

| 场景 | 方案 | 复杂度 |
|---|---|---|
| 本地开发 | `.env` 文件 (已在 .gitignore) | 🟢 低 |
| CI/CD | GitHub Secrets / GitLab Variables | 🟡 中 |
| 生产环境 | HashiCorp Vault / 云 KMS | 🔴 高 |
| Docker 部署 | Docker Secrets / Compose env_file | 🟡 中 |

### 本地开发密钥管理

```bash
# ✅ .env 文件必须在 .gitignore 中
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore

# ✅ 提供 .env.example 作为模板（无真实密钥）
cp .env .env.example
# 手动清空 .env.example 中的敏感值
```

### Docker 部署密钥注入

```yaml
# ❌ BAD: docker-compose.yml 中硬编码密钥
services:
  app:
    environment:
      DB_PASSWORD: "my_secret_password"

# ✅ GOOD: 通过 .env 文件注入
services:
  app:
    env_file:
      - .env
    environment:
      DB_PASSWORD: ${DB_PASSWORD}
```

### JWT 密钥生成

```bash
# 生成强随机 JWT 密钥
openssl rand -base64 64

# 或使用 PHP
php -r "echo bin2hex(random_bytes(32));"
```

### 检查密钥安全

```bash
# 检查是否有密钥意外提交到仓库
rg -rn "(?i)(api.?key|secret|password|token)\s*[=:]\s*['\"][a-zA-Z0-9]{8,}" \
  --glob '!vendor/**' --glob '!node_modules/**' --glob '!*.lock' --glob '!.env*'
```

## 常见问题排查

| 问题 | 解决方案 |
|------|---------|
| Swoole 未安装 | `pecl install swoole` 或使用 Docker |
| Composer 依赖失败 | `composer clear-cache && composer install` |
| Node 版本不匹配 | 使用 `nvm use 20` 切换版本 |
| MySQL 连接失败 | 检查 `.env` 中 DB_HOST 和端口，确认 MySQL 正在运行 |
| Redis 连接失败 | 检查 `.env` 中 REDIS_HOST，确认 Redis 正在运行 |
| Hyperf 启动失败 | 检查 `runtime/` 目录权限，运行 `php bin/hyperf.php di:init-proxy` |
| 端口冲突 9501 | `lsof -i :9501` 查看占用进程 |

## 验证清单

- [ ] PHP >= 8.1 且 Swoole >= 5.0 扩展已安装
- [ ] Composer 依赖安装成功
- [ ] Node.js >= 20 且 npm 安装成功
- [ ] `php bin/hyperf.php start` 可正常启动 (HTTP 9501)
- [ ] `npm run dev` 可正常启动 (Vite dev server)
- [ ] MySQL 和 Redis 连接正常
- [ ] 数据库迁移成功
- [ ] 所有环境变量已配置