Files

2026-07-03 15:58:29 +08:00

16 KiB

Raw Blame History

文件管理系统 OpenAPI 接口文档

Base URL: http://localhost:8080/api

认证方式: Authorization: Bearer <JWT Token>

统一响应格式: { "code": 0, "message": "success", "data": ... }

1. 认证 (Auth)

1.1 用户登录

POST /api/auth/login

请求体:

{ "username": "admin", "password": "admin123" }

响应:

{
  "code": 0,
  "data": {
    "token": "eyJhbGci...",
    "username": "admin",
    "nickname": "管理员",
    "role": "admin"
  }
}

1.2 用户注册

POST /api/auth/register

请求体:

{ "username": "user1", "password": "123456", "nickname": "用户1", "email": "user1@example.com" }

1.3 获取当前用户信息

GET /api/auth/profile
Authorization: Bearer <token>

1.4 获取当前用户权限

GET /api/auth/permissions
Authorization: Bearer <token>

响应:

{
  "code": 0,
  "data": {
    "roles": [{ "id": 1, "name": "admin", "display_name": "管理员" }],
    "permissions": ["file:create", "file:read", "file:update", "file:delete", "file:upload", "share:create"]
  }
}

2. 文件管理 (File)

2.1 上传文件(简单上传)

POST /api/file/upload?folder_id=1&storage_policy_id=1
Content-Type: multipart/form-data
Authorization: Bearer <token>

参数:

参数	类型	必填	说明
file	File	是	文件内容
folder_id	int	否	目标文件夹ID, 0=根目录
storage_policy_id	int	否	存储策略ID, 0=使用默认策略

响应:

{
  "code": 0,
  "data": {
    "id": 1,
    "name": "test.txt",
    "extension": "txt",
    "folder_id": 1,
    "size": 1024,
    "storage_key": "2026/07/02/ab/abcdef123456.txt",
    "storage_policy_id": 1,
    "mime_type": "text/plain"
  }
}

2.2 分片上传(大文件/断点续传)

Step 1: 初始化上传

POST /api/file/upload/init
Authorization: Bearer <token>

请求体:

{
  "file_name": "large_video.mp4",
  "file_size": 104857600,
  "md5": "d41d8cd98f00b204e9800998ecf8427e",
  "folder_id": 1,
  "policy_id": 1
}

响应:

{
  "code": 0,
  "data": {
    "upload_id": "uuid-xxx",
    "instant": false,
    "chunk_size": 5242880,
    "total": 20
  }
}

如果 instant: true, 表示文件已存在(秒传), 直接使用 file_id

Step 2: 逐片上传

PUT /api/file/upload/chunk/:uploadId/:index
Content-Type: multipart/form-data
Authorization: Bearer <token>
X-Checksum: sha256_of_chunk

表单字段: chunk = 分片二进制数据

Step 3: 查询进度(断点续传)

GET /api/file/upload/progress/:uploadId
Authorization: Bearer <token>

响应:

{
  "code": 0,
  "data": {
    "upload_id": "uuid-xxx",
    "total_chunks": 20,
    "uploaded": 15,
    "missing": [15, 16, 17, 18, 19],
    "status": 1
  }
}

missing 数组列出未上传的分片索引, 客户端只需重传这些分片

Step 4: 合并完成

POST /api/file/upload/merge/:uploadId
Authorization: Bearer <token>

Step 5: 取消上传

DELETE /api/file/upload/:uploadId
Authorization: Bearer <token>

2.3 获取文件信息

GET /api/file/:id
Authorization: Bearer <token>

2.3 根据 fileKey 查询文件信息

GET /api/file/info?key=2026/07/02/ab/abcdef123456.txt
Authorization: Bearer <token>

参数:

参数	类型	必填	说明
key	string	是	文件的 storage_key

2.4 直接下载文件流

GET /api/file/:id/download
Authorization: Bearer <token>

响应: 文件二进制流, Content-Disposition: attachment

2.5 获取下载链接

GET /api/file/:id/download-url
Authorization: Bearer <token>

