FileRise 3.38 API 使用详解

FileRise v3.38.0 REST API 与 WebDAV 实战：会话与 CSRF 约定、文件/文件夹/上传/分享/管理/个人域接口逐条 curl 实测回显、错误码与通用约定速查，含 WebDAV Basic 认证与挂载要点。

FileRiseFileRisePHP自托管文件服务器2026/10/30

FileRise 3.38 API 使用详解

目标：面向脚本化运维与二次开发，系统讲解 FileRise v3.38.0 的 REST API 与 WebDAV 入口——认证与会话、CSRF 约定、文件/文件夹/上传/分享/管理/个人各域接口的参数与实测回显、错误码约定。全部请求均在部署实例（详见《FileRise 3.38 Docker Compose 部署指南》）上用 curl 实测，响应逐字照抄。

一、环境信息

项目值
FileRise 版本v3.38.0（官方 Release ZIP）
实例入口http://localhost:8152（nginx+PHP-FPM Compose 栈）
演示账号admin / q1w2e3r4（管理员）
API 规范文件应用发布件自带 openapi.json.dist（实测 111 个端点定义）
实测数据根目录两个文件（demo-1mb.bin 1.0 MB、演示文档.txt 42 字节）与 reports/ 子目录（部署篇实测产物）
实测日期2026-10-30

二、前置条件

  1. 一个可达的 FileRise 实例与管理员账号（本文用演示账号 admin / q1w2e3r4）；
  2. curl（会话与文件上传用 -c/-b cookies.txt 维持 Cookie，JSON 请求带 Content-Type: application/json）；
  3. 理解两条横切约定：写操作需 CSRF 令牌（取法见下章），会话认证与 WebDAV 的 Basic 认证相互独立。

三、API 总览

  • 协议与入口：HTTP REST，统一挂在 /api/ 路径下，按域组织子目录（auth/file/folder/upload/admin/profile/share 等）；URL 不做版本号分段（版本随应用发布迭代，v3.38.0 规范含 111 个端点）；
  • 规范文件：发布件根目录的 openapi.json.dist 即完整 OpenAPI 规范，可导入 Swagger UI/Apifox 离线查阅；
  • 认证方式：主流接口为「会话 Cookie」（POST /api/auth/auth.php 登录后服务端签发）；WebDAV 入口 /webdav.php 用独立 HTTP Basic 认证；分享链接（share.php）以一次性令牌免认证访问；
  • CSRF 约定：登录后的所有写操作（POST/PUT）必须携带 X-CSRF-Token 头，令牌与会话绑定，缺失/不匹配返回 403 并软失效重发新令牌；
  • 响应形态：JSON 为主（成功多带 success/ok 字段，失败返回 {"error":"..."} 配合恰当 HTTP 状态码）；文件下载/分享下载直接回二进制流；
  • 限流：登录接口对连续失败有速率限制，超限返回 HTTP 429；
  • 分页/过滤：列表接口不做统一分页，目录内容由 folder 参数定位（如 folder=root），一次返回该目录全量清单；sourceId 参数用于多存储源场景（核心版固定 local）。

四、认证与首次调用

4.1 登录（POST /api/auth/auth.php）

请求体为 JSON：username、password 必填，remember_me、totp_code 可选。

curl -sS -c cookies.txt -X POST 'http://localhost:8152/api/auth/auth.php' \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' -w '\n[HTTP %{http_code}]\n'

实测回显：

{"status":"ok","success":"Login successful","isAdmin":true,"folderOnly":false,"readOnly":false,"disableUpload":false,"username":"admin"}
[HTTP 200]

失败场景实测（错误密码）：

{"error":"Invalid credentials"} [HTTP 401]

4.2 会话核验与登出

curl -sS -b cookies.txt 'http://localhost:8152/api/auth/checkAuth.php' -w '\n[HTTP %{http_code}]\n'

实测回显：

{"authenticated":true,"isAdmin":true,"totp_enabled":false,"username":"admin","folderOnly":false,"readOnly":false,"disableUpload":false}
[HTTP 200]

登出为 POST /api/auth/logout.php（携带会话 Cookie）。未携带有效会话调用受保护接口实测：

curl -sS 'http://localhost:8152/api/file/getFileList.php?folder=root'
{"error":"Unauthorized"} [HTTP 401]

4.3 获取 CSRF 令牌（写操作前置）

登录后第一次写操作会收到 403 或「软失效回发令牌」响应。实测最稳的取法：向任一写接口空发一次，从响应取 csrf_token（该响应同时已把令牌写入会话）：

curl -sS -b cookies.txt -X POST 'http://localhost:8152/api/upload/upload.php' -F 'file=@/dev/null' -F 'folder=root'

实测回显（令牌为当次会话实测原值）：

{"csrf_expired":true,"csrf_token":"452fc4cb5b644aa4bac7ec74aa70cc0fae5d074f0bc4c3e7329f267afc468ae5"} [HTTP 200]

