filesave_Bitiful 云存储文件管理系统

这是一个基于 Go + Vue 3 开发的云存储文件管理系统，可以轻松地上传、查看、下载和删除文件。本项目使用 Bitiful 缤纷云对象存储服务作为后端存储。

功能特点

• 简洁美观的用户界面（Vue 3 SPA + Bootstrap 5）
• 拖放上传文件功能（使用预签名 URL 直传，支持大文件）
• 文件列表查看，包含文件名、大小和上传时间
• 智能文件图标显示，支持 50+ 种文件类型
• 文件在线预览功能，支持 54 种文件类型：
  • 6 种图片格式（jpg, jpeg, png, gif, svg, webp）
  • 1 种 PDF 格式（使用 PDF.js 客户端渲染，支持分页和缩放）
  • 47 种文本/代码格式（完整语法高亮支持）
• 43 种编程语言和配置文件语法高亮：
  • Web 相关：HTML, CSS, JavaScript, TypeScript, JSX, TSX, JSON, XML
  • 编程语言：Go, Python, Java, C, C++, PHP, Ruby, Rust, Swift, Kotlin, Lua, Perl, R, Objective-C, VB.NET, Assembly, Scala, Dart
  • 配置文件：YAML, TOML, INI, Properties, Env
  • 脚本语言：Bash, Zsh, Fish, SQL
• 代码预览功能：行号显示、文本换行控制、明亮/暗色主题切换
• 一键下载文件
• 安全的文件删除功能，带确认对话框
• 富文本公告栏，支持编辑和保存
• 操作反馈提示
• 详细的请求日志记录
• 响应式设计，适配各种设备屏幕
• 明亮/暗色主题切换功能，支持系统主题偏好

技术栈

后端

• Go 1.21+
• gorilla/mux 路由框架
• aws-sdk-go-v2（S3 兼容存储服务对接）
• gopkg.in/yaml.v3（YAML 配置文件解析）
• 纯 JSON REST API（无模板渲染）
• SPA 静态文件托管

前端

• Vue 3 + Composition API（<script setup>）
• TypeScript
• Vite（构建工具）
• Vue Router 4（SPA 路由）
• Axios（HTTP 客户端）
• Bootstrap 5 + Bootstrap Icons
• Highlight.js（代码语法高亮）
• @vueup/vue-quill（富文本编辑器）
• pdfjs-dist（PDF 渲染）
• SCSS + CSS 变量（主题系统）

存储

• Bitiful 缤纷云对象存储服务（S3 兼容）

系统架构

后端架构（纯 REST API）

