labweb/supabase-stack/docs/FINAL_ARCHITECTURE_MINIO_INTERNAL.md

✅ MinIO 内网化架构 - 最终配置

架构变更总结

变更日期

2025-11-23

变更目标

• MinIO S3 对象存储改为仅内网访问
• 删除 MinIO 的所有 Traefik 公网路由
• 保留根路径 302 重定向到 /group/
• 通过 Supabase Storage API 提供公网文件上传下载功能

---

最终架构

内网访问 (Tailscale VPN Required)

服务	地址	用途
MinIO S3 API	http://100.64.0.2:9000	对象存储 API（管理员直接访问）
MinIO Console	http://100.64.0.2:9001	Web 管理界面
Supabase Dashboard	http://100.64.0.2:18000	数据库/后端管理

公网访问 (HTTPS)

服务	地址	说明
根路径	https://amiap.hzau.edu.cn/	302 重定向到 /group/
课题组网站	https://amiap.hzau.edu.cn/group/	Vue.js 前端
Supabase Storage	https://amiap.hzau.edu.cn/supa/storage/v1/	文件上传下载 API ✅
Supabase API	https://amiap.hzau.edu.cn/supa/	Auth/REST/Realtime
ABM 数据库	https://amiap.hzau.edu.cn/ABM/	WebSocket 项目

---

存储架构

公网文件上传下载流程

用户/应用
    ↓ HTTPS
https://amiap.hzau.edu.cn/supa/storage/v1/
    ↓ Traefik (去除 /supa 前缀)
Kong Gateway (Supabase API 网关)
    ↓ 内部网络
Supabase Storage Service (Docker 内部)
    ↓ S3 协议 (http://minio:9000)
MinIO 对象存储
    ↓
物理存储: /vol1/1000/s3

关键点：

• 用户不直接访问 MinIO
• 所有公网访问通过 Supabase Storage API
• MinIO 仅在 Docker 内部网络和 Tailscale 内网可访问
• 文件最终存储在 MinIO 容器 (/vol1/1000/s3)

内网直接访问（管理员）

管理员 (Tailscale VPN)
    ↓
http://100.64.0.2:9000  (MinIO S3 API)
http://100.64.0.2:9001  (MinIO Console)
    ↓
MinIO 容器
    ↓
物理存储: /vol1/1000/s3

---

配置变更详情

1. docker-compose.s3.yml

删除的配置:

# ❌ 已删除
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.minio-s3.rule=..."
  - "traefik.http.services.minio-s3-svc...."
  # ... 所有 Traefik labels

networks:
  - frontend  # ❌ 不再连接到 Traefik 网络

保留/更新的配置:

services:
  minio:
    ports:
      - "100.64.0.2:9000:9000"  # ✓ 仅 Tailscale IP
      - "100.64.0.2:9001:9001"  # ✓ 仅 Tailscale IP
    environment:
      MINIO_SERVER_URL: "http://100.64.0.2:9000"  # ✓ 内网 URL
      MINIO_BROWSER_REDIRECT_URL: "http://100.64.0.2:9001"
    networks:
      - default  # ✓ 仅 Supabase 内部网络

2. docker-compose.yml

修复的端口冲突:

# Studio Dashboard
studio:
  ports:
    - "100.64.0.2:18000:3000"  # ✓ Tailscale 内网访问

# Kong API Gateway
kong:
  # ✓ 不暴露端口，仅通过 Traefik 公网访问
  # Kong 通过 Docker 内部网络与其他服务通信

3. Supabase Storage 配置

Storage 通过内部网络连接 MinIO (docker-compose.yml):

storage:
  environment:
    STORAGE_BACKEND: s3
    GLOBAL_S3_ENDPOINT: http://minio:9000  # ✓ Docker 内部网络
    GLOBAL_S3_BUCKET: stub
    AWS_ACCESS_KEY_ID: ${MINIO_ROOT_USER}
    AWS_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD}

---

验证测试

✅ 测试结果

运行 examples/test_https_storage.py:

cd /vol1/1000/docker_server/traefik/supabase-stack
python3 examples/test_https_storage.py

测试结果: 5/5 通过 ✅

