pyGoEdge-UserPanel/README.md

# PyGoEdge 控制面板

基于 Python + Django + Bootstrap + MySQL 的按域名计费 CDN 加速控制面板，集成 GoEdge 管理员 API 作为底层 CDN 引擎。支持域名 CNAME 接入、配额与套餐管理、流量统计与账单、可运营的自定义管理面板。

## 主要特性

- 用户与认证：邮箱/用户名登录，用户中心与登录历史
- 域名接入：多子域名 CNAME 接入，源站配置向导，DNS 生效检测
- 套餐与功能：每域名包含流量、超量单价、功能开关（WAF、访问日志、HTTP/3、WebSocket、缓存/路径规则）
- 流量统计：日/小时流量与请求统计、带宽峰值、状态码聚合
- 计费与账单：按周期汇总套餐费与超量费用，生成账单与明细
- 运营管理：自定义运营面板（/admin-panel/），系统级默认配置、策略资源引用、异常流量检测
- GoEdge 集成：管理员 AccessKey → AccessToken 自动获取与缓存；网站创建与功能变更；日志检索
- 界面：Django 模板 + Bootstrap，Cloudflare 风格导航与模块布局

## 目录结构概览

```
pygoedge/
├─ manage.py
├─ requirements.txt
├─ .env.example / .env
├─ pygoedge_panel/
│  ├─ settings.py
│  ├─ settings/
│  │  ├─ base.py
│  │  ├─ dev.py
│  │  └─ prod.py
│  ├─ urls.py
│  ├─ wsgi.py / asgi.py
├─ core/
│  ├─ models.py (SystemSettings, OperationLog)
│  └─ goedge_client.py (GoEdge API 封装)
├─ accounts/ domains/ plans/ billing/ admin_panel/
│  └─ urls.py + views.py + models.py + templates
├─ templates/ static/
└─ ...
```

## 环境要求

- Python 3.10+（推荐 3.11）
- Django 5.2.x
- 数据库：默认 SQLite；生产推荐 MySQL 8.x
- 依赖：详见 `requirements.txt`
  - `python-dotenv`（加载 `.env`）
  - `requests`（GoEdge API）
  - `dnspython`（DNS 检测）
  - `PyMySQL`（Windows 下连接 MySQL）
  - `mysqlclient`（非 Windows 平台可选，性能更优）

## 安装与启动

### 1. 克隆与依赖安装

```
python -m venv .venv
.\.venv\Scripts\activate           # Windows
# 或 source .venv/bin/activate      # Linux/macOS
pip install -r requirements.txt
```

### 2. 配置环境变量

复制示例：

```
cp .env.example .env   # Windows 可手动复制
```

关键项：

- `DJANGO_ENV`：`dev` / `prod`
- `DJANGO_SECRET_KEY`：随机安全字符串
- `DJANGO_ALLOWED_HOSTS`：逗号分隔主机名，生产必填
- `DJANGO_CSRF_TRUSTED_ORIGINS`：例如 `https://panel.example.com`
- 数据库（默认 SQLite）：如用 MySQL，设置 `DB_ENGINE=mysql` 与连接参数
- GoEdge 管理员 API：
  - `GOEDGE_ADMIN_API_BASE_URL=https://your-goedge-host:port`
  - `GOEDGE_ACCESS_KEY_ID` / `GOEDGE_ACCESS_KEY`（用于换取 AccessToken）
  - `GOEDGE_ACCESS_TOKEN`（可选，若直接提供现成令牌）
  - `GOEDGE_DEFAULT_NODE_CLUSTER_ID`（创建站点所需集群 ID）
- 运营默认：
  - `DEFAULT_FREE_TRAFFIC_GB_PER_DOMAIN`（每域名默认免费流量，默认 15）
  - `CNAME_TEMPLATE`（CNAME 目标模板，如 `{sub}.cdn.example.com`）

`.env.example` 内容参考：

```
DJANGO_ENV=dev
DJANGO_SECRET_KEY=change-me
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
DJANGO_DEBUG=True
DJANGO_CSRF_TRUSTED_ORIGINS=
# DB_ENGINE=mysql
# DB_NAME=pygoedge
# DB_USER=root
# DB_PASSWORD=your-password
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_CONN_MAX_AGE=60
GOEDGE_ADMIN_API_BASE_URL=https://your-goedge-host:port
GOEDGE_ACCESS_KEY_ID=your-access-key-id
GOEDGE_ACCESS_KEY=your-access-key
GOEDGE_ACCESS_TOKEN=
GOEDGE_DEFAULT_NODE_CLUSTER_ID=1
```

### 3. 初始化数据库

```
python manage.py migrate
python manage.py createsuperuser
```

如使用 MySQL：

- Windows 推荐 `PyMySQL`（已在 `requirements.txt`），无需额外编译；
- Linux/macOS 可使用 `mysqlclient` 以获得更好性能（确保 MySQL 开发库已安装）。

