yunzerwebsite/filestoragesystem

Fork 0

Files

T

hero920103 1b5468995f first commit

2026-08-22 22:51:21 +08:00

21 KiB

Raw Blame History

文件存储系统 (FileStorageSystem)

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

功能概述

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 (令牌桶限流)

项目结构

filestoragesystem/
├── docs/                    # 文档目录
├── go/                      # Go后端代码
│   ├── cmd/                 # 主程序入口
│   ├── internal/            # 内部包
│   │   ├── config/          # 配置管理
│   │   ├── controller/      # 控制器层
│   │   │   ├── admin.go     # 系统管理控制器
│   │   │   ├── auth.go      # 认证控制器
│   │   │   ├── file.go      # 文件控制器
│   │   │   ├── project.go   # 项目控制器
│   │   │   ├── role.go      # 角色权限控制器
│   │   │   ├── stats.go     # 统计控制器
│   │   │   ├── user.go      # 用户管理控制器
│   │   │   └── webhook.go   # Webhook控制器
│   │   ├── middleware/       # 中间件
│   │   │   ├── auth.go      # 认证中间件(JWT/API Key)
│   │   │   ├── permission.go # 权限检查中间件
│   │   │   ├── logger.go    # 日志中间件
│   │   │   ├── cors.go      # 跨域中间件
│   │   │   ├── rate_limit.go # 限流中间件
│   │   │   └── site.go      # 站点状态中间件
│   │   ├── model/           # 数据模型
│   │   ├── repository/      # 数据访问层
│   │   ├── service/         # 业务逻辑层
│   │   └── utils/           # 工具函数
│   ├── pkg/                 # 公共包
│   ├── storage/             # 文件存储目录
│   ├── go.mod               # Go模块文件
│   └── main.go              # 程序入口
├── backend/                 # 前端项目（现有）
└── README.md                # 项目说明

数据库设计

用户表 (users)

CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role_id INTEGER DEFAULT 1,  -- 关联角色表
    status INTEGER DEFAULT 1,  -- 1:正常 0:禁用
    storage_used BIGINT DEFAULT 0,  -- 已用存储空间(字节)
    storage_limit BIGINT DEFAULT 10737418240,  -- 存储限制(默认10GB)
    last_login_at DATETIME,
    last_login_ip VARCHAR(50),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (role_id) REFERENCES roles(id)
);

角色表 (roles)

CREATE TABLE roles (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(50) UNIQUE NOT NULL,  -- 角色名称
    code VARCHAR(50) UNIQUE NOT NULL,  -- 角色编码：super_admin/admin/user
    description VARCHAR(255),  -- 角色描述
    is_system INTEGER DEFAULT 0,  -- 是否系统内置角色(不可删除)
    status INTEGER DEFAULT 1,  -- 1:启用 0:禁用
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 默认角色
INSERT INTO roles (name, code, description, is_system) VALUES
('超级管理员', 'super_admin', '系统超级管理员，拥有所有权限', 1),
('管理员', 'admin', '系统管理员，可管理用户和内容', 1),
('普通用户', 'user', '普通用户，管理自己的项目和文件', 1);

权限表 (permissions)

CREATE TABLE permissions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(50) NOT NULL,  -- 权限名称
    code VARCHAR(100) UNIQUE NOT NULL,  -- 权限编码
    module VARCHAR(50) NOT NULL,  -- 所属模块：user/project/file/system
    description VARCHAR(255),  -- 权限描述
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 默认权限
INSERT INTO permissions (name, code, module, description) VALUES
-- 用户管理
('查看用户列表', 'user:list', 'user', '查看所有用户列表'),
('查看用户详情', 'user:detail', 'user', '查看用户详细信息'),
('创建用户', 'user:create', 'user', '创建新用户'),
('编辑用户', 'user:edit', 'user', '编辑用户信息'),
('删除用户', 'user:delete', 'user', '删除用户'),
('禁用用户', 'user:disable', 'user', '禁用/启用用户'),
('分配角色', 'user:assign_role', 'user', '修改用户角色'),
('重置密码', 'user:reset_password', 'user', '重置用户密码'),
-- 项目管理
('查看项目列表', 'project:list', 'project', '查看项目列表'),
('创建项目', 'project:create', 'project', '创建新项目'),
('编辑项目', 'project:edit', 'project', '编辑项目信息'),
('删除项目', 'project:delete', 'project', '删除项目'),
-- 文件管理
('上传文件', 'file:upload', 'file', '上传文件'),
('下载文件', 'file:download', 'file', '下载文件'),
('删除文件', 'file:delete', 'file', '删除文件'),
('查看文件列表', 'file:list', 'file', '查看文件列表'),
-- 系统管理
('查看系统设置', 'system:settings:view', 'system', '查看系统设置'),
('修改系统设置', 'system:settings:edit', 'system', '修改系统设置'),
('查看操作日志', 'system:logs:operation', 'system', '查看操作日志'),
('查看系统日志', 'system:logs:system', 'system', '查看系统日志'),
('清理日志', 'system:logs:cleanup', 'system', '清理历史日志');

角色权限关联表 (role_permissions)

CREATE TABLE role_permissions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    role_id INTEGER NOT NULL,
    permission_id INTEGER NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE,
    FOREIGN KEY (permission_id) REFERENCES permissions(id) ON DELETE CASCADE,
    UNIQUE(role_id, permission_id)
);

