# DesignerCEP 线上部署指南

## 📋 部署架构概览

本项目包含三个主要部分：
1. **Shell（登录壳）**: 本地 CEP 扩展，负责登录和版本管理
2. **Core（核心应用）**: 通过后端服务器提供的 Web 应用
3. **Backend（后端服务）**: FastAPI 服务器，提供 API 和静态文件服务

---

## 🚀 一、前端部署

### 1.1 构建前准备

#### ✅ 关闭生产环境日志

在 `main.ts` 或应用入口添加：

```typescript
import { logger } from '@/utils/logger';

// 生产环境关闭日志
if (import.meta.env.PROD) {
    logger.disable();
} else {
    logger.enable();
}
```

或者在 `logger.ts` 中修改默认状态：

```typescript
class Logger {
    // 生产环境默认关闭，开发环境默认开启
    private _enabled: boolean = import.meta.env.DEV;
    // ...
}
```

#### ✅ 配置生产环境 API 地址

创建 `.env.production` 文件：

```env
# 生产环境配置
VITE_API_BASE_URL=https://your-domain.com/api/v1
VITE_API_SERVER=https://your-domain.com
```

修改 `config.ts`：

```typescript
export const config = {
    // 从环境变量读取
    apiBaseUrl: import.meta.env.VITE_API_BASE_URL || 'http://127.0.0.1:8000/api/v1',
    apiServer: import.meta.env.VITE_API_SERVER || 'http://127.0.0.1:8000',
    
    // ...其他配置
};
```

### 1.2 构建命令

```bash
# 进入 Designer 目录
cd Designer

# 安装依赖（如果还没安装）
npm install

# 构建生产版本
npm run build

# 构建完成后，产物在 dist/ 目录
```

### 1.3 构建产物说明

```
Designer/dist/
  ├── Shell/          # Shell 登录壳（本地 CEP 扩展使用）
  │   ├── index.html
  │   ├── assets/
  │   └── ...
  └── Designer/       # Core 核心应用（上传到服务器）
      ├── index.html
      ├── assets/
      └── ...
```

**重要说明：**
- `dist/Shell/` → 需要部署到服务器的两个地方：
  - 打包为 `.zip` 供 CEP 扩展下载：`static/shell/shell-{version}.zip`
  - 部署为在线登录页：`static/shell/` （直接部署文件）
- `dist/Designer/` → 上传到服务器的 `static/core/{version}/` 目录

---

## 🖥️ 二、后端部署

### 2.1 服务器要求

- **操作系统**: Linux (推荐 Ubuntu 20.04+) 或 Windows Server
- **Python 版本**: Python 3.9+
- **内存**: 最低 1GB，推荐 2GB+
- **磁盘**: 至少 10GB 可用空间（用于存储版本文件）
- **域名**: 需要一个域名并配置 DNS
- **SSL 证书**: 建议使用 Let's Encrypt 免费证书

### 2.2 部署步骤

#### 步骤 1: 上传代码

```bash
# 方式 1: Git 克隆（推荐）
ssh user@your-server
cd /var/www
git clone https://your-repo-url.git DesignerCEP
cd DesignerCEP/Server

# 方式 2: SCP 上传
# 本地执行
scp -r Server/ user@your-server:/var/www/DesignerCEP/
```

#### 步骤 2: 创建虚拟环境

```bash
cd /var/www/DesignerCEP/Server

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate  # Linux
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt
```

#### 步骤 3: 配置环境变量

创建 `.env` 文件：

```bash
# /var/www/DesignerCEP/Server/.env

# 基础配置
PROJECT_NAME=DesignerCEP
VERSION=1.0.0
DEBUG=False

# 安全配置
SECRET_KEY=your-super-secret-key-change-this-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=43200

# 数据库配置（如果使用）
DATABASE_URL=sqlite:///./designer.db
# 或使用 PostgreSQL/MySQL
# DATABASE_URL=postgresql://user:password@localhost/dbname

# CORS 配置
ALLOWED_ORIGINS=https://your-domain.com,https://www.your-domain.com

# 静态文件路径
STATIC_DIR=/var/www/DesignerCEP/Server/static
SHELL_DIR=/var/www/DesignerCEP/Server/static/shell
CORE_DIR=/var/www/DesignerCEP/Server/static/core
```

#### 步骤 4: 准备静态文件目录

```bash
# 创建目录结构
mkdir -p static/shell
mkdir -p static/core/1.0.0

# 1. 上传 Shell 在线登录页（用于网页访问）
scp -r Designer/dist/Shell/* user@your-server:/var/www/DesignerCEP/Server/static/shell/

# 2. 打包 Shell 供 CEP 扩展下载
cd Designer/dist
zip -r shell-1.0.0.zip Shell/
scp shell-1.0.0.zip user@your-server:/var/www/DesignerCEP/Server/static/downloads/
cd ../..

# 3. 上传 Core 构建产物
scp -r Designer/dist/Designer/* user@your-server:/var/www/DesignerCEP/Server/static/core/1.0.0/
```