响应:

{
  "code": 0,
  "data": {
    "download_url": "http://localhost:9000/seeyon-fs/2026/07/02/...?X-Amz-..."
  }
}

MinIO存储返回预签名URL(24小时有效), 本地存储返回API路径

2.6 预览文件流

GET /api/file/:id/preview
Authorization: Bearer <token>

响应: 文件二进制流, Content-Disposition: inline

2.7 获取预览链接

GET /api/file/:id/preview-url
Authorization: Bearer <token>

响应:

{
  "code": 0,
  "data": {
    "preview_url": "http://localhost:9000/seeyon-fs/2026/07/02/..."
  }
}

2.8 重命名文件

PUT /api/file/:id/rename
Authorization: Bearer <token>

请求体:

{ "new_name": "新文件名.txt" }

2.9 移动文件

POST /api/file/:id/move
Authorization: Bearer <token>

请求体:

{ "target_folder_id": 5 }

2.10 删除文件(移入回收站)

DELETE /api/file/:id
Authorization: Bearer <token>

2.11 恢复文件

POST /api/file/:id/restore
Authorization: Bearer <token>

2.12 永久删除文件

DELETE /api/file/:id/permanent
Authorization: Bearer <token>

2.13 搜索文件

GET /api/file/search?keyword=报告
Authorization: Bearer <token>

2.14 获取回收站列表

GET /api/file/trash
Authorization: Bearer <token>

3. 文件夹管理 (Folder)

3.1 创建文件夹

POST /api/folder
Authorization: Bearer <token>

请求体:

{ "name": "项目文档", "parent_id": 0 }

响应:

{
  "code": 0,
  "data": { "id": 1, "name": "项目文档", "parent_id": 0, "path": "/1/" }
}

3.2 获取文件夹内容(文件+子文件夹)

GET /api/folder/:id/children
Authorization: Bearer <token>

:id 为 root 时获取根目录

响应:

{
  "code": 0,
  "data": {
    "folders": [{ "id": 2, "name": "子文件夹", "parent_id": 1 }],
    "files": [{ "id": 1, "name": "test.txt", "size": 1024 }]
  }
}

3.3 重命名文件夹

PUT /api/folder/:id/rename
Authorization: Bearer <token>

请求体:

{ "new_name": "新名称" }

3.4 删除文件夹

DELETE /api/folder/:id
Authorization: Bearer <token>

4.1 创建分享链接

POST /api/share
Authorization: Bearer <token>

请求体:

{
  "file_id": 1,
  "password": "123456",
  "expire_hours": 24,
  "max_download": 10
}

响应:

{
  "code": 0,
  "data": {
    "id": 1,
    "share_code": "a1b2c3d4e5f6g7h8",
    "share_url": "/s/a1b2c3d4e5f6g7h8",
    "has_password": true,
    "expire_at": "2026-07-03T15:00:00Z",
    "max_download": 10,
    "download_count": 0
  }
}

4.2 获取我的分享列表

GET /api/share
Authorization: Bearer <token>

4.3 取消分享

DELETE /api/share/:id
Authorization: Bearer <token>

4.4 获取分享信息(公开)

GET /api/s/:code

响应:

{
  "code": 0,
  "data": {
    "file": { "name": "test.txt", "size": 1024, "mime_type": "text/plain" },
    "has_password": true,
    "expire_at": "2026-07-03T15:00:00Z"
  }
}

4.5 验证分享密码

POST /api/s/:code/verify

请求体:

{ "password": "123456" }

4.6 下载分享文件

GET /api/s/:code/download?password=123456

5. SSO 单点登录

5.1 获取SSO提供商列表(公开)

GET /api/sso/providers

响应:

{
  "code": 0,
  "data": [
    { "id": 1, "name": "wechat", "display_name": "企业微信", "type": "oauth2", "icon": "" },
    { "id": 2, "name": "dingtalk", "display_name": "钉钉", "type": "oauth2", "icon": "" }
  ]
}

5.2 获取SSO授权跳转URL