-- 超级管理员拥有所有权限
INSERT INTO role_permissions (role_id, permission_id)
SELECT 1, id FROM permissions;

-- 管理员权限
INSERT INTO role_permissions (role_id, permission_id)
SELECT 2, id FROM permissions WHERE code NOT IN ('user:delete', 'user:assign_role', 'system:settings:edit');

-- 普通用户权限
INSERT INTO role_permissions (role_id, permission_id)
SELECT 3, id FROM permissions WHERE code IN ('project:list', 'project:create', 'project:edit', 'project:delete', 'file:upload', 'file:download', 'file:delete', 'file:list');

API密钥表 (api_keys)

CREATE TABLE api_keys (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    access_key VARCHAR(32) UNIQUE NOT NULL,
    secret_key VARCHAR(64) NOT NULL,
    name VARCHAR(50),  -- 密钥名称
    status INTEGER DEFAULT 1,
    last_used_at DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

项目表 (projects)

CREATE TABLE projects (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    name VARCHAR(100) NOT NULL,
    description TEXT,
    storage_used BIGINT DEFAULT 0,
    storage_limit BIGINT DEFAULT 5368709120,  -- 默认5GB
    status INTEGER DEFAULT 1,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id),
    UNIQUE(user_id, name)
);

文件表 (files)

CREATE TABLE files (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    user_id INTEGER NOT NULL,
    filename VARCHAR(255) NOT NULL,  -- 原始文件名
    stored_path VARCHAR(500) NOT NULL,  -- 存储路径
    size BIGINT NOT NULL,
    mime_type VARCHAR(100),
    md5 VARCHAR(32),
    storage_type INTEGER DEFAULT 1,  -- 1:本地存储
    visibility INTEGER DEFAULT 1,  -- 1:私有 2:公开
    download_count BIGINT DEFAULT 0,  -- 下载次数
    status INTEGER DEFAULT 1,  -- 1:正常 0:已删除
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    deleted_at DATETIME,  -- 软删除时间
    FOREIGN KEY (project_id) REFERENCES projects(id),
    FOREIGN KEY (user_id) REFERENCES users(id)
);

临时链接表 (temp_links)

CREATE TABLE temp_links (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_id INTEGER NOT NULL,
    user_id INTEGER NOT NULL,
    token VARCHAR(64) UNIQUE NOT NULL,  -- 访问令牌
    password VARCHAR(50),  -- 访问密码(可选)
    max_count INTEGER DEFAULT 0,  -- 最大访问次数，0为不限
    used_count INTEGER DEFAULT 0,  -- 已访问次数
    expires_at DATETIME NOT NULL,  -- 过期时间
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (file_id) REFERENCES files(id),
    FOREIGN KEY (user_id) REFERENCES users(id)
);

流量统计表 (traffic_logs)

CREATE TABLE traffic_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    project_id INTEGER,
    file_id INTEGER,
    type INTEGER NOT NULL,  -- 1:上传 2:下载
    size BIGINT NOT NULL,  -- 流量大小(字节)
    ip VARCHAR(50),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE INDEX idx_traffic_logs_user ON traffic_logs(user_id);
CREATE INDEX idx_traffic_logs_created ON traffic_logs(created_at);

Webhook配置表 (webhooks)

CREATE TABLE webhooks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    project_id INTEGER,  -- 为空则为用户级别
    url VARCHAR(500) NOT NULL,
    secret VARCHAR(64),  -- 签名密钥
    events VARCHAR(255) NOT NULL,  -- 触发事件：file.upload,file.delete等
    status INTEGER DEFAULT 1,  -- 1:启用 0:禁用
    last_triggered_at DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