### 4. 启动开发服务

```
python manage.py runserver 0.0.0.0:8000
```

生产环境请结合反向代理（如 NGINX）与 WSGI/ASGI 服务部署，并在 `DJANGO_ENV=prod` 下启用安全项与静态资源收集：

```
python manage.py collectstatic
```

## 运营配置

### 管理入口

- Django 管理后台：`/admin/`
- 自定义运营面板：`/admin-panel/`

### SystemSettings（系统设置）

通过 Django Admin → SystemSettings 配置下列项：

- `goedge_base_url`：GoEdge 管理员 API 基础地址（与 `.env` 中 `GOEDGE_ADMIN_API_BASE_URL` 一致）
- `admin_access_key_id` / `admin_access_key`：管理员 AccessKey，用于自动获取 AccessToken
- `edge_access_token` / `edge_token_expires_at`：AccessToken 缓存与过期时间（自动维护）
- `default_node_cluster_id`：创建站点使用的节点集群 ID（可被 `.env` 覆盖）
- `default_free_traffic_gb_per_domain`：每域名默认免费流量（默认 15GB）
- `default_overage_policy`：超量策略（允许访问/限速/停服等 JSON 配置）
- `cname_template`：CNAME 目标模板（如 `{sub}.cdn.example.com`）
- 默认策略引用：`default_http_access_log_policy_id` / `default_http_firewall_policy_id`
- 异常流量检测：开关、阈值倍数、窗口天数、最小触发 GB
- 易支付预留：`epay_api_base_url`、`epay_pid`、`epay_key`

### GoEdge 集成说明

- 令牌策略：优先使用有效 `edge_access_token`；过期或缺失时用 AccessKey 获取并缓存
- 站点创建：`ServerService/createBasicHTTPServer` 或 `ServerService/createServer`（httpProxy）
- 功能同步：访问日志 / WebSocket / WAF / HTTP/3 / 缓存 / 路径规则 / 重写 / HTTPS 跳转 / 防盗链 / 客户端 IP / 停服 / 请求限速
- 统计读取：日/小时请求数、带宽峰值；访问日志分页检索与状态码聚合

## 业务功能与页面

- `/accounts/`：账号注册 / 登录 / 资料 / 登录历史
- `/domains/`：域名列表与接入向导（子域名、源站、套餐、生成 CNAME、DNS 检测）
- `/domains/<id>/`：域名详情（概览、统计、接入信息、功能设置）
- `/plans/`：套餐列表与升级（公开套餐对比）
- `/billing/`：账单列表与详情（套餐费、超量费用、调整）
- `/admin-panel/`：运营后台（系统设置、套餐管理、用户与域名管理、配额调整、计费与风控）

## 任务与定时（建议）

通过系统任务计划（Linux `cron` / Windows 任务计划）周期运行：

- 拉取每日统计：
  - `python manage.py pull_daily_stats`
- 拉取流量数据：
  - `python manage.py pull_traffic`
- 账单生成（周期结束时触发）：
  - `python manage.py generate_invoices`
- 演示数据初始化（可选）：
  - `python manage.py seed_demo_data`

建议频率：

- 每日统计：每小时或每日
- 流量拉取：每日 1 次（或按需更频繁）
- 账单生成：每月周期结束时运行

## 开发与部署建议

- 开发环境：`DJANGO_ENV=dev`、`DEBUG=True`，`ALLOWED_HOSTS=*`
- 生产环境：`DJANGO_ENV=prod`、`DEBUG=False`，明确 `DJANGO_ALLOWED_HOSTS` 与 `CSRF_TRUSTED_ORIGINS`
- 静态文件：生产执行 `collectstatic`，由前置代理服务静态目录 `STATIC_ROOT`
- 数据库连接复用：设置 `DB_CONN_MAX_AGE=60`（或更高）提高性能
- 安全：不在前端暴露任何 GoEdge AccessToken；所有变更走后端 API；关键操作写入 OperationLog

## 常见问题

- Windows 下 MySQL 连接：默认使用 `PyMySQL`，无需编译；如需 `mysqlclient`，请确保编译环境与 MySQL 开发库完整
- AccessToken 获取失败：检查 `GOEDGE_ADMIN_API_BASE_URL`、`GOEDGE_ACCESS_KEY_ID`、`GOEDGE_ACCESS_KEY` 是否正确，网络与证书是否可达
- 节点集群 ID 未配置：在 SystemSettings 或 `.env` 中填写 `GOEDGE_DEFAULT_NODE_CLUSTER_ID`
- CSRF 相关错误：生产环境设置 `DJANGO_CSRF_TRUSTED_ORIGINS` 与正确的 `ALLOWED_HOSTS`

## 许可证

暂未指定，按企业内部或项目需要补充。