auto-deploy-demo/README.md

# 快速Demo演示系统

一个简易的前端项目部署管理平台，支持快速上传、部署和运行前端演示项目。

## 功能特性

- **快速部署** - 拖拽上传文件，一键启动项目
- **多项目支持** - 同时运行多个演示项目
- **自动端口分配** - 自动分配可用端口（9000-9100）
- **SPA路由支持** - 自动处理前端路由刷新问题
- **安全登录** - 支持登录失败锁定机制
- **密码修改** - 用户可自行修改密码
- **域名配置** - 支持自定义域名生成项目链接
- **Nginx动态路由** - 支持Nginx反向代理，统一端口访问

## 技术栈

- **后端**: Node.js + Express
- **前端**: Vue 3 + Vite + Tailwind CSS
- **状态管理**: Pinia
- **进程管理**: PM2
- **反向代理**: Nginx（可选）

## 环境要求

- Node.js >= 16.0.0
- npm >= 8.0.0
- 操作系统: Windows / Linux / macOS
- Nginx（可选，用于动态路由模式）

## 运行模式

系统支持两种运行模式：

| 模式 | 说明 | URL格式 | 适用场景 |
|------|------|---------|----------|
| **多端口模式** | 每个项目独立端口 | `http://domain:9000/` | 本地开发、无Nginx环境 |
| **Nginx动态路由模式** | 所有项目共用80端口 | `http://domain/project/{id}/` | 服务器部署、生产环境 |

## 快速开始

### 安装依赖

```bash
# 安装后端依赖
npm install

# 安装前端依赖并构建
cd client
npm install
npm run build
cd ..
```

### 配置环境变量

复制配置文件并修改：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# 服务端口
PORT=8888

# 基础域名（部署到服务器时配置）
BASE_DOMAIN=your-domain.com

# 项目端口范围
PROJECT_PORT_START=9000
PROJECT_PORT_END=9100

