J-Board-Lite/docs/API.md

J-Board API

本文整理当前有效的 HTTP Route Handlers 和内部 Server Actions。对外 HTTP 结构化描述见 docs/openapi.yaml。

1. 通用约定

• 用户会话：NextAuth Cookie
• 管理接口：必须是管理员会话
• 探测接口：Authorization: Bearer <probe-token>
• 返回格式：JSON，文件下载接口除外
• 时间字段：ISO 8601 字符串

2. 认证

POST /api/auth/register

注册普通用户。

请求体：

{
  "email": "user@example.com",
  "password": "password123",
  "name": "Alice",
  "inviteCode": "optional",
  "turnstileToken": "optional"
}

GET|POST /api/auth/[...nextauth]

NextAuth 内置登录、登出、会话接口。

3. 公共数据

GET /api/public/app-info

返回站点名称、注册策略、维护公告、Turnstile 配置等公开信息。

GET /api/latency?nodeId=<id>

返回节点最新三网延迟。

GET /api/latency/history?nodeId=<id>&carrier=telecom&range=7d

返回节点延迟历史，range 支持 1d、7d、30d。

GET /api/traces?nodeId=<id>

返回节点三网路由追踪结果。

4. 支付

GET /api/payment/providers

返回当前启用的支付方式。

POST /api/payment/create

为待支付订单创建支付参数。

请求体：

{
  "orderId": "order-id",
  "provider": "epay"
}

GET /api/payment/order/{orderId}

查询当前用户自己的订单支付状态。

GET /api/payment/query/{tradeNo}

按支付流水号查询支付状态。

GET|POST /api/payment/notify/{provider}

支付平台异步通知入口。

5. 管理导出与节点读取

GET /api/admin/nodes

返回节点和已同步入站的简要信息。

GET /api/admin/nodes/{id}/inbounds

返回指定节点的已同步入站。

GET /api/admin/export/config

导出配置快照，包含站点设置、公告、服务、套餐、节点、入站、支付配置等。

GET /api/admin/export/audit-logs?q=<keyword>

导出审计日志。

GET /api/admin/backup/database

导出 SQL 数据库备份。

6. 探测上报

以下接口由 agent/jboard-agent 调用，探测 Token 存储在 NodeServer.agentToken 中并加密保存。

POST /api/agent/latency

请求体：

{
  "latencies": [
    { "carrier": "telecom", "latencyMs": 35 },
    { "carrier": "unicom", "latencyMs": 42 },
    { "carrier": "mobile", "latencyMs": 28 }
  ]
}

行为：更新 NodeLatency 并写入 NodeLatencyLog。

POST /api/agent/trace

请求体：

{
  "traces": [
    {
      "carrier": "telecom",
      "hops": [{ "hop": 1, "ip": "*", "geo": "", "latency": 0 }],
      "summary": "CN2 GIA",
      "hopCount": 12
    }
  ]
}

行为：按 nodeId + carrier 更新 RouteTrace。

7. 订阅与附件

GET /api/subscription/{id}?token=<downloadToken>

无需会话，但必须提供合法下载 token。成功返回 text/plain 订阅内容。

GET /api/support/attachments/{id}

工单附件访问接口，要求登录用户是附件所属工单用户本人或管理员。加 ?download=1 可触发下载。

8. Server Actions

Server Actions 是后台和用户端写操作的主要入口。所有管理动作必须经过 requireAdmin()，用户动作必须校验资源归属。

管理端

节点：src/actions/admin/nodes.ts

• createNode(formData)：创建 3x-ui 节点并同步入站
• updateNode(id, formData)：更新 3x-ui 节点连接信息并重新同步入站
• deleteNode(id)：删除节点及本地关联数据
• testNodeConnection(id)：测试 3x-ui 登录并同步入站
• batchTestNodeConnections(formData)：批量测试并同步节点
• updateInboundDisplayName(id, formData)：修改同步入站的前台展示名称
• deleteInbound(id)：仅删除本地入站镜像，不删除 3x-ui 入站
• generateAgentToken(nodeId)：生成探测 Token
• revokeAgentToken(nodeId)：撤销探测 Token

订阅：src/actions/admin/subscriptions.ts

• suspendSubscription(id)：暂停订阅，并通过 3x-ui 禁用代理客户端
• activateSubscription(id)：恢复订阅，并通过 3x-ui 启用代理客户端
• cancelSubscription(id)：取消订阅
• deleteSubscriptionPermanently(id)：删除订阅，并通过 3x-ui 删除代理客户端
• reassignStreamingSlot(...)：调整流媒体槽位
• batchSubscriptionOperation(formData)：批量处理订阅

订单：src/actions/admin/orders.ts

• confirmOrder(orderId)：手动确认订单并触发开通
• cancelOrder(orderId)：取消订单
• updateOrderReview(...)：更新风控/复核状态
• batchOrderOperation(formData)：批量操作订单

其他管理动作：

• 用户：src/actions/admin/users.ts
• 套餐：src/actions/admin/plans.ts
• 流媒体服务：src/actions/admin/services.ts
• 支付配置：src/actions/admin/payments.ts
• 公告：src/actions/admin/announcements.ts
• 工单：src/actions/admin/support.ts
• 系统设置：src/actions/admin/settings.ts
• 备份恢复：src/actions/admin/backups.ts
• 任务重试：src/actions/admin/tasks.ts
• 流量视图刷新：src/actions/admin/traffic.ts
• 优惠券与促销：src/actions/admin/commerce.ts

用户端

• src/actions/user/purchase.ts：立即购买、续费、增流量、查询库存
• src/actions/user/cart.ts：加入购物车、移除、清空、结算
• rotateSubscriptionAccess(subscriptionId)：重置代理订阅访问凭据，并同步更新 3x-ui 客户端
• src/actions/user/account.ts：资料、密码、邀请码
• src/actions/user/notifications.ts：已读、删除、清空
• src/actions/user/support.ts：创建、回复、关闭、删除工单
• src/actions/user/orders.ts：取消待支付订单、重新选择支付方式

约定

• 写操作必须做权限校验和输入校验
• 重要副作用必须记录审计日志
• 影响页面展示后必须 revalidatePath
• 代理客户端变更必须通过 src/services/node-panel 同步 3x-ui
• 不再新增节点控制面、运行配置下发、进程管理类 Action