Skip to content

AGENTS.md

Latest commit

 

History

History
167 lines (137 loc) · 7.36 KB

AGENTS.md

File metadata and controls

167 lines (137 loc) · 7.36 KB
Raw

AGENTS.md - 项目概述

本文件为 AI 助手和开发者提供项目的快速概览。

项目简介

filesave_Bitiful 是一个基于 Go + Vue 3 的云存储文件管理系统，使用 Bitiful 缤纷云对象存储服务（S3 兼容）作为后端存储。后端为纯 REST JSON API，前端为 Vue 3 SPA 单页应用。

技术栈

层级 技术
后端 Go 1.21+, gorilla/mux, aws-sdk-go-v2, gopkg.in/yaml.v3
前端 Vue 3 + Composition API, TypeScript, Vite, Vue Router 4, Axios
UI Bootstrap 5, Bootstrap Icons, SCSS + CSS 变量
富文本 @vueup/vue-quill (Quill.js Vue 3 封装)
代码高亮 Highlight.js（按需注册语言模块）
PDF 预览 pdfjs-dist (npm)
存储 Bitiful S3 兼容对象存储

核心文件结构

├── main.go                       # 后端主程序（纯 REST API + SPA 托管）
├── config.yaml                   # 主配置文件（.gitignore）
├── config.example.yaml           # 配置文件模板
├── frontend/                     # Vue 3 前端项目
│   ├── index.html                # Vite 入口
│   ├── package.json              # 前端依赖
│   ├── vite.config.ts            # Vite 配置（开发代理到 8080）
│   ├── tsconfig.json             # TypeScript 配置
│   ├── src/
│   │   ├── main.ts               # Vue 入口
│   │   ├── App.vue               # 根组件
│   │   ├── router/index.ts       # 路由（/, /files, /preview/:key）
│   │   ├── views/
│   │   │   ├── HomeView.vue      # 首页（上传 + 公告栏）
│   │   │   ├── FilesView.vue     # 文件列表页
│   │   │   └── PreviewView.vue   # 文件预览页（按类型分发）
│   │   ├── components/
│   │   │   ├── AppNavbar.vue     # 顶部导航栏
│   │   │   ├── ThemeToggle.vue   # 主题切换按钮
│   │   │   ├── FileUpload.vue    # 拖拽上传 + 进度条
│   │   │   ├── Announcement.vue  # 公告栏（Quill 编辑器）
│   │   │   ├── FileTable.vue     # 文件列表表格
│   │   │   ├── DeleteConfirm.vue # 删除确认弹窗（Teleport）
│   │   │   ├── CodePreview.vue   # 代码预览（高亮 + 行号 + 换行）
│   │   │   ├── ImagePreview.vue  # 图片预览
│   │   │   └── PdfPreview.vue    # PDF 预览（PDF.js + 工具栏）
│   │   ├── composables/
│   │   │   ├── useTheme.ts       # 主题切换逻辑
│   │   │   └── useUpload.ts      # 三步上传（获取 URL → 直传 S3 → 确认）
│   │   ├── services/
│   │   │   └── api.ts            # Axios 实例 + 类型化 API 定义
│   │   ├── utils/
│   │   │   ├── format.ts         # formatFileSize, formatTime
│   │   │   └── fileIcons.ts      # 文件图标映射表
│   │   └── styles/
│   │       ├── variables.scss    # CSS 变量主题
│   │       └── global.scss       # 全局样式（含暗色主题覆盖）
│   └── dist/                     # 构建产物（.gitignore）
├── static/                       # 静态资源（截图等）
├── data/                         # 数据存储（公告 JSON）
└── logs/                         # 服务日志（按日期分割）

API 端点

后端 JSON API