系统设置表 (system_settings)

CREATE TABLE system_settings (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    key VARCHAR(100) UNIQUE NOT NULL,  -- 设置键名
    value TEXT,  -- 设置值
    description VARCHAR(255),  -- 设置描述
    group_name VARCHAR(50) DEFAULT 'general',  -- 设置分组
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 默认设置数据
INSERT INTO system_settings (key, value, description, group_name) VALUES
('site_name', '文件存储系统', '站点名称', 'site'),
('site_description', '高效、安全的文件存储服务', '站点描述', 'site'),
('site_logo', '/assets/logo.png', '站点Logo路径', 'site'),
('site_icp', '', 'ICP备案号', 'site'),
('site_copyright', '© 2024 FileStorageSystem', '版权信息', 'site'),
('register_enabled', 'true', '是否开放注册', 'feature'),
('site_enabled', 'true', '站点是否启用', 'feature'),
('site_maintenance_msg', '系统维护中，请稍后再访问', '维护提示信息', 'feature'),
('default_storage_limit', '10737418240', '默认用户存储配额(字节)', 'storage'),
('default_project_limit', '5368709120', '默认项目存储配额(字节)', 'storage'),
('max_file_size', '104857600', '单文件最大限制(字节)', 'storage'),
('allowed_file_types', '*', '允许的文件类型(*表示所有)', 'storage'),
('api_rate_limit', '100', 'API请求频率限制(次/分钟)', 'api'),
('temp_link_max_age', '3600', '临时链接默认有效期(秒)', 'api'),
('webhook_enabled', 'true', '是否启用Webhook回调', 'api');

操作日志表 (operation_logs)

CREATE TABLE operation_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER,  -- 操作用户ID，系统操作为NULL
    username VARCHAR(50),  -- 用户名，便于查询
    action VARCHAR(50) NOT NULL,  -- 操作类型：login/logout/upload/download/delete/create/update
    resource_type VARCHAR(50),  -- 资源类型：user/project/file/apikey
    resource_id INTEGER,  -- 资源ID
    resource_name VARCHAR(255),  -- 资源名称
    ip VARCHAR(50),  -- 操作IP
    user_agent VARCHAR(500),  -- 用户代理
    request_path VARCHAR(500),  -- 请求路径
    request_method VARCHAR(10),  -- 请求方法
    status INTEGER DEFAULT 1,  -- 1:成功 0:失败
    error_message TEXT,  -- 错误信息
    extra_data TEXT,  -- 额外数据(JSON)
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE INDEX idx_operation_logs_user ON operation_logs(user_id);
CREATE INDEX idx_operation_logs_action ON operation_logs(action);
CREATE INDEX idx_operation_logs_created ON operation_logs(created_at);

系统日志表 (system_logs)

CREATE TABLE system_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    level VARCHAR(10) NOT NULL,  -- 日志级别：debug/info/warn/error/fatal
    module VARCHAR(50),  -- 模块名称：server/database/storage/auth
    message TEXT NOT NULL,  -- 日志内容
    stack_trace TEXT,  -- 堆栈信息
    request_id VARCHAR(50),  -- 请求ID，用于链路追踪
    ip VARCHAR(50),  -- 相关IP
    extra_data TEXT,  -- 额外数据(JSON)
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_system_logs_level ON system_logs(level);
CREATE INDEX idx_system_logs_module ON system_logs(module);
CREATE INDEX idx_system_logs_created ON system_logs(created_at);

API设计

认证相关

POST /api/v1/auth/register - 用户注册
POST /api/v1/auth/login - 用户登录
POST /api/v1/auth/apikeys - 生成API密钥
GET /api/v1/auth/apikeys - 获取API密钥列表
DELETE /api/v1/auth/apikeys/:id - 删除API密钥

项目管理

POST /api/v1/projects - 创建项目
GET /api/v1/projects - 获取项目列表
GET /api/v1/projects/:id - 获取项目详情
PUT /api/v1/projects/:id - 更新项目信息
DELETE /api/v1/projects/:id - 删除项目

文件操作 (需要API Key认证)

POST /api/v1/files/upload - 上传文件
GET /api/v1/files/:id - 获取文件信息
GET /api/v1/files/:id/download - 下载文件
DELETE /api/v1/files/:id - 删除文件
GET /api/v1/files - 获取文件列表
POST /api/v1/files/:id/temp-link - 生成临时访问链接
GET /api/v1/files/temp/:token - 通过临时链接访问文件

用户管理 (需要管理员权限)

GET /api/v1/admin/users - 获取用户列表
GET /api/v1/admin/users/:id - 获取用户详情
POST /api/v1/admin/users - 创建用户
PUT /api/v1/admin/users/:id - 编辑用户信息
DELETE /api/v1/admin/users/:id - 删除用户
PUT /api/v1/admin/users/:id/status - 启用/禁用用户
PUT /api/v1/admin/users/:id/role - 修改用户角色
POST /api/v1/admin/users/:id/reset-password - 重置用户密码

角色权限管理 (需要超级管理员权限)

GET /api/v1/admin/roles - 获取角色列表
GET /api/v1/admin/roles/:id - 获取角色详情(含权限)
POST /api/v1/admin/roles - 创建角色
PUT /api/v1/admin/roles/:id - 编辑角色
DELETE /api/v1/admin/roles/:id - 删除角色(系统角色不可删)
PUT /api/v1/admin/roles/:id/permissions - 配置角色权限
GET /api/v1/admin/permissions - 获取权限列表(按模块分组)

存储统计

GET /api/v1/stats/user - 用户存储统计
GET /api/v1/stats/project/:id - 项目存储统计
GET /api/v1/stats/traffic - 流量统计

系统管理 (需要管理员权限)

GET /api/v1/admin/settings - 获取系统设置
PUT /api/v1/admin/settings - 更新系统设置
GET /api/v1/admin/settings/:group - 获取分组设置
PUT /api/v1/admin/settings/:group - 更新分组设置

日志管理 (需要管理员权限)

GET /api/v1/admin/logs/operation - 获取操作日志列表
GET /api/v1/admin/logs/operation/:id - 获取操作日志详情
GET /api/v1/admin/logs/system - 获取系统日志列表
GET /api/v1/admin/logs/system/:id - 获取系统日志详情
DELETE /api/v1/admin/logs/cleanup - 清理历史日志

站点状态 (公开接口)

GET /api/v1/status - 获取站点状态（维护模式、注册开关等）

开发计划

阶段一：基础框架

初始化Go项目，配置依赖
实现基础路由和中间件
SQLite数据库连接和迁移
用户注册/登录功能

阶段二：核心功能

API密钥管理
项目CRUD操作
文件上传功能
文件下载功能

阶段三：系统管理

系统设置管理（站点信息、注册开关、站点开关）
操作日志记录和查询
系统日志记录和查询
角色权限管理（RBAC）
用户管理（列表、封禁、角色分配、密码重置）
权限检查中间件

阶段四：完善功能

文件删除和回收站
存储统计和流量统计
临时访问链接
API限流
错误处理和日志
配置文件支持

阶段五：优化和测试

单元测试
性能优化
API文档生成
部署脚本

快速开始

环境要求

Go 1.21+
SQLite 3

安装和运行

# 进入Go后端目录
cd go

# 安装依赖
go mod tidy

# 运行程序
go run main.go

配置文件

# config.yaml
server:
  port: 8080
  mode: debug  # debug/release

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

storage:
  root: ./storage/files
  max_size: 100MB  # 单文件最大限制

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

jwt:
  secret: your-secret-key  # 请修改为随机密钥
  expire: 24h  # Token过期时间

注意事项

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

许可证

MIT License

21 KiB Raw Blame History Unescape Escape

文件存储系统 (FileStorageSystem)

功能概述

1. 用户系统

2. 项目管理

3. 文件管理

4. API接口

5. 存储引擎

6. 安全特性

7. 系统管理

技术架构

后端技术栈

项目结构

数据库设计

用户表 (users)

角色表 (roles)

权限表 (permissions)

角色权限关联表 (role_permissions)

API密钥表 (api_keys)

项目表 (projects)

文件表 (files)

临时链接表 (temp_links)

流量统计表 (traffic_logs)

Webhook配置表 (webhooks)

系统设置表 (system_settings)

操作日志表 (operation_logs)

系统日志表 (system_logs)

API设计

认证相关

项目管理

文件操作 (需要API Key认证)

用户管理 (需要管理员权限)

角色权限管理 (需要超级管理员权限)

存储统计

系统管理 (需要管理员权限)

日志管理 (需要管理员权限)

站点状态 (公开接口)

开发计划

阶段一：基础框架

阶段二：核心功能

阶段三：系统管理

阶段四：完善功能

阶段五：优化和测试

快速开始

环境要求

安装和运行

配置文件

注意事项

许可证

21 KiB

Raw Blame History