文件上传

学习如何上传和管理文件。

🎯 文件管理

BaaS File 模块提供:

文件上传功能
项目级文件归属
访问控制
文件使用统计

📝 上传文件方式

方式 1: 通过实体 API 上传

文件上传功能集成在实体 API 中，使用 multipart/form-data 格式：

创建实体时上传文件：


POST /api/v1/{tenant_id}/projects/{project_id}/entities/users
Content-Type: multipart/form-data
 
# 表单字段：
name=张三
email=zhangsan@example.com
avatar=@avatar.jpg  # 文件字段

更新实体时上传文件：


PUT /api/v1/{tenant_id}/projects/{project_id}/entities/users/{id}/upload
Content-Type: multipart/form-data
 
# 表单字段：
avatar=@new-avatar.jpg

💡 详细的 API 使用说明请参考实体 API 文档 - 带文件上传的创建/更新

方式 2: 通过 BaaS 文件管理页面

BaaS 文件管理

访问路径： http://YOUR_HOST/baas/files

权限要求： 拥有项目权限的用户

功能特性：

可视化文件管理界面
按项目组织文件
文件预览和下载
上传文件功能
文件统计信息（总文件数、存储空间、项目数量）

适用场景：

项目成员管理项目文件
批量上传文件
查看项目文件使用情况

方式 3: 系统管理页面（管理员）

系统文件管理

访问路径： http://YOUR_HOST/admin/content/files

权限要求： 系统管理员

功能特性：

查看所有上传的文件
文件基本信息管理
批量操作

限制：

❌ 无法查看文件归属的项目
❌ 无法按项目筛选文件
ℹ️ 建议使用 /baas/files 进行项目级文件管理

🔗 关联文件到实体

方式 1: API 上传（推荐）

使用 multipart/form-data 一步完成文件上传和实体创建：


curl -X POST "http://YOUR_HOST/api/v1/{tenant_id}/projects/{project_id}/entities/users" \
  -H "X-BaaS-Tenant-ID: tenant_7375b0cd" \
  -H "X-BaaS-Project-ID: tenant_7375b0cd_project_6888d012be80c" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "name=张三" \
  -F "email=zhangsan@example.com" \
  -F "avatar=@/path/to/avatar.jpg"

方式 2: 使用文件 ID

如果文件已经上传，可以在实体中使用文件 ID (FID)：


# 1. 查询已上传的文件 ID
docker exec -it pg17 psql -U postgres -d drubase -c "
  SELECT fid, filename, uri
  FROM file_managed
  ORDER BY created DESC
  LIMIT 10;
"
 
# 2. 在实体中使用文件 ID
POST /api/v1/{tenant_id}/projects/{project_id}/entities/users
Content-Type: application/json
 
{
  "name": "李四",
  "email": "lisi@example.com",
  "avatar": 123  // 使用已上传文件的 FID
}

常见文件字段：

用户头像字段 avatar: 文件 FID
团队 Logo 字段 logo: 文件 FID
附件字段 attachment: 文件 FID

📊 文件管理对比

功能	BaaS 文件管理 `/baas/files`	系统管理 `/admin/content/files`	实体 API `multipart/form-data`
访问权限	项目成员	系统管理员	API 用户
项目归属	✅ 显示	❌ 不显示	✅ 自动关联
文件统计	✅ 按项目统计	✅ 全局统计	-
批量上传	✅ 支持	✅ 支持	单文件
文件预览	✅ 支持	✅ 支持	-
推荐场景	项目文件管理	系统维护	程序化上传

✅ 验证文件上传


# 查询文件记录
docker exec -it pg17 psql -U postgres -d drubase -c "
  SELECT fid, uid, filename, filesize, created
  FROM file_managed
  WHERE fid = 123;
"
 
# 查询项目文件使用情况
docker exec -it pg17 psql -U postgres -d drubase -c "
  SELECT project_id, COUNT(*) as file_count, SUM(filesize) as total_size
  FROM baas_project_file_usage
  GROUP BY project_id;
"