Initial commit - DesignerCEP Project with Caddy deployment

2025-12-19 21:27:17 +08:00
commit 8ea58fe480
170 changed files with 47469 additions and 0 deletions
--- a/tempdocs/线上部署指南.md
+++ b/tempdocs/线上部署指南.md
@@ -0,0 +1,634 @@
+# 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
+