目录结构应该是：

```
Server/
  ├── app/
  ├── static/
  │   ├── shell/                  # Shell 在线登录页
  │   │   ├── index.html
  │   │   ├── assets/
  │   │   └── ...
  │   ├── downloads/              # 下载文件（供 CEP 扩展）
  │   │   └── shell-1.0.0.zip
  │   └── core/
  │       └── 1.0.0/              # Core 核心应用
  │           ├── index.html
  │           ├── assets/
  │           └── ...
  ├── .env
  ├── requirements.txt
  └── main.py
```

**说明：**
- `static/shell/` - Shell 在线登录页，用户退出登录后访问这里
- `static/downloads/shell-1.0.0.zip` - 供 CEP 扩展首次下载的 Shell 安装包
- `static/core/1.0.0/` - Core 核心应用，用户登录后使用

#### 步骤 5: 使用 Gunicorn 运行（生产环境）

安装 Gunicorn：

```bash
pip install gunicorn uvicorn[standard]
```

创建启动脚本 `start.sh`:

```bash
#!/bin/bash
cd /var/www/DesignerCEP/Server
source venv/bin/activate

gunicorn app.main:app \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    --access-logfile logs/access.log \
    --error-logfile logs/error.log \
    --daemon
```

```bash
chmod +x start.sh
./start.sh
```

#### 步骤 6: 使用 Systemd 管理服务（推荐）

创建服务文件 `/etc/systemd/system/designer-cep.service`:

```ini
[Unit]
Description=DesignerCEP Backend Service
After=network.target

[Service]
Type=notify
User=www-data
Group=www-data
WorkingDirectory=/var/www/DesignerCEP/Server
Environment="PATH=/var/www/DesignerCEP/Server/venv/bin"
ExecStart=/var/www/DesignerCEP/Server/venv/bin/gunicorn \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    app.main:app

Restart=always
RestartSec=3

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

启动服务：

```bash
# 重载 systemd
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start designer-cep

# 设置开机自启
sudo systemctl enable designer-cep

# 查看状态
sudo systemctl status designer-cep

# 查看日志
sudo journalctl -u designer-cep -f
```

---

## 🔧 三、Nginx 反向代理配置

### 3.1 安装 Nginx

```bash
sudo apt update
sudo apt install nginx
```

### 3.2 配置 Nginx

创建配置文件 `/etc/nginx/sites-available/designer-cep`:

```nginx
# HTTP 重定向到 HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com www.your-domain.com;
    
    # Let's Encrypt 验证
    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }
    
    # 重定向到 HTTPS
    location / {
        return 301 https://$server_name$request_uri;
    }
}

# HTTPS 配置
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name your-domain.com www.your-domain.com;
    
    # SSL 证书配置
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    
    # 日志
    access_log /var/log/nginx/designer-cep-access.log;
    error_log /var/log/nginx/designer-cep-error.log;
    
    # 客户端最大上传大小（用于大文件上传）
    client_max_body_size 100M;
    
    # API 代理
    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        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;
        
        # WebSocket 支持（如果需要）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
    
    # Shell 在线登录页
    location /shell/ {
        alias /var/www/DesignerCEP/Server/static/shell/;
        try_files $uri $uri/ /shell/index.html;
        
        # HTML 不缓存，资源文件缓存
        location ~* \.html$ {
            expires -1;
            add_header Cache-Control "no-cache, no-store, must-revalidate";
        }
        
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 7d;
            add_header Cache-Control "public, immutable";
        }
    }
    
    # 下载文件（供 CEP 扩展下载）
    location /downloads/ {
        alias /var/www/DesignerCEP/Server/static/downloads/;
        autoindex off;
        
        # 强制下载
        add_header Content-Disposition "attachment";
        
        # 缓存配置
        expires 7d;
        add_header Cache-Control "public, immutable";
    }
    
    # Core 静态文件
    location /core/ {
        alias /var/www/DesignerCEP/Server/static/core/;
        try_files $uri $uri/ =404;
        
        # SPA 路由支持（如果需要）
        # try_files $uri $uri/ /core/$1/index.html;
        
        # 缓存配置
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
        
        location ~* \.html$ {
            expires -1;
            add_header Cache-Control "no-cache, no-store, must-revalidate";
        }
    }
    
    # 健康检查
    location /health {
        proxy_pass http://127.0.0.1:8000/health;
        access_log off;
    }
}
```

启用配置：

```bash
# 创建软链接
sudo ln -s /etc/nginx/sites-available/designer-cep /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重载 Nginx
sudo systemctl reload nginx
```

### 3.3 配置 SSL 证书（Let's Encrypt）

```bash
# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

