首次提交后端接口

2026-01-27 20:48:47 +08:00
commit 40db55e85d
177 changed files with 18905 additions and 0 deletions
--- a/docs/domain_integration_guide.md
+++ b/docs/domain_integration_guide.md
@@ -0,0 +1,142 @@
+# 域名管理集成指南
+
+## 1Panel 接口文档
+
+1Panel API 文档地址：http://47.109.57.58:42588/1panel/swagger/index.html
+
+## 架构设计
+
+### 数据流
+
+```
+前端(域名管理页面)
+    ↓
+后端(PlatformDomainController)
+    ↓
+后端(PlatformDomainService)
+    ↓ 存储/读取
+数据库(platform_domain表)
+    ↓ 部署时调用
+1Panel API(创建网站/申请证书/配置HTTPS)
+```
+
+### 核心流程
+
+1. **域名创建**：用户在前端新建域名 → 后端存储到数据库（状态为 `pending`，部署状态为 `not_deployed`）
+
+2. **项目关联**：用户在项目管理中绑定域名 → 自动生成项目地址和部署路径
+
+3. **项目部署**（点击"部署"按钮时触发）：
+   - 检查/创建 1Panel 网站
+   - 如果启用 HTTPS，检查/申请 SSL 证书
+   - 配置 HTTPS（强制跳转）
+   - 更新域名和项目状态
+
+## 后端接口
+
+### 域名管理 API
+
+| 方法   | 路径                            | 描述                   |
+| ------ | ------------------------------- | ---------------------- |
+| GET    | /platform/domain/list           | 分页获取域名列表       |
+| GET    | /platform/domain/all            | 获取所有域名           |
+| GET    | /platform/domain/{id}           | 获取域名详情           |
+| POST   | /platform/domain                | 新增域名               |
+| PUT    | /platform/domain/{id}           | 更新域名               |
+| DELETE | /platform/domain/{id}           | 删除域名               |
+| GET    | /platform/domain/stats          | 域名统计信息           |
+| POST   | /platform/domain/deploy         | 部署域名到 1Panel      |
+| POST   | /platform/domain/{id}/check-dns | 检查 DNS 解析状态      |
+| POST   | /platform/domain/{id}/sync      | 从 1Panel 同步域名信息 |
+
+### 部署请求参数
+
+```json
+{
+  "domainId": 1,
+  "enableHttps": true,
+  "acmeAccountId": 1,
+  "dnsAccountId": 1,
+  "createIfNotExist": true
+}
+```
+
+### 部署结果
+
+```json
+{
+  "success": true,
+  "message": "部署流程完成",
+  "websiteId": 123,
+  "sslCertificateId": 456,
+  "steps": [
+    {
+      "step": "检查网站",
+      "status": "success",
+      "message": "网站已存在，ID: 123"
+    },
+    {
+      "step": "检查SSL证书",
+      "status": "success",
+      "message": "证书已存在，ID: 456"
+    },
+    { "step": "配置HTTPS", "status": "success", "message": "HTTPS配置成功" }
+  ]
+}
+```
+
+## 数据库表结构
+
+### platform_domain 表
+
+新增字段（V6\_\_domain_enhance.sql）：
+
+- `panel_website_id` - 1Panel 网站 ID
+- `panel_ssl_id` - 1Panel 证书 ID
+- `site_path` - 网站目录路径
+- `alias` - 网站别名
+- `deploy_status` - 部署状态（not_deployed/deploying/deployed/failed）
+- `last_deploy_time` - 最后部署时间
+- `last_deploy_message` - 最后部署消息
+
+## 前端集成
+
+### API 文件
+
+`src/api/domain.ts` - 域名管理 API 封装
+
+### 使用示例
+
+```typescript
+import {
+  getDomainList,
+  createDomain,
+  deployDomain,
+  checkDomainDns,
+} from "@/api/domain";
+
+// 获取域名列表
+const { records, total } = await getDomainList({ page: 1, pageSize: 10 });
+
+// 创建域名
+await createDomain({
+  domain: "example.com",
+  serverId: 1,
+  port: 80,
+});
+
+// 部署域名
+const result = await deployDomain({
+  domainId: 1,
+  enableHttps: true,
+  acmeAccountId: 1,
+  dnsAccountId: 1,
+});
+```
+
+## 注意事项
+
+1. 部署操作是异步的，可能需要等待证书申请完成（最长 120 秒）
+2. 首次部署会自动创建网站目录，路径为 `/opt/1panel/www/sites/{域名}/index`
+3. SSL 证书申请需要配置 Acme 账户和 DNS 账户（在 1Panel 中配置）
+4. 部署完成后，项目的"部署"按钮会自动同步状态