auto-deploy-demo/.trae/specs/nginx-dynamic-routing/spec.md

# 动态路由与Nginx自动化配置 Spec

## Why
当前系统为每个项目分配独立端口（9000-9100），存在以下问题：
1. 服务器防火墙需要开放大量端口
2. URL不够友好（需要带端口号）
3. 手动配置Nginx反向代理繁琐

通过动态路由+Nginx自动化配置，可以实现：
- 所有项目共用单一端口（80/443）
- 友好的URL路径（如 `/project/{id}/`）
- 自动化Nginx配置更新，无需手动干预

## What Changes
- **新增** Nginx配置管理服务
- **新增** Nginx配置模板系统
- **修改** 项目访问方式从多端口改为动态路由
- **修改** processManager 启动逻辑，使用固定内部端口
- **新增** Nginx配置自动重载机制
- **新增** 本地开发模式支持（可选安装Nginx）

## Impact
- Affected specs: 项目部署流程、URL生成规则、端口管理
- Affected code: 
  - `server/services/processManager.js`
  - `server/services/projectService.js`
  - `server/config/index.js`
  - 新增 `server/services/nginxManager.js`
  - 新增 `server/templates/nginx/` 配置模板

## ADDED Requirements

### Requirement: Nginx配置管理服务
系统 SHALL 提供Nginx配置管理服务，支持自动生成和更新Nginx配置。

#### Scenario: 创建项目时生成Nginx配置
- **WHEN** 用户创建新项目
- **THEN** 系统自动为该项目生成Nginx location配置块
- **AND** 配置文件保存到指定目录
- **AND** 自动重载Nginx使配置生效

#### Scenario: 删除项目时清理Nginx配置
- **WHEN** 用户删除项目
- **THEN** 系统自动移除该项目的Nginx配置
- **AND** 自动重载Nginx使配置生效

#### Scenario: 启动项目时更新upstream
- **WHEN** 项目启动成功
- **THEN** 系统更新Nginx upstream配置指向正确的内部端口
- **AND** 自动重载Nginx使配置生效

### Requirement: 动态路由访问
系统 SHALL 通过动态路由路径访问不同项目，而非独立端口。

#### Scenario: 访问项目
- **WHEN** 用户访问 `/project/{projectId}/`
- **THEN** Nginx将请求代理到对应项目的内部服务
- **AND** 项目内部服务运行在固定内部端口范围（如127.0.0.1:9000-9100）

#### Scenario: 生成项目URL
- **WHEN** 项目启动成功
- **THEN** 系统生成格式为 `{BASE_URL}/project/{projectId}/` 的访问地址
- **AND** 不再包含端口号

### Requirement: 本地开发模式支持
系统 SHALL 支持本地开发环境，可选择是否使用Nginx。

#### Scenario: 本地无Nginx环境
- **WHEN** 系统检测到本地未安装或未配置Nginx
- **THEN** 系统回退到原有的多端口模式
- **AND** 在日志中提示可安装Nginx获得更好体验

#### Scenario: 本地有Nginx环境
- **WHEN** 系统检测到本地已安装Nginx
- **THEN** 系统使用动态路由模式
- **AND** 自动配置Nginx

### Requirement: Nginx配置模板
系统 SHALL 使用模板化方式管理Nginx配置。

#### Scenario: 主配置模板
- **GIVEN** 系统需要生成Nginx主配置
- **WHEN** 初始化或配置变更
- **THEN** 使用预定义模板生成 `auto-deploy.conf`
- **AND** 模板支持变量替换（如端口范围、项目列表）

#### Scenario: 项目location模板
- **GIVEN** 需要为项目生成location配置
- **WHEN** 创建或更新项目配置
- **THEN** 使用location模板生成配置片段
- **AND** 支持SPA路由回退处理

### Requirement: 配置热重载
系统 SHALL 在配置变更后自动重载Nginx。

#### Scenario: 配置变更后重载
- **WHEN** Nginx配置文件被修改
- **THEN** 系统执行 `nginx -s reload` 命令
- **AND** 检查重载结果
- **AND** 失败时回滚配置并记录错误日志

### Requirement: 环境配置扩展
系统 SHALL 扩展环境配置以支持Nginx相关设置。