# 自动续期（已自动配置 cron）
sudo certbot renew --dry-run
```

---

## 🔒 四、安全配置

### 4.1 防火墙配置

```bash
# 允许 SSH
sudo ufw allow 22/tcp

# 允许 HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 启用防火墙
sudo ufw enable

# 查看状态
sudo ufw status
```

### 4.2 生产环境安全检查清单

- [ ] 修改 `SECRET_KEY` 为随机强密钥
- [ ] 设置 `DEBUG=False`
- [ ] 配置正确的 `ALLOWED_ORIGINS`
- [ ] 使用 HTTPS（SSL 证书）
- [ ] 配置数据库（不使用 SQLite）
- [ ] 设置文件上传大小限制
- [ ] 配置日志轮转
- [ ] 关闭前端日志输出
- [ ] 定期备份数据库和用户数据
- [ ] 配置监控和告警

---

## 📦 五、版本更新流程

### 5.1 发布新版本

```bash
# 1. 本地构建新版本
cd Designer
npm run build

# 2. 上传到服务器
scp -r dist/Designer/* user@your-server:/var/www/DesignerCEP/Server/static/core/1.0.1/

# 3. 更新后端版本配置
# 在后端 API 中更新 current_version 为 1.0.1
```

### 5.2 版本管理建议

```
static/core/
  ├── 1.0.0/    # 旧版本保留
  ├── 1.0.1/    # 当前版本
  └── 1.0.2/    # 新版本
```

后端 API 返回最新版本号，客户端自动下载更新。

---

## 🔍 六、监控与日志

### 6.1 日志管理

创建日志轮转配置 `/etc/logrotate.d/designer-cep`:

```
/var/www/DesignerCEP/Server/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    notifempty
    create 0640 www-data www-data
    sharedscripts
    postrotate
        systemctl reload designer-cep > /dev/null 2>&1 || true
    endscript
}
```

### 6.2 性能监控

推荐使用：
- **PM2**: 进程管理和监控
- **Prometheus + Grafana**: 指标监控
- **Sentry**: 错误追踪
- **ELK Stack**: 日志分析

---

## 🚀 七、快速部署脚本

创建 `deploy.sh` 一键部署脚本：

```bash
#!/bin/bash

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

echo -e "${GREEN}========================================${NC}"
echo -e "${GREEN}  DesignerCEP 自动部署脚本${NC}"
echo -e "${GREEN}========================================${NC}"

# 1. 拉取最新代码
echo -e "\n${YELLOW}[1/6] 拉取最新代码...${NC}"
git pull origin main

# 2. 构建前端
echo -e "\n${YELLOW}[2/6] 构建前端...${NC}"
cd Designer
npm install
npm run build
cd ..

# 3. 上传 Core 到服务器
echo -e "\n${YELLOW}[3/6] 上传 Core 到服务器...${NC}"
VERSION=$(node -p "require('./Designer/package.json').version")
ssh user@your-server "mkdir -p /var/www/DesignerCEP/Server/static/core/$VERSION"
scp -r Designer/dist/Designer/* user@your-server:/var/www/DesignerCEP/Server/static/core/$VERSION/

# 4. 更新后端代码
echo -e "\n${YELLOW}[4/6] 更新后端代码...${NC}"
ssh user@your-server "cd /var/www/DesignerCEP/Server && git pull origin main"

# 5. 重启后端服务
echo -e "\n${YELLOW}[5/6] 重启后端服务...${NC}"
ssh user@your-server "sudo systemctl restart designer-cep"

# 6. 检查服务状态
echo -e "\n${YELLOW}[6/6] 检查服务状态...${NC}"
ssh user@your-server "sudo systemctl status designer-cep --no-pager"

echo -e "\n${GREEN}========================================${NC}"
echo -e "${GREEN}  部署完成！${NC}"
echo -e "${GREEN}  版本: $VERSION${NC}"
echo -e "${GREEN}========================================${NC}"
```

使用方法：

```bash
chmod +x deploy.sh
./deploy.sh
```

---

## ❓ 八、常见问题

### Q1: CORS 跨域问题
**A**: 在后端 `.env` 中正确配置 `ALLOWED_ORIGINS`。

### Q2: 静态文件 404
**A**: 检查 Nginx 配置中的 `alias` 路径是否正确。

### Q3: API 请求超时
**A**: 调整 Nginx `proxy_read_timeout` 和 Gunicorn `timeout` 参数。

### Q4: 前端日志仍然输出
**A**: 确保在生产环境中调用了 `logger.disable()`。

### Q5: 版本更新后客户端没反应
**A**: 检查后端 API 返回的版本号是否正确，清除客户端缓存。

---

## 📞 技术支持

如遇到部署问题，请检查：
1. 后端日志：`sudo journalctl -u designer-cep -f`
2. Nginx 日志：`sudo tail -f /var/log/nginx/designer-cep-error.log`
3. 系统资源：`htop` 或 `top`

---

**最后更新**: 2024-12-17