feeling
/
auto-deploy-demo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
auto-deploy-demo/.trae/specs/nginx-dynamic-routing/spec.md

8.4 KiB
Raw Blame History

动态路由与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):

# 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):

# 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. 重载失败时回滚