#### Scenario: 新增环境变量
- **GIVEN** 用户配置 `.env` 文件
- **WHEN** 系统读取配置
- **THEN** 支持以下新增配置项：
  - `USE_NGINX` - 是否使用Nginx（true/false/auto）
  - `NGINX_CONFIG_DIR` - Nginx配置目录路径
  - `NGINX_TEMPLATE_PATH` - 配置模板路径
  - `NGINX_RELOAD_CMD` - Nginx重载命令

## MODIFIED Requirements

### Requirement: 项目URL生成
**原需求**: 项目URL格式为 `http://{domain}:{port}/`
**修改为**: 项目URL格式为 `{BASE_URL}/project/{projectId}/`

### Requirement: 端口管理
**原需求**: 项目使用外部可访问端口（9000-9100）
**修改为**: 项目使用内部端口（127.0.0.1:9000-9100），外部通过Nginx代理访问

## Technical Design

### 架构设计

```
                    ┌─────────────────────────────────────┐
                    │           Nginx (80/443)            │
                    │                                     │
                    │  location /project/xxx/ {           │
                    │      proxy_pass http://127.0.0.1:9000│
                    │  }                                  │
                    └──────────────┬──────────────────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              │                    │                    │
              ▼                    ▼                    ▼
       ┌──────────┐         ┌──────────┐         ┌──────────┐
       │ 项目1     │         │ 项目2     │         │ 项目N     │
       │ :9000    │         │ :9001    │         │ :90xx    │
       │(内部端口) │         │(内部端口) │         │(内部端口) │
       └──────────┘         └──────────┘         └──────────┘
```

### 文件结构

```
server/
├── services/
│   ├── nginxManager.js      # 新增：Nginx配置管理
│   ├── processManager.js    # 修改：端口绑定127.0.0.1
│   └── projectService.js    # 修改：URL生成逻辑
├── templates/
│   └── nginx/
│       ├── main.conf.tpl    # 主配置模板
│       └── location.conf.tpl # location配置模板
└── config/
    └── index.js             # 修改：新增Nginx配置项

nginx/
└── sites-enabled/
    └── auto-deploy.conf     # 生成的Nginx配置
```

### Nginx配置模板示例

**主配置模板 (main.conf.tpl)**:
```nginx
# Auto-generated by auto-deploy-demo
# Do not edit manually

upstream projects {
    # 项目upstream配置将由系统自动生成
}

server {
    listen {{PORT}};
    server_name {{SERVER_NAME}};
    
    # 管理后台
    location / {
        proxy_pass http://127.0.0.1:{{MANAGER_PORT}};
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    # API接口
    location /api/ {
        proxy_pass http://127.0.0.1:{{MANAGER_PORT}}/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    # 项目路由 - 由系统动态生成
    {{PROJECT_LOCATIONS}}
}
```

**Location配置模板 (location.conf.tpl)**:
```nginx
# Project: {{PROJECT_NAME}} ({{PROJECT_ID}})
location /project/{{PROJECT_ID}}/ {
    proxy_pass http://127.0.0.1:{{PROJECT_PORT}}/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # SPA路由支持
    try_files $uri $uri/ /project/{{PROJECT_ID}}/index.html;
}
```

### 核心流程

**项目启动流程**:
```
1. 查找可用内部端口
2. 启动项目服务（绑定127.0.0.1）
3. 生成/更新Nginx location配置
4. 重载Nginx
5. 返回项目URL: {BASE_URL}/project/{id}/
```

**项目停止流程**:
```
1. 停止项目进程
2. 更新Nginx配置（移除upstream或标记为down）
3. 重载Nginx
```

**项目删除流程**:
```
1. 停止项目（如运行中）
2. 删除项目文件
3. 移除Nginx location配置
4. 重载Nginx
```

### 本地开发模式

当 `USE_NGINX=auto` 时：
1. 检测系统是否安装Nginx
2. 检测Nginx配置目录是否可写
3. 若检测失败，回退到多端口模式
4. 在控制台输出当前模式信息

### 安全考虑

1. Nginx配置文件权限控制
2. 配置变更前备份
3. 配置验证（`nginx -t`）后再重载
4. 重载失败时回滚