mirror of
https://github.com/JetSprow/J-Board-Lite.git
synced 2026-05-01 01:14:10 +05:30
Initial commit
This commit is contained in:
JetSprow
219
docs/API.md
Normal file
219
docs/API.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 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`
|
||||
|
||||
注册普通用户。
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
为待支付订单创建支付参数。
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"latencies": [
|
||||
{ "carrier": "telecom", "latencyMs": 35 },
|
||||
{ "carrier": "unicom", "latencyMs": 42 },
|
||||
{ "carrier": "mobile", "latencyMs": 28 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
行为：更新 `NodeLatency` 并写入 `NodeLatencyLog`。
|
||||
|
||||
### `POST /api/agent/trace`
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
385
docs/openapi.yaml
Normal file
385
docs/openapi.yaml
Normal file
@@ -0,0 +1,385 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: J-Board API
|
||||
version: 0.2.0
|
||||
description: Current J-Board Route Handlers. Node provisioning uses 3x-ui; probe API only accepts latency and trace uploads.
|
||||
servers:
|
||||
- url: https://your-domain.com
|
||||
security: []
|
||||
tags:
|
||||
- name: Auth
|
||||
- name: Public
|
||||
- name: Payment
|
||||
- name: Admin
|
||||
- name: Probe
|
||||
- name: Subscription
|
||||
paths:
|
||||
/api/auth/register:
|
||||
post:
|
||||
tags: [Auth]
|
||||
summary: Register a user
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RegisterRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Registered
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OkResponse'
|
||||
'400':
|
||||
description: Invalid request
|
||||
/api/public/app-info:
|
||||
get:
|
||||
tags: [Public]
|
||||
summary: Get public app settings
|
||||
responses:
|
||||
'200':
|
||||
description: App info
|
||||
/api/latency:
|
||||
get:
|
||||
tags: [Public]
|
||||
summary: Get latest carrier latency for a node
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/NodeId'
|
||||
responses:
|
||||
'200':
|
||||
description: Latest latencies
|
||||
/api/latency/history:
|
||||
get:
|
||||
tags: [Public]
|
||||
summary: Get latency history for a node and carrier
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/NodeId'
|
||||
- name: carrier
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/components/schemas/Carrier'
|
||||
- name: range
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
enum: [1d, 7d, 30d]
|
||||
responses:
|
||||
'200':
|
||||
description: Latency history
|
||||
/api/traces:
|
||||
get:
|
||||
tags: [Public]
|
||||
summary: Get latest route traces for a node
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/NodeId'
|
||||
responses:
|
||||
'200':
|
||||
description: Route traces
|
||||
/api/payment/providers:
|
||||
get:
|
||||
tags: [Payment]
|
||||
summary: List enabled payment providers
|
||||
responses:
|
||||
'200':
|
||||
description: Providers
|
||||
/api/payment/create:
|
||||
post:
|
||||
tags: [Payment]
|
||||
summary: Create payment parameters for an order
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreatePaymentRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Payment created
|
||||
/api/payment/order/{orderId}:
|
||||
get:
|
||||
tags: [Payment]
|
||||
summary: Get order payment state
|
||||
parameters:
|
||||
- name: orderId
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Order state
|
||||
/api/payment/query/{tradeNo}:
|
||||
get:
|
||||
tags: [Payment]
|
||||
summary: Query payment by trade number
|
||||
parameters:
|
||||
- name: tradeNo
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Payment state
|
||||
/api/payment/notify/{provider}:
|
||||
get:
|
||||
tags: [Payment]
|
||||
summary: Payment provider notification callback
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/Provider'
|
||||
responses:
|
||||
'200':
|
||||
description: Callback handled
|
||||
post:
|
||||
tags: [Payment]
|
||||
summary: Payment provider notification callback
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/Provider'
|
||||
responses:
|
||||
'200':
|
||||
description: Callback handled
|
||||
/api/admin/nodes:
|
||||
get:
|
||||
tags: [Admin]
|
||||
summary: List nodes and synced inbounds
|
||||
security:
|
||||
- cookieAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Nodes
|
||||
/api/admin/nodes/{id}/inbounds:
|
||||
get:
|
||||
tags: [Admin]
|
||||
summary: List synced inbounds for a node
|
||||
security:
|
||||
- cookieAuth: []
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Inbounds
|
||||
/api/admin/export/config:
|
||||
get:
|
||||
tags: [Admin]
|
||||
summary: Export configuration snapshot
|
||||
security:
|
||||
- cookieAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: JSON file
|
||||
/api/admin/export/audit-logs:
|
||||
get:
|
||||
tags: [Admin]
|
||||
summary: Export audit logs
|
||||
security:
|
||||
- cookieAuth: []
|
||||
parameters:
|
||||
- name: q
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: JSON file
|
||||
/api/admin/backup/database:
|
||||
get:
|
||||
tags: [Admin]
|
||||
summary: Export SQL database backup
|
||||
security:
|
||||
- cookieAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: SQL file
|
||||
/api/agent/latency:
|
||||
post:
|
||||
tags: [Probe]
|
||||
summary: Upload carrier latency probe results
|
||||
security:
|
||||
- probeToken: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LatencyUpload'
|
||||
responses:
|
||||
'200':
|
||||
description: Accepted
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OkResponse'
|
||||
'401':
|
||||
description: Invalid probe token
|
||||
/api/agent/trace:
|
||||
post:
|
||||
tags: [Probe]
|
||||
summary: Upload carrier route trace results
|
||||
security:
|
||||
- probeToken: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TraceUpload'
|
||||
responses:
|
||||
'200':
|
||||
description: Accepted
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OkResponse'
|
||||
'401':
|
||||
description: Invalid probe token
|
||||
/api/subscription/{id}:
|
||||
get:
|
||||
tags: [Subscription]
|
||||
summary: Download subscription content with token
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: token
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Subscription text
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
type: string
|
||||
/api/support/attachments/{id}:
|
||||
get:
|
||||
tags: [Subscription]
|
||||
summary: Download or preview support attachment
|
||||
security:
|
||||
- cookieAuth: []
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: download
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
'200':
|
||||
description: Attachment file
|
||||
components:
|
||||
securitySchemes:
|
||||
cookieAuth:
|
||||
type: apiKey
|
||||
in: cookie
|
||||
name: next-auth.session-token
|
||||
probeToken:
|
||||
type: http
|
||||
scheme: bearer
|
||||
parameters:
|
||||
NodeId:
|
||||
name: nodeId
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
Provider:
|
||||
name: provider
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
schemas:
|
||||
OkResponse:
|
||||
type: object
|
||||
properties:
|
||||
ok:
|
||||
type: boolean
|
||||
required: [ok]
|
||||
Carrier:
|
||||
type: string
|
||||
enum: [telecom, unicom, mobile]
|
||||
RegisterRequest:
|
||||
type: object
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
password:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
inviteCode:
|
||||
type: string
|
||||
turnstileToken:
|
||||
type: string
|
||||
required: [email, password]
|
||||
CreatePaymentRequest:
|
||||
type: object
|
||||
properties:
|
||||
orderId:
|
||||
type: string
|
||||
provider:
|
||||
type: string
|
||||
required: [orderId, provider]
|
||||
LatencyUpload:
|
||||
type: object
|
||||
properties:
|
||||
latencies:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
carrier:
|
||||
$ref: '#/components/schemas/Carrier'
|
||||
latencyMs:
|
||||
type: number
|
||||
required: [carrier, latencyMs]
|
||||
required: [latencies]
|
||||
TraceHop:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
properties:
|
||||
hop:
|
||||
type: integer
|
||||
ip:
|
||||
type: string
|
||||
geo:
|
||||
type: string
|
||||
latency:
|
||||
type: number
|
||||
TraceUpload:
|
||||
type: object
|
||||
properties:
|
||||
traces:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
carrier:
|
||||
$ref: '#/components/schemas/Carrier'
|
||||
hops:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/TraceHop'
|
||||
summary:
|
||||
type: string
|
||||
hopCount:
|
||||
type: integer
|
||||
required: [carrier, hops]
|
||||
required: [traces]
|
||||
Reference in New Issue
Block a user