JetSprow/J-Board-Lite
1
0
Fork 0
mirror of https://github.com/JetSprow/J-Board-Lite.git synced 2026-05-01 01:14:10 +05:30
Code Issues Packages Projects Releases Wiki Activity
Files
8034392408182b9ecc38c3f0da2496100d2037f3
J-Board-Lite/docs/API.md
JetSprow 8034392408 docs: update lite deployment and feature docs
2026-05-01 04:56:06 +10:00

15 KiB
Raw Blame History

J-Board Lite API 与 Server Actions

本文整理 J-Board Lite 当前有效的 HTTP Route Handlers 和内部 Server Actions。HTTP 对外结构化描述见 docs/openapi.yaml；本文更偏向工程阅读和排障。

通用约定

  • 普通用户身份：NextAuth Cookie 会话。
  • 管理员身份：NextAuth Cookie 会话，且用户角色为 ADMIN。
  • Agent 身份：Authorization: Bearer <agent-token>。
  • 返回格式：默认 JSON，订阅内容和文件下载接口除外。
  • 时间字段：ISO 8601 字符串。
  • 写操作：必须做权限校验、输入校验、审计记录和必要的 revalidatePath。
  • 3x-ui 密码、Agent Token、SMTP 密码、支付密钥等敏感字段在数据库中加密保存。

认证与公开信息

POST /api/auth/register

注册普通用户。是否允许注册、是否必须邀请码、是否需要邮箱验证由后台系统设置控制。

请求体：

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

行为：

  • 校验邮箱、密码、邀请码和 Turnstile。
  • 当注册邮箱验证开启时，先写入 PendingRegistration 并发送验证邮件，用户不会立即创建。
  • 只有邮箱验证链接通过后，系统才创建 User 并激活。
  • 当注册邮箱验证关闭时，用户直接成为可登录用户。

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

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

GET /api/public/app-info

返回站点名称、注册策略、维护公告、Turnstile 配置、网站公开配置等信息。前端登录页、注册页和公共布局会使用它。

延迟与路由展示

GET /api/latency?nodeId=<id>

返回节点最新三网延迟。

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

返回节点延迟历史。carrier 通常为 telecom、unicom、mobile；range 支持 1d、7d、30d。

GET /api/latency/recommendations

返回前台线路推荐所需的延迟聚合结果。

GET /api/traces?nodeId=<id>

返回节点三网路由追踪结果。服务端会重新归一化历史数据，修正 CN2 GIA、CN2 GT、CMIN2、CMI 等线路分类。

支付接口

GET /api/payment/providers

返回当前启用的支付方式。普通用户创建订单或切换支付方式时使用。?target=wallet 会排除余额支付，避免用户用余额给余额充值。

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}

支付平台异步通知入口。当前 provider 包括：

  • epay
  • alipay_f2f
  • usdt_trc20 的链上入账由查询任务处理，不依赖传统 HTTP 回调。

行为：

  • 校验签名或链上入账。
  • 标记订单已支付。
  • 调用 src/services/provision.ts 创建或续费订阅。
  • 代理订阅会同步 3x-ui client。
  • 充值订单回调会进入钱包入账流程，成功后写入 WalletTransaction。

钱包接口

GET /api/wallet/recharge/{id}

查询当前用户自己的余额充值订单。充值支付页会读取金额、状态、支付方式和流水号。

POST /api/wallet/recharge/payment/create

为余额充值订单创建外部支付参数。

请求体：

{
  "rechargeId": "wallet-recharge-order-id",
  "provider": "epay",
  "channel": "alipay"
}

行为：

  • 要求登录用户拥有该充值订单，且订单仍为 PENDING。
  • 不允许 provider=balance。
  • 调用对应支付适配器生成支付链接、二维码或链上收款信息。

GET /api/wallet/recharge/query/{tradeNo}

按充值流水号主动查询支付状态。用于充值页轮询或回调异常时兜底。

POST /api/wallet/redeem-card

兑换充值卡。余额卡立即入账余额；套餐卡立即激活对应套餐。已使用、过期或不存在的卡密会返回可展示错误。

订阅与用户资源

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

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

行为：

  • 校验订阅状态、到期时间和 token。
  • 记录订阅访问日志和真实 IP。
  • 执行订阅访问限流和地区变化风控。
  • 当订阅被暂停或风控限制时，返回错误内容或拒绝访问。

GET /api/subscription/all

返回用户聚合订阅内容。用于部分客户端的一键导入或总订阅入口。

GET /api/notifications

返回当前用户通知列表。

GET /api/support/attachments/{id}

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

管理读取与导出

以下接口要求管理员会话。

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 数据库备份。备份包含用户、订单、节点、支付、SMTP 等敏感信息，应加密保存。

Agent 上报接口

以下接口由 agent/jboard-agent 调用。Agent Token 存储在 NodeServer.agentToken 中，并加密保存。请求头必须为：

Authorization: Bearer <agent-token>

服务端会通过 Token 匹配到具体节点 nodeId。

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": "203.0.113.1",
          "geo": "CN",
          "latency": 3.5,
          "asn": "AS4809",
          "owner": "China Telecom CN2",
          "isp": "China Telecom"
        }
      ],
      "summary": "CN2 GIA",
      "hopCount": 12
    }
  ]
}

行为：

  • 服务端重新分类线路，避免旧 Agent 或 nexttrace 文案导致误判。
  • 按 nodeId + carrier 更新 RouteTrace。
  • 线路分类会优先识别 CN2 GIA、CN2 GT、CMIN2、CMI 等常见中国方向线路。

POST /api/agent/node-access

接收 Agent 从 Xray access log 聚合出的真实节点连接事件。

请求体：