测试项	状态	说明
列出 Buckets	✅	发现 2 个 bucket
创建/确认 Bucket	✅	test-https 存在
上传/更新文件	✅	79 bytes 上传成功
下载文件	✅	内容完整
生成签名 URL	✅	临时链接可用

测试命令示例

# 测试根路径重定向
curl -I https://amiap.hzau.edu.cn
# 期望: HTTP/2 302 + Location: /group/

# 测试 Supabase Storage API
curl -I https://amiap.hzau.edu.cn/supa/storage/v1/bucket \
  -H "apikey: YOUR_API_KEY"
# 期望: HTTP/2 200

# 测试 MinIO 内网访问（需要 Tailscale）
curl -I http://100.64.0.2:9000/minio/health/live
# 期望: HTTP/1.1 200 OK

# 测试 MinIO Console（需要 Tailscale）
curl -I http://100.64.0.2:9001
# 期望: HTTP/1.1 200 OK + Server: MinIO Console

---

安全优势

1. 最小权限原则

• MinIO 不再暴露到公网
• 仅授权用户（Tailscale VPN）可直接访问 MinIO

2. 访问控制

• 公网访问必须通过 Supabase Storage API
• 支持细粒度的权限控制（RLS）
• 自动签名 URL，临时授权

3. 攻击面减小

• 减少了公网暴露的端口和服务
• MinIO 管理界面仅内网可访问
• 降低了潜在的 DDoS 风险

---

使用指南

公网文件上传下载

Python 示例:

import requests

BASE_URL = 'https://amiap.hzau.edu.cn/supa'
API_KEY = 'your_anon_key'

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

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

# 下载文件
response = requests.get(
    f'{BASE_URL}/storage/v1/object/bucket-name/file.txt',
    headers=headers
)
content = response.content

JavaScript 示例:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://amiap.hzau.edu.cn/supa',
  'your_anon_key'
)

// 上传文件
const { data, error } = await supabase.storage
  .from('bucket-name')
  .upload('file.txt', file)

// 下载文件
const { data: fileData } = await supabase.storage
  .from('bucket-name')
  .download('file.txt')

内网管理（MinIO Console）

1. 连接 Tailscale VPN
2. 访问: http://100.64.0.2:9001
3. 登录凭证:
   • 用户名: bsxzZAJ3fvDquup
   • 密码: c2dc1bca7aa4d0adc308f69b6d41eddfaa110a9572ad1b410d73ea0633523fe9

MinIO 命令行工具 (mc)

# 配置别名
mc alias set myminio http://100.64.0.2:9000 \
  bsxzZAJ3fvDquup \
  c2dc1bca7aa4d0adc308f69b6d41eddfaa110a9572ad1b410d73ea0633523fe9

# 列出 buckets
mc ls myminio

# 上传文件
mc cp local-file.txt myminio/stub/

# 下载文件
mc cp myminio/stub/file.txt ./

---

故障排查

问题: Supabase Storage API 返回 404

检查:

# 1. 确认 Kong 运行正常
docker ps | grep kong

# 2. 查看 Kong 日志
docker logs supabase-kong --tail 50

# 3. 测试 Kong 健康状态
docker inspect supabase-kong --format='{{.State.Health.Status}}'

问题: MinIO 内网无法访问

检查:

# 1. 确认 Tailscale 连接
tailscale status
ping 100.64.0.2

# 2. 检查 MinIO 容器
docker ps | grep minio

# 3. 查看端口绑定
docker port supabase-minio-1

问题: 文件上传失败

检查:

# 1. 查看 Storage 日志
docker logs supabase-storage --tail 50

# 2. 确认 Storage 到 MinIO 的连接
docker exec supabase-storage ping -c 1 minio

# 3. 检查 Storage 环境变量
docker exec supabase-storage env | grep -E "GLOBAL_S3|MINIO"

---

相关文档

• examples/test_https_storage.py - Storage API 功能测试
• MINIO_LOGIN_FIX.md - MinIO Console 登录问题修复
• INTERNAL_ACCESS_FIXED.md - 内网访问配置
• DEPLOYMENT_GUIDE.md - 完整部署指南

---

修改日期: 2025-11-23
架构版本: v3.0 (MinIO 内网化)
状态: ✅ 已验证，生产就绪
测试: 5/5 通过