AxaBoxs文件柜

开箱即用的自托管文件快传系统 —— 存放与领取，都在这一个柜里。

AxaBoxs文件柜（基于开源项目 FileCodeBox 深度定制）是一套部署在自己服务器上的文件/文本分享服务：上传文件或文本后生成一个短提取码，对方无需注册登录，凭码即可取件。全程数据自持，不经过任何第三方网盘。

---

一、项目简介

• 取件即走：分享者拿到 5 位提取码，接收者在首页输入即可下载文件或复制文本，无需账号、无需安装客户端
• 数据自持：文件存自己的服务器或自己的对象存储，提取记录只留在浏览器本地
• 策略可控：有效期（按天 / 小时 / 分钟 / 永久 / 按提取次数）、上传大小与频率、文件类型白名单、游客上传开关，全部后台可调
• 开箱即用：首次访问自动进入初始化向导，一分钟完成配置

二、功能特点

1. 分享与取件

• 双类型分享：文件分享与文本分享（文本直出可复制，适合口令、代码片段）
• 灵活过期策略：按天 / 按小时 / 按分钟 / 永久有效 / 按提取次数耗尽即失效
• 提取码可配置：随机字符或纯数字两种生成方式
• 批量加码：同一物理文件可批量派生多个提取码，各码的有效期与提取次数独立统计
• 续期与次数管理：后台可对任意分享续期、调整剩余提取次数
• 取件辅助：取件记录本地留存、二维码分享、文本内容在线预览（含代码/Markdown 渲染，已做 XSS 转义）
• 公开统计：首页展示存储节点状态、单文件上限、默认保留时长、可存类型等规格信息

2. 上传体系

• 分片上传：大文件分片并行上传、断点续传，服务端合并时校验 SHA-256，分片过期自动清理
• 直传存储：支持预签名直传模式，浏览器直连对象存储，字节流不经过应用服务器（另有代理模式可选）
• 配额与限流：总存储容量上限、单文件大小上限、上传频率（次数/分钟）三重控制，容量预留机制防止并发超限
• 游客上传开关：开启后访客可直接上传；关闭则上传需管理员身份

3. 存储后端

• 多后端支持：本地磁盘、S3 兼容对象存储（阿里云 OSS、腾讯云 COS、MinIO、AWS S3 等）、WebDAV、OneDrive、OpenDAL 协议层
• 存储迁移工具：切换后端后一键搬运存量文件——目标已存在自动跳过（幂等）、可中断续跑、失败明细可视化、迁移期间读取自动回退旧后端保证老提取码可用
• 生命周期自动清理：过期文件与其分片由后台任务定时删除，存储后端与数据库记录保持一致

4. 管理后台

• 仪表盘：总文件数、存储空间、今日/昨日分享与容量、运行时长，以及基于状态洞察的”文件健康”面板（需关注 / 存储异常 / 即将过期 / 未取件 / 永久有效），每类均可一键跳转处理
• 文件管理：多条件检索、批量删除 / 续期 / 加码、文件元数据查看、取件与下载统计
• 本地分享：直接浏览挂载到服务器的 NAS / 本地目录（如 /app/data/local），不占用柜子存储即可生成提取码
• 账号管理：多管理员账号（用户名 + 密码）、超级管理员 / 普通操作员两级角色、账号禁用与密码重置、会话即时吊销、可选”仅账号登录”模式
• 系统设置：站点信息、SEO、公告通知、界面主题、登录会话时长、Robots 配置等，保存即生效
• 存储迁移：见上，图形化操作与进度展示

5. 安全设计

• 口令存储：scrypt（内存困难算法）加盐哈希，历史弱哈希格式在登录成功时透明升级
• 会话机制：JWT 签名令牌（HS256），修改管理员口令自动轮换签名密钥使全体旧会话失效；账号改密 / 禁用 / 删除通过令牌版本号即时吊销该账号所有会话
• 多级限流：登录失败、取件错误、上传、元数据查询四类独立 IP 频率限制，超限自动锁定
• 账号保护：登录失败不区分”用户不存在 / 密码错误”防账号枚举；末位超级管理员保护；改口令需超管身份
• 上传防护：文件类型白名单、大小与频率限制、存储配额预留
• 出站校验：S3 / WebDAV 端点配置防 SSRF（内网地址、IP 速记、DNS 重绑定形态检测）
• 渲染安全：文本与 Markdown 预览经 DOMPurify 净化，防存储型 XSS

6. 体验细节

• 中文 / 英文双语界面，一键切换
• 亮色 / 暗色主题（跟随系统可自动切换）
• 响应式布局，桌面与移动端均可操作
• 管理端侧边栏导航 + 路由级加载过渡，取件页大字号分位输入框
• 版本信息透明：后台展示服务端与前端构建版本

三、技术栈

后端

组件	说明
Python + FastAPI	高性能异步 Web 框架，全链路 async
Starlette + Uvicorn	ASGI 服务器，支持 HTTP/1.1 流式响应
Tortoise ORM + SQLite	异步 ORM，零依赖嵌入式数据库，免装 MySQL
aioboto3	S3 兼容对象存储异步客户端（含 multipart 分片合并）
GZip 中间件	响应压缩，静态资源与 API 传输更省流量

前端

组件	说明
Vue 3 + TypeScript	组合式 API + 严格类型检查
Vite	构建工具，路由级代码分割、产物哈希命名
Tailwind CSS	原子化样式，亮暗双主题体系
Pinia	状态管理（会话、配置、告警）
vue-i18n	中英双语
Vue Router	Hash 路由，管理端懒加载
其他	axios（统一鉴权拦截器）、qrcode（二维码）、JSZip / FileSaver（批量打包下载）、marked + DOMPurify（内容预览净化）

架构分层（前端约定）

src/├── services/      # 请求封装（axios 实例、鉴权拦截、统一错误出口）├── composables/   # 组合式业务逻辑（视图层不直接触达服务）├── stores/        # Pinia 全局状态├── views/         # 页面（取件 / 发送 / 登录 / 后台各页）└── layout/        # 管理后台框架（侧边栏 + 顶栏 + 路由视图）

配套架构守护脚本在构建期强制约束分层规则（如视图层禁止直接导入服务类），防止约定随迭代腐化。

四、部署与运行

• 环境：Python 3.13+，pip install -r requirements.txt 后 python main.py 即可运行
• 反代：nginx 将站点全部流量代理至应用端口（默认 12345）即可，静态资源由应用自行吐出
• 数据：SQLite 单文件数据库位于 data/ 目录，备份即拷贝；文件实体位于所选存储后端
• 升级：内置数据库迁移机制（migrations_001-008），新版本启动时自动增量执行，无需手工改库

五、适用场景

• 团队 / 朋友间临时传大文件，替代网盘链接与聊天工具压缩包
• 跨设备文本、口令、代码片段的中转
• NAS / 本地目录的轻量对外分享（文件留在原处，只发提取码）
• 需要数据完全自持、不依赖第三方的私密快传场景