# 项目部署流程设计文档

## 概述

本文档描述了项目管理模块与 1Panel 服务器的集成方案，采用**前后端分离架构**：

- **前端**：负责 UI 交互，调用后端 API
- **后端**：存储项目数据到数据库，调用 1Panel API 执行部署

## 架构设计

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           架构示意图                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────┐      ┌──────────────┐      ┌──────────────┐           │
│  │   前端      │──────│   后端 API   │──────│   1Panel     │           │
│  │  (Vue.js)   │ HTTP │  (Spring)    │ HTTP │   服务器     │           │
│  └─────────────┘      └──────────────┘      └──────────────┘           │
│        │                    │                                           │
│        │                    ▼                                           │
│        │              ┌──────────┐                                     │
│        │              │  MySQL   │                                     │
│        │              │  数据库  │                                     │
│        │              └──────────┘                                     │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

## 后端实现

### 1. 实体类扩展 (`PlatformProject.java`)

新增字段：

- `shortName` - 项目简称
- `projectGroup` - 项目分组
- `logo` - Logo 文字
- `color` - 主题色
- `domain` - 绑定域名
- `enableHttps` - 是否启用 HTTPS
- `panelWebsiteId` - 1Panel 网站 ID
- `panelSslId` - 1Panel 证书 ID
- `lastDeployTime` - 最后部署时间
- `lastDeployStatus` - 最后部署状态
- `lastDeployMessage` - 最后部署消息

### 2. DTO 类

- `DeployRequest.java` - 部署请求参数
- `DeployResult.java` - 部署结果

### 3. 服务类

- `OnePanelService.java` - 1Panel 服务接口
- `OnePanelServiceImpl.java` - 1Panel 服务实现

### 4. 控制器 (`PlatformProjectController.java`)

新增接口：
| 接口 | 方法 | 说明 |
|------|------|------|
| `/platform/project/deploy` | POST | 部署项目 |
| `/platform/project/{serverId}/websites` | GET | 获取网站列表 |
| `/platform/project/{serverId}/certificates` | GET | 获取证书列表 |
| `/platform/project/{serverId}/acme-accounts` | GET | 获取 Acme 账户 |
| `/platform/project/{serverId}/dns-accounts` | GET | 获取 DNS 账户 |

### 5. 数据库迁移

执行 `src/main/resources/db/migration_project_deploy.sql`

## 前端实现

### 1. API 封装 (`src/api/project.ts`)

- `deployProject` - 部署项目
- `getServerAcmeAccounts` - 获取 Acme 账户
- `getServerDnsAccounts` - 获取 DNS 账户

### 2. 项目管理页面

- 部署按钮
- 部署确认弹窗
- 部署进度抽屉

## 完整部署流程

1. 前端：用户点击"部署"按钮
2. 前端：打开部署确认弹窗，配置 HTTPS 选项
3. 前端：调用后端 POST /platform/project/deploy
4. 后端：从数据库获取项目和服务器信息
5. 后端：检查/创建网站
6. 后端：如启用 HTTPS，检查/申请证书
7. 后端：配置网站 HTTPS
8. 后端：更新项目状态到数据库
9. 前端：显示部署结果

## 1Panel Token 生成算法

```java
// Token = md5('1panel' + API-Key + UnixTimestamp)
String rawToken = "1panel" + apiKey + timestamp;
String token = DigestUtils.md5DigestAsHex(rawToken.getBytes());
```

## 配置说明

### 服务器配置

在 `platform_server` 表中配置：

- `panel_port` - 1Panel 端口（默认 42588）
- `panel_api_key` - 1Panel API 密钥

### 项目配置

创建项目时配置：

- `domain` - 绑定域名
- `serverId` - 目标服务器
- `deployPath` - 部署路径

## 安全注意事项

1. API 密钥存储在后端数据库，不暴露给前端
2. 每次请求生成新 Token，防止重放攻击
3. 建议在 1Panel 中配置 API 白名单