DP/tempdocs/生产环境部署实操指南.md

# 🚀 DesignerCEP 生产环境部署实操指南

本文档为您提供从零开始部署 DesignerCEP 到 Linux 服务器（Ubuntu/Debian/CentOS）的完整操作步骤。

---

## 📋 1. 准备工作

### 1.1 服务器与域名
- **服务器**: 建议 Ubuntu 20.04+ (已购买)
- **域名**: `your-domain.com` (已购买)
- **DNS 解析**: 请将域名 A 记录解析到服务器公网 IP。

### 1.2 本地文件准备
在您的电脑上创建一个 `deployment` 文件夹，用于存放准备上传的文件。

#### A. 后端代码
复制 `Server` 目录下的以下文件/文件夹到 `deployment/Server`：
- `app/` (文件夹)
- `requirements.txt`
- `.env` (稍后修改)
- `main.py` (如果有入口文件在根目录，或者确认入口是 `app.main`)

#### B. 前端构建
1. **配置生产环境地址**：
   修改 `Designer/.env.production`：
   ```env
   VITE_API_SERVER=https://your-domain.com
   ```

2. **构建项目**：
   在 `Designer` 目录下运行：
   ```bash
   npm run build
   ```
   这将生成 `Designer/dist` 目录，包含 `Shell` 和 `Designer` (Core) 两个文件夹。

3. **打包 Shell**：
   将 `Designer/dist/Shell` 文件夹压缩为 `shell-1.0.1.zip` (版本号请参考 package.json)。

#### C. 最终上传清单
您的 `deployment` 文件夹结构应如下：
```
deployment/
├── Server/                 # 后端代码
│   ├── app/
│   └── requirements.txt
├── Shell/                  # 前端 Shell (来自 dist/Shell)
├── Core/                   # 前端 Core (来自 dist/Designer)
└── shell-1.0.1.zip         # 压缩包 (来自 dist/Shell)
```

---

## 🖥️ 2. 服务器环境安装

使用 SSH 登录您的服务器：
```bash
ssh root@your-server-ip
```

### 2.1 安装基础软件
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y python3 python3-pip python3-venv unzip curl

# 安装 Caddy (Web 服务器)
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy
```

---

## 📂 3. 上传与部署文件

### 3.1 创建目录结构
```bash
# 创建应用根目录
sudo mkdir -p /var/www/DesignerCEP/Server

# 创建静态文件目录
sudo mkdir -p /var/www/DesignerCEP/Server/static/shell
sudo mkdir -p /var/www/DesignerCEP/Server/static/core/1.0.1
sudo mkdir -p /var/www/DesignerCEP/Server/static/downloads

# 设置权限
sudo chown -R www-data:www-data /var/www/DesignerCEP
sudo chmod -R 755 /var/www/DesignerCEP
```

### 3.2 上传文件 (在本地执行)
打开新的终端窗口（本地），执行上传命令：

```bash
# 假设您在 deployment 目录的上级目录
cd path/to/deployment