# Nginx配置（动态路由模式）
USE_NGINX=auto
NGINX_CONFIG_DIR=./nginx/sites-enabled
NGINX_TEMPLATE_PATH=./server/templates/nginx
NGINX_RELOAD_CMD=nginx -s reload
NGINX_TEST_CMD=nginx -t
```

### 启动服务

```bash
npm start
```

访问 http://localhost:8888 进入系统。

### 默认账号

- 用户名: `admin`
- 密码: `admin123`

---

## Windows 本地开发环境

### 方式一：多端口模式（无需Nginx）

默认配置 `USE_NGINX=auto`，系统会自动检测Nginx。本地未安装Nginx时，自动使用多端口模式。

```env
# .env
USE_NGINX=false
```

启动后访问：
- 管理后台: http://localhost:8888
- 项目地址: http://localhost:9000、http://localhost:9001 等

### 方式二：Nginx动态路由模式

#### 1. 安装Nginx（Windows）

**方法A - 使用Chocolatey（推荐）:**
```powershell
# 安装Chocolatey（如未安装）
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# 安装Nginx
choco install nginx
```

**方法B - 手动安装:**
1. 下载Nginx: http://nginx.org/en/download.html (选择 Stable version → nginx/Windows)
2. 解压到 `C:\nginx`
3. 将 `C:\nginx` 添加到系统环境变量 PATH

#### 2. 配置Nginx

创建Nginx配置目录：
```powershell
# 在项目目录下创建
mkdir nginx\sites-enabled
```

编辑 `C:\nginx\conf\nginx.conf`，在 http 块末尾添加：
```nginx
http {
    # ... 其他配置 ...
    
    # 引入自动生成的配置
    include Q:/agentProject/auto-deploy-demo/nginx/sites-enabled/*.conf;
}
```

#### 3. 配置环境变量

```env
# .env
USE_NGINX=true
NGINX_CONFIG_DIR=./nginx/sites-enabled
NGINX_RELOAD_CMD=nginx -s reload
NGINX_TEST_CMD=nginx -t
```

#### 4. 启动服务

```powershell
# 启动Nginx
start nginx

# 启动应用
npm start
```

启动后访问：
- 管理后台: http://localhost:8888
- 项目地址: http://localhost/project/{id}/

---

## Linux 服务器部署

### 方式一：多端口模式

适用于无需Nginx或已有其他反向代理的场景。

```env
# .env
USE_NGINX=false
PORT=8888
BASE_DOMAIN=your-domain.com
```

防火墙配置：
```bash
sudo firewall-cmd --permanent --add-port=8888/tcp
sudo firewall-cmd --permanent --add-port=9000-9100/tcp
sudo firewall-cmd --reload
```

### 方式二：Nginx动态路由模式（推荐）

#### 1. 安装Nginx

```bash
# CentOS/RHEL
sudo yum install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx

# Ubuntu/Debian
sudo apt update
sudo apt install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx
```

#### 2. 创建配置目录

```bash
# 在项目目录下创建
mkdir -p /path/to/app/nginx/sites-enabled
```

#### 3. 配置Nginx主配置

编辑 `/etc/nginx/nginx.conf`，在 http 块内添加：
```nginx
http {
    # ... 其他配置 ...
    
    # 引入自动生成的配置
    include /path/to/app/nginx/sites-enabled/*.conf;
}
```

#### 4. 配置环境变量

```env
# .env
PORT=8888
BASE_DOMAIN=demo.your-domain.com
USE_NGINX=true
NGINX_CONFIG_DIR=/path/to/app/nginx/sites-enabled
NGINX_TEMPLATE_PATH=/path/to/app/server/templates/nginx
NGINX_RELOAD_CMD=sudo nginx -s reload
NGINX_TEST_CMD=sudo nginx -t
```

#### 5. 配置sudo权限（重要）

为了让Node.js应用能够执行nginx命令，需要配置sudo免密：

```bash
sudo visudo
```

添加以下内容（替换 `www-user` 为实际运行用户）：
```
www-user ALL=(ALL) NOPASSWD: /usr/sbin/nginx -s reload, /usr/sbin/nginx -t
```

#### 6. 防火墙配置

```bash
# 只需开放80和443端口
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload
```

#### 7. 启动服务

```bash
npm install --production
```

**方式A：使用systemd服务（推荐）**

创建服务文件：
```bash
sudo nano /etc/systemd/system/auto-deploy.service
```

内容如下（修改路径和用户）：
```ini
[Unit]
Description=Auto Deploy Demo
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/app
ExecStart=/usr/bin/node server/index.js
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
```

启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl enable auto-deploy
sudo systemctl start auto-deploy
```

**方式B：使用PM2（可选）**

```bash
sudo npm install -g pm2
pm2 start server/index.js --name auto-deploy-demo
pm2 save
pm2 startup
```

启动后访问：
- 管理后台: http://demo.your-domain.com/
- 项目地址: http://demo.your-domain.com/project/{id}/

---

## 一键打包部署（推荐）

本地构建，服务器直接运行，无需在服务器上安装Node.js。

### 部署模式

| 模式 | 命令 | 端口 | 适用场景 |
|------|------|------|----------|
| **单端口模式** | `.\build-dist.ps1 -SinglePort` | 8080→80 | 宿主机有Nginx，只需一个端口 |
| **多端口模式** | `.\build-dist.ps1` | 8888+9000-9100 | 宿主机无Nginx，直接暴露多端口 |

### 单端口模式架构（推荐）

```
用户请求
    │
    ▼
┌─────────────────────────────────────┐
│        宿主机 Nginx (80)            │
│  demo.example.com → localhost:8080  │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      Docker 容器 (8080→80)          │
│  ┌───────────────────────────────┐  │
│  │    容器内 Nginx (80)          │  │
│  │  / → 管理后台 (127.0.0.1:8888)│  │
│  │  /project/123/ → :9000       │  │
│  │  /project/456/ → :9001       │  │
│  └───────────────────────────────┘  │
│  ┌───────────────────────────────┐  │
│  │  Node.js 服务 (127.0.0.1:8888)│  │
│  │  项目服务 (127.0.0.1:9000+)   │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘
```

### 本地打包

**Windows PowerShell:**
```powershell
# 单端口模式（推荐）
.\build-dist.ps1 -SinglePort

# 多端口模式
.\build-dist.ps1
```

**Linux/Mac:**
```bash
chmod +x build-dist.sh

# 单端口模式（推荐）
./build-dist.sh --single-port

# 多端口模式
./build-dist.sh
```

打包完成后会生成：
- `deploy-dist/` - 部署目录
- `auto-deploy-dist-single-YYYYMMDD_HHMMSS.zip` - 压缩包

### 服务器部署

1. **上传部署包**
```bash
scp auto-deploy-dist-*.zip user@server:/opt/auto-deploy/
```

2. **解压并启动**
```bash
cd /opt/auto-deploy
unzip auto-deploy-dist-*.zip
docker-compose up -d
```

3. **配置宿主机Nginx**

创建 `/etc/nginx/conf.d/demo.conf`:
```nginx
server {
    listen 80;
    server_name demo.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
    }
}
```

重载Nginx:
```bash
sudo nginx -t && sudo nginx -s reload
```

4. **访问管理后台**
```
http://demo.example.com/
```

### 部署包结构

```
deploy-dist/
├── Dockerfile           # Docker构建文件
├── docker-compose.yml   # Docker编排文件
├── package.json         # 依赖配置
├── server/              # 后端代码
├── client/dist/         # 前端构建产物
├── data/                # 数据目录（持久化）
├── projects/            # 项目文件（持久化）
├── .env                 # 环境变量
└── README.md            # 部署说明
```

---

## Docker 部署（推荐）

适用于宿主机已有Nginx的场景。

### 架构说明

```
┌─────────────────────────────────────────────────────────────┐
│                        宿主机                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Nginx (80/443)                         │   │
│  │   location / { proxy_pass http://127.0.0.1:8888; }  │   │
│  │   location /project/ { proxy_pass http://127.0.0.1:9000-9100; } │
│  └──────────────────────┬──────────────────────────────┘   │
│                         │                                   │
│  ┌──────────────────────▼──────────────────────────────┐   │
│  │           Docker Container                           │   │
│  │   ┌─────────────────────────────────────────────┐   │   │
│  │   │  Node.js App (8888) - 管理后台/API          │   │   │
│  │   └─────────────────────────────────────────────┘   │   │
│  │   ┌─────────────────────────────────────────────┐   │   │
│  │   │  项目服务 (9000-9100) - 演示项目            │   │   │
│  │   └─────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

### 1. 构建前端

```bash
cd client
npm install
npm run build
cd ..
```

### 2. 构建Docker镜像

```bash
docker build -t auto-deploy-demo .
```

### 3. 启动容器

**方式A：使用docker-compose（推荐）**

```bash
docker-compose up -d
```

**方式B：使用docker run**

```bash
docker run -d \
  --name auto-deploy-demo \
  -p 8888:8888 \
  -p 9000:9000 \
  -p 9001:9001 \
  -p 9002:9002 \
  -p 9003:9003 \
  -p 9004:9004 \
  -p 9005:9005 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/projects:/app/projects \
  -e BASE_DOMAIN=your-domain.com \
  -e USE_NGINX=false \
  -e PROJECT_BIND_ADDRESS=0.0.0.0 \
  auto-deploy-demo
```

> **注意**: Docker模式下必须设置 `PROJECT_BIND_ADDRESS=0.0.0.0`，否则宿主机无法访问项目服务。

### 4. 配置宿主机Nginx

在宿主机的Nginx配置中添加：

```nginx
# /etc/nginx/conf.d/auto-deploy.conf

server {
    listen 80;
    server_name demo.your-domain.com;

    # 管理后台和API
    location / {
        proxy_pass http://127.0.0.1:8888;
        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;
    }
}

# 每个项目使用独立子域名（推荐方案）
# 项目1: http://project1.demo.your-domain.com
server {
    listen 80;
    server_name project1.demo.your-domain.com;
    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# 项目2: http://project2.demo.your-domain.com
server {
    listen 80;
    server_name project2.demo.your-domain.com;
    location / {
        proxy_pass http://127.0.0.1:9001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 5. 简化方案：直接使用端口访问

如果不需要域名，可以直接通过端口访问：

- 管理后台: http://your-server-ip:8888
- 项目1: http://your-server-ip:9000
- 项目2: http://your-server-ip:9001

### Docker常用命令

```bash
# 查看日志
docker logs -f auto-deploy-demo

# 重启容器
docker restart auto-deploy-demo

# 停止容器
docker-compose down

# 更新部署
docker-compose down
docker-compose build
docker-compose up -d
```

---

## 使用指南

### 创建项目

1. 点击右上角「新建项目」按钮
2. 填写项目名称和描述
3. 拖拽或点击上传项目文件
4. 点击「创建项目」完成

### 部署项目

1. 在项目列表点击「启动项目」
2. 系统自动分配端口并启动
3. 点击生成的链接访问项目

### 修改密码

1. 点击右上角「设置」按钮
2. 输入当前密码和新密码
3. 点击「确认修改」

### 安全特性

- 连续3次密码错误将锁定账户10分钟
- 锁定期间显示实时倒计时
- 提供「忘记密码」入口

---

## 项目结构

```
auto-deploy-demo/
├── server/                 # 后端代码
│   ├── index.js           # 入口文件
│   ├── config/            # 配置模块
│   ├── routes/            # API路由
│   │   ├── auth.js        # 认证相关
│   │   ├── projects.js    # 项目管理
│   │   └── deploy.js      # 部署相关
│   ├── services/          # 业务服务
│   │   ├── projectService.js
│   │   ├── processManager.js
│   │   └── nginxManager.js    # Nginx配置管理
│   ├── templates/         # 配置模板
│   │   └── nginx/
│   │       ├── main.conf.tpl
│   │       └── location.conf.tpl
│   ├── middleware/        # 中间件
│   ├── utils/             # 工具函数
│   │   └── loginLimiter.js
│   └── data/              # 数据存储目录
├── client/                 # 前端代码
│   ├── src/
│   │   ├── views/         # 页面组件
│   │   ├── components/    # 通用组件
│   │   └── stores/        # 状态管理
│   └── dist/              # 构建产物
├── nginx/                  # Nginx配置目录
│   └── sites-enabled/     # 自动生成的配置
├── projects/               # 上传的项目存储
├── deploy/                 # 部署脚本
└── .env                    # 环境配置
```

---

## API 接口

### 认证相关

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/auth/login | 用户登录 |
| GET | /api/auth/verify | 验证Token |
| POST | /api/auth/change-password | 修改密码 |
| GET | /api/auth/lock-status/:username | 获取锁定状态 |

### 项目管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/projects | 获取项目列表 |
| POST | /api/projects | 创建项目 |
| GET | /api/projects/:id | 获取项目详情 |
| DELETE | /api/projects/:id | 删除项目 |

### 部署相关

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/deploy/:id/start | 启动项目 |
| POST | /api/deploy/:id/stop | 停止项目 |
| GET | /api/deploy/:id/status | 获取运行状态 |
| GET | /api/deploy/:id/logs | 获取运行日志 |
| GET | /api/deploy/nginx/status | 获取Nginx配置状态 |

---

## 支持的项目类型

| 类型 | 说明 |
|------|------|
| 静态HTML | 直接部署，无需构建 |
| Vue/React构建产物 | 上传dist目录内容 |
| Vite项目 | 自动识别并启动 |

---

## 注意事项

1. **文件大小**: 单个文件最大100MB
2. **端口范围**: 
   - 管理系统: 8888
   - 演示项目: 9000-9100（内部端口，Nginx模式下外部不可见）
3. **并发限制**: 最多同时运行100个项目
4. **数据备份**: 请定期备份 `server/data` 和 `projects` 目录
5. **Nginx模式**: 需要确保Node.js进程有权限执行nginx命令

---

## 常见问题

### Q: 上传后项目无法访问？

检查项目是否包含 `index.html` 入口文件。

### Q: 启动失败怎么办？

查看项目详情页的操作日志，了解错误原因。

### Q: 刷新页面显示404？

系统已支持SPA路由回退，如仍有问题请检查项目路由配置。

### Q: 如何修改登录密码？

点击右上角「设置」按钮，在弹窗中修改密码。

### Q: 密码错误多次被锁定？

连续3次密码错误将锁定10分钟，请等待倒计时结束后重试。

### Q: Nginx模式下项目无法访问？

1. 检查Nginx是否正常运行: `nginx -t`
2. 检查配置文件是否生成: `cat nginx/sites-enabled/auto-deploy.conf`
3. 检查Nginx错误日志: `tail -f /var/log/nginx/error.log`
4. 确认Node.js有权限执行nginx命令

### Q: Windows下Nginx命令执行失败？

确保Nginx安装目录已添加到系统PATH环境变量，或使用完整路径：
```env
NGINX_RELOAD_CMD=C:\nginx\nginx.exe -s reload
NGINX_TEST_CMD=C:\nginx\nginx.exe -t
```

---

## 许可证

MIT License

## 联系方式

如有问题或建议，请联系系统管理员。