多环境隔离器

使用一条命令，为基于 uvicorn/FastAPI 的项目（支持 Vue/React 前端）生成完全隔离的开发（dev）、测试（test）、生产（prod）环境。

该能力的作用

本能力解决多智能体 AI 团队中的一个常见问题：开发者、测试人员与生产用户相互干扰。 它生成一套完整的环境隔离方案，确保：

• Valina（开发者） 可在 8000/3000 端口自由试错，不影响他人
• Choco（测试人员） 可在 8001/3001 端口使用隔离的测试数据及 Playwright 测试验证发布版本
• 生产环境 稳定运行于 8002/4173 端口，完全不受开发/测试活动影响

每个环境均拥有独立的配置文件、启动脚本（后端 + 前端）、数据库、媒体存储目录及 Playwright 测试配置——彼此彻底隔离。

生成内容说明

执行初始化脚本后，将在目标项目内创建如下结构：

your-project/
├── .env.dev              # 开发配置：DEBUG=True，启用热重载，无速率限制
├── .env.test             # 测试配置：启用速率限制，QA 相关设置
├── .env.prod             # 生产配置：DEBUG=False，启用安全 CORS，多 worker 模式
├── scripts/
│   # 后端脚本
│   ├── start-backend-dev.sh    # 在 8000 端口启动开发服务（含 --reload）
│   ├── start-backend-test.sh   # 在 8001 端口启动测试服务
│   └── start-backend-prod.sh   # 在 8002 端口启动生产服务（自动 worker 数量）
│   # 前端脚本（Vue/React）
│   ├── start-frontend-dev.sh   # 在 3000 端口启动开发前端
│   ├── start-frontend-test.sh  # 在 3001 端口启动测试前端
│   └── start-frontend-prod.sh  # 在 4173 端口启动生产前端（预览模式）
│   # 测试脚本
│   └── run-playwright-tests.sh # 在测试环境运行 Playwright 端到端测试
├── data/
│   ├── dev/              # 开发数据库 + 媒体上传目录（可安全删除）
│   │   └── media/
│   ├── test/             # 测试数据库 + 媒体上传目录
│   │   └── media/
│   └── prod/             # 生产数据库 + 媒体上传目录（请务必定期备份！）
│       └── media/
├── docs/
│   └── MULTI_ENV_SETUP.md  # 自动生成的团队部署指南
├── cloud_docs/frontend/
│   └── playwright.config.ts  # Playwright 测试配置（仅当前端存在时生成）
└── .gitignore            # 已更新，排除 .env.* 和 data/ 目录

使用方法

步骤 1：运行初始化脚本

python3 scripts/setup_envs.py /path/to/your-project 
  --name "Your Project Name" 
  --dev-backend-port 8000 
  --dev-frontend-port 3000 
  --test-backend-port 8001 
  --test-frontend-port 3001 
  --prod-backend-port 8002 
  --prod-frontend-port 4173 
  --dev-user "Valina" 
  --test-user "Choco" 
  --app-module "server.main:app" 
  --frontend-dir "cloud_docs/frontend"

除 --name 外，其余参数均为可选，均已预设合理默认值。

步骤 2：启动各环境

# Valina（开发）使用
./scripts/start-dev.sh        # 同时启动后端（8000）和前端（3000）

# Choco（测试）使用
./scripts/start-test.sh       # 同时启动后端（8001）和前端（3001）
./scripts/run-playwright-tests.sh  # 运行端到端测试

# 生产环境使用
./scripts/start-prod.sh       # 同时启动后端（8002）和前端（4173）

步骤 2：自定义配置

编辑生成的 .env.dev、.env.test、.env.prod 文件，添加项目专属配置，例如 API 密钥、外部服务地址等。

步骤 3：启动任一环境

# 启动开发环境（启用热重载）
./scripts/start-dev.sh

# 启动测试环境
./scripts/start-test.sh

# 启动生产环境
./scripts/start-prod.sh

每个脚本均加载其对应 .env.* 配置文件，绑定独立端口，并写入各自的 data/ 子目录。

命令参考

python3 scripts/setup_envs.py  --name  [options]

各环境关键差异速览

推荐的 Git 分支策略

采用本方案的团队建议如下分支模型：

main ──────────── 生产环境（start-prod.sh）— 端口 8002/4173
  ├── release/* ── 测试环境（start-test.sh + run-playwright-tests.sh）— 端口 8001/3001
  └── feature/* ── 开发环境（start-dev.sh）— 端口 8000/3000

1. Valina（开发者） 在 feature/* 分支开发，部署至开发环境（8000/3000）
2. 合并至 release/* 分支后，Choco（测试人员） 在测试环境（8001/3001）进行验证
3. Choco 运行 Playwright 测试：./scripts/run-playwright-tests.sh
4. 测试通过后，合并至 main 分支，并部署至生产环境（8002/4173）

并行开发与测试

核心优势：Valina 与 Choco 可同时工作，互不冲突！

时间  | Valina（开发）              | Choco（测试）
------|---------------------------|---------------------------
14:00 | start-dev.sh（8000/3000）  | -
14:05 | 继续编码...                | start-test.sh（8001/3001）
14:10 | 继续编码...                | run-playwright-tests.sh
14:20 | 继续编码...                | 测试通过！提交结果
14:25 | 继续编码...                | stop-test.sh

零端口冲突！零数据干扰！ ✅

重要注意事项

• 已有文件不会被覆盖。 若 .env.dev 已存在，脚本将跳过并输出警告。可安全重复执行。
• 后端启动脚本专为 uvicorn 设计。 生成的 start-backend-*.sh 脚本调用 uvicorn 命令。如使用其他框架，请在生成后手动修改脚本。
• 前端脚本支持 Vue/React。 生成的 start-frontend-*.sh 脚本使用 npm run dev 和 npm run preview。Vite 项目可开箱即用。
• 生产环境 JWT 密钥必须更换。 生成的 .env.prod 中 JWT_SECRET 仅为占位符，请上线前替换为强随机值。
• 请备份生产数据。 data/prod/ 目录包含生产数据库，请建立定期备份机制。
• Playwright 测试依赖 Node.js。 测试脚本要求已安装 Playwright：npm install -D @playwright/test
• 测试数据清理建议。 Playwright 测试运行后，建议清理测试数据以保持测试环境整洁。

详细配置参考

关于所有环境变量及故障排查，请查阅 references/config-options.md