GET /api/sso/auth/url?provider_id=1

响应:

{
  "code": 0,
  "data": {
    "auth_url": "https://open.work.weixin.qq.com/wwopen/sso/qrConnect?...",
    "state": "random_csrf_state"
  }
}

5.3 SSO回调(重定向)

GET /api/sso/callback?provider_id=1&code=AUTH_CODE&state=xxx

第三方授权后回调, 自动重定向到前端: /login?sso=success&token=xxx&username=xxx

5.4 SSO回调(JSON)

POST /api/sso/callback

请求体:

{ "provider_id": 1, "code": "AUTH_CODE" }

响应:

{
  "code": 0,
  "data": {
    "token": "eyJhbGci...",
    "username": "sso_oauth2_zhangsan",
    "nickname": "张三",
    "role": "user"
  }
}

5.5 获取SSO提供商详情(管理员)

GET /api/admin/sso/providers/:id
Authorization: Bearer <token>

5.6 创建SSO提供商(管理员)

POST /api/admin/sso/providers
Authorization: Bearer <token>

请求体:

{
  "name": "wechat",
  "type": "oauth2",
  "display_name": "企业微信",
  "icon": "https://example.com/wechat.png",
  "auto_create": 1,
  "default_role": "viewer",
  "config": {
    "client_id": "ww123456",
    "client_secret": "secret_xxx",
    "auth_url": "https://open.work.weixin.qq.com/wwopen/sso/qrConnect",
    "token_url": "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
    "user_info_url": "https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo",
    "redirect_uri": "http://localhost:8080/api/sso/callback",
    "scopes": "snsapi_userinfo"
  }
}

支持的 SSO 类型:

type	说明	必填 config 字段
oauth2	OAuth 2.0	client_id, client_secret, auth_url, token_url, user_info_url, redirect_uri
oidc	OpenID Connect	同 oauth2 + issuer_url
cas	CAS	cas_server_url, redirect_uri
ldap	LDAP	ldap_server, ldap_port, ldap_base_dn, ldap_bind_user, ldap_bind_pass

5.7 更新SSO提供商(管理员)

PUT /api/admin/sso/providers/:id
Authorization: Bearer <token>

请求体同创建, 字段可选(只传需要修改的字段)

5.8 启用/禁用SSO提供商(管理员)

PUT /api/admin/sso/providers/:id/toggle
Authorization: Bearer <token>

请求体:

{ "status": 1 }

5.9 删除SSO提供商(管理员)

DELETE /api/admin/sso/providers/:id
Authorization: Bearer <token>

6. 用户管理 (Admin)

6.1 用户列表

GET /api/admin/users?page=1&size=20
Authorization: Bearer <token>

6.2 创建用户

POST /api/admin/users
Authorization: Bearer <token>

请求体:

{
  "username": "user1",
  "password": "123456",
  "nickname": "用户1",
  "email": "user1@example.com",
  "role_ids": [2],
  "storage_quota": 10737418240
}

6.3 更新用户

PUT /api/admin/users/:id
Authorization: Bearer <token>

6.4 删除用户

DELETE /api/admin/users/:id
Authorization: Bearer <token>

6.5 重置密码

PUT /api/admin/users/:id/password
Authorization: Bearer <token>

请求体:

{ "password": "new_password" }

6.6 设置用户角色

PUT /api/admin/users/:id/roles
Authorization: Bearer <token>

请求体:

{ "role_ids": [1, 2] }

7. 角色权限管理 (Admin)

7.1 角色列表

GET /api/admin/roles
Authorization: Bearer <token>

7.2 创建角色

POST /api/admin/roles
Authorization: Bearer <token>

请求体:

{ "name": "editor", "display_name": "编辑者", "description": "可编辑文件" }

7.3 更新角色

PUT /api/admin/roles/:id
Authorization: Bearer <token>

7.4 删除角色

DELETE /api/admin/roles/:id
Authorization: Bearer <token>

7.5 设置角色权限

PUT /api/admin/roles/:id/permissions
Authorization: Bearer <token>

请求体:

