CN-JS-HuiBai/SingBox-Gopanel

Fork 0

Files

CN-JS-HuiBai 87ae55ebcf

build / build (api, amd64, linux) (push) Failing after -52s

Details

build / build (api, arm64, linux) (push) Failing after -52s

Details

build / build (api.exe, amd64, windows) (push) Failing after -51s

Details

完善API文档，修复保存按钮的BUG

2026-04-18 22:51:33 +08:00

32 KiB

Raw Permalink Blame History

Xboard API 返回 JSON 结构

基于 reference/Xboard 控制器、资源类、服务类静态分析整理。

说明：

T 代表具体数据类型。
“标准成功壳子”来自 App\Helpers\ApiResponse::success()。
“标准失败壳子”来自 App\Helpers\ApiResponse::fail() 和全局异常处理。
少量接口直接 response()->json() 或返回文本/文件，不走统一壳子。
后台前缀统一记为 /api/v2/{admin_secure_path}。

统一返回壳子

标准成功壳子 `StandardSuccess<T>`

{
  "status": "success",
  "message": "操作成功",
  "data": "<T>",
  "error": null
}

标准失败壳子 `StandardFail`

{
  "status": "fail",
  "message": "错误信息",
  "data": null,
  "error": null
}

如果抛出 ApiException，error 可能带校验细节：

{
  "status": "fail",
  "message": "错误信息",
  "data": null,
  "error": {
    "field": [
      "具体错误"
    ]
  }
}

分页壳子 `Paginate<T>`

{
  "total": 100,
  "current_page": 1,
  "per_page": 10,
  "last_page": 10,
  "data": [
    "<T>"
  ]
}

简单列表壳子 `DataTotal<T>`

{
  "data": [
    "<T>"
  ],
  "total": 100
}

自定义分页壳子 `DataPagination<T>`

{
  "data": [
    "<T>"
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 10,
    "per_page": 15,
    "total": 150
  }
}

裸 `data` 壳子 `BareData<T>`

{
  "data": "<T>"
}

仅消息 `MessageOnly`

{
  "message": "文本消息"
}

共享数据结构

`AuthData`

{
  "token": "用户订阅 token",
  "auth_data": "Bearer <sanctum_token>",
  "is_admin": false
}

`SessionToken`

来自 Sanctum token 原始序列化，核心字段通常包含：

{
  "id": 1,
  "name": "随机 token 名称",
  "abilities": ["*"],
  "last_used_at": "2026-04-18T00:00:00.000000Z",
  "expires_at": "2027-04-18T00:00:00.000000Z",
  "created_at": "2026-04-18T00:00:00.000000Z",
  "updated_at": "2026-04-18T00:00:00.000000Z"
}

`PlanResource`

{
  "id": 1,
  "group_id": 1,
  "name": "套餐名",
  "tags": ["tag1"],
  "content": "展示文案",
  "month_price": 1000,
  "quarter_price": 2000,
  "half_year_price": 3000,
  "year_price": 4000,
  "two_year_price": 5000,
  "three_year_price": 6000,
  "onetime_price": 7000,
  "reset_price": 800,
  "capacity_limit": 100,
  "transfer_enable": 107374182400,
  "speed_limit": 100,
  "device_limit": 3,
  "show": true,
  "sell": true,
  "renew": true,
  "reset_traffic_method": 0,
  "sort": 1,
  "created_at": 1710000000,
  "updated_at": 1710000000
}

`OrderResource`

Order 原始字段加两个派生字段：

{
  "id": 1,
  "user_id": 1,
  "plan_id": 1,
  "trade_no": "uuid",
  "total_amount": 1000,
  "balance_amount": 0,
  "status": 0,
  "type": 1,
  "period": "month_price",
  "coupon_id": null,
  "payment_id": null,
  "created_at": 1710000000,
  "updated_at": 1710000000,
  "plan": "<PlanResource|null>"
}

`TicketResource`

{
  "id": 1,
  "level": 1,
  "reply_status": 0,
  "status": 0,
  "subject": "主题",
  "message": [
    "<MessageResource>"
  ],
  "created_at": 1710000000,
  "updated_at": 1710000000,
  "user_id": 1
}

`MessageResource`

{
  "id": 1,
  "ticket_id": 1,
  "is_me": true,
  "message": "正文",
  "created_at": 1710000000,
  "updated_at": 1710000000
}

