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
|
||||
Reference in New Issue
Block a user