nanxiisletJava/docs/domain_integration_guide.md

域名管理集成指南

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 同步域名信息

部署请求参数

{
  "domainId": 1,
  "enableHttps": true,
  "acmeAccountId": 1,
  "dnsAccountId": 1,
  "createIfNotExist": true
}

部署结果

{
  "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 封装

使用示例

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