BaiycPan 网盘 API 文档

本页面与当前后端实现对齐，包含请求参数和返回示例。

统一响应格式

{
  "code": 0,
  "msg": "获取成功",
  "data": {},
  "timestamp": 1714012345
}

0 成功；400 参数错误；401 未登录；404 不存在；500 服务错误
公开接口无需登录；客户接口需客户会话；管理接口需管理员会话

公开接口

GET/api/site-config

参数：无

字段字典（data）

字段	类型	必返	含义
`site_name`	string	是	站点名称
`site_url`	string	是	站点对外访问地址（可能为空字符串）

{
  "code": 0,
  "msg": "获取成功",
  "data": {"site_name":"BaiycPan网盘","site_url":"https://example.com"},
  "timestamp": 1714012345
}

GET/api/public/packages

参数：无（仅返回已启用套餐）

字段字典（data[]，套餐对象）

字段	类型	必返	含义
`id`	number	是	套餐 ID
`name`	string	是	套餐名称
`price`	number	是	价格
`status`	number	是	状态（1=启用）
`enable_direct_link`	number	是	套餐表自带直连标记（展示用，实际以绑定用户组为准）
`group_enable_url_transfer`	number	否	绑定用户组是否开启在线转存（1=开）
`group_referral_register_percent`	number	否	绑定用户组：下级充值/购套餐分成比例（0=关闭）
`group_referral_share_reward`	number	否	绑定用户组：单次分享下载奖励（元，0=关闭）

注：后端实际返回完整套餐对象（字段较多），此处仅列出前端联调常用字段。

{
  "code": 0,
  "msg": "ok",
  "data": [{"id":1,"name":"月度套餐","price":9.9,"group_enable_direct_link":1,"group_enable_url_transfer":0,"group_referral_register_percent":10,"group_referral_share_reward":0.05}]
}

GET/api/public/share/:code

路径参数：code（6-18位数字）

字段字典（data）

字段	类型	必返	含义
`file_name`	string	是	文件名
`file_size`	number	是	文件大小（字节）
`download_url`	string	是	下载地址（已包含 ts/sig）
`password_required`	boolean	是	是否需要密码

{
  "code": 0,
  "msg": "ok",
  "data": {
    "file_name":"demo.zip",
    "file_size":123456,
    "download_url":"/s/123456/download?ts=1714012345&sig=xxxx",
    "password_required":true
  }
}

GET/s/:code/download?ts=...&sig=...&pwd=...

下载文件流；失败时返回文本错误（如签名无效、密码错误、防盗链拦截）

字段字典（成功响应 Header）

Header	类型	必返	含义
`X-Download-Speed-KB`	string	否	服务端计算限速（KB/s）
`X-Accel-Limit-Rate`	string	否	兼容 Nginx 的限速提示（字节/秒）
`Content-Disposition`	string	是	下载文件名

客户接口（/api/customer）

GET/api/customer/package-status

参数：无

字段字典（data）

字段	类型	必返	含义
`has_package`	boolean	是	是否已购买套餐（且有到期时间）
`package_name`	string	是	套餐名称（可能为空）
`package_expire`	string	是	到期时间（可能为空）
`package_expired`	boolean	是	是否已过期
`days_remaining`	number	是	剩余天数（未过期时）
`minutes_remaining`	number	是	剩余分钟（未过期时）
`show_direct_menu`	boolean	是	是否展示直连菜单

{
  "code":0,
  "msg":"获取成功",
  "data":{"has_package":true,"package_name":"月度套餐","show_direct_menu":true}
}

GET/api/customer/recharge-plans

参数：无

字段字典（data[]，充值方案对象）

字段	类型	必返	含义
`id`	number	是	方案 ID
`name`	string	是	方案名称
`amount`	number	是	充值金额
`bonus_amount`	number	否	赠送金额（可能为 0）
`status`	number	是	状态（1=启用）
`sort_order`	number	否	排序