1. 路由层

   • gorilla/mux 路由管理
   • /api/* 前缀的 RESTful JSON API
   • SPA 静态文件托管（frontend/dist）

2. 中间件层

   • 请求日志中间件（详细的请求响应日志）

3. API 层

   • 文件上传（预签名 URL）
   • 文件列表（JSON）
   • 文件下载（预签名 URL 重定向）
   • 文件删除（JSON）
   • 文件预览（JSON 元数据）
   • 公告管理（JSON）

4. 存储层

   • S3 客户端封装
   • 预签名 URL 生成

前端架构（Vue 3 SPA）

1. 视图层

   • HomeView（上传 + 公告栏）
   • FilesView（文件列表）
   • PreviewView（文件预览，按类型分发）

2. 组件层

   • AppNavbar + ThemeToggle（导航 + 主题）
   • FileUpload（拖拽上传 + 进度条）
   • FileTable + DeleteConfirm（文件表格 + 删除确认）
   • Announcement（Quill 富文本编辑器）
   • CodePreview / ImagePreview / PdfPreview（多类型预览）

3. 逻辑层（Composables）

   • useTheme（主题切换，消除重复代码）
   • useUpload（三步上传：获取 URL → 直传 S3 → 确认）

4. 服务层

   • Axios 实例 + 类型化 API 定义

日志系统

• 多级日志记录
• 请求追踪
• 性能监控
• 日志本地持久化（按日期分割）

快速开始

环境要求

• Go 1.21+
• Node.js 18+（仅前端开发时需要）
• 可用的 S3 兼容存储服务

开发模式

前后端分别启动，Vite 开发服务器自动代理 API 请求到 Go 后端。

1. 克隆项目并安装依赖

   git clone <repo-url>
   cd filesave_Bitiful
   go mod tidy
   cd frontend && npm install && cd ..

2. 配置 config.yaml 或设置环境变量

   cp config.example.yaml config.yaml
   # 编辑 config.yaml 填入你的配置
   
   # 或使用环境变量
   export S3_SECRET_KEY=your_secret_key
   export S3_BUCKET_NAME=your_bucket_name

3. 启动后端

   go run .

4. 启动前端开发服务器（新终端）

   cd frontend
   npm run dev

5. 访问 http://localhost:5173（Vite 开发服务器）

生产模式

先构建前端，Go 服务器直接托管 SPA 静态文件。

1. 构建前端

   cd frontend
   npm run build
   cd ..

2. 构建并运行后端

   go build -o filesave .
   ./filesave

3. 访问 http://localhost:8080

目录结构

├── main.go                       # 后端主程序（纯 REST API）
├── config.yaml                   # 主配置文件（含敏感信息，已在 .gitignore）
├── config.example.yaml           # 配置文件模板
├── frontend/                     # Vue 3 前端项目
│   ├── index.html                # Vite 入口 HTML
│   ├── package.json              # 前端依赖
│   ├── vite.config.ts            # Vite 配置（含开发代理）
│   ├── tsconfig.json             # TypeScript 配置
│   ├── src/
│   │   ├── main.ts               # Vue 应用入口
│   │   ├── App.vue               # 根组件
│   │   ├── router/
│   │   │   └── index.ts          # Vue Router 路由定义
│   │   ├── views/
│   │   │   ├── HomeView.vue      # 首页（上传 + 公告栏）
│   │   │   ├── FilesView.vue     # 文件列表页
│   │   │   └── PreviewView.vue   # 文件预览页
│   │   ├── components/
│   │   │   ├── AppNavbar.vue     # 顶部导航栏
│   │   │   ├── ThemeToggle.vue   # 主题切换按钮
│   │   │   ├── FileUpload.vue    # 拖拽上传 + 进度条
│   │   │   ├── Announcement.vue  # 公告栏（Quill 编辑器）
│   │   │   ├── FileTable.vue     # 文件列表表格
│   │   │   ├── DeleteConfirm.vue # 删除确认弹窗
│   │   │   ├── CodePreview.vue   # 代码预览（高亮 + 行号）
│   │   │   ├── ImagePreview.vue  # 图片预览
│   │   │   └── PdfPreview.vue    # PDF 预览（PDF.js）
│   │   ├── composables/
│   │   │   ├── useTheme.ts       # 主题切换逻辑
│   │   │   └── useUpload.ts      # 文件上传逻辑
│   │   ├── services/
│   │   │   └── api.ts            # Axios 实例 + API 定义
│   │   ├── utils/
│   │   │   ├── format.ts         # 格式化工具函数
│   │   │   └── fileIcons.ts      # 文件图标映射
│   │   └── styles/
│   │       ├── variables.scss     # CSS 变量（主题）
│   │       └── global.scss        # 全局样式
│   └── dist/                     # 构建产物（.gitignore）
├── static/                       # 静态资源（截图等）
├── data/                         # 数据存储目录
│   └── announcement.json         # 公告内容存储
├── logs/                         # 日志目录
├── go.mod                        # Go 模块文件
├── go.sum                        # Go 模块校验文件
├── AGENTS.md                     # AI 助手项目概述
└── README.md                     # 项目说明文档

API 接口说明

1. 获取上传预签名 URL

• 路径: POST /get-upload-url
• 请求: { filename: string, fileSize: number }
• 响应: { uploadUrl: string, fileKey: string, method: string, expiresIn: number }

2. 确认上传完成

• 路径: POST /confirm-upload
• 请求: { fileKey: string }
• 响应: { status: "ok" }

3. 文件列表

• 路径: GET /api/files
• 响应: { files: [{ name, size, lastModified, key, isPreviewable }] }

4. 文件下载

• 路径: GET /download/{key}
• 响应: 302 重定向到预签名 URL（1 小时有效期）

5. 删除文件

• 路径: DELETE /api/files/{key}
• 响应: { status: "success" }

6. 文件预览

• 路径: GET /api/preview/{key}
• 响应: { filename, type, content?, language?, fileSize?, presignedUrl? }
  • type 为 image / pdf 时返回 presignedUrl
  • type 为 text 时返回 content + language
  • type 为 other 时返回 presignedUrl（下载）

7. 获取公告

• 路径: GET /api/announcement
• 响应: { delta, html, lastUpdated }

8. 保存公告

• 路径: POST /save-announcement
• 请求: { delta: object, html: string }
• 响应: { status: "success", lastUpdated: string }

自定义配置

方式一：使用 YAML 配置文件（推荐）

创建 config.yaml 文件：

# S3 服务端点
s3_endpoint: "https://s3.bitiful.net"

# S3 区域
region: "cn-east-1"

# 服务监听端口
port: ":8080"

# S3 对象前缀
s3_prefix: "API/"

# S3 访问密钥
access_key: "your_access_key"

# S3 秘密密钥（可通过环境变量 S3_SECRET_KEY 覆盖）
secret_key: "your_secret_key"

# S3 存储桶名称（可通过环境变量 S3_BUCKET_NAME 覆盖）
bucket_name: "your_bucket_name"

# 公告数据文件路径
announcement_file: "data/announcement.json"

# 日志目录
log_dir: "logs"

# 静态文件目录
static_dir: "static"

# 前端构建产物目录（SPA 托管）
frontend_dir: "frontend/dist"

方式二：使用环境变量（生产环境推荐）

export S3_SECRET_KEY=your_secret_key
export S3_BUCKET_NAME=your_bucket_name

用户界面特性

公告栏功能

系统提供可编辑的公告栏功能：

1. 富文本编辑：基于 @vueup/vue-quill 实现，支持文本格式化、列表、链接和图片等
2. 即时编辑：通过编辑按钮进入编辑模式，支持所见即所得的编辑体验
3. 内容持久化：公告内容保存在服务器，重启后保持不变
4. 操作反馈：编辑和保存操作都有明确的界面反馈
5. 修改记录：显示最后更新时间，方便了解公告的时效性

文件预览功能

支持的文件类型（共 54 种）

1. 图片预览（6 种） — jpg, jpeg, png, gif, svg, webp
2. PDF 预览（1 种） — 使用 PDF.js 渲染，支持分页、缩放、键盘快捷键
3. 代码/文本预览（47 种） — 完整语法高亮，行号切换，文本换行控制

预览功能特性

• 47 种编程语言和配置文件语法高亮（Highlight.js）
• 可切换明亮/暗色代码主题
• 行号显示切换
• 文本换行控制

主题切换

• 自动检测系统主题偏好
• 手动切换按钮
• LocalStorage 记忆用户选择
• 全局统一主题管理（useTheme composable）

响应式设计

• 移动设备友好的界面布局
• 适应不同屏幕尺寸的流式布局

部署说明

1. 构建前端

   cd frontend && npm install && npm run build && cd ..

2. 构建可执行文件

   go build -o filesave .

3. 准备部署环境

   • 确保 frontend/dist 目录包含前端构建产物
   • 创建 config.yaml 配置文件或设置环境变量

4. 运行应用

   ./filesave

注意事项

1. 安全性考虑

   • 请确保正确设置 S3_SECRET_KEY 和 S3_BUCKET_NAME 环境变量或配置文件
   • 建议在生产环境中使用 HTTPS
   • config.yaml 包含敏感信息，已添加到 .gitignore

2. 性能优化

   • 文件上传使用预签名 URL 直传到 S3
   • 下载和预览使用预签名 URL 重定向
   • 图片/PDF 预览客户端直接从 S3 加载
   • SPA 架构，页面切换无刷新

3. 开发与生产

   • 开发时使用 Vite dev server（端口 5173），自动代理 API 到 Go 后端
   • 生产时 Go 服务器直接托管 frontend/dist，单一端口运行

贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个项目。在提交代码前，请确保：

1. 代码符合 Go 和 TypeScript 的代码规范
2. 前端代码通过 vue-tsc 类型检查
3. 添加了必要的注释和文档
4. 更新了相关文档

许可证

MIT License