labweb/supabase-stack/docs/STORAGE_TROUBLESHOOTING.md

Storage 故障排查指南

常见问题

1. 下载文件返回 500 错误

症状:

GET /storage/v1/object/{bucket}/{file}
Status: 500 Internal Server Error
{"statusCode":"500","error":"Internal","message":"Internal Server Error"}

原因:

• 数据库中有对象元数据，但文件系统中没有实际文件
• 通常发生在后端切换后（S3 → 文件系统）

解决方法:

# 方法 1: 清理单个 bucket 的旧数据
docker exec supabase-db psql -U postgres -d postgres \
  -c "DELETE FROM storage.objects WHERE bucket_id = 'your-bucket-name';"

# 方法 2: 查看所有对象
docker exec supabase-db psql -U postgres -d postgres \
  -c "SELECT bucket_id, name, created_at FROM storage.objects ORDER BY created_at DESC LIMIT 20;"

# 方法 3: 清理所有对象（谨慎！）
docker exec supabase-db psql -U postgres -d postgres \
  -c "TRUNCATE TABLE storage.objects CASCADE;"

重新上传文件后测试:

python3 examples/test_https_storage.py

2. 文件更新返回 500 错误

症状:

PUT /storage/v1/object/{bucket}/{file}
Status: 500
TypeError: paths[1] must be of type string

原因:

• 文件系统后端的已知 bug
• 更新文件时路径解析错误

解决方法:

使用 DELETE + POST 代替 PUT:

import requests

headers = {'apikey': API_KEY, 'Authorization': f'Bearer {API_KEY}'}

# 1. 删除旧文件
requests.delete(
    f'{BASE_URL}/storage/v1/object/bucket/file.txt',
    headers=headers
)

# 2. 上传新文件
with open('file.txt', 'rb') as f:
    requests.post(
        f'{BASE_URL}/storage/v1/object/bucket/file.txt',
        headers={**headers, 'Content-Type': 'text/plain'},
        data=f
    )

3. 文件路径包含 "undefined"

症状:

volumes/storage/undefined/stub/bucket/file.txt/version-id

说明:

• 这不是错误！
• "undefined" 是文件系统后端的固定目录结构
• 完全正常，可以忽略

4. 旧 S3 后端的文件无法访问

症状:

• 从 MinIO (S3) 迁移到文件系统后端
• 旧文件无法下载，返回 500 或 404

原因:

• 文件元数据格式不兼容
• 数据库记录的路径与实际存储不匹配

解决方法:

1. 清理旧数据 (推荐):

# 清理特定 bucket
docker exec supabase-db psql -U postgres -d postgres \
  -c "DELETE FROM storage.objects WHERE bucket_id = 'old-bucket';"

2. 迁移数据到新 bucket:

# 1. 从 MinIO 下载所有文件（如果还在运行）
# 2. 清理数据库
# 3. 重新上传到文件系统后端

3. 保留 MinIO (最简单):

# 回滚到 MinIO 后端
cp docker-compose.yml.backup-before-rustfs docker-compose.yml
docker compose -f docker-compose.s3.yml up -d
docker compose restart storage

5. Storage 服务启动失败

检查日志:

docker logs supabase-storage --tail 50

常见问题:

• 数据库连接失败

  docker ps | grep supabase-db
  docker logs supabase-db --tail 20
  

• 环境变量配置错误

  docker exec supabase-storage env | grep STORAGE
  

• 卷挂载问题

  ls -la volumes/storage/
  chmod 777 volumes/storage/
  

诊断命令

检查 Storage 配置

# 查看后端类型
docker exec supabase-storage env | grep STORAGE_BACKEND

# 文件后端 -> STORAGE_BACKEND=file
# S3 后端 -> STORAGE_BACKEND=s3

检查数据库

# 列出所有 buckets
docker exec supabase-db psql -U postgres -d postgres \
  -c "SELECT id, name, public, created_at FROM storage.buckets;"

# 列出所有对象
docker exec supabase-db psql -U postgres -d postgres \
  -c "SELECT bucket_id, name, created_at FROM storage.objects LIMIT 10;"

# 统计对象数量
docker exec supabase-db psql -U postgres -d postgres \
  -c "SELECT bucket_id, COUNT(*) FROM storage.objects GROUP BY bucket_id;"

检查文件系统

# 查看存储目录
ls -la volumes/storage/

# 查找所有文件
find volumes/storage/ -type f

# 检查文件大小
du -sh volumes/storage/*

最佳实践

1. 后端选择

生产环境:

• ✅ 使用 MinIO (S3) 后端
• 功能完整、稳定可靠
• 有管理界面

开发/测试环境:

• ✅ 可使用文件系统后端
• 简单、资源占用少
• 注意功能限制

2. 数据迁移

如需切换后端:

1. 备份数据库

   docker exec supabase-db pg_dump -U postgres postgres > backup.sql
   

2. 导出文件（MinIO → 文件系统）

   # 下载所有文件
   # 清理数据库
   # 重新上传
   

3. 测试验证

   python3 examples/test_https_storage.py
   

3. 日常维护

定期检查:

# 检查存储空间
df -h volumes/storage/

# 检查对象数量
docker exec supabase-db psql -U postgres -d postgres \
  -c "SELECT COUNT(*) FROM storage.objects;"

# 检查服务健康
docker ps | grep storage

清理无用数据:

# 删除孤立的数据库记录（没有对应文件）
# 手动检查并清理

快速测试

完整功能测试

python3 examples/test_https_storage.py

单项测试

# 上传
curl -X POST "https://amiap.hzau.edu.cn/supa/storage/v1/object/test/file.txt" \
  -H "apikey: YOUR_KEY" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: text/plain" \
  -d "test content"

# 下载
curl "https://amiap.hzau.edu.cn/supa/storage/v1/object/test/file.txt" \
  -H "apikey: YOUR_KEY" \
  -H "Authorization: Bearer YOUR_KEY"

# 删除
curl -X DELETE "https://amiap.hzau.edu.cn/supa/storage/v1/object/test/file.txt" \
  -H "apikey: YOUR_KEY" \
  -H "Authorization: Bearer YOUR_KEY"

相关文档

• STORAGE_FILE_BACKEND_MIGRATION.md - 后端迁移指南
• FINAL_ARCHITECTURE_MINIO_INTERNAL.md - MinIO 架构
• examples/test_https_storage.py - 测试脚本

---

最后更新: 2025-12-05
适用版本: Supabase Storage API v1.29.0