diff --git a/.codegraph/.gitignore b/.codegraph/.gitignore new file mode 100644 index 0000000..d20c0fe --- /dev/null +++ b/.codegraph/.gitignore @@ -0,0 +1,5 @@ +# CodeGraph data files — local to each machine, not for committing. +# Ignore everything in .codegraph/ except this file itself, so transient +# files (the database, daemon.pid, sockets, logs) never show up in git. +* +!.gitignore diff --git a/README.md b/README.md new file mode 100644 index 0000000..cc0eacd --- /dev/null +++ b/README.md @@ -0,0 +1,202 @@ +# 文件存储系统 (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) +```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 + +### 后端安装和运行 +```bash +# 进入Go后端目录 +cd go + +# 安装依赖 +go mod tidy + +# 运行程序 +go run main.go +``` + +### 前端安装和运行 +```bash +# 进入前端目录 +cd backend + +# 安装依赖 +npm install + +# 启动开发服务器 +npm run dev +``` + +### 配置文件 + +#### 后端配置 (go/config.yaml) +```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](docs/README.md) + +## 注意事项 + +1. **安全性**:生产环境需要修改JWT密钥,启用HTTPS +2. **性能**:大量文件建议使用对象存储服务(如MinIO、阿里云OSS) +3. **备份**:定期备份SQLite数据库和文件存储目录 +4. **监控**:建议添加Prometheus监控指标 +5. **日志管理**:定期清理过期日志,避免数据库过大 +6. **站点维护**:开启维护模式时,确保管理员仍可访问后台 +7. **权限控制**:管理员账户需在配置文件中预设,避免权限滥用 + +## 许可证 + +MIT License \ No newline at end of file diff --git a/backend/.env.development b/backend/.env.development new file mode 100644 index 0000000..9d57d8a --- /dev/null +++ b/backend/.env.development @@ -0,0 +1,4 @@ +# 开发环境配置(本地调试) +VITE_API_BASE_URL=http://localhost:8100/api/v1 +VITE_APP_TITLE=云泽文件存储云平台 (开发) +VITE_APP_ENV=development \ No newline at end of file diff --git a/backend/.env.production b/backend/.env.production new file mode 100644 index 0000000..b021c48 --- /dev/null +++ b/backend/.env.production @@ -0,0 +1,4 @@ +# 生产环境配置 +VITE_API_BASE_URL=https://file.yunzer.cn/api/v1 +VITE_APP_TITLE=云泽文件存储云平台 +VITE_APP_ENV=production \ No newline at end of file diff --git a/backend/index.html b/backend/index.html index 03aaa0f..319f97b 100644 --- a/backend/index.html +++ b/backend/index.html @@ -1,10 +1,10 @@ - +
-安全、高效的私有云文件存储服务
+go/config.yaml 的 admin 配置段,首次登录后请立即在「个人中心 → 修改密码」中修改。docs/2026)与可见性;相同内容(MD5 一致)的文件自动去重,只占用一份物理存储。VACUUM INTO 生成一致性快照,文件保存在服务器 go/storage/backups/ 目录,命名格式 backup-年月日-时分秒.db。go/storage/filestoragesystem.db(重命名为该文件名)→ ③ 重新启动服务。https://file.yunzer.cn/api/v1;开发环境 http://localhost:8100/api/v1{ "code": 0, "message": "ok", "data": ... },code=0 表示成功,非 0 为错误码。data = { "list": [], "total": 0, "page": 1, "page_size": 20 }Content-Type: application/json。调用 POST /auth/login 获取 token,后续请求携带 Authorization: Bearer <token>,默认 24 小时过期。
请求头携带 4 个字段:
+签名算法:
+签名串 = accessKey + "\n" + timestamp + "\n" + nonce + "\n" + HTTP方法(大写) + "\n" + 请求路径(不含域名和查询参数) +X-Signature = HMAC-SHA256( secretKey, 签名串 ) 的十六进制小写字符串+
/api/v1/files(不含 ?参数)。
+ {{ curlExample }}
+ {{ pythonExample }}
+ 订阅事件触发后,系统向回调地址发送 POST 请求(Content-Type: application/json,超时 10 秒):
{
+ "event": "file.upload",
+ "timestamp": 1755900000,
+ "data": { "file_id": 1, "filename": "a.png", "project_id": 1 }
+}
+ 可订阅事件:file.upload、file.delete、file.restore、project.create、project.delete。回调处理应尽快返回 200,耗时逻辑请异步处理。