初始化
This commit is contained in:
250
.cursor/skills/env-setup/SKILL.md
Normal file
250
.cursor/skills/env-setup/SKILL.md
Normal file
@@ -0,0 +1,250 @@
|
||||
---
|
||||
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 连接正常
|
||||
- [ ] 数据库迁移成功
|
||||
- [ ] 所有环境变量已配置
|
||||
Reference in New Issue
Block a user