635 lines
14 KiB
Markdown
635 lines
14 KiB
Markdown
# 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
|
||
|