此后全部写请求统一携带 -H "X-CSRF-Token: 452fc4cb..."。登出重登、会话过期后令牌随之失效，重新按本节获取。

五、各 API 域详解

5.1 文件域（/api/file/）

文件列表：GET /api/file/getFileList.php（参数 folder、可选 sourceId）

curl -sS -b cookies.txt 'http://localhost:8152/api/file/getFileList.php?folder=root'

实测回显（节选，两个文件按名称排序）：

{"files":[{"name":"demo-1mb.bin","modified":"10/30/26  02:36AM","uploaded":"10/30/26  02:36AM","size":"1.0 MB","sizeBytes":1048576,"uploader":"admin","tags":[],"mime":"application/octet-stream","sourceId":"local","content":"","contentTruncated":false},{"name":"演示文档.txt","modified":"10/30/26  02:36AM","uploaded":"10/30/26  02:36AM","size":"42 bytes","sizeBytes":42,"uploader":"admin","tags":[],"mime":"text/plain","sourceId":"local","content":"","contentTruncated":false}],"globalTags":[],"sourceId":"local"}

每项字段：名称、修改/上传时间、人类可读与精确字节数、上传者、标签、MIME 类型、来源（local）；content 为小文本文件的预览片段（超限截断时 contentTruncated=true）。

重命名：PUT /api/file/renameFile.php（JSON：folder、oldName、newName 必填，需 CSRF）

{"success":"File renamed successfully","newName":"演示文档.txt"} [HTTP 200]

删除（进回收站）：POST /api/file/deleteFiles.php（JSON：folder + files 数组，支持批量，需 CSRF）

{"success":"Files moved to Trash: 演示文档.txt"} [HTTP 200]

回收站清单：GET /api/file/getTrashItems.php 与 恢复：POST /api/file/restoreFiles.php（JSON：files 为回收站名数组）

[{"type":"file","originalFolder":"/var/www/uploads/","originalName":"演示文档.txt","trashName":"演示文档.txt_1793342223_21d315a7","trashedAt":1793342223,"uploaded":"10/30/26  02:36AM","uploader":"admin","deletedBy":"admin"}]
{"success":"Items restored: 演示文档.txt","restored":["演示文档.txt"]} [HTTP 200]

下载：GET /api/file/download.php（参数 folder、file，URL 编码中文文件名）

curl -sS -b cookies.txt 'http://localhost:8152/api/file/download.php?folder=root&file=%E6%BC%94%E7%A4%BA%E6%96%87%E6%A1%A3.txt'
FileRise upload test line 1
line 2 你好
 [HTTP 200]

错误形态实测：参数名误用 filename → {"error":"Invalid file name."} [HTTP 400]；目标文件在回收站 → {"error":"Access forbidden."} [HTTP 404]。

分享链接三件套：创建 POST /api/file/createShareLink.php（JSON：folder、file 必填，expirationValue/expirationUnit、password 可选，需 CSRF）、清单 GET /api/file/getShareLinks.php?folder=root、免认证下载 GET /api/file/share.php?token=<令牌>。实测创建 60 分钟有效链接：

{"token":"cdc10341552d42a5d85c9d27d65775a1","expires":1793346744} [HTTP 200]
{"cdc10341552d42a5d85c9d27d65775a1":{"folder":"root","file":"demo-1mb.bin","expires":1793346744,"password":"","createdBy":"admin","createdAt":1793343144}} [HTTP 200]
share download: HTTP 200 size=1048576

💡 技术拓展：文件域还提供移动 moveFiles / 复制 copyFiles / 新建文本 createFile / 在线保存 saveFile / 打包下载 downloadZip / 在线解压 extractZip / 彻底清空回收站 deleteTrashFiles 等端点（规范文件实查），调用约定与上文一致：folder+目标名定位、写操作带 CSRF、批量操作传数组。本文选取读写删改分享六类高频端点全量实测，其余按规范类推即可。

5.2 上传域（/api/upload/）

单发上传：POST /api/upload/upload.php（multipart 表单，需 CSRF）

  • file：文件字段（实测字段名为 file；按规范示例写 fileToUpload 会得到 {"error":"No files received"} [HTTP 400]，实测排障见部署篇 5.3）；
  • folder：目标目录，缺省 root；
  • 支持 resumable* 系列参数走分块续传路径（浏览器前端默认使用，脚本场景单发即可）。

实测（1 MB 二进制 + 42 字节文本）：

{"success":"Files uploaded successfully","newFilename":null} [HTTP 200]
{"success":"Files uploaded successfully","newFilename":null} [HTTP 200]

配套端点：checkExisting.php（同名/同内容去重预检）、removeChunks.php（清理分块）。

5.3 文件夹域（/api/folder/）

创建：POST /api/folder/createFolder.php（JSON：folderName 必填、parent 默认 root，需 CSRF）

{"success":true,"folder":"reports"} [HTTP 200]

清单：GET /api/folder/getFolderList.php?folder=root