{
  "events": [
    {
      "clientEmail": "user@example.com-cmojtnp3",
      "sourceIp": "220.240.111.193",
      "inboundTag": "inbound-17583",
      "network": "tcp",
      "targetHost": "example.com",
      "targetPort": 443,
      "action": "accepted",
      "connectionCount": 18,
      "uniqueTargetCount": 14,
      "firstSeenAt": "2026-04-29T09:20:05+10:00",
      "lastSeenAt": "2026-04-29T09:20:07+10:00"
    }
  ]
}

行为：

  • 通过 clientEmail 匹配 NodeClient.email。
  • 同时要求该 client 属于当前 Agent Token 对应节点。
  • 写入 SubscriptionAccessLog，来源标记为“节点真实连接”。
  • 使用 sourceIp 执行国家、省/地区、城市变化风控。
  • 使用 connectionCount 和 uniqueTargetCount 执行节点日志行为风控。
  • 创建 SubscriptionRiskEvent、通知、审计日志，并在需要时自动暂停订阅。

返回示例：

{
  "ok": true,
  "processed": 1,
  "skipped": 0,
  "warnings": 0,
  "suspended": 0
}

常见跳过原因：

  • Xray access log 没有 email: 字段。
  • email: 与本地 NodeClient.email 不一致。
  • 日志来自 [api -> api] 这类 3x-ui 本地 API 通信。
  • 后台关闭了订阅风控总控或节点日志风控。

Server Actions

Server Actions 是后台和用户端写操作的主要入口。它们不是公开 HTTP API，不建议第三方直接调用。

管理端 Actions

节点：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)：生成 Agent Token。
  • revokeAgentToken(nodeId)：撤销 Agent 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/subscription-risk.ts

  • 更新复核状态和复核备注。
  • 生成风险报告。
  • 向用户发送风险报告并开启用户端全屏限制。
  • 解除封控限制并恢复可恢复的代理订阅。
  • 保持封禁/暂停并记录最终处理结果。

后台“订阅风控”页面依赖 src/services/subscription-risk-review.ts 整理地图、IP、分析日志和报告文本。

日志清理：src/actions/admin/logs.ts

  • deleteAdminLogEntry({ target, id })：删除单条审计、任务、流量、节点延迟、风控访问或风控事件日志。
  • cleanupExpiredAdminLogs({ target, cutoffDays })：按日志范围和保留天数手动清理过期日志，并写入审计日志。

自动清理由 src/services/log-cleanup-scheduler.ts 启动，默认每天最多执行一次，读取 AppConfig.logCleanupEnabled 和 AppConfig.logRetentionDays。自动清理和手动过期清理都会保留仍处于用户端限制中的风控事件。

套餐 Push：src/actions/admin/subscription-transfers.ts

  • deleteAdminSubscriptionTransfer(id)：删除管理端 Push 历史记录。待接收记录会先取消转让、恢复套餐、退回已扣手续费，再删除记录；已完成记录只删除历史。

订单：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/logs.ts
  • 备份恢复：src/actions/admin/backups.ts
  • 任务重试：src/actions/admin/tasks.ts
  • 流量视图刷新：src/actions/admin/traffic.ts
  • 优惠券与促销：src/actions/admin/commerce.ts
  • 充值卡：src/actions/admin/recharge-cards.ts，生成余额卡/套餐卡、删除卡密并在需要时释放套餐库存。

用户端 Actions

  • 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：取消待支付订单、重新选择支付方式。
  • src/actions/user/wallet.ts：创建余额充值订单、兑换充值卡、取消待支付充值订单。
  • src/actions/user/subscription-transfer.ts：发起套餐 Push、接收、拒收、取消。发起时会暂停套餐并禁用 3x-ui client，接收成功后会为接收方生成新的 client。

风控数据模型要点

  • SubscriptionAccessLog：保存订阅 API 访问和节点真实连接证据。
  • SubscriptionRiskEvent：保存风控事件、复核状态、报告、用户端限制和最终处理动作。
  • SubscriptionRiskReason：包含城市、省/地区、国家变化，以及节点高频、目标分散等原因。
  • AppConfig：保存订阅风控总控、自动暂停开关、阈值、节点日志风控阈值，以及日志清理开关、保留天数和上次清理时间。
  • NodeClient.email：用于匹配 Xray access log 中的 email:。它可能形如 user@example.com-cmojtnp3，不要手动在 3x-ui 修改。
  • WalletAccount / WalletTransaction / WalletRechargeOrder：保存用户余额、余额流水和充值订单。
  • RechargeCard：保存余额卡和套餐卡，套餐卡会参与套餐库存占用计算。
  • SubscriptionTransfer：保存套餐 Push 全流程状态、费用承担方、扣费/退款时间、周期起点和 24 小时过期时间。

错误处理约定

  • 输入校验失败：返回 400 或在 Server Action 中返回可展示错误。
  • 未登录：返回 401 或跳转登录。
  • 权限不足：返回 403 或抛出权限错误。
  • 资源不存在：返回 404 或抛出 not found。
  • 外部服务失败：保留审计日志或任务记录，前端展示简洁错误。
  • 生产环境 Server Components 会隐藏原始堆栈；排障时看 docker compose logs -f app。

维护约定

  • 新增公开 HTTP 接口时，同时更新 docs/API.md 和 docs/openapi.yaml。
  • 新增 Agent 上报字段时，同时更新 agent/jboard-agent/README.md。
  • 新增系统设置时，同时更新 .env.example 或 README 中对应后台配置说明。
  • 涉及 3x-ui 客户端状态的写操作必须通过 src/services/node-panel 同步。
  • 不再新增节点控制面、运行配置下发、Xray 进程管理类 Action。
Reference in New Issue View Git Blame Copy Permalink