Files

452 lines
14 KiB
Markdown
Raw Permalink Normal View History

2025-11-18 03:36:49 +08:00
# 项目开发需求说明文档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`
- statuspending_dns / active / suspended / deleted
- current_plan_id (FK → plans)
- current_cycle_start
- current_cycle_end
- cname_targetsJSON子域名与 CNAME 目标映射)
- origin_configJSON源站地址/端口/协议等)
- 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_modeper_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` 等)
- valuebool/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
- statusunpaid / 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 风格面板。