HyperNode-AI/说明.md

HyperNode-AI 说明

HyperNode-AI 是算力节点的控制面。节点程序部署在各处，本服务负责登记节点、接收心跳、下发模拟任务、按天计算积分，并记录提现。

时间全部使用 UTC。每日清算的触发时刻是北京时间 00:05，入账的是上一个已经结束的 UTC 日。

本地开发直接启动时监听 8000。服务器按 部署.md 安装后监听 33333。

pip install -r requirements.txt
python -m app

目录

路径	内容
app/models.py	数据表
app/api.py	HTTP 接口
app/services/heartbeat.py	心跳与离线判断
app/services/tasks.py	任务下发与 nonce 校验
app/services/yield_engine.py	产出公式与按日入账
app/jobs/daily_yield.py	凌晨清算入口
app/scheduler.py	进程内定时任务
app/settle.py	可单独执行的清算命令
frontend/	Vue 3 控制台源码。改完后在该目录执行 npm run build
web/	控制台构建结果，服务启动后打开 /
deploy/manage.sh	Ubuntu 22.04 交互式部署，支持 curl | bash

数据表

业务表：

• users：钱包地址、可选用户名和密码、角色 user / admin、注册时间。
• compute_nodes：节点 SN、购买金额、12 个月授权、online / offline、最后心跳。可选 callback_url 用来推送任务。
• node_yields：每日算力产出和积分。同一节点同一天只有一条。
• withdrawal_logs：提现金额、资产符号、链上哈希、状态。

计算用的表：

• uptime_intervals：一段连续在线时间。
• compute_tasks：下发的模拟任务和回传结果。
• scheduler_locks：多台服务实例同时跑定时任务时互斥。

产出公式

授权金额按授权起止日期的天数线性释放，再乘当天表现系数。单节点累计积分不超过购买金额。

• 在线率 = 当天授权窗口内的在线秒数 / 当天授权有效秒数
• 任务响应率 = 校验通过且执行成功的任务数 / 当天下发任务数
• 当天没有下发任务时，表现系数 = 在线率
• 有任务时，表现系数 = 0.7 × 在线率 + 0.3 × 响应率
• 算力产出 = 购买金额 × 表现系数
• 当日积分 = 算力产出 / 授权天数

开放的在线区间如果最后心跳已超过 15 分钟，只计算到最后一次心跳。

权重可用环境变量 ONLINE_WEIGHT、TASK_WEIGHT 修改，默认 0.7 和 0.3。

运行中的三件事

服务进程里有三个定时任务：

1. 每 5 分钟检查心跳。超过 15 分钟没有心跳，或授权到期，节点改为 offline，在线区间结束在最后一次心跳。
2. 每 5 分钟向在线、授权仍有效、且没有未完成任务的节点随机下发任务，每轮最多 20 台。任务带 task_id 和一次性 nonce。节点若配置了 callback_url，会额外 POST 一次；否则节点用拉取接口领取。
3. 北京时间 00:05 结算上一个已结束的 UTC 日，写入 node_yields。同一天已有记录则跳过。

回传必须带上任务里的 nonce。超时、重复回传、nonce 不匹配都不算成功。

登录

普通用户可以注册钱包、用户名和密码。之后用钱包地址，或用户名加密码登录。管理员只能用账号密码。

新部署会在安装结束时打印管理员账号 admin 和随机密码，并写入 /opt/hypernode/.env 的 ADMIN_PASSWORD。已经部署过的机器如果 .env 里没有这两项，服务第一次启动会在日志里写一次初始密码：

journalctl -u hypernode.service | grep 初始密码

页面路由：

• /login 登录和注册
• /dashboard 用户自己的节点、今日预计积分、提现申请
• /admin 管理员看总用户、总节点、总产出、节点在线率和提现审核

节点心跳、拉任务、回传任务不需要登录。查看全网数据、清算、确认提现需要管理员令牌。

接口

前缀都是 /api/v1。金额在 JSON 里是字符串。浏览器登录后带 Authorization: Bearer <token>。

方法	路径	作用
POST	/auth/register	注册钱包，可带用户名和密码，返回令牌
POST	/auth/login	钱包地址，或用户名加密码
GET	/me/dashboard	当前用户的节点、积分和提现
POST	/me/nodes	给当前钱包登记节点
POST	/me/withdrawals	当前用户申请提现
GET	/admin/summary	管理员：用户数、节点数、总产出
GET	/admin/users	管理员：全网用户
GET	/admin/nodes	管理员：节点状态与今日在线率
GET	/admin/withdrawals	管理员：提现审核列表
POST	/admin/withdrawals/{id}/confirm	管理员：写入链上哈希并完成
POST	/admin/withdrawals/{id}/reject	管理员：拒绝并释放占用的积分
POST	/users	只登记钱包，不设置密码
POST	/nodes	登记节点，必须是该钱包本人或管理员
GET	/nodes/{sn}	查看节点
POST	/node/heartbeat	心跳，请求体 {"sn":"..."}
GET	/node/{sn}/tasks	拉取未完成任务
POST	/node/task/report	回传 sn、task_id、success、nonce
GET	/nodes/{sn}/contribution?yield_date=YYYY-MM-DD	预览某日产出，不入账
POST	/yield/settle?yield_date=YYYY-MM-DD	手动清算，不传日期则清算昨天
GET	/nodes/{sn}/yields	节点流水
GET	/users/{wallet}/balance	可用积分
POST	/withdrawals	申请提现
POST	/withdrawals/{id}/confirm	写入 tx_hash 并完成
POST	/withdrawals/{id}/reject	拒绝并释放占用的积分

可用积分 = 已入账积分 − 待处理提现 − 已完成提现。

健康检查是 /health，不在 /api/v1 下面。

配置

生产环境的配置在 /opt/hypernode/.env。也可以在启动前用同名环境变量覆盖。

变量	默认值	含义
DATABASE_URL	部署后指向 /var/lib/hypernode/hypernode.db	数据库。可改为 PostgreSQL 连接串
HEARTBEAT_TIMEOUT_MINUTES	15	心跳超时
OFFLINE_CHECK_MINUTES	5	离线巡检间隔
TASK_DISPATCH_MINUTES	5	任务下发间隔
DISPATCH_BATCH_SIZE	20	每轮最多下发数量
TASK_DEADLINE_MINUTES	10	任务回传时限
ONLINE_WEIGHT / TASK_WEIGHT	0.7 / 0.3	有任务时的表现系数权重
YIELD_TIMEZONE	Asia/Shanghai	清算触发时区
YIELD_HOUR / YIELD_MINUTE	0 / 5	清算时刻
LICENSE_MONTHS	12	新节点授权月数
DISABLE_SCHEDULER	false	设为 true 时不启动定时任务
JWT_SECRET	空则自动生成并写入数据库	登录令牌签名
JWT_EXPIRE_MINUTES	1440	令牌有效分钟数
ADMIN_USERNAME	admin	初始管理员用户名
ADMIN_PASSWORD	空则首次启动随机生成并写入日志	初始管理员密码
ADMIN_WALLET	admin-root	初始管理员钱包地址

修改 .env 后执行 systemctl restart hypernode。