注：后端返回完整充值方案对象，此处列出常用字段。

GET/api/customer/pan-capabilities

参数：无

字段字典（data）

字段	类型	必返	含义
`show_direct_menu`	boolean	是	是否展示直连菜单
`download_speed_kb`	number	是	下载限速（KB/s）
`user_group`	object\|null	是	用户组对象（可能为 null）
`enable_url_transfer`	boolean	是	是否允许在线转存（用户组或管理员为客户单独开启）
`direct_by_group`	boolean	是	用户组是否开启直连
`direct_by_customer_extra`	boolean	是	管理员是否在客户管理中单独开启直连

{
  "code":0,
  "msg":"获取成功",
  "data":{"show_direct_menu":true,"enable_url_transfer":false,"download_speed_kb":1024,"direct_by_group":true,"direct_by_customer_extra":false}
}

GET/api/customer/files

参数：无

字段字典（data[]，文件对象）

字段	类型	必返	含义
`id`	number	是	文件 ID
`customer_id`	number	是	所属客户
`file_name`	string	是	文件名
`file_size`	number	否	文件大小（字节）
`mime_type`	string	否	MIME 类型
`path`	string	是	服务端存储路径（本地路径）
`status`	number	是	状态（1=正常，0=回收站）

注：后端返回完整文件对象，此处列出常用字段。

POST/api/customer/files

Body：file_name 必填，file_size/mime_type/path 可选

字段字典（返回 data，创建后的文件对象）

返回为创建后的文件对象（同“文件列表 data[]”字段）。至少包含 id/customer_id/file_name/path/status。

{
  "file_name":"demo.zip",
  "file_size":123456,
  "mime_type":"application/zip",
  "path":""
}

DELETE/api/customer/files/:id

路径参数：id 文件ID（逻辑删除到回收站）

GET/api/customer/recycle-bin

参数：无

字段字典（data[]，回收站对象）

字段	类型	必返	含义
`id`	number	是	回收站记录 ID
`file_id`	number	是	文件 ID
`customer_id`	number	是	所属客户
`file_name`	string	是	文件名
`file_size`	number	否	文件大小（字节）
`original_path`	string	是	原始存储路径
`deleted_at`	string	是	删除时间
`expire_at`	string	是	过期清理时间

POST/api/customer/recycle-bin/:id/restore

路径参数：id 回收站ID

DELETE/api/customer/recycle-bin/:id

路径参数：id 回收站ID（物理删除）

GET/api/customer/share-links

参数：无

字段字典（data[]，分享对象）

字段	类型	必返	含义
`id`	number	是	分享 ID
`file_id`	number	是	文件 ID
`share_code`	string	是	分享码（6-18 位数字）
`allow_referers`	string	否	允许来源域名白名单
`max_downloads`	number	否	最大下载次数（0=不限）
`download_count`	number	否	已下载次数
`expire_at`	string\|null	否	过期时间
`status`	number	是	状态（1=启用）

注：后端返回完整分享对象，此处列出常用字段。

POST/api/customer/share-links

Body：file_id 必填；支持 code_length、expire_hours、max_downloads、password、allow_referers

字段字典（返回 data）

字段	类型	必返	含义
`share_code`	string	是	分享码
`share_url`	string	是	分享访问路径（/s/xxxx）

{
  "file_id":1001,
  "code_length":8,
  "expire_hours":24,
  "max_downloads":100,
  "password":"1234",
  "allow_referers":"example.com,foo.com"
}

{
  "code":0,
  "msg":"创建成功",
  "data":{"share_code":"12345678","share_url":"/s/12345678"}
}

POST/api/customer/upload/chunk/init

Body：file_name、file_size、total_chunks 必填；chunk_size 可选

字段字典（返回 data）

字段	类型	必返	含义
`upload_id`	string	是	上传会话 ID
`chunk_size`	number	是	服务端最终采用的分片大小（字节）

GET/api/customer/upload/chunk/status?upload_id=...

字段字典（返回 data）