[{"folder":"root","fileCount":2,"metadataFile":"root_metadata.json"},{"folder":"reports","fileCount":null,"metadataFile":"reports_metadata.json"}] [HTTP 200]

清单同时给出每个目录的元数据文件名（metadata/ 目录下按目录分文件存储，与配置篇 5.1 对应）。其余端点：renameFolder、deleteFolder、moveFolder、isEmpty、listChildren 等，约定同上。

5.4 管理域（/api/admin/，仅管理员）

读配置：GET /api/admin/getConfig.php——实测回显键结构（节选）：

{"header_title":"FileRise","loginOptions":[...],"globalOtpauthUrl":"","enableWebDAV":true,"safeUploadPolicy":"strict","sharedMaxUploadSize":52428800,"oidc":{...},"branding":{...},"demoMode":false,"uploads":{"resumableChunkMb":...,"resumableTtlHours":...},"display":{...},"onlyoffice":{...},"clamav":{...},"proSearch":{...},"storageSources":{...}}

（完整逐键解读见《FileRise 3.38 配置参数详解》第三、五章。）

写配置：POST /api/admin/updateConfig.php（JSON 局部更新，需 CSRF）——实测开启 WebDAV：

{"success":"Configuration updated successfully."} [HTTP 200]

用户管理：addUser.php（含首启初始化模式 ?setup=1，实测建号 {"ok":true,"data":{"success":"User added successfully"}} [HTTP 200]；日常加用户为管理员会话+CSRF）、getUsers.php、changeUserPassword.php、removeUser.php；权限细控另有 updateUserPermissions.php、admin/acl/saveGrants.php（逐文件夹 ACL）。

5.5 个人域（/api/profile/）

当前用户：GET /api/profile/getCurrentUser.php

{"username":"admin","isAdmin":true,"totp_enabled":false,"profile_picture":""} [HTTP 200]

其余：changePassword、totp_setup/totp_verify/totp_disable/totp_recover、updateUserPanel、uploadPicture。

5.6 WebDAV 入口（/webdav.php，独立认证）

WebDAV 与 REST 平行提供，HTTP Basic 认证（admin / q1w2e3r4），默认由管理配置 enableWebDAV 管控（实测默认关闭返回 403，开启后实测）：

curl -sS -u admin:q1w2e3r4 -X PROPFIND 'http://localhost:8152/webdav.php' -H 'Depth: 1' -w '[HTTP %{http_code}]\n' | head -c 400

[HTTP 207]
<?xml version="1.0"?>
<d:multistatus xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns"><d:response><d:href>/webdav.php/</d:href><d:propstat><d:prop><d:getlastmodified>Fri, 30 Oct 2026 06:37:56 GMT</d:getlastmodified><d:resourcetype><d:collection/></d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat></d:response><d:response><d:href>/webdav.php/reports/</d:href>…（节选）

标准 DAV 方法（PROPFIND/GET/PUT/MKCOL/COPY/MOVE/DELETE）按 RFC 4918 语义作用于上传目录树；桌面网盘客户端/Rclone 挂载时用 http://<host>:<port>/webdav.php 作服务地址、管理员分配的账号作凭据。

六、通用约定速查

约定内容实测依据
认证会话 Cookie（auth.php 签发）；WebDAV 走独立 Basic4.1 / 5.6
CSRF写操作统一 X-CSRF-Token 头；令牌随会话软失效重发4.3
定位目录用 folder（root=根），文件/目录名 UTF-8 URL 编码5.1 下载中文文件名
批量删除/恢复/移动类接口均接受数组5.1 deleteFiles/restoreFiles
错误码400 参数/文件名错、401 未认证/凭据错、403 CSRF 缺失或权限/WebDAV 关闭、404 不存在、422 校验失败（用户名/密码规则）、429 登录限速各节实测与规范
响应成功带 success/ok，失败 {"error":"..."}；下载/分享为二进制流全域实测

七、常见问题

Q1：脚本调写接口全部 403 会话与 CSRF 双前提：先 auth.php 登录保存 Cookie，再按 4.3 取令牌；两者任一过期都会 403，重取即可。

Q2：上传 400 No files received multipart 字段名必须是 file（不是 fileToUpload），且请求携带 CSRF 头；分块续传参数与单发字段不可混用。

Q3：中文文件名接口报 Invalid file name 下载类接口的文件名参数需 URL 编码（演示文档.txt → %E6%BC%94%E7%A4%BA%E6%96%87%E6%A1%A3.txt，实测通过）；JSON 体内则直接写中文即可（renameFile 实测通过）。

Q4：分享链接打不开 核对 token 是否完整、expires 是否过期（时间戳）；带密码的链接需在分享页输入密码换取访问。

Q5：管理员接口 401/403 admin 域与 ACL 授权仅对 isAdmin=true 的会话开放（checkAuth 可核验）；普通用户会话调用返回 403 属预期行为。

八、参考链接