# 域名管理集成指南

## 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. 部署完成后，项目的"部署"按钮会自动同步状态