# 1. 上传后端
scp -r Server/* root@your-server-ip:/var/www/DesignerCEP/Server/

# 2. 上传 Shell 静态文件
scp -r Shell/* root@your-server-ip:/var/www/DesignerCEP/Server/static/shell/

# 3. 上传 Core 静态文件 (注意：这里是上传特定版本)
# 如果您有多个版本，请重复此步骤，例如 1.0.0, 1.0.1 等
scp -r Core/* root@your-server-ip:/var/www/DesignerCEP/Server/static/core/1.0.1/

# 4. 上传 Shell 压缩包
scp shell-1.0.1.zip root@your-server-ip:/var/www/DesignerCEP/Server/static/downloads/

# 5. 上传历史版本 (如果您有 archives 文件夹)
# 假设您本地有一个 archives 文件夹包含 core-v1.0.0.zip 等
# scp -r archives/* root@your-server-ip:/var/www/DesignerCEP/Server/archives/
# 并在服务器上解压到 /var/www/DesignerCEP/Server/static/core/
```

### 3.3 批量上传历史版本（可选）
如果您需要一次性部署多个历史版本，可以按照以下步骤操作：

1.  **在本地准备版本**：
    将所有需要部署的 `core-vX.X.X.zip` 文件放在一个文件夹中，例如 `all_versions`。

2.  **上传到服务器**：
    ```bash
    scp -r all_versions/*.zip root@your-server-ip:/var/www/DesignerCEP/Server/archives/
    ```

3.  **在服务器上解压**：
    登录服务器，运行以下命令批量解压：
    ```bash
    cd /var/www/DesignerCEP/Server/archives
    # 安装 unzip (如果未安装)
    sudo apt install unzip

    # 遍历解压所有 core zip 文件到 static/core
    for f in core-v*.zip; do
        # 提取版本号 (假设文件名格式为 core-v1.0.0.zip)
        version=$(echo "$f" | sed 's/core-v//' | sed 's/.zip//')
        
        echo "Deploying version $version..."
        sudo mkdir -p "/var/www/DesignerCEP/Server/static/core/$version"
        sudo unzip -o "$f" -d "/var/www/DesignerCEP/Server/static/core/$version"
    done
    
    # 修正权限
    sudo chown -R www-data:www-data /var/www/DesignerCEP/Server/static/core
    ```

### 3.4 修正权限 (服务器端)
```bash
sudo chown -R www-data:www-data /var/www/DesignerCEP
```

---

## ⚙️ 4. 后端服务配置

### 4.1 安装 Python 依赖
```bash
cd /var/www/DesignerCEP/Server

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
pip install gunicorn uvicorn[standard]
```

### 4.2 配置环境变量
创建 `.env` 文件：
```bash
nano .env
```
粘贴以下内容（**已为您预填好域名**）：
```env
ENV=production
PROJECT_NAME=DesignerCEP
API_V1_STR=/api/v1
SECRET_KEY=generate-a-secure-random-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=43200
DATABASE_URL=sqlite:///./designercep.db

# 关键：允许 CORS 的域名
ALLOWED_ORIGINS=https://aidg168.uk,https://www.aidg168.uk,https://backend.aidg168.uk

# 邮箱配置 (可选，如果您需要发送邮件)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
EMAILS_FROM_EMAIL=your-email@gmail.com
EMAILS_FROM_NAME=DesignerCEP
```

### 4.3 配置 Systemd 服务
创建服务文件：
```bash
sudo nano /etc/systemd/system/designer-cep.service
```
粘贴内容：
```ini
[Unit]
Description=DesignerCEP Backend
After=network.target

[Service]
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 app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 127.0.0.1:8000
Restart=always

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

启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl enable designer-cep
sudo systemctl start designer-cep
sudo systemctl status designer-cep  # 检查是否显示 Active: active (running)
```

---

## 🌐 5. Caddy 配置 (HTTPS & 反向代理)

**⚠️ 关键提示：Cloudflare SSL 模式必须设置为 Full (Strict)**

编辑 Caddy 配置文件：
```bash
sudo nano /etc/caddy/Caddyfile
```
**清空原有内容，粘贴以下内容**：

```caddy
# ========== 主域名 (Shell & Core & Downloads) ==========
aidg168.uk, www.aidg168.uk {
    # 1. Shell 静态页面
    handle /shell/* {
        root * /var/www/DesignerCEP/Server/static/shell
        try_files {path} {path}/ /shell/index.html
        file_server
    }

    # 2. Core 核心应用
    handle /core/* {
        root * /var/www/DesignerCEP/Server/static/core
        file_server
    }

    # 3. 下载文件
    handle /downloads/* {
        root * /var/www/DesignerCEP/Server/static/downloads
        file_server
    }

    # 4. 根路径跳转到 Shell
    handle / {
        redir /shell/ permanent
    }

    # 5. 压缩与日志
    encode gzip
    log {
        output file /var/log/caddy/designer-cep.log
    }
}

# ========== API 专用域名 (FastAPI) ==========
backend.aidg168.uk {
    # 1. API 代理到后端 (FastAPI)
    reverse_proxy 127.0.0.1:8000

    # 2. 压缩与日志
    encode gzip
    log {
        output file /var/log/caddy/designer-cep-api.log
    }
}
```

重启 Caddy：
```bash
sudo systemctl restart caddy
sudo systemctl status caddy
```

---

## 🔒 6. 安全与网络检查 (必做!)

**1. 确认 Cloudflare SSL 模式**
- 登录 Cloudflare 控制台 -> SSL/TLS -> Overview
- **必须选择**: `Full (Strict)`
- *原因*: Caddy 会自动申请 Let's Encrypt 证书，Cloudflare 需要信任这个有效证书。

**2. 确认防火墙端口**
在服务器上执行：
```bash
sudo ufw allow 80
sudo ufw allow 443
sudo ufw reload
```

**3. 确认 Caddy 监听状态**
在服务器上执行：
```bash
sudo ss -lntp | grep 443
```
*预期输出*: 应该看到 `caddy` 进程正在监听 `*:443`。

**4. 快速自检 (在服务器上执行)**
```bash
# 1. 检查 DNS (应返回 Cloudflare IP)
dig backend.aidg168.uk +short

# 2. 本机测试 API (绕过 Cloudflare)
curl -v http://127.0.0.1:8000/health

# 3. 域名测试 (走公网)
curl -I https://backend.aidg168.uk/health
```

---

## ✅ 7. 验证部署

打开浏览器访问：
1. **API 健康检查**: `https://backend.aidg168.uk/health` (应返回 `{"status": "healthy"}`)
2. **Shell 页面**: `https://aidg168.uk/shell/` (应显示登录页)
3. **Core 版本**: `https://aidg168.uk/core/1.0.1/index.html` (确认版本存在)

---

## 🔄 更新维护

### 更新前端
1. 本地 `npm run build`
2. 上传新文件到对应目录
3. 不需要重启服务

### 更新后端
1. 上传新代码到 `/var/www/DesignerCEP/Server`
2. 重启服务：`sudo systemctl restart designer-cep`