`KnowledgeResource`

{
  "id": 1,
  "category": "分类",
  "title": "标题",
  "body": "正文，可选",
  "updated_at": 1710000000
}

`InviteCodeResource`

{
  "user_id": 1,
  "code": "ABCDEFGH",
  "pv": 12,
  "status": 0,
  "created_at": 1710000000,
  "updated_at": 1710000000
}

`CommissionLogResource`

{
  "id": 1,
  "order_amount": 1000,
  "trade_no": "uuid",
  "get_amount": 100,
  "created_at": 1710000000
}

`TrafficLogResource`

{
  "d": 1024,
  "u": 2048,
  "record_at": 1710000000,
  "server_rate": 1,
  "user_id": 1
}

`NodeResource`

{
  "id": 1,
  "type": "vmess",
  "version": 2,
  "name": "香港 01",
  "rate": 1,
  "tags": ["hk"],
  "is_online": true,
  "cache_key": "hash",
  "last_check_at": 1710000000
}

`NodeConfig`

节点配置的公共骨架如下，具体字段按协议追加：

{
  "protocol": "vmess|trojan|vless|shadowsocks|hysteria|tuic|anytls|socks|naive|http|mieru",
  "listen_ip": "0.0.0.0",
  "server_port": 443,
  "network": "tcp|ws|grpc|...",
  "networkSettings": {},
  "base_config": {
    "push_interval": 60,
    "pull_interval": 60
  },
  "routes": [],
  "custom_outbounds": [],
  "custom_routes": [],
  "cert_config": {}
}

协议常见追加字段：

shadowsocks: cipher, plugin, plugin_opts, server_key
vmess: tls, multiplex
trojan: host, server_name, tls, tls_settings, multiplex
vless: tls, flow, decryption, tls_settings, multiplex
hysteria: version, host, server_name, up_mbps, down_mbps, obfs, obfs-password
tuic: version, server_name, congestion_control, tls_settings, auth_timeout, zero_rtt_handshake, heartbeat
anytls: server_name, padding_scheme

V1 Guest

接口	成功返回	失败/特殊返回
`GET /api/v1/guest/plan/fetch`	`StandardSuccess<PlanResource[]>`	`StandardFail`
`POST /api/v1/guest/telegram/webhook`	空响应体，`200`	`StandardFail`，常见为 `401`
`GET/POST /api/v1/guest/payment/notify/{method}/{uuid}`	可能是 `StandardFail`，也可能是纯文本 `"success"`，也可能是支付插件自定义返回	失败时通常 `StandardFail`
`GET /api/v1/guest/comm/config`	`StandardSuccess<{ tos_url, is_email_verify, is_invite_force, email_whitelist_suffix, is_captcha, captcha_type, recaptcha_site_key, recaptcha_v3_site_key, recaptcha_v3_score_threshold, turnstile_site_key, app_description, app_url, logo, is_recaptcha }>`	`StandardFail`

V1 Passport

接口	成功返回	失败/特殊返回
`POST /api/v1/passport/auth/register`	`StandardSuccess<AuthData>`	`StandardFail`
`POST /api/v1/passport/auth/login`	`StandardSuccess<AuthData>`	`StandardFail`
`GET /api/v1/passport/auth/token2Login`	分支 1: `302` 跳转；分支 2: `BareData<AuthData>`	参数错误时 `{"message":"Invalid request"}` 或 `{"message":"Token error"}`
`POST /api/v1/passport/auth/forget`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v1/passport/auth/getQuickLoginUrl`	`StandardSuccess<string>`	未授权时 `401`，格式为 `{"message":[401001,"..."]}` 或 `{"message":[401200,"..."]}`
`POST /api/v1/passport/auth/loginWithMailLink`	`StandardSuccess<string	object>`
`POST /api/v1/passport/comm/sendEmailVerify`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v1/passport/comm/pv`	`StandardSuccess<true>`	`StandardFail`

V1 User

