pyGoEdge-UserPanel/reference/report/progress_2025-11-07.md

PyGoEdge 面板开发进度报告（2025-11-07）

概览

• 本次迭代聚焦：修复 GoEdge API 认证与集群配置问题，完善域名接入闭环的关键一环（创建服务），并补齐“套餐”展示与选择。
• 当前状态：开发服务器运行稳定；关键错误已可读性提示；新增页面可预览。

本次迭代完成项

• 核心配置与容错
  • 在 SystemSettings 新增 default_node_cluster_id 字段，并完成迁移，支持默认集群配置。
  • GoEdgeClient 增强：
    • base_url 解析与端口范围校验（1–65535），提前发现无效配置。
    • 所有 HTTP 请求统一添加超时（连接 5s / 读取 15s），避免长时间卡顿。
    • 令牌使用策略优化：优先使用已有 edge_access_token（在有效期内），否则用 AccessKeyId/AccessKey 获取；错误信息更清晰。
    • nodeClusterId 使用回退顺序：入参 → SystemSettings.default_node_cluster_id → 环境变量 GOEDGE_DEFAULT_NODE_CLUSTER_ID；未配置时立即抛出引导性错误。
• 业务流程：添加域名
  • domains/add 提交时调用 createBasicHTTPServer 创建网站，错误通过 Django messages 快速展示。
  • 自动生成 CNAME 映射并保存域名记录为 pending_dns 状态。
• 套餐管理与展示
  • 新增套餐列表页 /plans/，展示“公开（is_public）+ 激活（is_active）+ 允许新购（allow_new_purchase）”的套餐。
  • 添加域名表单的套餐下拉仅显示可购套餐，避免用户选择不可用套餐。
  • 导航在“域名列表 / 添加域名”中增加“套餐”入口便于跳转。
• 管理后台
  • SystemSettings 管理页列表中新增显示 default_node_cluster_id，便于运维核对与配置。

关键修复与改动详情

• 端口非法导致“Failed to parse”问题：通过 base_url 校验在初始化阶段就抛出可读性错误，避免到请求阶段才发现。
• POST 提交卡顿问题：统一请求超时，网络错误通过异常转为明确提示（如连接超时）。
• invalid 'nodeClusterId'：通过新增默认集群 ID 并在客户端加入回退逻辑解决。

新增页面/接口

• 页面：
  • GET /plans/：公开套餐列表（模板：templates/plans/list.html）。
  • 导航更新：templates/domains/list.html、templates/domains/add.html 增加“套餐”按钮。
• 客户端接口：
  • GoEdgeClient.create_basic_http_server() 与 create_server_http_proxy() 注入 nodeClusterId 回退逻辑与请求超时。

环境与配置变化

• .env 新增占位：
  • GOEDGE_DEFAULT_NODE_CLUSTER_ID=（需填写为 GoEdge 的有效集群 ID）。
• 可在 Django Admin → SystemSettings 中配置：
  • goedge_base_url、admin_access_key_id、admin_access_key、default_node_cluster_id。
• 获取 nodeClusterId 的方法（管理员 API）：
  • 使用 APIAccessTokenService/getAPIAccessToken 获取令牌后，调用 NodeClusterService/findAllEnabledNodeClusters。
  • PowerShell 示例：

    $base = $env:GOEDGE_ADMIN_API_BASE_URL
    $id = $env:GOEDGE_ACCESS_KEY_ID
    $key = $env:GOEDGE_ACCESS_KEY
    $resp = Invoke-RestMethod -Method Post -Uri "$base/APIAccessTokenService/getAPIAccessToken" -ContentType 'application/json' -Body (@{type='admin';accessKeyId=$id;accessKey=$key}|ConvertTo-Json)
    $token = $resp.data.token
    $clusters = Invoke-RestMethod -Method Post -Uri "$base/NodeClusterService/findAllEnabledNodeClusters" -ContentType 'application/json' -Headers @{ 'X-Edge-Access-Token' = $token } -Body '{}'
    $clusters.nodeClusters | Select-Object id, name
    

运行与预览

• 开发服务器：0.0.0.0:8001（已运行）。
• 预览地址：
  • 套餐列表：http://127.0.0.1:8001/plans/
  • 域名列表：http://127.0.0.1:8001/domains/
  • 添加域名：http://127.0.0.1:8001/domains/add/
• 当前状态：系统检查无问题；错误通过页面消息提示。

待办与下一步

• DNS 生效检测：在域名详情页提供“立即检测”，后端调用 DNS 查询判断。
• 域名详情页：展示当前套餐、流量进度、接入信息、功能设置入口。
• 流量统计任务：基于 domains.management.commands.pull_daily_stats 增加调度与管理页入口。
• 账单生成与展示：实现周期账单与明细页（billing），支持人工调账与标记支付。
• 运营控制台 /admin-panel/：搭建基础框架与系统设置、套餐管理、配额调整。

风险与注意事项

• 生产配置：goedge_base_url 建议使用 HTTPS；不要在前端暴露 Access Token。
• 集群 ID：必须配置为有效的可用集群，否则创建网站会失败。
• 令牌与密钥安全：AccessKey 请使用受控凭据；令牌缓存过期需自动续期（已支持）。

---

备注：reference/todolist.md 中的初始化任务（T02）已实际完成（项目结构与核心 app 已就位），后续可统一在运营面板上线后更新 todolist 状态与细粒度任务拆分。