字段	类型	必返	含义
`upload_id`	string	是	上传会话 ID
`total_chunks`	number	是	总分片数
`uploaded_indexes`	number[]	是	已上传分片下标列表（从 0 开始）

POST/api/customer/upload/chunk/part

multipart：upload_id、index、chunk(file)

字段字典（表单参数）

字段	类型	必填	含义
`upload_id`	string	是	上传会话 ID
`index`	number	是	分片下标（从 0 开始）
`chunk`	file	是	分片文件

POST/api/customer/upload/chunk/complete

Body：{"upload_id":"..."}

字段字典（返回 data）

字段	类型	必返	含义
`file_id`	number	是	新建文件记录 ID
`file_path`	string	是	合并后的服务端路径

PUT/api/customer/nickname

Body：{"nickname":"新昵称"}

字段字典（请求 Body）

字段：nickname（string，必填，最长 50）。

POST/api/customer/avatar

multipart：avatar 文件

字段字典（表单参数）

字段：avatar（file，必填）。

PUT/POST/api/customer/password

Body：旧密码/新密码字段（按当前前端调用）

字段字典（请求 Body）

此接口字段以实际实现为准（通常为 old_password / new_password）。

PUT/api/customer/api-key

参数：无（重置并返回新 API Key）

字段字典（返回 data）

返回为新的 API Key（字段名以接口返回为准）。

充值与支付

POST/customer/recharge/buy-package

Body：{"package_id":1}

字段字典（请求 Body）

字段：package_id（number，必填）。成功后通常仅返回 code/msg/timestamp。

POST/customer/recharge/card

Body：{"card_no":"...","card_pwd":"..."}

字段字典（返回 data）

字段	类型	必返	含义
`amount`	number	是	本次充值金额
`balance`	number	是	充值后的余额

POST/customer/recharge/online

Body：{"amount":10,"pay_type":"alipay"}

字段字典（返回 data）

字段	类型	必返	含义
`order_no`	string	是	订单号
`pay_url`	string	是	可直接打开的支付地址
`pay_action`	string	是	submit.php 地址
`pay_fields`	object	是	表单字段（含 sign 等）
`pay_qrcode`	string	否	网关 mapi 返回的二维码内容（如有）

{
  "code":0,
  "msg":"订单创建成功",
  "data":{"order_no":"R202604251234560001","pay_url":"https://.../submit.php?..."}
}

GET/customer/recharge/order-status?order_no=...

字段字典（返回 data）

字段	类型	必返	含义
`order_no`	string	是	订单号
`pay_status`	number	是	支付状态（1=已支付）
`amount`	number	是	订单金额

GET/POST/api/pay/notify

易支付异步通知，成功返回纯文本 success

GET/POST/api/pay/return

同步回调，返回 HTML 页面并跳回充值页

管理接口（/admin）

GET/admin/user-groups/data

POST/admin/user-groups

PUT/admin/user-groups/:id

DELETE/admin/user-groups/:id

{
  "name":"注册用户组",
  "description":"默认组",
  "download_speed_kb":256,
  "storage_quota_mb":10240,
  "is_default_register":1,
  "enable_direct_link":0,
  "status":1
}

GET/admin/storage-policies/data

POST/admin/storage-policies

PUT/admin/storage-policies/:id

DELETE/admin/storage-policies/:id

{
  "name":"本地存储",
  "driver":"local",
  "base_path":"web/static/uploads/files",
  "is_default":1,
  "status":1
}

GET/admin/files/data

DELETE/admin/files/:id（移入回收站）

GET/admin/recycle-bin/data

POST/admin/recycle-bin/:id/restore

DELETE/admin/recycle-bin/:id

GET/admin/share-visits/data

客户页面路由映射

以下路由与 /api/customer/* 的业务一致，参数结构相同：

/customer/files、/customer/share-links、/customer/recycle-bin
/customer/upload/chunk/init|status|part|complete
/customer/pan-capabilities