452 lines
14 KiB
Markdown
452 lines
14 KiB
Markdown
# 项目开发需求说明文档（Django + Bootstrap + MySQL）
|
||
|
||
> 本文档用于告诉 AI Agent：需要开发一个 **类似 Cloudflare / 百度云加速的域名加速面板**，
|
||
> 使用 **Python + Django（非前后端分离）+ Bootstrap + MySQL**，并集成 GoEdge 管理员 API 作为底层 CDN 引擎。
|
||
|
||
---
|
||
|
||
## 1. 项目目标
|
||
|
||
- 搭建一个 **按域名计费的 CDN 加速控制面板**，用户以 CNAME 方式接入域名。
|
||
- 每个域名默认有 **每月 15GB 免费流量**（该值应可在管理后台配置，并可对用户/域名单独调整）。
|
||
- 支持多种 **套餐（Plan）**，不同套餐控制：
|
||
- 每个域名的免费/包含流量额度
|
||
- 每 GB 超量单价
|
||
- 可用功能（WAF、日志、HTTP/3、访问控制、缓存高级规则等）
|
||
- 系统提供：
|
||
- 用户注册登录、域名接入管理、流量统计展示
|
||
- 套餐订购与变更、账单与支付（先定义结构，支付接入可预留）
|
||
- 强大的管理后台（基于 Django Admin + 自定义页面），可灵活配置套餐、免费额度、功能开关、超量策略等。
|
||
- 后端使用 Django 模板 + Bootstrap 完成 UI，**不做前后端分离**。
|
||
|
||
---
|
||
|
||
## 2. 技术栈与基础要求
|
||
|
||
- **后端框架**：Python 3.x + Django 4.x（或当前 LTS）
|
||
- **前端框架**：Django Template + Bootstrap 5（或当前版本）
|
||
- **数据库**：MySQL 8.x
|
||
- **CDN 引擎集成**：通过 HTTP 调用 **GoEdge 管理员 API**（使用 X-Edge-Access-Token）
|
||
- **用户认证**：
|
||
- 使用 Django 内置认证体系扩展（或自定义 User 模型）
|
||
- 支持邮箱 / 用户名登录
|
||
- **语言**：
|
||
- 首版可仅中文界面，保留 i18n 结构，便于未来多语言。
|
||
|
||
---
|
||
|
||
## 3. 核心业务概念与模型
|
||
|
||
### 3.1 用户（User）
|
||
|
||
- 平台登录账号（客户）。
|
||
- 一个用户可以拥有多个域名。
|
||
|
||
### 3.2 域名（Domain / Site / Zone）
|
||
|
||
- 用户添加的待加速域名，如 `example.com`。
|
||
- 用户通过将其子域名（如 `www.example.com`）CNAME 到平台提供的加速域名接入。
|
||
- 每个域名：
|
||
- 绑定一个当前套餐（Plan）
|
||
- 拥有每月免费/包含流量额度
|
||
- 有一套独立的功能配置（WAF 开关、缓存规则等）
|
||
|
||
### 3.3 套餐（Plan）
|
||
|
||
- 按域名计费的套餐模版。
|
||
- 定义：
|
||
- 基础月费：每个域名每月多少钱
|
||
- 包含流量：每个域名每月包含多少 GB
|
||
- 超量单价：每 GB 超出后的费用
|
||
- 功能开关：是否支持 WAF、日志下载、HTTP/3、WebSocket、自定义规则等
|
||
- 可见/可购状态：是否显示给普通用户新购/升级、是否仅管理员可用
|
||
|
||
### 3.4 域名套餐实例（DomainPlan / Subscription）
|
||
|
||
- 某个域名当前使用的套餐实例。
|
||
- 记录：
|
||
- `domain` + `plan`
|
||
- 当前计费周期（开始时间/结束时间）
|
||
- 实际生效的配额（可在 Plan 基础上对该域名单独 override）
|
||
- 自定义价格/流量/功能
|
||
|
||
### 3.5 流量使用记录（Traffic Usage）
|
||
|
||
- 以 **域名 + 日期** 为粒度记录流量数据。
|
||
- 用于：
|
||
- 展示流量图表
|
||
- 计算是否超过“免费额度”和“套餐包含流量”
|
||
- 计算超量费用
|
||
|
||
### 3.6 账单 / 订单（Invoice / Order）
|
||
|
||
- 对应一个计费周期或某一段用量的费用结果。
|
||
- 包含：
|
||
- 基础套餐费用
|
||
- 超量流量费用
|
||
- 优惠/调整
|
||
- 是否已支付
|
||
|
||
---
|
||
|
||
## 4. 功能模块（用户侧）
|
||
|
||
### 4.1 用户注册 / 登录 / 账号管理
|
||
|
||
**需求：**
|
||
|
||
- 用户可以通过邮箱注册账号。
|
||
- 登录支持：
|
||
- 用户名 + 密码 或 邮箱 + 密码
|
||
- 验证码系统（预留，可以用简单图形验证码）。
|
||
- 用户中心页面：
|
||
- 修改密码
|
||
- 查看登录历史（最近若干登录 IP、时间）
|
||
- 管理个人信息（名称、联系方式）
|
||
|
||
### 4.2 域名列表 & 概览
|
||
|
||
- 页面：`/domains/`
|
||
- 展示内容：
|
||
- 域名名称
|
||
- 当前套餐名称
|
||
- 本月已用流量 / 当前月度可用流量
|
||
- 状态（未接入 / DNS 未生效 / 正常 / 超额 / 暂停）
|
||
- 支持操作：
|
||
- 添加新域名
|
||
- 进入域名详情
|
||
- 删除/停用域名（逻辑删除或状态标记）
|
||
|
||
### 4.3 添加域名流程（CNAME 接入向导）
|
||
|
||
页面流程（可以拆成一个页面多步骤）：
|
||
|
||
1. 用户输入域名（`example.com`）
|
||
2. 选择接入子域名（可填多个，如 `www.example.com`、`static.example.com`）
|
||
3. 填写源站信息：
|
||
- 源站地址（IP 或 源站域名）
|
||
- 回源协议（HTTP/HTTPS）
|
||
- 回源端口
|
||
4. 选择套餐（默认 Free 套餐，支持可选升级）
|
||
5. 创建后：
|
||
- 后端调用 GoEdge Admin API 创建对应的 Server 与配置；
|
||
- 生成 CNAME 目标，例如：`www.example.com.cdn.platform.com`
|
||
6. 页面展示：
|
||
- 需要添加的 DNS 记录列表
|
||
- 状态为“等待 DNS 配置”
|
||
- 提供“立即检测 DNS 生效情况”的按钮（后台通过 DNS 查询判断）
|
||
|
||
### 4.4 域名详情页
|
||
|
||
- 路径示例：`/domains/<domain_id>/`
|
||
- 展示模块：
|
||
|
||
1. **概览**
|
||
- 当前套餐信息
|
||
- 本月流量进度条（已用 vs 总额度）
|
||
- 超量状态提示（如已超过套餐流量 X GB）
|
||
|
||
2. **统计（流量 / 请求）**
|
||
- 近 24 小时 / 7 天 / 30 天：
|
||
- 流量图（MB/GB）
|
||
- 请求数
|
||
- HTTP 状态码分布（200/404/5xx）
|
||
- 按地区/运营商分布（若 GoEdge 支持）
|
||
|
||
3. **接入信息**
|
||
- 当前接入的子域名和对应的 CNAME 记录
|
||
- DNS 状态
|
||
|
||
4. **功能设置（视套餐决定是否可见/可编辑）**
|
||
- SSL/TLS 设置
|
||
- 缓存规则
|
||
- WAF 总开关
|
||
- IP 黑白名单
|
||
- 路径规则（简单页面规则）
|
||
|
||
> 所有修改类操作都通过 Django 视图调用 GoEdge Admin API 更新配置。
|
||
|
||
### 4.5 套餐列表 & 升级
|
||
|
||
- 页面：`/plans/`
|
||
- 展示所有 **对用户公开的套餐**，包括：
|
||
- 套餐名称、月费
|
||
- 每域名包含流量
|
||
- 超量单价
|
||
- 功能对比（表格形式）
|
||
- 在域名详情页可以：
|
||
- 点击「升级套餐」
|
||
- 跳转到套餐列表，选中一个 Plan → 后端进行升级逻辑（仅变更套餐记录，计费逻辑后续执行）
|
||
|
||
> 支付可先不做实际第三方接口，预留订单记录和“标记为已支付”的操作。
|
||
|
||
### 4.6 账单 / 费用
|
||
|
||
- 页面：`/billing/`
|
||
- 用户可查看：
|
||
- 历史账单列表：时间区间、金额、状态
|
||
- 每个账单详情：
|
||
- 流量用量明细（按域名）
|
||
- 超量部分计算方式
|
||
|
||
> 样式可以简单先实现，支付流程在后端逻辑中预留钩子。
|
||
|
||
---
|
||
|
||
## 5. 功能模块（管理员后台）
|
||
|
||
### 5.1 使用 Django Admin 的基础管理
|
||
|
||
- 启用 Django Admin，并注册模型：
|
||
- 用户管理
|
||
- 域名管理
|
||
- 套餐管理
|
||
- 域名套餐实例（DomainPlan/Subscription）
|
||
- 流量记录
|
||
- 账单/订单
|
||
|
||
### 5.2 自定义管理面板（独立于 admin site 的运营后台）
|
||
|
||
> 目的：提供一个比 Django Admin 更贴合业务的运营控制台。
|
||
|
||
可能路径：`/admin-panel/`（与 Django admin 区分）
|
||
|
||
功能：
|
||
|
||
#### 5.2.1 全局系统设置
|
||
|
||
- 例如 `SystemSettings` 表，对应的配置项：
|
||
- `default_free_traffic_gb_per_domain`（默认每域名每月免费流量，默认 15）
|
||
- 默认超量策略（超量是否允许访问、是否限速、是否自动停服）
|
||
- GoEdge API 地址 + 管理员 `X-Edge-Access-Token`
|
||
- 默认 CNAME 目标域名模板（如 `<subdomain>.cdn.xxx.com`）
|
||
|
||
#### 5.2.2 套餐管理（Plans）
|
||
|
||
- 新增/编辑/删除套餐：
|
||
- 套餐名称、描述
|
||
- 月费（每域名月费）
|
||
- 每域名包含流量（GB）
|
||
- 超量单价（元/GB）
|
||
- 功能开关（布尔或 JSON 配置）：
|
||
- 启用 WAF（是/否）
|
||
- 是否支持自定义 SSL 证书
|
||
- 是否支持实时日志
|
||
- 是否支持 HTTP/3
|
||
- 是否支持 WebSocket
|
||
- 是否支持自定义规则（页面规则数量上限）
|
||
- 可见性：
|
||
- 是否对普通用户展示
|
||
- 是否允许新购
|
||
- 是否允许续费
|
||
- 是否只允许管理员手动分配
|
||
|
||
#### 5.2.3 用户与域名管理
|
||
|
||
- 用户列表：
|
||
- 查看用户基本信息、注册时间、状态
|
||
- 查看该用户下所有域名
|
||
- 域名列表：
|
||
- 按域名搜索、按用户过滤
|
||
- 查看当前使用的套餐、用量、状态
|
||
- 操作：
|
||
- 手动切换套餐
|
||
- 为该域名增加 **额外的免费流量额度**（本周期）
|
||
- 为该域名设置 **自定义超量单价**
|
||
- 暂停/恢复域名
|
||
- 查看与 GoEdge 的映射关系（serverId / clusterId 等）
|
||
|
||
#### 5.2.4 免费流量与配额调整
|
||
|
||
- 支持对以下层级做手动调整：
|
||
1. 全局默认（所有新域名默认免费 15GB）
|
||
2. 某个套餐的包含流量
|
||
3. 某个用户的默认免费额度（该用户新添加的域名都使用这个值）
|
||
4. 某个具体域名在当前周期的 **个人额外赠送流量**
|
||
|
||
- 在管理面板中应有页面：
|
||
- 显示每个域名：
|
||
- 基础套餐流量
|
||
- 全局默认调整
|
||
- 用户层级额外
|
||
- 域名本身额外
|
||
- 以及最终计算出的“本周期可用总免费流量”。
|
||
|
||
#### 5.2.5 计费与账单管理
|
||
|
||
- 账单列表：
|
||
- 账单编号、用户、计费周期、总金额、是否已支付
|
||
- 支持：
|
||
- 手动标记账单为已支付
|
||
- 重新生成某个周期的账单（用于调试或运营）
|
||
- 对超量部分进行 **人工减免或加价**（在账单上增加调账项目）
|
||
|
||
#### 5.2.6 运维监控 & 风控（可分阶段实现）
|
||
|
||
- 简单版本：
|
||
- 全平台每日总流量曲线
|
||
- 域名按流量排序的 Top N 列表
|
||
- 进一步：
|
||
- 配置“异常流量检测阈值”（例如当日流量超过过去 7 日平均的 3 倍）→ 标记异常域名
|
||
|
||
---
|
||
|
||
## 6. 数据库设计（概要说明）
|
||
|
||
> 这里仅做表与字段的**概念说明**，具体字段类型和索引由 AI Agent 在实现时按 MySQL 习惯设计。
|
||
|
||
### 6.1 用户相关
|
||
|
||
- `users`（可扩展 Django User 或自定义）
|
||
- id
|
||
- username
|
||
- email
|
||
- password_hash
|
||
- is_active
|
||
- is_staff / is_superuser
|
||
- created_at, updated_at
|
||
|
||
- `user_profile`（可选扩展）
|
||
- user_id (FK)
|
||
- display_name
|
||
- contact_phone
|
||
- default_free_traffic_gb_per_domain_override（用户级默认免费流量覆盖值）
|
||
|
||
### 6.2 域名与接入
|
||
|
||
- `domains`
|
||
- id
|
||
- user_id (FK)
|
||
- name（`example.com`）
|
||
- status（pending_dns / active / suspended / deleted）
|
||
- current_plan_id (FK → plans)
|
||
- current_cycle_start
|
||
- current_cycle_end
|
||
- cname_targets（JSON，子域名与 CNAME 目标映射）
|
||
- origin_config（JSON：源站地址/端口/协议等）
|
||
- edge_server_id（在 GoEdge 中的 serverId）
|
||
- created_at, updated_at
|
||
|
||
- `domain_overrides`（域名级别的配额/价格/功能覆盖，可合并到 domains 里）
|
||
- domain_id (FK)
|
||
- extra_free_traffic_gb_current_cycle（本周期额外赠送的免费流量）
|
||
- custom_overage_price_per_gb
|
||
- custom_features (JSON)
|
||
- note
|
||
|
||
### 6.3 套餐 & 功能
|
||
|
||
- `plans`
|
||
- id
|
||
- name
|
||
- description
|
||
- billing_mode（per_domain_monthly）
|
||
- base_price_per_domain
|
||
- included_traffic_gb_per_domain
|
||
- overage_price_per_gb
|
||
- allow_overage（是否允许超量计费）
|
||
- is_active
|
||
- is_public
|
||
- allow_new_purchase
|
||
- allow_renew
|
||
- created_at, updated_at
|
||
|
||
- `plan_features`（或直接用 JSON 存在 plans 中）
|
||
- plan_id
|
||
- key（如 `waf_enabled`、`http3_enabled` 等）
|
||
- value（bool/int/string）
|
||
|
||
### 6.4 流量统计与计费
|
||
|
||
- `domain_traffic_daily`
|
||
- id
|
||
- domain_id (FK)
|
||
- day（日期）
|
||
- bytes
|
||
- peak_bandwidth_mbps
|
||
- created_at
|
||
|
||
- `invoices`
|
||
- id
|
||
- user_id
|
||
- period_start
|
||
- period_end
|
||
- amount_plan_total（该周期所有域名套餐费用之和）
|
||
- amount_overage_total
|
||
- amount_adjustment（手工调整）
|
||
- amount_total
|
||
- status（unpaid / paid / cancelled）
|
||
- created_at, paid_at
|
||
|
||
- `invoice_items`
|
||
- id
|
||
- invoice_id (FK)
|
||
- domain_id (FK)
|
||
- description（如“基础套餐费用”、“超量流量费用”等）
|
||
- quantity（如 GB 数）
|
||
- unit_price
|
||
- amount
|
||
|
||
---
|
||
|
||
## 7. 业务流程说明（供实现时参考）
|
||
|
||
### 7.1 域名接入流程
|
||
|
||
1. 用户登录 → 添加域名 → 填写源站 → 选择套餐 → 创建域名记录 + 调 GoEdge 创建 Server
|
||
2. 系统生成 CNAME 目标 → 显示给用户
|
||
3. 用户配置 DNS → 前端提供“检测”按钮 → 后端通过 DNS 查询判断已生效
|
||
4. DNS 生效后，域名状态从 `pending_dns` → `active`，开始正式计流量。
|
||
|
||
### 7.2 计费周期与流量统计（按月）
|
||
|
||
1. 每天定时任务，从 GoEdge 统计 API 拉各域名的流量/请求数据，写入 `domain_traffic_daily`。
|
||
2. 每个域名有自己的计费周期（默认按自然月，也可按首次接入日算周期）。
|
||
3. 周期结束时，后台任务：
|
||
- 计算该周期每个域名总流量
|
||
- 对比“免费/套餐包含流量”：
|
||
- 未超出 → 只收套餐费
|
||
- 超出 → 套餐费 + 超量*单价
|
||
- 生成 `invoice` 和 `invoice_items` 记录。
|
||
|
||
4. 对于未支付账单，可根据策略：
|
||
- 在下一周期开始前停止所有域名（状态为 `suspended`）
|
||
- 或只允许免费额度，超出部分阻断。
|
||
|
||
---
|
||
|
||
## 8. 界面与前端要求（Django + Bootstrap）
|
||
|
||
- 全站使用 Django 模板 + Bootstrap 布局：
|
||
- 顶部导航：登录用户信息、域名列表入口、套餐、账单入口
|
||
- 左侧在“域名详情页”使用类似 Cloudflare 的菜单列表（概览 / 分析 / SSL / 缓存 / 防火墙 / 设置）
|
||
- 表格和列表使用 Bootstrap Table 风格。
|
||
- 表单使用 CSRF 保护。
|
||
- 操作类按钮（如“升级套餐”、“暂停域名”）需二次确认弹窗。
|
||
|
||
---
|
||
|
||
## 9. 安全与权限
|
||
|
||
- 使用 Django Auth + `login_required` 装饰器保护用户页面。
|
||
- 管理后台分两套：
|
||
- Django Admin（仅超级用户访问）
|
||
- 自定义运营面板 `/admin-panel/`（限 staff 与具有相应权限的用户）
|
||
- 所有与 GoEdge API 交互的操作仅在后端进行，前端不暴露任何 GoEdge Access Token。
|
||
- 重要操作（删除域名、切换套餐、调账等）写「操作日志表」，记录操作人、时间、变更内容。
|
||
|
||
---
|
||
|
||
## 10. 可扩展点（后续版本预留）
|
||
|
||
- 支付功能集成（支付宝 / 微信 / Stripe 等）基于易支付：
|
||
- 暂时只定义订单、账单结构，后续接入支付网关。
|
||
- 工单系统（Ticket）
|
||
|
||
---
|
||
|
||
> **AI Agent 实施重点：**
|
||
> - 先完成基础模型（用户 / 域名 / 套餐 / 流量 / 账单）和管理后台结构。
|
||
> - 实现「添加域名 → 生成 CNAME → 拉取流量 → 生成账单」完整闭环。
|
||
> - 前端使用 Django 模板 + Bootstrap 提供一个简单但清晰的 Cloudflare 风格面板。
|