SingBox-Gopanel/docs/API.md

API 文档

本文档覆盖当前 Go 重构版本中已经接入并可用于前台/后台重构联调的主要接口。

认证与通用约定

• 基础前缀：/api
• 用户接口：/api/v1/user/*
• 后台配置接口：/api/v2/{secure_path}/*
• plugin 后台接口：/api/v1/{secure_path}/*
• 鉴权方式：Authorization: Bearer <jwt>
• 标准成功响应：

{
  "data": {}
}

Supplementary Parity Endpoints

The current Go backend also exposes these Xboard-compatible endpoints:

• POST /api/v1/passport/auth/getQuickLoginUrl
• POST /api/v1/passport/auth/loginWithMailLink
• POST /api/v1/passport/comm/pv
• GET /api/v1/user/comm/config
• POST /api/v1/user/transfer
• POST /api/v1/user/getQuickLoginUrl
• GET /api/v1/user/notice/fetch
• GET /api/v1/user/stat/getTrafficLog
• GET /api/v1/user/invite/save
• GET /api/v1/user/invite/fetch
• GET /api/v1/user/invite/details
• POST /api/v1/user/order/save
• POST /api/v1/user/order/checkout
• GET /api/v1/user/order/check
• GET /api/v1/user/order/detail
• GET /api/v1/user/order/fetch
• GET /api/v1/user/order/getPaymentMethod
• POST /api/v1/user/order/cancel
• POST /api/v1/user/coupon/check
• GET /api/v1/user/telegram/getBotInfo
• POST /api/v1/user/comm/getStripePublicKey
• POST /api/v1/user/gift-card/check
• POST /api/v1/user/gift-card/redeem
• GET /api/v1/user/gift-card/history
• GET /api/v1/user/gift-card/detail
• GET /api/v1/user/gift-card/types
• POST /api/v2/{secure_path}/config/save

Notes:

• order APIs now cover create, query, cancel, payment-method lookup, and zero-amount completion

• invite APIs now read/write the existing v2_* tables directly

• gift card routes are no longer 501, but full reward-application business logic still needs a later dedicated migration

• 标准失败响应：

{
  "message": "error message"
}

Passport

POST /api/v1/passport/auth/login

登录。

请求：

{
  "email": "admin@example.com",
  "password": "password123"
}

响应：

{
  "data": {
    "token": "<jwt>",
    "auth_data": "<jwt>",
    "is_admin": true
  }
}

POST /api/v1/passport/auth/register

注册并直接返回登录态。

GET /api/v1/passport/auth/token2Login?verify=<token>

使用一次性 verify 令牌换取登录态。

POST /api/v1/passport/comm/sendEmailVerify

生成邮箱验证码。

请求：

{
  "email": "user@example.com"
}

响应中会返回 debug_code，便于当前开发阶段联调。

POST /api/v1/passport/auth/forget

使用邮箱验证码重置密码。

请求：

{
  "email": "user@example.com",
  "email_code": "123456",
  "password": "new-password"
}

用户前台接口

GET /api/v1/user/info

返回当前用户信息。

GET /api/v1/user/getSubscribe

返回订阅信息与订阅链接。

GET /api/v1/user/getStat

返回 [待支付订单数, 打开工单数, 邀请人数]。

GET /api/v1/user/server/fetch

返回当前用户可用节点列表。

GET /api/v1/user/checkLogin

返回当前登录状态与管理员标记。

GET /api/v1/user/resetSecurity

重置订阅令牌与 UUID。

POST /api/v1/user/changePassword

修改密码。

POST /api/v1/user/update

更新 remind_expire / remind_traffic。

知识库

GET /api/v1/user/knowledge/fetch

返回知识库文章列表。

查询参数：

• language: 可选，默认 zh-CN

GET /api/v1/user/knowledge/getCategory

返回知识库分类列表。

工单

GET /api/v1/user/ticket/fetch

不带 id 时返回当前用户工单列表。

GET /api/v1/user/ticket/fetch?id=<ticketId>

返回工单详情与消息列表。

POST /api/v1/user/ticket/save

创建工单。

请求：

{
  "subject": "节点异常",
  "level": 1,
  "message": "请帮我检查节点状态"
}

POST /api/v1/user/ticket/reply

回复工单。

POST /api/v1/user/ticket/close

关闭工单。

POST /api/v1/user/ticket/withdraw

撤回工单，当前实现为将工单状态置为关闭。

活跃会话

GET /api/v1/user/getActiveSession

返回当前用户活跃 JWT 会话列表。

POST /api/v1/user/removeActiveSession

撤销指定会话。

请求：

{
  "session_id": "uuid"
}

Plugin: Real Name Verification

GET /api/v1/user/real-name-verification/status

返回实名状态、是否可提交、实名信息掩码、审核结果等。

POST /api/v1/user/real-name-verification/submit

提交实名信息。

请求：

{
  "real_name": "张三",
  "identity_no": "110101199001011234"
}

管理端：

• GET /api/v1/{secure_path}/realname/records
• POST /api/v1/{secure_path}/realname/review/{userId}
• POST /api/v1/{secure_path}/realname/reset/{userId}
• POST /api/v1/{secure_path}/realname/sync-all
• POST /api/v1/{secure_path}/realname/approve-all
• POST /api/v1/{secure_path}/realname/clear-cache

Plugin: User Online Devices

GET /api/v1/user/user-online-devices/get-ip

返回：

• 在线 IP 列表
• session_overview
  • 在线设备数
  • 设备限制
  • 活跃会话列表

管理端：

• GET /api/v1/{secure_path}/user-online-devices/users

Plugin: User Add IPv6 Subscription

GET /api/v1/user/user-add-ipv6-subscription/check

检查当前用户是否允许启用 IPv6 子账号。

POST /api/v1/user/user-add-ipv6-subscription/enable

启用或同步 IPv6 影子账号。

POST /api/v1/user/user-add-ipv6-subscription/sync-password

将主账号密码同步到 IPv6 子账号。

后台统一接口

GET /api/v2/{secure_path}/config/fetch

返回应用名称、站点 URL、后台路径、节点拉取/推送周期。

GET /api/v2/{secure_path}/system/getSystemStatus

返回系统时间与站点基础信息。

GET /api/v2/{secure_path}/plugin/getPlugins

返回 v2_plugins 列表。

GET /api/v2/{secure_path}/plugin/types

返回插件类型。

GET /api/v2/{secure_path}/plugin/integration-status

返回当前 plugin 在 Go 后端中的整合完成度说明。

示例字段：

{
  "data": {
    "real_name_verification": {
      "enabled": true,
      "status": "complete"
    },
    "user_online_devices": {
      "enabled": true,
      "status": "complete"
    },
    "user_add_ipv6_subscription": {
      "enabled": true,
      "status": "integrated_with_runtime_sync"
    }
  }
}