207 lines
7.8 KiB
Markdown
207 lines
7.8 KiB
Markdown
# 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`
|
||
|
||
## 许可证
|
||
|
||
暂未指定，按企业内部或项目需要补充。 |