diff --git a/.env.example b/.env.example index 6050663..04a48f1 100644 --- a/.env.example +++ b/.env.example @@ -1,4 +1,4 @@ -# J-Board panel +# J-Board Lite panel APP_PORT="3000" SITE_NAME="J-Board Lite" diff --git a/README.md b/README.md index 743f33d..493e706 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # J-Board Lite -J-Board Lite 是 J-Board 的轻量版本，面向 1C1G 小机器和低资源 Docker 环境优化。它保留代理订阅售卖、流媒体共享、支付、订阅交付、工单、邮件、公告、审计、探测展示与订阅风控等核心功能，同时使用 SQLite 和进程内限流，避免 Postgres、Redis 等额外服务带来的部署负担。 +J-Board Lite 是 J-Board 的轻量版本，面向 1C1G 小机器和低资源 Docker 环境优化。它保留代理订阅售卖、流媒体共享、钱包余额、充值卡、套餐 Push、支付、订阅交付、工单、邮件、公告、审计、探测展示与订阅风控等核心功能，同时使用 SQLite 和进程内限流，避免 Postgres、Redis 等额外服务带来的部署负担。 J-Board Lite 的定位很明确：它是 J-Board 的轻量化部署版本，不是新的节点控制面，也不替代 3x-ui。节点实际运行、入站协议、Xray 客户端配置仍由 3x-ui 维护；面板负责售卖、开通、订阅交付、售后和风险审查，并通过只读 Agent 从节点侧采集延迟、路由和 Xray access log 证据。 @@ -32,7 +32,9 @@ J-Board Lite 只保存售卖和展示需要的节点镜像数据。入站协议 - 支持 Cloudflare Turnstile 人机验证。 - 代理套餐和流媒体套餐购买、续费、增流量。 - 购物车、订单、支付状态查询和支付方式切换。 +- 钱包余额充值、余额支付、余额卡兑换和套餐卡兑换。 - 代理订阅查看、订阅链接下载、订阅访问重置。 +- 套餐 Push：输入接收方邮箱和当前密码即可发起转让，接收方需在 24 小时内确认。 - 线路体验展示：三网延迟、延迟历史、三网路由追踪。 - 流媒体订阅凭据展示。 - 通知中心、工单售后、账号资料、邀请码。 @@ -43,7 +45,9 @@ J-Board Lite 只保存售卖和展示需要的节点镜像数据。入站协议 - 3x-ui 节点管理：保存面板地址、账号、密码，测试连接并同步入站。 - 本地入站展示名维护，套餐绑定同步后的入站线路。 - 探测 Token 管理：用于 Agent 上报延迟、路由和节点日志。 -- 用户、订单、套餐、订阅、流媒体服务、支付配置。 +- 用户、订单、充值订单、套餐、订阅、流媒体服务、支付配置。 +- 钱包与卡密：生成余额充值卡、套餐充值卡，查看兑换详情，删除卡密；套餐卡会占用/释放套餐库存。 +- 套餐 Push 管理：配置总开关、固定转让费、单周期次数、最低剩余天数和最低剩余流量，查看和删除历史记录。 - SMTP 邮件服务设置、注册邮箱验证开关、邮件模板发送。 - 公告、工单、系统设置、审计日志、任务中心、备份恢复。 - 日志清理：审计、任务、流量、延迟和风控日志支持手动删除与自动过期清理。 @@ -328,11 +332,13 @@ server { 2. 配置 SMTP 邮件服务并点击“测试发信”。 3. 按需要开启注册邮箱验证。忘记密码和邮箱变更也会使用 SMTP。 4. 进入“支付配置”，填写并启用至少一种支付方式。 -5. 添加 3x-ui 节点，测试连接并同步入站。 -6. 创建代理套餐，绑定入站；或创建流媒体服务和套餐。 -7. 在节点页生成探测 Token，安装 Agent。 -8. 用普通用户注册、下单、支付、查看订阅，走一遍完整流程。 -9. 进入“订阅风控”，确认地图、IP、分析日志、人工操作按钮都能正常展示。 +5. 如需钱包，确认余额支付开启，并用低金额测试余额充值和余额支付。 +6. 添加 3x-ui 节点，测试连接并同步入站。 +7. 创建代理套餐，绑定入站；或创建流媒体服务和套餐。 +8. 按需配置充值卡、套餐 Push、三网推荐和线路体验。 +9. 在节点页生成探测 Token，安装 Agent。 +10. 用普通用户注册、下单、支付、查看订阅，走一遍完整流程。 +11. 进入“订阅风控”，确认地图、IP、分析日志、人工操作按钮都能正常展示。 可以展示给用户的常用入口： @@ -341,6 +347,8 @@ server { - 套餐商店：`https://你的域名/store` - 用户中心：`https://你的域名/dashboard` - 订阅列表：`https://你的域名/subscriptions` +- 钱包：`https://你的域名/wallet` +- 套餐 Push：`https://你的域名/subscriptions/push` - 工单中心：`https://你的域名/support` ## 邮件与邮箱验证 @@ -361,6 +369,7 @@ SMTP 配置在后台“系统设置”中完成，密码会加密保存在数据 | 支付方式 | 适用场景 | 必填信息 | 回调 / 查询说明 | | --- | --- | --- | --- | +| 余额支付 | 默认启用，适合用户用钱包余额支付订单 | 可选显示名称 | 不走外部网关。关闭时后台会提示确认，普通订单不能再选择余额支付；余额充值本身不能使用余额支付。 | | 易支付 | 第三方聚合支付，常用于支付宝/微信通道 | API 地址、商户 ID、商户密钥、启用渠道 | 通知地址为 `https://你的域名/api/payment/notify/epay`。支持 `alipay`、`wxpay` 渠道。 | | 支付宝当面付 | 支付宝官方扫码支付 | App ID、应用私钥、支付宝公钥、网关地址 | 通知地址为 `https://你的域名/api/payment/notify/alipay_f2f`，也支持订单查询兜底。 | | USDT TRC20 | 加密货币收款 | TRC20 钱包地址、汇率，可选 TronGrid API Key | 没有传统回调，系统按订单金额查询近期 TRC20 入账。建议配置 TronGrid API Key 提高稳定性。 | @@ -373,6 +382,27 @@ SMTP 配置在后台“系统设置”中完成，密码会加密保存在数据 - 支付宝密钥可以填写纯 key 内容或 PEM 格式；系统会自动补 PEM 包装。 - USDT TRC20 按金额匹配入账，测试时避免短时间出现多笔完全相同金额。 +## 钱包、充值卡与套餐 Push + +钱包在用户端 `/wallet` 使用。用户可以创建余额充值订单，选择除余额支付外的外部支付方式完成充值；充值订单可取消，管理员可在订单页的“充值订单”标签查看。普通商品订单支持余额支付，余额不足时会给出可读错误。 + +充值卡在后台“商业配置”中生成： + +- 余额充值卡：兑换后立即入账用户余额。 +- 套餐充值卡：只能绑定已有套餐，兑换后立即激活套餐。 +- 套餐卡生成时会立即占用套餐库存；删除尚未兑换且未过期的套餐卡会释放库存。 +- 卡密列表支持分页、每页数量选择、查看兑换人和兑换时间。 + +套餐 Push 在用户端 `/subscriptions/push` 使用，后台在“系统设置 -> 套餐 Push”配置： + +- 可单独开启或关闭套餐 Push。 +- 可设置固定转让费，支持转出方支付或接收方支付。 +- 可设置同一订阅周期内最多 Push 次数。续费后进入新周期，次数重新计算。 +- 可设置低于多少天到期、剩余多少 GB 流量时不可 Push。 +- 发起后套餐会暂停并禁用 3x-ui client；接收方 24 小时内确认后才转入。 +- 接收成功会删除旧 3x-ui client，给接收方生成新的 client；过期、拒收或取消会恢复原套餐并退回已扣手续费。 +- 管理端 `/admin/subscription-transfers` 可查看详情并删除历史记录。待接收记录被管理员删除时，会先取消转让、恢复套餐并退费。 + ## 节点、3x-ui 与 Agent 节点接入流程： diff --git a/agent/jboard-agent/README.md b/agent/jboard-agent/README.md index c783a89..350f28a 100644 --- a/agent/jboard-agent/README.md +++ b/agent/jboard-agent/README.md @@ -158,14 +158,14 @@ Agent 会解析： - `uniqueTargetCount`：聚合窗口内不同目标数。 - `firstSeenAt` / `lastSeenAt`：窗口内首次和最近连接时间。 -没有 `email:` 的日志会跳过，因为服务端无法把它归属到 J-Board 的 `NodeClient`。`[api -> api]` 这类 3x-ui 本地 API 通信通常也会跳过。 +没有 `email:` 的日志会跳过，因为服务端无法把它归属到 J-Board Lite 的 `NodeClient`。`[api -> api]` 这类 3x-ui 本地 API 通信通常也会跳过。 ## Xray client email 与用户邮箱 -J-Board 用户邮箱和 Xray client email 不一定完全相同。例如： +J-Board Lite 用户邮箱和 Xray client email 不一定完全相同。例如： ```text -J-Board 用户邮箱：user@example.com +J-Board Lite 用户邮箱：user@example.com Xray client email：user@example.com-cmojtnp3 ``` @@ -281,7 +281,7 @@ systemctl restart jboard-agent - 后台系统设置是否开启订阅风控总控。 - 后台是否开启节点日志风控。 - access log 是否包含 `email:`。 -- `email:` 是否与 J-Board 数据库里的 `NodeClient.email` 一致。 +- `email:` 是否与 J-Board Lite 数据库里的 `NodeClient.email` 一致。 - Agent Token 是否属于当前节点。 - 面板日志是否有 `/api/agent/node-access` 的错误。 diff --git a/docs/API.md b/docs/API.md index 824578c..0669ee2 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,6 +1,6 @@ -# J-Board API 与 Server Actions +# J-Board Lite API 与 Server Actions -本文整理 J-Board 当前有效的 HTTP Route Handlers 和内部 Server Actions。HTTP 对外结构化描述见 `docs/openapi.yaml`；本文更偏向工程阅读和排障。 +本文整理 J-Board Lite 当前有效的 HTTP Route Handlers 和内部 Server Actions。HTTP 对外结构化描述见 `docs/openapi.yaml`；本文更偏向工程阅读和排障。 ## 通用约定 @@ -33,7 +33,8 @@ 行为： - 校验邮箱、密码、邀请码和 Turnstile。 -- 当注册邮箱验证开启时，用户会进入 `PENDING_EMAIL` 状态并收到验证邮件。 +- 当注册邮箱验证开启时，先写入 `PendingRegistration` 并发送验证邮件，用户不会立即创建。 +- 只有邮箱验证链接通过后，系统才创建 `User` 并激活。 - 当注册邮箱验证关闭时，用户直接成为可登录用户。 ### `GET|POST /api/auth/[...nextauth]` @@ -66,7 +67,7 @@ NextAuth 内置登录、登出、会话接口。 ### `GET /api/payment/providers` -返回当前启用的支付方式。普通用户创建订单或切换支付方式时使用。 +返回当前启用的支付方式。普通用户创建订单或切换支付方式时使用。`?target=wallet` 会排除余额支付，避免用户用余额给余额充值。 ### `POST /api/payment/create` @@ -109,6 +110,41 @@ NextAuth 内置登录、登出、会话接口。 - 标记订单已支付。 - 调用 `src/services/provision.ts` 创建或续费订阅。 - 代理订阅会同步 3x-ui client。 +- 充值订单回调会进入钱包入账流程，成功后写入 `WalletTransaction`。 + +## 钱包接口 + +### `GET /api/wallet/recharge/{id}` + +查询当前用户自己的余额充值订单。充值支付页会读取金额、状态、支付方式和流水号。 + +### `POST /api/wallet/recharge/payment/create` + +为余额充值订单创建外部支付参数。 + +请求体： + +```json +{ + "rechargeId": "wallet-recharge-order-id", + "provider": "epay", + "channel": "alipay" +} +``` + +行为： + +- 要求登录用户拥有该充值订单，且订单仍为 `PENDING`。 +- 不允许 `provider=balance`。 +- 调用对应支付适配器生成支付链接、二维码或链上收款信息。 + +### `GET /api/wallet/recharge/query/{tradeNo}` + +按充值流水号主动查询支付状态。用于充值页轮询或回调异常时兜底。 + +### `POST /api/wallet/redeem-card` + +兑换充值卡。余额卡立即入账余额；套餐卡立即激活对应套餐。已使用、过期或不存在的卡密会返回可展示错误。 ## 订阅与用户资源 @@ -320,6 +356,10 @@ Server Actions 是后台和用户端写操作的主要入口。它们不是公 自动清理由 `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)`：手动确认订单并触发开通。 @@ -341,6 +381,7 @@ Server Actions 是后台和用户端写操作的主要入口。它们不是公 - 任务重试：`src/actions/admin/tasks.ts` - 流量视图刷新：`src/actions/admin/traffic.ts` - 优惠券与促销：`src/actions/admin/commerce.ts` +- 充值卡：`src/actions/admin/recharge-cards.ts`，生成余额卡/套餐卡、删除卡密并在需要时释放套餐库存。 ### 用户端 Actions @@ -351,6 +392,8 @@ Server Actions 是后台和用户端写操作的主要入口。它们不是公 - `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。 ## 风控数据模型要点 @@ -359,6 +402,9 @@ Server Actions 是后台和用户端写操作的主要入口。它们不是公 - `SubscriptionRiskReason`：包含城市、省/地区、国家变化，以及节点高频、目标分散等原因。 - `AppConfig`：保存订阅风控总控、自动暂停开关、阈值、节点日志风控阈值，以及日志清理开关、保留天数和上次清理时间。 - `NodeClient.email`：用于匹配 Xray access log 中的 `email:`。它可能形如 `user@example.com-cmojtnp3`，不要手动在 3x-ui 修改。 +- `WalletAccount` / `WalletTransaction` / `WalletRechargeOrder`：保存用户余额、余额流水和充值订单。 +- `RechargeCard`：保存余额卡和套餐卡，套餐卡会参与套餐库存占用计算。 +- `SubscriptionTransfer`：保存套餐 Push 全流程状态、费用承担方、扣费/退款时间、周期起点和 24 小时过期时间。 ## 错误处理约定 diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 697913b..49305c0 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -1,8 +1,8 @@ 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. + title: J-Board Lite API + version: 0.3.0 + description: Current J-Board Lite Route Handlers. Node provisioning uses 3x-ui; the Agent API accepts latency, route trace, and Xray access log uploads. servers: - url: https://your-domain.com security: [] @@ -11,8 +11,10 @@ tags: - name: Public - name: Payment - name: Admin - - name: Probe + - name: Agent - name: Subscription + - name: Wallet + - name: Support paths: /api/auth/register: post: @@ -82,6 +84,14 @@ paths: get: tags: [Payment] summary: List enabled payment providers + parameters: + - name: target + in: query + required: false + schema: + type: string + enum: [order, wallet] + description: Use wallet to exclude balance payment from recharge flows. responses: '200': description: Providers @@ -200,10 +210,10 @@ paths: description: SQL file /api/agent/latency: post: - tags: [Probe] - summary: Upload carrier latency probe results + tags: [Agent] + summary: Upload carrier latency results security: - - probeToken: [] + - agentToken: [] requestBody: required: true content: @@ -218,13 +228,13 @@ paths: schema: $ref: '#/components/schemas/OkResponse' '401': - description: Invalid probe token + description: Invalid agent token /api/agent/trace: post: - tags: [Probe] + tags: [Agent] summary: Upload carrier route trace results security: - - probeToken: [] + - agentToken: [] requestBody: required: true content: @@ -239,7 +249,24 @@ paths: schema: $ref: '#/components/schemas/OkResponse' '401': - description: Invalid probe token + description: Invalid agent token + /api/agent/node-access: + post: + tags: [Agent] + summary: Upload aggregated Xray access log events + security: + - agentToken: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/NodeAccessUpload' + responses: + '200': + description: Accepted + '401': + description: Invalid agent token /api/subscription/{id}: get: tags: [Subscription] @@ -264,7 +291,7 @@ paths: type: string /api/support/attachments/{id}: get: - tags: [Subscription] + tags: [Support] summary: Download or preview support attachment security: - cookieAuth: [] @@ -282,13 +309,99 @@ paths: responses: '200': description: Attachment file + /api/subscription/all: + get: + tags: [Subscription] + summary: Download aggregate subscription content + security: + - cookieAuth: [] + responses: + '200': + description: Subscription text + content: + text/plain: + schema: + type: string + /api/notifications: + get: + tags: [Subscription] + summary: List current user notifications + security: + - cookieAuth: [] + responses: + '200': + description: Notifications + /api/wallet/recharge/{id}: + get: + tags: [Wallet] + summary: Get current user's wallet recharge order + security: + - cookieAuth: [] + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: Recharge order + /api/wallet/recharge/payment/create: + post: + tags: [Wallet] + summary: Create external payment parameters for a wallet recharge order + security: + - cookieAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateWalletRechargePaymentRequest' + responses: + '200': + description: Payment created + '400': + description: Invalid recharge or payment provider + /api/wallet/recharge/query/{tradeNo}: + get: + tags: [Wallet] + summary: Query wallet recharge payment by trade number + security: + - cookieAuth: [] + parameters: + - name: tradeNo + in: path + required: true + schema: + type: string + responses: + '200': + description: Recharge payment state + /api/wallet/redeem-card: + post: + tags: [Wallet] + summary: Redeem a balance or subscription recharge card + security: + - cookieAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/RedeemRechargeCardRequest' + responses: + '200': + description: Redeemed + '400': + description: Invalid, used, or expired card components: securitySchemes: cookieAuth: type: apiKey in: cookie name: next-auth.session-token - probeToken: + agentToken: type: http scheme: bearer parameters: @@ -336,7 +449,25 @@ components: type: string provider: type: string + channel: + type: string required: [orderId, provider] + CreateWalletRechargePaymentRequest: + type: object + properties: + rechargeId: + type: string + provider: + type: string + channel: + type: string + required: [rechargeId, provider] + RedeemRechargeCardRequest: + type: object + properties: + code: + type: string + required: [code] LatencyUpload: type: object properties: @@ -383,3 +514,38 @@ components: type: integer required: [carrier, hops] required: [traces] + NodeAccessUpload: + type: object + properties: + events: + type: array + items: + type: object + properties: + clientEmail: + type: string + sourceIp: + type: string + inboundTag: + type: string + network: + type: string + enum: [tcp, udp] + targetHost: + type: string + targetPort: + type: integer + action: + type: string + connectionCount: + type: integer + uniqueTargetCount: + type: integer + firstSeenAt: + type: string + format: date-time + lastSeenAt: + type: string + format: date-time + required: [clientEmail, sourceIp, inboundTag, network, action, connectionCount, uniqueTargetCount] + required: [events] diff --git a/scripts/install-jboard-agent.sh b/scripts/install-jboard-agent.sh index f009778..e2ad40c 100755 --- a/scripts/install-jboard-agent.sh +++ b/scripts/install-jboard-agent.sh @@ -190,7 +190,7 @@ write_systemd_service() { local service_tmp="$TMP_DIR/${SERVICE_NAME}.service" cat > "$service_tmp" </dev/null; then diff --git a/scripts/install-jboard-panel.sh b/scripts/install-jboard-panel.sh index 1e2a870..7b520c6 100755 --- a/scripts/install-jboard-panel.sh +++ b/scripts/install-jboard-panel.sh @@ -239,7 +239,7 @@ load_resource_helpers() { } prepare_repo() { - section "准备 J-Board 代码" + section "准备 J-Board Lite 代码" local default_dir default_dir="$(resolve_default_app_dir)" @@ -253,7 +253,7 @@ prepare_repo() { git_in_repo pull --ff-only origin "$BRANCH" elif [ -e "$APP_DIR" ] && [ "$(find "$APP_DIR" -mindepth 1 -maxdepth 1 2>/dev/null | wc -l | tr -d ' ')" != "0" ]; then echo "安装目录已存在且不为空：$APP_DIR" >&2 - echo "请换一个目录，或设置 APP_DIR 指向空目录/已有 J-Board 仓库。" >&2 + echo "请换一个目录，或设置 APP_DIR 指向空目录/已有 J-Board Lite 仓库。" >&2 exit 1 else run_as_root mkdir -p "$(dirname "$APP_DIR")" @@ -291,7 +291,7 @@ write_env() { tmp="$(mktemp)" { - printf '# J-Board panel\n' + printf '# J-Board Lite Docker panel\n' printf 'APP_PORT="%s"\n' "$(env_escape "$APP_PORT")" printf 'SITE_NAME="%s"\n' "$(env_escape "$SITE_NAME")" printf '\n# SQLite for local tools and Docker\n' @@ -499,7 +499,7 @@ print_summary() { } main() { - section "J-Board 一键部署向导" + section "J-Board Lite Docker 一键部署向导" echo "这个脚本会安装 Docker、准备配置、初始化数据库并启动面板。" echo "适合全新 Linux 服务器；已有环境会尽量保留现有 .env。" diff --git a/scripts/upgrade-jboard-agent.sh b/scripts/upgrade-jboard-agent.sh index c765cd1..0cad9ba 100755 --- a/scripts/upgrade-jboard-agent.sh +++ b/scripts/upgrade-jboard-agent.sh @@ -222,7 +222,7 @@ write_systemd_service() { local service_tmp="$TMP_DIR/${SERVICE_NAME}.service" cat > "$service_tmp" </dev/null; then