{ "permission_ids": [1, 2, 3, 4, 5] }

7.6 权限列表

GET /api/admin/permissions
Authorization: Bearer <token>

7.7 创建权限

POST /api/admin/permissions
Authorization: Bearer <token>

请求体:

{ "code": "file:download", "name": "下载文件", "resource": "file", "action": "download" }

7.8 删除权限

DELETE /api/admin/permissions/:id
Authorization: Bearer <token>

8. 存储策略管理 (Admin)

8.1 存储策略列表

GET /api/admin/storage-policies
Authorization: Bearer <token>

8.2 创建存储策略

POST /api/admin/storage-policies
Authorization: Bearer <token>

请求体 (本地存储):

{ "name": "本地存储", "type": "local", "config": { "base_path": "./data/storage" } }

请求体 (MinIO):

{
  "name": "MinIO存储",
  "type": "minio",
  "config": {
    "endpoint": "localhost:9000",
    "access_key": "admin",
    "secret_key": "123456789",
    "bucket": "seeyon-fs",
    "use_ssl": false
  }
}

8.3 更新存储策略

PUT /api/admin/storage-policies/:id
Authorization: Bearer <token>

8.4 删除存储策略

DELETE /api/admin/storage-policies/:id
Authorization: Bearer <token>

9. 组织架构管理 (Admin)

9.1 部门列表(树形)

GET /api/admin/departments
Authorization: Bearer <token>

响应:

{
  "code": 0,
  "data": [
    {
      "id": 1, "name": "总公司", "code": "HQ", "parent_id": 0,
      "children": [
        { "id": 2, "name": "技术部", "code": "TECH", "parent_id": 1 },
        { "id": 3, "name": "产品部", "code": "PM", "parent_id": 1 }
      ]
    }
  ]
}

9.2 创建部门

POST /api/admin/departments
Authorization: Bearer <token>

请求体:

{ "name": "技术部", "code": "TECH", "parent_id": 1, "sort_order": 1 }

9.3 更新部门

PUT /api/admin/departments/:id
Authorization: Bearer <token>

9.4 删除部门

DELETE /api/admin/departments/:id
Authorization: Bearer <token>

10. 系统设置

10.1 健康检查

GET /health

响应: { "status": "ok" }

10.2 获取CDN配置(管理员)

GET /api/admin/settings/cdn
Authorization: Bearer <token>

响应:

{
  "code": 0,
  "data": {
    "cdn_host": "http://localhost:3090",
    "cdn_path_prefix": "/public",
    "local_base_path": "D:/Seeyon/A8/localfile"
  }
}

10.3 更新CDN配置(管理员)

PUT /api/admin/settings/cdn
Authorization: Bearer <token>

请求体:

{
  "cdn_host": "http://localhost:3090",
  "cdn_path_prefix": "/public"
}

响应:

{
  "code": 0,
  "message": "CDN配置已更新",
  "data": {
    "cdn_host": "http://localhost:3090",
    "cdn_path_prefix": "/public",
    "example_url": "http://localhost:3090/public/2026/07/02/ab/abcdef.txt"
  }
}

生成的链接格式: cdn_host + cdn_path_prefix + / + storage_key

例如: http://localhost:3090/public/2026/07/02/30/306d8f65344c19bd.txt

权限标识一览

权限标识	说明
file:create	创建文件/文件夹
file:read	查看文件
file:update	修改文件
file:delete	删除文件
file:upload	上传文件
share:create	创建分享
share:manage	管理分享
user:manage	用户管理
role:manage	角色管理
sso:manage	SSO管理
system:manage	系统管理
*	所有权限(超级管理员)

2.17 统一文件访问(自动选择模式)

GET /api/file/:id/access
Authorization: Bearer <token>

根据存储策略的 access_mode 自动选择:

proxy: 中转模式, 直接返回文件流

presigned: 预签名模式, 302重定向到MinIO

cdn: CDN模式, 302重定向到CDN地址

2.18 获取文件访问URL

GET /api/file/:id/access-url
Authorization: Bearer <token>

