# 前端 App 部署功能使用说明

## 📦 功能概述

新增的部署功能可以将已构建好的 `dist_core` 目录部署到服务器 `/var/www/app/`，并提供完整的版本历史管理和回滚功能。

---

## 🚀 使用流程

### 1. 准备工作

#### 1.1 安装依赖
```bash
cd AdminTool
pip install -r requirements.txt
```

确保已安装：
- `PyQt5` - GUI 界面
- `paramiko` - SSH 连接
- `pymysql` - MySQL 数据库
- `requests` - API 请求

#### 1.2 配置服务器信息

编辑 `AdminTool/deploy_config.json`：
```json
{
  "host": "103.97.201.136",
  "port": "22",
  "username": "root",
  "password": "你的密码",
  "remote_path": "/var/www/app",
  "mysql": {
    "host": "localhost",
    "port": "3306",
    "username": "designer_user",
    "password": "DesignerPass123!",
    "database": "designer_db"
  }
}
```

#### 1.3 构建前端

**在部署前，请先手动构建前端：**
```bash
cd Designer
npm run build:core
```

构建完成后会生成 `Designer/dist_core/` 目录。

---

### 2. 启动管理工具

```bash
cd AdminTool
python admin_gui.py
```

打开后切换到 **"自动化部署"** 标签页。

---

### 3. 部署新版本

#### 步骤：

1. **选择 dist_core 目录**
   - 点击 "浏览..." 按钮
   - 选择 `Designer/dist_core` 目录

2. **添加备注（可选）**
   - 例如：`修复主题同步bug`、`新增管理后台功能`

3. **点击 "🚀 部署到服务器"**
   - 系统会：
     - 自动生成时间戳版本号（如 `20231220_153045`）
     - 备份当前运行版本到 `/var/www/app_versions/backup_XXXXXX/`
     - 清空 `/var/www/app/`
     - 上传新版本
     - 保存版本到 `/var/www/app_versions/20231220_153045/`
     - 记录到 MySQL 数据库

4. **查看部署日志**
   - 底部日志区域会实时显示进度
   - 部署成功后会弹出提示

---

### 4. 查看版本历史

部署成功后，版本会自动显示在 **"版本历史管理"** 表格中：

| 版本号 | 部署时间 | 大小(MB) | 备注 | 状态 |
|--------|----------|----------|------|------|
| 20231220_153045 | 2023-12-20 15:30:45 | 12.5 | 修复主题同步bug | ✅ 当前 |
| 20231220_102030 | 2023-12-20 10:20:30 | 12.3 | 初始版本 | |

- **绿色 "✅ 当前"** 表示正在服务器上运行的版本
- 点击 **"🔄 刷新列表"** 可手动刷新

---

### 5. 回滚到历史版本

如果新版本有问题，可以快速回滚：

1. **选择要回滚的版本**
   - 在表格中点击某个历史版本

2. **点击 "⏪ 回滚到选中版本"**
   - 确认对话框会显示版本信息

3. **确认回滚**
   - 系统会：
     - 备份当前版本
     - 从 `/var/www/app_versions/` 复制选中版本到 `/var/www/app/`
     - 更新数据库

4. **刷新页面**
   - 访问 `https://app.aidg168.uk/` 查看回滚结果

---

### 6. 删除历史版本

如果某个版本不再需要：

1. **选择要删除的版本**
2. **点击 "🗑️ 删除选中版本"**
3. **确认删除**
   - 会同时删除：
     - 数据库记录
     - 服务器文件 `/var/www/app_versions/XXXXXX/`

**注意**：
- ❌ 无法删除当前正在使用的版本
- ⚠️ 删除操作不可恢复

---

## 📁 服务器目录结构

```
/var/www/
├── app/                          ← 当前运行版本（Caddy 直接访问）
│   ├── index.html
│   ├── assets/
│   └── ...
│
└── app_versions/                 ← 版本历史存档
    ├── 20231220_153045/          ← 版本 1
    ├── 20231220_164522/          ← 版本 2
    ├── backup_20231221_092301/   ← 自动备份
    └── ...
```

---

## 🗄️ 数据库表结构

**表名**：`app_deployments`

```sql
CREATE TABLE app_deployments (
  id INT PRIMARY KEY AUTO_INCREMENT,
  version VARCHAR(50) UNIQUE NOT NULL,        -- 版本号（时间戳）
  deployed_at DATETIME NOT NULL,              -- 部署时间
  is_current BOOLEAN DEFAULT FALSE,           -- 是否当前版本
  file_size_mb DECIMAL(10, 2),                -- 文件大小（MB）
  comment VARCHAR(500),                       -- 备注
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

---

## ❓ 常见问题

### Q1: 部署后需要重启 Caddy 吗？
**A**: 通常不需要。Caddy 会自动读取 `/var/www/app/` 中的新文件。但如果页面没更新，可以尝试：
```bash
ssh root@your-server
systemctl restart caddy
```

### Q2: 如果数据库连接失败怎么办？
**A**: 检查 `deploy_config.json` 中的 MySQL 配置：
- 主机地址（`host`）
- 端口（`port`）
- 用户名和密码
- 数据库名（`database`）

### Q3: 如何查看服务器上的实际文件？
**A**: 使用 SSH 登录：
```bash
ssh root@103.97.201.136
cd /var/www/app
ls -lh
```

### Q4: 部署失败后如何恢复？
**A**: 如果部署中断：
1. 进入 GUI 的"版本历史管理"
2. 选择上一个稳定版本
3. 点击"回滚"

### Q5: 可以同时部署到多个服务器吗？
**A**: 当前版本不支持。如需要，可以：
- 修改服务器配置
- 重新部署

---

## 🛠️ 技术细节

### 版本号生成规则
- 格式：`YYYYMMDD_HHMMSS`
- 示例：`20231220_153045` = 2023年12月20日 15:30:45
- 自动生成，无需手动输入

### 备份机制
- **部署新版本时**：自动备份当前版本为 `backup_{timestamp}`
- **回滚时**：自动备份当前版本
- 备份存储在 `/var/www/app_versions/`

### 上传方式
- 使用 SFTP（基于 SSH）
- 递归上传整个目录
- 实时显示上传进度

---

## ⚠️ 注意事项

1. **部署前务必构建**
   - 必须先运行 `npm run build:core`
   - 确保 `dist_core/` 目录存在且完整

2. **生产环境谨慎操作**
   - 部署会直接替换线上版本
   - 建议先在测试环境验证

3. **保留足够历史版本**
   - 建议至少保留 3-5 个历史版本
   - 便于快速回滚

4. **定期清理旧版本**
   - 旧版本会占用服务器空间
   - 定期删除不再需要的版本

---

## 📞 支持

如有问题，请联系开发者或查看：
- [AdminTool/README.md](./README.md)
- [项目文档](../README.md)