filestoragesystem/README.md

文件存储系统 (FileStorageSystem)

一个类似七牛云的文件存储系统，提供用户注册、项目隔离存储、API文件操作等功能。

环境配置

前端环境配置

开发环境 (.env.development)

VITE_API_BASE_URL=http://localhost:8100/api/v1
VITE_APP_TITLE=云泽文件存储云平台 (开发)
VITE_APP_ENV=development

生产环境 (.env.production)

VITE_API_BASE_URL=https://file.yunzer.cn/api/v1
VITE_APP_TITLE=云泽文件存储云平台
VITE_APP_ENV=production

后端配置

配置文件 (go/config.yaml)

server:
  port: 8100
  mode: debug
  domain: https://file.yunzer.cn

环境变量

• FSS_SERVER_PORT: 服务器端口
• FSS_SERVER_MODE: 运行模式 (debug/release)
• FSS_SERVER_DOMAIN: 生产环境域名
• FSS_JWT_SECRET: JWT密钥
• FSS_JWT_EXPIRE: JWT过期时间

功能概述

1. 用户系统

• 用户注册/登录：支持邮箱/手机号注册，JWT认证
• API密钥管理：每个用户可生成多个API Key，用于程序化访问
• 用户信息管理：个人资料、密码修改、账户设置
• 角色权限：基于角色的访问控制(RBAC)，灵活配置权限
• 账户安全：登录失败锁定、密码强度要求

2. 项目管理

• 项目创建：用户可创建多个独立项目（如项目A、项目B）
• 项目隔离：每个项目拥有独立的存储空间和文件命名空间
• 项目配额：可设置每个项目的存储容量限制
• 项目成员（可选）：支持项目级别的权限管理

3. 文件管理

• 文件上传：支持单文件/批量上传，断点续传
• 文件下载：直接下载或生成临时下载链接
• 文件删除：软删除/硬删除，回收站机制
• 文件元数据：文件名、大小、类型、上传时间、MD5校验
• 文件目录：支持虚拟目录结构组织文件
• 文件访问控制：公开/私有文件设置，访问密码保护
• 临时链接：生成带过期时间的临时访问URL
• 文件预览：图片、视频、文档在线预览（可选）

4. API接口

• RESTful API：标准REST风格接口
• 认证方式：API Key + Secret签名认证
• SDK支持：提供Go/Python/JavaScript SDK（后期）

5. 存储引擎

• 本地存储：文件存储在本地文件系统
• 元数据存储：SQLite数据库存储文件元数据、用户信息等
• 文件去重：基于MD5的文件去重，节省存储空间
• 存储统计：项目/用户级别的存储使用统计
• 流量统计：记录上传/下载流量，便于计费分析
• 自定义域名：支持绑定自定义域名访问文件（可选）

6. 安全特性

• API认证：HMAC-SHA256签名认证
• 访问控制：项目级别的文件访问隔离
• 文件限制：可配置的文件大小、类型限制

7. 系统管理

• 系统设置：站点名称、站点描述、Logo配置、备案信息等
• 注册开关：控制是否开放用户注册功能
• 站点开关：站点维护模式，临时关闭站点访问
• 操作日志：记录用户关键操作（登录、文件操作、项目管理等）
• 系统日志：记录系统运行日志（错误、警告、调试信息）
• 存储配置：默认存储配额、文件大小限制、允许的文件类型
• 邮件配置：SMTP设置，用于发送通知邮件（可选）
• 用户管理：用户列表、封禁/解封、角色分配、密码重置
• 角色管理：创建/编辑/删除角色，配置角色权限
• 权限管理：查看系统权限点，按模块分组
• API限流：请求频率限制，防止滥用
• Webhook回调：文件上传/删除等事件的HTTP回调通知
• 数据备份：数据库和文件的手动/自动备份

技术架构

后端技术栈

• 语言：Go 1.21+
• Web框架：Gin (高性能HTTP框架)
• 数据库：SQLite (嵌入式数据库)
• ORM：GORM (Go ORM库)
• 配置管理：Viper
• 日志：Zap (高性能日志库)
• 认证：JWT + API Key签名
• 限流：golang.org/x/time/rate (令牌桶限流)

前端技术栈

• 框架：Vue 3 + TypeScript
• UI组件：Element Plus
• 构建工具：Vite
• HTTP客户端：Axios
• 状态管理：Pinia

快速开始

环境要求

• Go 1.21+
• SQLite 3
• Node.js 16+
• npm 或 yarn

后端安装和运行

# 进入Go后端目录
cd go

# 安装依赖
go mod tidy

# 运行程序
go run main.go

前端安装和运行

# 进入前端目录
cd backend

# 安装依赖
npm install

# 启动开发服务器
npm run dev

配置文件

后端配置 (go/config.yaml)

server:
  port: 8100
  mode: debug
  domain: https://file.yunzer.cn

database:
  driver: sqlite
  source: ./storage/data.db

storage:
  root: ./storage/files
  backups: ./storage/backups

admin:
  username: admin
  password: admin123  # 首次运行后请修改
  email: admin@example.com
  role: super_admin

jwt:
  secret: please-change-this-secret-key  # 生产环境请修改为随机密钥
  expire: 24h

log:
  level: info
  dir: ./storage/logs
  max_days: 7

前端配置

• 开发环境：.env.development
• 生产环境：.env.production

详细文档

更多详细信息请查看 docs/README.md

注意事项

1. 安全性：生产环境需要修改JWT密钥，启用HTTPS
2. 性能：大量文件建议使用对象存储服务（如MinIO、阿里云OSS）
3. 备份：定期备份SQLite数据库和文件存储目录
4. 监控：建议添加Prometheus监控指标
5. 日志管理：定期清理过期日志，避免数据库过大
6. 站点维护：开启维护模式时，确保管理员仍可访问后台
7. 权限控制：管理员账户需在配置文件中预设，避免权限滥用

许可证

MIT License