响应:

{
  "code": 0,
  "data": {
    "mode": "presigned",
    "url": "http://files.example.com/minio/seeyon-fs/2026/07/02/...?X-Amz-...",
    "file_name": "test.pdf",
    "file_size": 1024000,
    "content_type": "application/pdf"
  }
}

2.19 分享文件统一访问(公开)

GET /api/s/:code/access?password=xxx

访问模式说明

模式	适用场景	工作原理
`proxy`	私有文件、严格权限	Nginx→Server鉴权→Server从MinIO拉取→返回给用户
`presigned`	公开分享、大文件	Server生成预签名URL→用户直连MinIO(经Nginx代理)
`cdn`	静态资源、本地存储	返回CDN地址, 用户直接访问

预签名模式配置示例:

{
  "endpoint": "localhost:9000",
  "bucket": "seeyon-fs",
  "access_key": "admin",
  "secret_key": "123456789",
  "access_mode": "presigned",
  "nginx_endpoint": "http://files.example.com"
}

nginx_endpoint: Nginx公网地址, 替换MinIO内部地址, 用户通过Nginx访问MinIO

存储策略类型

type	说明	config 字段
local	本地磁盘	base_path
minio	MinIO	endpoint, access_key, secret_key, bucket, use_ssl
s3	AWS S3	endpoint, access_key, secret_key, bucket, region, use_ssl
oss	阿里云 OSS	endpoint, access_key, secret_key, bucket, region

16 KiB Raw Blame History

文件管理系统 OpenAPI 接口文档

1. 认证 (Auth)

1.1 用户登录

1.2 用户注册

1.3 获取当前用户信息

1.4 获取当前用户权限

2. 文件管理 (File)

2.1 上传文件(简单上传)

2.2 分片上传(大文件/断点续传)

2.3 获取文件信息

2.3 根据 fileKey 查询文件信息

2.4 直接下载文件流

2.5 获取下载链接

2.6 预览文件流

2.7 获取预览链接

2.8 重命名文件

2.9 移动文件

2.10 删除文件(移入回收站)

2.11 恢复文件

2.12 永久删除文件

2.13 搜索文件

2.14 获取回收站列表

3. 文件夹管理 (Folder)

3.1 创建文件夹

3.2 获取文件夹内容(文件+子文件夹)

3.3 重命名文件夹

3.4 删除文件夹

4. 分享管理 (Share)

4.1 创建分享链接

4.2 获取我的分享列表

4.3 取消分享

4.4 获取分享信息(公开)

4.5 验证分享密码

4.6 下载分享文件

5. SSO 单点登录

5.1 获取SSO提供商列表(公开)

5.2 获取SSO授权跳转URL

5.3 SSO回调(重定向)

5.4 SSO回调(JSON)

5.5 获取SSO提供商详情(管理员)

5.6 创建SSO提供商(管理员)

5.7 更新SSO提供商(管理员)

5.8 启用/禁用SSO提供商(管理员)

5.9 删除SSO提供商(管理员)

6. 用户管理 (Admin)

6.1 用户列表

6.2 创建用户

6.3 更新用户

6.4 删除用户

6.5 重置密码

6.6 设置用户角色

7. 角色权限管理 (Admin)

7.1 角色列表

7.2 创建角色

7.3 更新角色

7.4 删除角色

7.5 设置角色权限

7.6 权限列表

7.7 创建权限

7.8 删除权限

8. 存储策略管理 (Admin)

8.1 存储策略列表

8.2 创建存储策略

8.3 更新存储策略

8.4 删除存储策略

9. 组织架构管理 (Admin)

9.1 部门列表(树形)

9.2 创建部门

9.3 更新部门

9.4 删除部门

10. 系统设置

10.1 健康检查

10.2 获取CDN配置(管理员)

10.3 更新CDN配置(管理员)

权限标识一览

2.17 统一文件访问(自动选择模式)

2.18 获取文件访问URL

2.19 分享文件统一访问(公开)

访问模式说明

16 KiB

Raw Blame History