接口	成功返回	失败/特殊返回
`GET /api/v1/user/resetSecurity`	`StandardSuccess<string>`，即新的订阅地址	`StandardFail`
`GET /api/v1/user/info`	`StandardSuccess<{ email, transfer_enable, last_login_at, created_at, banned, remind_expire, remind_traffic, expired_at, balance, commission_balance, plan_id, discount, commission_rate, telegram_id, uuid, avatar_url }>`	`StandardFail`
`POST /api/v1/user/changePassword`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v1/user/update`	`StandardSuccess<true>`	`StandardFail`
`GET /api/v1/user/getSubscribe`	`StandardSuccess<{ plan_id, token, expired_at, u, d, transfer_enable, email, uuid, device_limit, speed_limit, next_reset_at, plan?, subscribe_url, reset_day }>`	`StandardFail`
`GET /api/v1/user/getStat`	`StandardSuccess<[pending_order_count, pending_ticket_count, invite_user_count]>`	`StandardFail`
`GET /api/v1/user/checkLogin`	`StandardSuccess<{ is_login: true, is_admin?: true }>`	`StandardFail`
`POST /api/v1/user/transfer`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v1/user/getQuickLoginUrl`	`StandardSuccess<string>`	`StandardFail`
`GET /api/v1/user/getActiveSession`	`StandardSuccess<SessionToken[]>`	`StandardFail`
`POST /api/v1/user/removeActiveSession`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v1/user/order/save`	`StandardSuccess<string>`，即 `trade_no`	`StandardFail`
`POST /api/v1/user/order/checkout`	`{"type": -1	0
`GET /api/v1/user/order/check`	`StandardSuccess<number>`，即订单状态码	`StandardFail`
`GET /api/v1/user/order/detail`	`StandardSuccess<OrderResource>`，可能附加 `try_out_plan_id`、`surplus_orders`	`StandardFail`
`GET /api/v1/user/order/fetch`	`StandardSuccess<OrderResource[]>`	`StandardFail`
`GET /api/v1/user/order/getPaymentMethod`	`StandardSuccess<Array<{ id, name, payment, icon, handling_fee_fixed, handling_fee_percent }>>`	`StandardFail`
`POST /api/v1/user/order/cancel`	`StandardSuccess<true>`	`StandardFail`
`GET /api/v1/user/plan/fetch`	`StandardSuccess<PlanResource[]	PlanResource>`
`GET /api/v1/user/invite/save`	`StandardSuccess<boolean>`	`StandardFail`
`GET /api/v1/user/invite/fetch`	`StandardSuccess<{ codes: InviteCodeResource[], stat: [invite_user_count, commission_sum, uncheck_commission_balance, commission_rate, commission_balance] }>`	`StandardFail`
`GET /api/v1/user/invite/details`	`DataTotal<CommissionLogResource>`	通常无统一失败壳子
`GET /api/v1/user/notice/fetch`	`DataTotal<NoticeModel>`	通常无统一失败壳子
`POST /api/v1/user/ticket/reply`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v1/user/ticket/close`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v1/user/ticket/save`	`StandardSuccess<true>`	`StandardFail`
`GET /api/v1/user/ticket/fetch`	`StandardSuccess<TicketResource[]	TicketResource>`
`POST /api/v1/user/ticket/withdraw`	`StandardSuccess<true>`	`StandardFail`
`GET /api/v1/user/server/fetch`	`{"data": NodeResource[]}`，带 `ETag`，命中时返回 `304` 空体	无节点时仍是空数组
`POST /api/v1/user/coupon/check`	`StandardSuccess<CouponModel>`，其中 `limit_plan_ids`、`limit_period` 已被格式化	`StandardFail`
`POST /api/v1/user/gift-card/check`	`StandardSuccess<{ code_info: { code, template: { name, description, type, type_name, icon, background_image, theme_color }, status, status_name, expires_at, usage_count, max_usage, plan_info? }, reward_preview: object, can_redeem: boolean, reason: string	null }>`
`POST /api/v1/user/gift-card/redeem`	`StandardSuccess<{ message, rewards, invite_rewards, template_name }>`	`StandardFail`
`GET /api/v1/user/gift-card/history`	`DataPagination<{ id, code, template_name, template_type, template_type_name, rewards_given, invite_rewards, multiplier_applied, created_at }>`	校验失败时框架默认校验 JSON
`GET /api/v1/user/gift-card/detail`	`StandardSuccess<{ id, code, template: { name, description, type, type_name, icon, theme_color }, rewards_given, invite_rewards, invite_user, user_level_at_use, plan_id_at_use, multiplier_applied, notes, created_at }>`	`StandardFail`
`GET /api/v1/user/gift-card/types`	`StandardSuccess<{ types: object }>`	`StandardFail`
`GET /api/v1/user/telegram/getBotInfo`	`StandardSuccess<{ username: string }>`	`StandardFail`
`GET /api/v1/user/comm/config`	`StandardSuccess<{ is_telegram, telegram_discuss_link, stripe_pk, withdraw_methods, withdraw_close, currency, currency_symbol, commission_distribution_enable, commission_distribution_l1, commission_distribution_l2, commission_distribution_l3 }>`	`StandardFail`
`POST /api/v1/user/comm/getStripePublicKey`	`StandardSuccess<string>`	`StandardFail`
`GET /api/v1/user/knowledge/fetch`	`StandardSuccess<KnowledgeResource	{ [category: string]: KnowledgeResource[] }>`
`GET /api/v1/user/knowledge/getCategory`	路由存在，但控制器中无该方法	实际调用大概率 `500`
`GET /api/v1/user/stat/getTrafficLog`	`StandardSuccess<TrafficLogResource[]>`	`StandardFail`

V1 Server

接口	成功返回	失败/特殊返回
`GET /api/v1/server/UniProxy/config`	`NodeConfig`，带 `ETag`，命中时 `304` 空体	非统一壳子
`GET /api/v1/server/UniProxy/user`	`{"users":[{ "id":1, "uuid":"...", "speed_limit":100, "device_limit":3 }]}`，带 `ETag`	非统一壳子
`POST /api/v1/server/UniProxy/push`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v1/server/UniProxy/alive`	`{"data": true}`	解析失败时 `{"error":"Invalid online data"}`
`GET /api/v1/server/UniProxy/alivelist`	`{"alive": { "uid": ["1.1.1.1"] }}`	非统一壳子
`POST /api/v1/server/UniProxy/status`	`{"data": true, "code": 0, "message": "success"}`	校验失败时为框架校验 JSON
`GET /api/v1/server/ShadowsocksTidalab/user`	`{"data":[{ "id":1, "port":443, "cipher":"aes-256-gcm", "secret":"uuid" }]}`，带 `ETag`	非统一壳子
`POST /api/v1/server/ShadowsocksTidalab/submit`	`{"ret":1,"msg":"ok"}`	非统一壳子
`GET /api/v1/server/TrojanTidalab/config`	原始 JSON 字符串，核心字段为 `run_type/local_addr/local_port/remote_addr/remote_port/password/ssl/api`	失败时 `StandardFail`
`GET /api/v1/server/TrojanTidalab/user`	`{"msg":"ok","data":[{...用户原始字段..., "trojan_user":{"password":"uuid"}}]}`，带 `ETag`	非统一壳子
`POST /api/v1/server/TrojanTidalab/submit`	`{"ret":1,"msg":"ok"}`	非统一壳子

V1 Client

接口	成功返回	失败/特殊返回
`GET /api/v1/client/subscribe`	非 JSON；返回订阅文本，具体格式取决于客户端协议类	不可用时 `403` 空文本
`GET /{subscribe_path}/{token}`	同上	同上
`GET /api/v1/client/app/getConfig`	非 JSON；返回 Clash YAML 文本	非统一壳子
`GET /api/v1/client/app/getVersion`	`StandardSuccess<{ windows_version, windows_download_url, macos_version, macos_download_url, android_version, android_download_url }>`；对旧 UA 会退化为 `{ version, download_url }`	`StandardFail`

V2 Passport / User / Client / Server

接口	成功返回	失败/特殊返回
`/api/v2/passport/*`	与对应 `/api/v1/passport/*` 完全相同	同 V1
`GET /api/v2/user/resetSecurity`	与 `/api/v1/user/resetSecurity` 相同	同 V1
`GET /api/v2/user/info`	与 `/api/v1/user/info` 相同	同 V1
`GET /api/v2/client/app/getConfig`	`{"data": { app_info, features, ui_config, business_rules, server_config, security_config, payment_config, notification_config, cache_config, last_updated, config_hash }}`	非统一壳子
`GET /api/v2/client/app/getVersion`	与 `/api/v1/client/app/getVersion` 相同	同 V1
`POST /api/v2/server/handshake`	`{"websocket":{"enabled":true,"ws_url":"wss://example.com:8076"}}` 或 `{"websocket":{"enabled":false}}`	非统一壳子
`POST /api/v2/server/report`	`{"data": true}`	非统一壳子
其余 `/api/v2/server/config	user	push

V2 Admin - Config / Plan / Server

接口	成功返回	失败/特殊返回
`GET /api/v2/{admin_secure_path}/config/fetch`	`StandardSuccess<ConfigMappings>`；带 `key` 时仅返回单组	`StandardFail`
`POST /api/v2/{admin_secure_path}/config/save`	`StandardSuccess<true>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/config/getEmailTemplate`	`StandardSuccess<string[]>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/config/getThemeTemplate`	`StandardSuccess<string[]>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/config/setTelegramWebhook`	`StandardSuccess<{ success: true, webhook_url: string, webhook_base_url: string	null }>`
`POST /api/v2/{admin_secure_path}/config/testSendMail`	`{"data": <MailLogModel>}`	非统一壳子
`GET /api/v2/{admin_secure_path}/plan/fetch`	`StandardSuccess<PlanModel[]>`，每项额外带 `group/users_count/active_users_count`	`StandardFail`
`POST /api/v2/{admin_secure_path}/plan/save`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/plan/drop`	`StandardSuccess<boolean>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/plan/update`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/plan/sort`	`StandardSuccess<true>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/server/group/fetch`	`StandardSuccess<ServerGroupModel[]>`，含 `users_count/server_count`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/group/save`	`StandardSuccess<boolean>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/group/drop`	`StandardSuccess<boolean>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/server/route/fetch`	`{"data": <ServerRouteModel[]>}`	非统一壳子
`POST /api/v2/{admin_secure_path}/server/route/save`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/route/drop`	`{"data": true}`	失败时 `StandardFail`
`GET /api/v2/{admin_secure_path}/server/manage/getNodes`	`StandardSuccess<ServerModel[]>`，附加 `groups/parent/last_check_at/last_push_at/online/is_online/available_status/cache_key/load_status/metrics/online_conn`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/manage/sort`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/manage/update`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/manage/save`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/manage/drop`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/manage/copy`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/manage/batchDelete`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/manage/resetTraffic`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/server/manage/batchResetTraffic`	`StandardSuccess<true>`	`StandardFail`

ConfigMappings 的顶层 key 为：

invite
site
subscribe
server
email
telegram
app
safe
subscribe_template

V2 Admin - Order / User / Stat

接口	成功返回	失败/特殊返回
`ANY /api/v2/{admin_secure_path}/order/fetch`	`Paginate<OrderModel>`；每项多出 `plan`，且 `period` 已转换成旧字段名	`StandardFail`
`POST /api/v2/{admin_secure_path}/order/update`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/order/assign`	`StandardSuccess<string>`，即 `trade_no`	`StandardFail`
`POST /api/v2/{admin_secure_path}/order/paid`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/order/cancel`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/order/detail`	`StandardSuccess<OrderModel>`，含 `user/plan/commission_log/invite_user/surplus_orders/period`	`StandardFail`
`ANY /api/v2/{admin_secure_path}/user/fetch`	`Paginate<AdminUser>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/user/update`	`StandardSuccess<true>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/user/getUserInfoById`	`StandardSuccess<UserModel>`，已加载 `invite_user`	`StandardFail`
`POST /api/v2/{admin_secure_path}/user/generate`	单个生成: `StandardSuccess<true>`；批量生成 JSON: `{"code":0,"message":"批量生成成功","data":[{ email, password, expired_at, uuid, created_at, subscribe_url }]}`；也可能返回 CSV 文件	`StandardFail`
`POST /api/v2/{admin_secure_path}/user/dumpCSV`	非 JSON；CSV 文件流	参数错误时 `StandardFail`
`POST /api/v2/{admin_secure_path}/user/sendMail`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/user/ban`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/user/resetSecret`	`StandardSuccess<boolean>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/user/setInviteUser`	路由存在，但控制器无方法	实际调用大概率 `500`
`POST /api/v2/{admin_secure_path}/user/destroy`	`StandardSuccess<true>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/stat/getOverride`	`{"data": { month_income, month_register_total, ticket_pending_total, commission_pending_total, day_income, last_month_income, commission_month_payout, commission_last_month_payout, online_nodes, online_devices, online_users, today_traffic, month_traffic, total_traffic }}`	非统一壳子
`GET /api/v2/{admin_secure_path}/stat/getStats`	`{"data": { todayIncome, dayIncomeGrowth, currentMonthIncome, lastMonthIncome, monthIncomeGrowth, lastMonthIncomeGrowth, currentMonthCommissionPayout, lastMonthCommissionPayout, commissionGrowth, commissionPendingTotal, currentMonthNewUsers, totalUsers, activeUsers, userGrowth, onlineUsers, onlineDevices, ticketPendingTotal, onlineNodes, todayTraffic, monthTraffic, totalTraffic }}`	非统一壳子
`GET /api/v2/{admin_secure_path}/stat/getServerLastRank`	`StandardSuccess<array>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/stat/getServerYesterdayRank`	`StandardSuccess<array>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/stat/getOrder`	`{"code":0,"message":"success","data":{"list":[...],"summary":{...}}}`	非统一壳子
`ANY /api/v2/{admin_secure_path}/stat/getStatUser`	`{"data":[<StatUserModel>],"total":100}`	非统一壳子
`GET /api/v2/{admin_secure_path}/stat/getRanking`	路由存在，但控制器无方法	实际调用大概率 `500`
`GET /api/v2/{admin_secure_path}/stat/getStatRecord`	`{"data": <service_result>}`	非统一壳子
`GET /api/v2/{admin_secure_path}/stat/getTrafficRank`	`{"timestamp":"2026-04-18T00:00:00+00:00","data":[{ id, name, value, previousValue, change, timestamp }]}`	非统一壳子

AdminUser 为 User 原始字段加：

{
  "balance": 12.34,
  "commission_balance": 1.23,
  "subscribe_url": "https://example.com/s/xxxxx",
  "plan": {
    "id": 1,
    "name": "套餐"
  },
  "invite_user": {
    "id": 2,
    "email": "a@example.com"
  },
  "group": {
    "id": 1,
    "name": "默认组"
  },
  "total_used": 123456789
}

V2 Admin - Notice / Ticket / Coupon / Knowledge

接口	成功返回	失败/特殊返回
`GET /api/v2/{admin_secure_path}/notice/fetch`	`StandardSuccess<NoticeModel[]>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/notice/save`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/notice/update`	路由存在，但控制器无方法	实际调用大概率 `500`
`POST /api/v2/{admin_secure_path}/notice/drop`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/notice/show`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/notice/sort`	`StandardSuccess<true>`	`StandardFail`
`ANY /api/v2/{admin_secure_path}/ticket/fetch`	详情模式: `StandardSuccess<TicketModel>`，含 `messages/user`；列表模式: `{"data":[<TicketModel+user>],"total":100}`	`StandardFail`
`POST /api/v2/{admin_secure_path}/ticket/reply`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/ticket/close`	`StandardSuccess<true>`	`StandardFail`
`ANY /api/v2/{admin_secure_path}/coupon/fetch`	`Paginate<CouponModel>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/coupon/generate`	单个/编辑时 `StandardSuccess<true>`；批量生成时直接输出 CSV 文本	`StandardFail`
`POST /api/v2/{admin_secure_path}/coupon/drop`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/coupon/show`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/coupon/update`	源码成功路径未 `return`，实际大概率是 `200` 空响应体	失败时 `StandardFail`
`GET /api/v2/{admin_secure_path}/knowledge/fetch`	`StandardSuccess<KnowledgeModel[]	KnowledgeModel>`
`GET /api/v2/{admin_secure_path}/knowledge/getCategory`	`StandardSuccess<string[]>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/knowledge/save`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/knowledge/show`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/knowledge/drop`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/knowledge/sort`	`StandardSuccess<true>`	`StandardFail`

V2 Admin - Gift Card / Payment

接口	成功返回	失败/特殊返回
`ANY /api/v2/{admin_secure_path}/gift-card/templates`	`Paginate<GiftCardTemplateModel>`；源码中自定义映射结果未真正返回	校验失败时为框架校验 JSON
`POST /api/v2/{admin_secure_path}/gift-card/create-template`	`StandardSuccess<GiftCardTemplateModel>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/gift-card/update-template`	`StandardSuccess<GiftCardTemplateModel>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/gift-card/delete-template`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/gift-card/generate-codes`	JSON 模式: `StandardSuccess<{ batch_id, count, message }>`；导出模式: CSV 文件流	`StandardFail`
`ANY /api/v2/{admin_secure_path}/gift-card/codes`	`Paginate<GiftCardCodeModel>`；源码中自定义映射结果未真正返回	校验失败时为框架校验 JSON
`POST /api/v2/{admin_secure_path}/gift-card/toggle-code`	`StandardSuccess<{ message }>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/gift-card/export-codes`	非 JSON；纯文本下载，每行一个 code	校验失败时为框架校验 JSON
`POST /api/v2/{admin_secure_path}/gift-card/update-code`	`StandardSuccess<GiftCardCodeModel>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/gift-card/delete-code`	`StandardSuccess<{ message }>`	`StandardFail`
`ANY /api/v2/{admin_secure_path}/gift-card/usages`	`Paginate<GiftCardUsageModel	mapped_item>`
`ANY /api/v2/{admin_secure_path}/gift-card/statistics`	`StandardSuccess<{ total_stats, daily_usages, type_stats }>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/gift-card/types`	`StandardSuccess<object>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/payment/fetch`	`StandardSuccess<PaymentModel[]>`，每项附加 `notify_url`	`StandardFail`
`GET /api/v2/{admin_secure_path}/payment/getPaymentMethods`	`StandardSuccess<string[]>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/payment/getPaymentForm`	`StandardSuccess<array>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/payment/save`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/payment/drop`	`StandardSuccess<boolean>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/payment/show`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/payment/sort`	`StandardSuccess<true>`	`StandardFail`

V2 Admin - System / Theme / Plugin / Traffic Reset

接口	成功返回	失败/特殊返回
`GET /api/v2/{admin_secure_path}/system/getSystemStatus`	`StandardSuccess<{ schedule: boolean, horizon: boolean, schedule_last_runtime: mixed }>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/system/getQueueStats`	`StandardSuccess<{ failedJobs, jobsPerMinute, pausedMasters, periods, processes, queueWithMaxRuntime, queueWithMaxThroughput, recentJobs, status, wait }>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/system/getQueueWorkload`	`StandardSuccess<array>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/system/getQueueMasters`	返回体由 Laravel Horizon 原生控制器决定；`reference/Xboard` 中未定义	无法仅凭仓库精确静态还原
`GET /api/v2/{admin_secure_path}/system/getHorizonFailedJobs`	`{"data":[...],"total":100,"current":1,"page_size":20}`	非统一壳子
`ANY /api/v2/{admin_secure_path}/system/getAuditLog`	`{"data":[<AdminAuditLogModel>],"total":100}`	非统一壳子
`GET /api/v2/{admin_secure_path}/theme/getThemes`	`StandardSuccess<{ themes: string[], active: string }>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/theme/upload`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/theme/delete`	`StandardSuccess<true>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/theme/saveThemeConfig`	`StandardSuccess<object>`	`StandardFail`
`POST /api/v2/{admin_secure_path}/theme/getThemeConfig`	`StandardSuccess<object>`	`StandardFail`
`GET /api/v2/{admin_secure_path}/plugin/types`	`{"data":[{ value, label, description, icon }]}`	非统一壳子
`GET /api/v2/{admin_secure_path}/plugin/getPlugins`	`{"data":[{ code, name, version, description, author, type, is_installed, is_enabled, is_protected, can_be_deleted, config, readme, need_upgrade }]}`	非统一壳子
`POST /api/v2/{admin_secure_path}/plugin/upload`	`{"message":"插件上传成功"}`	失败时 `400 {"message":"..."}`
`POST /api/v2/{admin_secure_path}/plugin/delete`	`{"message":"插件删除成功"}`	`400/403 {"message":"..."}`
`POST /api/v2/{admin_secure_path}/plugin/install`	`{"message":"插件安装成功"}`	`400 {"message":"..."}`
`POST /api/v2/{admin_secure_path}/plugin/uninstall`	`{"message":"插件卸载成功"}`	`400 {"message":"..."}`
`POST /api/v2/{admin_secure_path}/plugin/enable`	`{"message":"插件启用成功"}`	`400 {"message":"..."}`
`POST /api/v2/{admin_secure_path}/plugin/disable`	`{"message":"插件禁用成功"}`	通常无统一失败壳子
`GET /api/v2/{admin_secure_path}/plugin/config`	`{"data": { ...plugin_config }}`	`400 {"message":"..."}`
`POST /api/v2/{admin_secure_path}/plugin/config`	`{"message":"配置更新成功"}`	`400 {"message":"..."}`
`POST /api/v2/{admin_secure_path}/plugin/upgrade`	`{"message":"插件升级成功"}`	`400 {"message":"..."}`
`GET /api/v2/{admin_secure_path}/traffic-reset/logs`	`DataPagination<{ id, user_id, user_email, reset_type, reset_type_name, reset_time, old_traffic, new_traffic, trigger_source, trigger_source_name, metadata, created_at }>`	校验失败时为框架校验 JSON
`GET /api/v2/{admin_secure_path}/traffic-reset/stats`	`{"data": { total_resets, auto_resets, manual_resets, cron_resets }}`	非统一壳子
`GET /api/v2/{admin_secure_path}/traffic-reset/user/{userId}/history`	`{"data": { user: { id, email, reset_count, last_reset_at, next_reset_at }, history: [{ id, reset_type, reset_type_name, reset_time, old_traffic, trigger_source, trigger_source_name, metadata }] }}`	非统一壳子
`POST /api/v2/{admin_secure_path}/traffic-reset/reset-user`	`{"message":"...","data": { user_id, email, reset_time, next_reset_at }}`	失败时 `400/500 {"message":"..."}`

已知源码级异常点

接口	源码现状	影响
`/api/v1/user/knowledge/getCategory`	路由存在，控制器无方法	实际调用大概率 500
`/api/v2/{admin_secure_path}/user/setInviteUser`	路由存在，控制器无方法	实际调用大概率 500
`/api/v2/{admin_secure_path}/stat/getRanking`	路由存在，控制器无方法	实际调用大概率 500
`/api/v2/{admin_secure_path}/notice/update`	路由存在，控制器无方法	实际调用大概率 500
`/api/v2/{admin_secure_path}/coupon/update`	成功路径没有显式 `return`	可能返回 `200` 空响应体
`/api/v2/{admin_secure_path}/gift-card/templates`	代码构造了映射后的 `$data`，但最终返回的是原始 paginator	文档按“原始模型分页”处理
`/api/v2/{admin_secure_path}/gift-card/codes`	同上	文档按“原始模型分页”处理
`/api/v2/{admin_secure_path}/system/getQueueMasters`	指向 Horizon 外部控制器	仅能标记为“仓库外定义”

32 KiB Raw Permalink Blame History Unescape Escape

Xboard API 返回 JSON 结构

统一返回壳子

标准成功壳子 StandardSuccess<T>

标准失败壳子 StandardFail

分页壳子 Paginate<T>

简单列表壳子 DataTotal<T>

自定义分页壳子 DataPagination<T>

裸 data 壳子 BareData<T>

仅消息 MessageOnly

共享数据结构

AuthData

SessionToken

PlanResource

OrderResource

TicketResource

MessageResource

KnowledgeResource

InviteCodeResource

CommissionLogResource

TrafficLogResource

NodeResource

NodeConfig

V1 Guest

V1 Passport

V1 User

V1 Server

V1 Client

V2 Passport / User / Client / Server

V2 Admin - Config / Plan / Server

V2 Admin - Order / User / Stat

V2 Admin - Notice / Ticket / Coupon / Knowledge

V2 Admin - Gift Card / Payment

V2 Admin - System / Theme / Plugin / Traffic Reset

已知源码级异常点

32 KiB

Raw Permalink Blame History

标准成功壳子 `StandardSuccess<T>`

标准失败壳子 `StandardFail`

分页壳子 `Paginate<T>`

简单列表壳子 `DataTotal<T>`

自定义分页壳子 `DataPagination<T>`

裸 `data` 壳子 `BareData<T>`

仅消息 `MessageOnly`

`AuthData`

`SessionToken`

`PlanResource`

`OrderResource`

`TicketResource`

`MessageResource`

`KnowledgeResource`

`InviteCodeResource`

`CommissionLogResource`

`TrafficLogResource`

`NodeResource`

`NodeConfig`