本文章仅针对开源项目的分析。由于网上V2board的API文档实在是太少了，而且基本上没有提到有管理端的，所以我特地整理了这个文档。
1. 文档说明
提取范围：v2board-master 源码中的路由、控制器、请求校验（FormRequest）
路由前缀：/api/v1
后台前缀：/api/v1/{secure_path}
{secure_path} 来自 config('v2board.secure_path', config('v2board.frontend_admin_path', hash('crc32b', config('app.key'))))
统一 API 中间件：ForceJson（强制 JSON）+ Language（可用 content-language 请求头切换语言）
2. 鉴权与返回约定
2.1 鉴权方式
用户端鉴权（
middleware: user）- 读取
auth_data（body/query）或Authorization请求头 - 通过
AuthService::decryptAuthData()解 JWT
- 读取
管理端鉴权（
middleware: admin）- 同用户端，但要求
is_admin = 1
- 同用户端，但要求
客户端订阅鉴权（
middleware: client）- 必须传
token（query/body），并在v2_user.token命中
- 必须传
员工端鉴权（
middleware: staff）- 同用户端，但要求
is_staff = 1
- 同用户端，但要求
2.2 通用成功返回
大多数接口：
{
"data": "..."
}部分接口会额外返回：
- 分页：
{ data: [...], total: 123 } - 支付下单：
{ type: number, data: any }
2.3 通用失败返回
源码大量使用 abort(status, message)。常见：
- 认证失败：
403 - 参数/业务失败：
500 - 不存在或关闭功能：
404
生产环境常见响应体示例：
{
"message": "未登录或登陆已过期"
}或
{
"message": "Order does not exist"
}3. 用户端 API
下述“用户端”包含：
- 访客/登录注册（
guest+passport） - 登录后用户能力（
user） - 订阅客户端输出（
client）
3.1 访客与登录注册（Guest/Passport）
3.1.1 GET /api/v1/guest/comm/config
- 鉴权：无
- 控制器：
App\Http\Controllers\Guest\CommController@config - 请求参数：无
返回字段（
data）：tos_urlis_email_verifyis_invite_forceemail_whitelist_suffixis_recaptcharecaptcha_site_keyapp_descriptionapp_urllogo
- 成功示例：
{
"data": {
"tos_url": "https://example.com/tos",
"is_email_verify": 1,
"is_invite_force": 0,
"email_whitelist_suffix": ["gmail.com", "qq.com"],
"is_recaptcha": 0,
"recaptcha_site_key": null,
"app_description": "V2Board is best",
"app_url": "https://panel.example.com",
"logo": "https://panel.example.com/logo.png"
}
}- 失败示例：通常无业务失败，配置异常时返回
500+message
3.1.2 GET /api/v1/guest/plan/fetch
- 鉴权：无
- 控制器：
Guest\PlanController@fetch - 请求参数：无
- 返回字段：
data为可展示套餐数组 - 成功示例：
{
"data": [
{
"id": 1,
"name": "Pro",
"group_id": 1,
"month_price": 1999,
"show": 1
}
]
}- 失败示例：
500+message
3.1.3 POST /api/v1/passport/auth/register
- 鉴权：无
- 控制器：
Passport\AuthController@register 请求参数（body）：
emailrequired|email:strictpasswordrequired|min:8invite_codenullable（开启强制邀请时必填）email_codenullable（开启邮箱验证码时必填）recaptcha_datanullable（开启 recaptcha 时使用）
返回字段：
data.token（用户订阅 token）data.is_admindata.auth_data（后续用户鉴权 JWT）
- 成功示例：
{
"data": {
"token": "user_token_xxx",
"is_admin": 0,
"auth_data": "jwt_xxx"
}
}- 失败示例：
{
"message": "Email already exists"
}3.1.4 POST /api/v1/passport/auth/login
- 鉴权：无
- 控制器：
Passport\AuthController@login 请求参数（body）：
emailrequired|email:strictpasswordrequired|min:8
- 返回字段：同注册接口（
token/is_admin/auth_data） - 成功示例：
{
"data": {
"token": "user_token_xxx",
"is_admin": 1,
"auth_data": "jwt_xxx"
}
}- 失败示例：
{
"message": "Incorrect email or password"
}3.1.5 GET /api/v1/passport/auth/token2Login
- 鉴权：无
- 控制器：
Passport\AuthController@token2Login 请求参数（query）：
tokennullable（存在时 302 跳转到前端登录 URL）verifynullable（存在时兑换临时 token，直接返回登录态）redirectnullable
返回字段：
verify分支返回data.token/is_admin/auth_data
- 成功示例（verify 分支）：
{
"data": {
"token": "user_token_xxx",
"is_admin": 0,
"auth_data": "jwt_xxx"
}
}- 失败示例：
{
"message": "Token error"
}3.1.6 POST /api/v1/passport/auth/forget
- 鉴权：无
- 控制器：
Passport\AuthController@forget 请求参数（body）：
emailrequired|email:strictpasswordrequired|min:8email_coderequired
- 返回字段：
data: true - 成功示例：
{
"data": true
}- 失败示例：
{
"message": "Incorrect email verification code"
}3.1.7 POST /api/v1/passport/auth/getQuickLoginUrl
- 鉴权：需要
auth_data或Authorization - 控制器：
Passport\AuthController@getQuickLoginUrl 请求参数（body）：
redirectnullableauth_datanullable（也可放请求头）
- 返回字段：
data为一次性登录链接 - 成功示例：
{
"data": "https://panel.example.com/#/login?verify=...&redirect=dashboard"
}- 失败示例：
403+message: 未登录或登陆已过期
3.1.8 POST /api/v1/passport/auth/loginWithMailLink
- 鉴权：无
- 控制器：
Passport\AuthController@loginWithMailLink 请求参数（body）：
emailrequired|email:strictredirectnullable
- 返回字段：
data为邮件登录链接（或true） - 成功示例：
{
"data": "https://panel.example.com/#/login?verify=..."
}- 失败示例：
{
"message": "Sending frequently, please try again later"
}3.1.9 POST /api/v1/passport/comm/sendEmailVerify
- 鉴权：无
- 控制器：
Passport\CommController@sendEmailVerify 请求参数（body）：
emailrequired|email:strictrecaptcha_datanullable
- 返回字段：
data: true - 成功示例：
{ "data": true } - 失败示例：
{ "message": "Email verification code has been sent, please request again later" }
3.1.10 POST /api/v1/passport/comm/pv
- 鉴权：无
- 控制器：
Passport\CommController@pv 请求参数（body）：
invite_codenullable
- 返回字段：
data: true - 成功示例：
{ "data": true } - 失败示例：
500+message
3.2 登录后用户 API（User）
统一鉴权：auth_data（body/query）或 Authorization（header）
3.2.1 用户资料与账户
GET /api/v1/user/info
- 控制器：
User\UserController@info - 参数：无
返回字段（
data）：emailtransfer_enablelast_login_atcreated_atbannedremind_expireremind_trafficexpired_atbalancecommission_balanceplan_iddiscountcommission_ratetelegram_iduuidavatar_url（控制器拼接）
- 成功示例：
{
"data": {
"email": "[email protected]",
"transfer_enable": 107374182400,
"expired_at": 1780000000,
"balance": 1200,
"commission_balance": 500,
"uuid": "uuid_xxx",
"avatar_url": "https://cdn.v2ex.com/gravatar/..."
}
}- 失败：
{ "message": "The user does not exist" }
GET /api/v1/user/checkLogin
- 控制器：
User\UserController@checkLogin - 参数：无
- 返回字段：
data.is_login、data.is_admin（管理员才有） - 成功示例：
{ "data": { "is_login": true, "is_admin": true } } - 失败：
403未登录
POST /api/v1/user/changePassword
- 控制器：
User\UserController@changePassword 参数（body）：
old_passwordrequirednew_passwordrequired|min:8
- 返回：
data: true - 成功示例：
{ "data": true } - 失败：
{ "message": "The old password is wrong" }
POST /api/v1/user/update
- 控制器：
User\UserController@update 参数（body）：
remind_expirein:0,1remind_trafficin:0,1
- 返回：
data: true - 成功示例：
{ "data": true } - 失败：
{ "message": "Save failed" }
GET /api/v1/user/getStat
- 控制器：
User\UserController@getStat - 参数：无
返回：
data数组（顺序）[待支付订单数, 未关闭工单数, 邀请用户数]
- 成功示例：
{ "data": [1, 0, 12] } - 失败：
403未登录
POST /api/v1/user/transfer
- 控制器：
User\UserController@transfer 参数（body）：
transfer_amountrequired|integer|min:1
- 返回：
data: true - 成功示例：
{ "data": true } - 失败：
{ "message": "Insufficient commission balance" }
GET /api/v1/user/resetSecurity
- 控制器：
User\UserController@resetSecurity - 参数：无
- 返回：
data新订阅地址 - 成功示例：
{
"data": "https://sub.example.com/api/v1/client/subscribe?token=new_token"
}- 失败：
{ "message": "Reset failed" }
POST /api/v1/user/getQuickLoginUrl
- 控制器：
User\UserController@getQuickLoginUrl - 参数：
redirectnullable - 返回：
data一次性登录 URL - 成功示例：
{ "data": "https://panel.example.com/#/login?verify=..." } - 失败：
500/403 + message
GET /api/v1/user/getActiveSession
- 控制器：
User\UserController@getActiveSession - 参数：无
返回：
data对象（session\_id => 元信息）- 元信息：
ip,login_at,ua
- 元信息：
- 成功示例：
{
"data": {
"session_guid_1": {
"ip": "1.2.3.4",
"login_at": 1762000000,
"ua": "Mozilla/5.0"
}
}
}- 失败：
{ "message": "The user does not exist" }
POST /api/v1/user/removeActiveSession
- 控制器：
User\UserController@removeActiveSession 参数（body）：
session_idrequired
- 返回：
data: true/false - 成功示例：
{ "data": true } - 失败：
{ "message": "The user does not exist" }
3.2.2 订阅、节点与流量
GET /api/v1/user/getSubscribe
- 控制器：
User\UserController@getSubscribe - 参数：无
返回字段（
data）：- 用户字段：
plan_id,token,expired_at,u,d,transfer_enable,email,uuid plan（套餐对象，可空）subscribe_urlreset_day
- 用户字段：
- 成功示例：
{
"data": {
"plan_id": 1,
"token": "user_token_xxx",
"u": 123,
"d": 456,
"transfer_enable": 107374182400,
"subscribe_url": "https://sub.example.com/api/v1/client/subscribe?token=...",
"reset_day": 12,
"plan": {
"id": 1,
"name": "Pro"
}
}
}- 失败：
{ "message": "Subscription plan does not exist" }
GET /api/v1/user/server/fetch
- 控制器：
User\ServerController@fetch - 参数：无
- 返回：
data节点数组（由ServerService::getAvailableServers生成） - 额外：返回
ETag，若命中If-None-Match会304 - 成功示例：
{
"data": [
{
"type": "vmess",
"name": "HK-01",
"host": "hk.example.com",
"port": 443,
"rate": 1
}
]
}- 失败：通常为
304或500
GET /api/v1/user/stat/getTrafficLog
- 控制器：
User\StatController@getTrafficLog - 参数：无
返回：
data[]，每条含u,d,record_at,user_id,server_rate
- 成功示例：
{
"data": [
{
"u": 1024,
"d": 2048,
"record_at": 1761955200,
"user_id": 10,
"server_rate": 1
}
]
}- 失败：
403未登录
GET /api/v1/user/plan/fetch
- 控制器：
User\PlanController@fetch 参数（query）：
idnullable（传则查单套餐）
返回：
- 传
id：data单套餐 - 不传：
data可售套餐数组（已按容量扣减）
- 传
- 成功示例：
{
"data": [
{
"id": 1,
"name": "Pro",
"capacity_limit": 132
}
]
}- 失败：
{ "message": "Subscription plan does not exist" }
3.2.3 订单
POST /api/v1/user/order/save
- 控制器：
User\OrderController@save 参数（body）：
plan_idrequiredperiodrequired|in:month_price,quarter_price,half_year_price,year_price,two_year_price,three_year_price,onetime_price,reset_pricecoupon_codenullable
- 返回：
data=trade_no - 成功示例：
{
"data": "202607091234567890"
}- 失败示例：
{
"message": "You have an unpaid or pending order, please try again later or cancel it"
}POST /api/v1/user/order/checkout
- 控制器：
User\OrderController@checkout 参数（body）：
trade_norequiredmethodrequired（支付方式 ID）tokennullable（Stripe 等）
返回字段：
type：支付输出类型（由支付网关决定）data：支付数据（URL、表单、SDK 参数等）
- 成功示例：
{
"type": 1,
"data": {
"redirect": "https://pay.example.com/..."
}
}- 免费订单成功示例：
{
"type": -1,
"data": true
}- 失败示例：
{ "message": "Payment method is not available" }
GET /api/v1/user/order/check
- 控制器：
User\OrderController@check 参数（query）：
trade_norequired
- 返回：
data= 订单状态（0/1/2/3） - 成功示例：
{ "data": 0 } - 失败：
{ "message": "Order does not exist" }
GET /api/v1/user/order/detail
- 控制器：
User\OrderController@detail 参数（query）：
trade_norequired
返回字段（
data）：- 订单主字段（trade\_no、status、plan\_id、period、total\_amount...）
plantry_out_plan_idsurplus_orders（若存在）
- 成功示例：
{
"data": {
"trade_no": "202607091234567890",
"status": 0,
"plan_id": 1,
"period": "month_price",
"total_amount": 1999,
"plan": {
"id": 1,
"name": "Pro"
},
"try_out_plan_id": 0
}
}- 失败：
{ "message": "Order does not exist or has been paid" }
GET /api/v1/user/order/fetch
- 控制器：
User\OrderController@fetch 参数（query）：
statusnullable
- 返回：
data[]订单列表（隐藏id,user_id，并追加plan） - 成功示例：
{ "data": [{ "trade_no": "...", "status": 0, "plan": { "id": 1 } }] } - 失败：
403未登录
GET /api/v1/user/order/getPaymentMethod
- 控制器：
User\OrderController@getPaymentMethod - 参数：无
返回：
data[]，每项含id,name,payment,icon,handling_fee_fixed,handling_fee_percent
- 成功示例：
{
"data": [
{
"id": 1,
"name": "Stripe",
"payment": "StripeCredit",
"icon": "stripe",
"handling_fee_fixed": 0,
"handling_fee_percent": 2.5
}
]
}- 失败：
500+message
POST /api/v1/user/order/cancel
- 控制器：
User\OrderController@cancel 参数（body）：
trade_norequired
- 返回：
data: true - 成功示例：
{ "data": true } - 失败：
{ "message": "You can only cancel pending orders" }
3.2.4 工单
GET /api/v1/user/ticket/fetch
- 控制器：
User\TicketController@fetch 参数（query）：
idnullable（传时返回单工单 + 消息列表）
返回：
- 不传
id：data[]工单列表 - 传
id：data工单对象 +message[]（含is_me）
- 不传
- 成功示例：
{
"data": {
"id": 1001,
"subject": "无法连接",
"status": 0,
"message": [
{
"user_id": 10,
"message": "请帮忙排查",
"is_me": true
}
]
}
}- 失败：
{ "message": "Ticket does not exist" }
POST /api/v1/user/ticket/save
- 控制器：
User\TicketController@save 参数（body）：
subjectrequiredlevelrequired|in:0,1,2messagerequired
- 返回：
data: true - 成功示例：
{ "data": true } - 失败：
{ "message": "There are other unresolved tickets" }
POST /api/v1/user/ticket/reply
- 控制器：
User\TicketController@reply 参数（body）：
idrequiredmessagerequired
- 返回：
data: true - 成功示例：
{ "data": true } - 失败：
{ "message": "The ticket is closed and cannot be replied" }
POST /api/v1/user/ticket/close
- 控制器：
User\TicketController@close 参数（body）：
idrequired
- 返回：
data: true - 成功示例：
{ "data": true } - 失败：
{ "message": "Close failed" }
POST /api/v1/user/ticket/withdraw
- 控制器：
User\TicketController@withdraw 参数（body）：
withdraw_methodrequiredwithdraw_accountrequired
- 返回：
data: true - 成功示例：
{ "data": true } - 失败：
{ "message": "Unsupported withdrawal method" }
3.2.5 邀请与公告
GET /api/v1/user/invite/save
- 控制器：
User\InviteController@save - 参数：无
- 返回：
data（布尔） - 成功示例：
{ "data": true } - 失败：
{ "message": "The maximum number of creations has been reached" }
GET /api/v1/user/invite/fetch
- 控制器：
User\InviteController@fetch - 参数：无
返回字段：
data.codes[]data.stat[]：- 注册用户数
- 有效佣金
- 确认中佣金
- 佣金比例
- 可用佣金
- 成功示例：
{
"data": {
"codes": [{ "code": "ABCD1234", "status": 0 }],
"stat": [12, 3500, 200, 10, 1200]
}
}- 失败：
500+message
GET /api/v1/user/invite/details
- 控制器：
User\InviteController@details 参数（query）：
currentnullable默认 1page_sizenullable最小有效值 10
- 返回：
data[]+total - 成功示例：
{ "data": [{ "trade_no": "...", "get_amount": 100 }], "total": 20 } - 失败：
500+message
GET /api/v1/user/notice/fetch
- 控制器：
User\NoticeController@fetch 参数（query）：
currentnullable默认 1
- 返回：
data[]+total - 成功示例：
{ "data": [{ "id": 1, "title": "维护通知" }], "total": 5 } - 失败：
500+message
3.2.6 其它用户接口
POST /api/v1/user/coupon/check
- 控制器：
User\CouponController@check 参数（body）：
coderequiredplan_idnullable
- 返回：
data为 coupon 对象 - 成功示例：
{ "data": { "id": 1, "code": "SALE50", "type": 2, "value": 50 } } - 失败：
{ "message": "Coupon cannot be empty" }
GET /api/v1/user/telegram/getBotInfo
- 控制器：
User\TelegramController@getBotInfo - 参数：无
- 返回：
data.username - 成功示例：
{ "data": { "username": "my_bot" } } - 失败：
500+message
GET /api/v1/user/comm/config
- 控制器：
User\CommController@config - 参数：无
返回字段：
is_telegramtelegram_discuss_linkstripe_pkwithdraw_methodswithdraw_closecurrencycurrency_symbolcommission_distribution_enablecommission_distribution_l1/l2/l3
- 成功示例：
{ "data": { "currency": "CNY", "currency_symbol": "¥" } } - 失败：
500+message
POST /api/v1/user/comm/getStripePublicKey
- 控制器：
User\CommController@getStripePublicKey 参数（body）：
idrequired（支付方式 ID）
- 返回：
data（Stripe publishable key） - 成功示例：
{ "data": "pk_live_xxx" } - 失败：
{ "message": "payment is not found" }
GET /api/v1/user/knowledge/fetch
- 控制器：
User\KnowledgeController@fetch 参数（query）：
idnullablelanguagenullablekeywordnullable
返回：
- 传
id：单文章对象 - 不传：按分类分组对象
- 传
- 成功示例：
{
"data": {
"新手": [
{
"id": 1,
"category": "新手",
"title": "如何订阅"
}
]
}
}- 失败：
{ "message": "Article does not exist" }
GET /api/v1/user/knowledge/getCategory
- 控制器：
User\KnowledgeController@getCategory - 参数：无
- 返回：与
fetch的分类数据一致（按分类分组） - 成功示例：
{ "data": { "新手": [{ "id": 1, "title": "..." }] } } - 失败：
500+message
3.3 客户端订阅 API（Client）
3.3.1 GET /api/v1/client/subscribe
- 鉴权：
token（query/body） - 控制器：
Client\ClientController@subscribe 参数（query）：
tokenrequiredflagnullable（用于识别客户端协议）
- 返回：纯文本（非 JSON），按客户端协议输出订阅
- 成功示例：
vmess://...
ss://...
trojan://...- 失败示例：
403token is null/token is error
3.3.2 GET /api/v1/client/app/getConfig
- 鉴权：
token - 控制器：
Client\AppController@getConfig - 参数（query）：
tokenrequired - 返回：YAML（Clash 配置文本）
- 成功示例：
proxies:
- name: HK-01
type: vmess- 失败：
403token 错误
3.3.3 GET /api/v1/client/app/getVersion
- 鉴权：
token - 控制器：
Client\AppController@getVersion - 参数：无（会读取
User-Agent） 返回字段：
- 常规：
windows_version/windows_download_url/macos_version/macos_download_url/android_version/android_download_url - 特定 UA：仅返回单平台
version/download_url
- 常规：
- 成功示例：
{
"data": {
"windows_version": "1.2.3",
"windows_download_url": "https://example.com/win.exe",
"macos_version": "1.2.3",
"macos_download_url": "https://example.com/mac.dmg",
"android_version": "1.2.3",
"android_download_url": "https://example.com/app.apk"
}
}- 失败：
403token 错误
4. 管理端 API（Admin）
统一前缀：/api/v1/{secure_path}
统一鉴权：admin 中间件（auth_data 或 Authorization，且 is_admin=1）
注：以下按功能分组，均给出控制器溯源。部分无 FormRequest 的接口参数来自控制器内 validate() 或 input() 判空逻辑。
此处为付费内容，请 购买 后查看
5. 访客回调与其它路由补充
5.1 支付回调
GET|POST /api/v1/guest/payment/notify/{method}/{uuid}
- 控制器：
Guest\PaymentController@notify - 鉴权：无（依赖支付回调签名与
uuid） - 参数：网关自定义
- 成功输出：
success或网关custom_result - 失败：
500 fail/verify error/handle error
5.2 Telegram webhook
POST /api/v1/guest/telegram/webhook
- 控制器：
Guest\TelegramController@webhook 参数：
access_token（query，必须等于md5(telegram_bot_token)）- body 为 Telegram update
- 成功：无固定 JSON（命令处理后可能无输出）
- 失败：
401（token 不匹配）
5.3 服务端对接入口（节点上报/拉取）
ANY /api/v1/server/{class}/{action}
- 路由：
ServerRoute - 行为：动态实例化
App\Http\Controllers\Server\{Class}Controller@{action} - 说明：该入口面向节点程序与后端通讯，不属于前台用户/后台管理 UI API
6. 字段与状态码补充
6.1 常见金额与流量单位
- 金额：多数为“分”（int），前端显示需
/100 - 流量：多数为字节（bytes），部分界面按
GB换算
6.2 常见状态含义（按源码习惯）
订单
status：0待支付1/2/3视业务流程定义（已支付/取消/已完成等）
工单
status：0未关闭1已关闭
6.3 登录态结构（AuthService::generateAuthData）
{
"token": "用户订阅token",
"is_admin": 0,
"auth_data": "JWT"
}7. 主要源码位置
路由：
app/Providers/RouteServiceProvider.phpapp/Http/Routes/*.php
控制器：
app/Http/Controllers/Passport/*app/Http/Controllers/Guest/*app/Http/Controllers/User/*app/Http/Controllers/Client/*app/Http/Controllers/Admin/*app/Http/Controllers/Admin/Server/*
请求校验：
app/Http/Requests/Passport/*app/Http/Requests/User/*app/Http/Requests/Admin/*
鉴权：
app/Http/Middleware/User.phpapp/Http/Middleware/Admin.phpapp/Http/Middleware/Client.phpapp/Services/AuthService.php
本文章采用 CC BY-NC-SA 4.0 协议授权，转载请注明来源。
文章名称：V2Board API 完整API文档 （包括管理端）
文章链接：https://blog.lhl.one/artical/1301.html
躲闪的男孩
小白
ailinaidentical
LHL