路由 方法 功能 响应格式
/api/files GET 文件列表 { files: [{name, size, lastModified, key, isPreviewable}] }
/api/files/{key} DELETE 删除文件 { status: "success" }
/api/preview/{key} GET 文件预览信息 { filename, type, content?, language?, fileSize?, presignedUrl? }
/api/announcement GET 获取公告 { delta, html, lastUpdated }
/get-upload-url POST 获取预签名上传 URL { uploadUrl, fileKey, method, expiresIn }
/confirm-upload POST 确认上传 { status: "ok" }
/download/{key} GET 下载文件 302 重定向到预签名 URL
/save-announcement POST 保存公告 { status, lastUpdated }

前端路由

路径 组件 功能
/ HomeView 首页（文件上传 + 公告栏）
/files FilesView 文件列表
/preview/:key PreviewView 文件预览（按类型分发）

配置说明

YAML 配置文件 (config.yaml)

s3_endpoint: "https://s3.bitiful.net"
region: "cn-east-1"
port: ":8080"
s3_prefix: "API/"
access_key: ""
secret_key: ""          # 可通过环境变量 S3_SECRET_KEY 覆盖
bucket_name: ""         # 可通过环境变量 S3_BUCKET_NAME 覆盖
announcement_file: "data/announcement.json"
log_dir: "logs"
static_dir: "static"
frontend_dir: "frontend/dist"

环境变量覆盖（可选）

  • S3_SECRET_KEY — 覆盖配置文件中的 secret_key
  • S3_BUCKET_NAME — 覆盖配置文件中的 bucket_name

快速启动

# 开发模式（前后端分别启动）
go run .                                          # 终端 1：启动后端（:8080）
cd frontend && npm install && npm run dev         # 终端 2：启动前端（:5173，代理 API 到 :8080）

# 生产模式（先构建前端，Go 直接托管 SPA）
cd frontend && npm install && npm run build && cd ..
go run .
# 访问 http://localhost:8080

如果是 AI Agent 启动 go run，一定要在 30s 后自动中断该命令，不要卡死！

代码关键点

后端 (main.go)

  • 纯 REST API：所有接口返回 JSON，不再有 HTML 模板渲染
  • SPA 托管：spaHandler 提供 frontend/dist 静态文件，未匹配路径回退到 index.html
  • 预签名 URL：上传/下载/预览均使用 S3 预签名 URL，客户端直传
  • 预览 API：根据文件类型返回不同 JSON 结构（type: image|pdf|text|other）
  • 辅助函数：writeJSON/writeJSONError 统一 JSON 响应

前端架构

  • Composition API：全部使用 <script setup> 语法
  • Composables：useTheme（主题管理）、useUpload（三步上传流程）
  • 按需加载：Highlight.js 按语言注册，减小打包体积
  • PDF.js：通过 pdfjs-dist npm 包使用，Vite 自动处理 Worker 文件
  • Quill 编辑器：使用 @ready 事件 + pendingContent 缓冲区加载初始内容（避免 content prop 的 diff 报错）
  • 主题切换：通过 data-bs-theme 属性 + CSS 变量实现，localStorage 持久化

预览支持的文件类型

分类 数量 类型
图片 6 jpg, jpeg, png, gif, svg, webp
PDF 1 pdf
文本/代码 47 txt, md, log, html, htm, css, js, json, xml, go, py, java, c, cpp, h, hpp, ts, tsx, jsx, php, rb, rs, swift, kt, kts, lua, pl, r, m, vb, asm, scala, dart, yml, yaml, toml, ini, conf, cfg, config, properties, env, sh, bash, zsh, fish, sql

总计：54 种文件类型

注意事项

  1. 配置安全: config.yaml 包含敏感信息，已添加到 .gitignore
  2. 前端构建: 生产部署前必须先 cd frontend && npm run build
  3. 开发代理: Vite 开发服务器将 /api、/get-upload-url 等请求代理到 Go 后端
  4. 文件覆盖: 同名文件上传会直接覆盖
  5. 上传方式: 预签名 URL 直传 S3，支持大文件
  6. 下载方式: 预签名 URL 重定向
  7. 主题支持: 明亮/暗色主题切换，全局统一管理

此文件由 AI 生成，用于帮助快速理解项目结构 最后更新: 2026-05-04