nanxiisletAdmin/.agent/workflows/deploy-workflow.md

项目部署流程设计文档

概述

本文档描述了项目管理模块与 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 生成算法

// 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 白名单