FileCodeBox

文件快递柜-匿名口令分享文本，文件，像拿快递一样取文件（FileCodeBox - File Express Cabinet - Anonymous Passcode Sharing Text, Files, Like Taking Express Delivery for Files）

From vastsa·Updated June 12, 2026·View on GitHub·

[English](./readme_en.md) | [在线演示](https://share.lanol.cn) | [部署教程](https://github.com/vastsa/FileCodeBox/wiki/部署教程) | [常见问题](https://github.com/vastsa/FileCodeBox/wiki/常见问题) | [QQ群: 739673698](https://qm.qq.com/q/PemPzhdEIM) The project is written primarily in Python, distributed under the GNU Lesser General Public License v3.0 license, first published in 2022. It has gained significant community traction with 8,330 stars and 1,037 forks on GitHub. Key topics include: anonymous, fastapi, filecodebox, python, tool.

Latest release: V2.3

December 30, 2025View Changelog →

FileCodeBox

文件快递柜 - 匿名口令分享文本和文件

像拿快递一样取文件，无需注册，输入口令即可获取

English | 在线演示 | 部署教程 | 常见问题 | QQ群: 739673698

bash
# 🚀 一键部署
docker run -d -p 12345:12345 -v /opt/FileCodeBox:/app/data --name filecodebox lanol/filecodebox:latest
# 国内镜像（如果上面拉取缓慢）: docker.cnb.cool/aixk/filecodebox

</div>

📝 项目简介

FileCodeBox 是一个轻量级的文件分享工具，基于 FastAPI + Vue3 开发。用户可以通过简单的方式匿名分享文本和文件，接收者只需输入提取码即可获取内容——就像从快递柜取出快递一样简单。

应用场景

场景	描述
📁 临时文件分享	快速分享文件，无需注册登录
📝 代码片段分享	分享代码、配置文件等文本内容
🕶️ 匿名文件传输	保护隐私的点对点传输
🔄 跨设备传输	在不同设备间快速同步文件
💾 临时存储	支持自定义过期时间的云存储
🌐 私有服务	搭建企业或个人专属分享服务

✨ 功能特性

🚀 轻量高效

FastAPI + SQLite3 后端
Vue3 + Element Plus 前端
Docker 一键部署
资源占用极低

</td> <td width="33%" valign="top">

🔒 安全可靠

IP 上传频率限制
提取码错误次数限制
文件自动过期清理
支持管理员认证

</td> <td width="33%" valign="top">

📤 便捷上传

拖拽上传
复制粘贴上传
命令行 curl 上传
批量文件上传

</td> </tr> <tr> <td width="33%" valign="top">

🎫 灵活分享

随机/自定义提取码
可设置有效期（时间/次数）
支持永久有效
文本和文件统一管理

</td> <td width="33%" valign="top">

💾 多存储支持

本地文件系统
S3 兼容存储
OneDrive
OpenDAL

</td> <td width="33%" valign="top">

🌍 国际化

简体中文
繁体中文
English
响应式设计 / 深色模式

</td> </tr> </table>

🖼️ 界面预览

前端源码仓库：2024主题 | 2023主题

🚀 快速开始

Docker 部署（推荐）

方式一：Docker CLI

bash
# Docker Hub（推荐）
docker run -d --restart always -p 12345:12345 -v /opt/FileCodeBox:/app/data --name filecodebox lanol/filecodebox:latest

# 国内镜像（如果 Docker Hub 拉取缓慢）
docker run -d --restart always -p 12345:12345 -v /opt/FileCodeBox:/app/data --name filecodebox docker.cnb.cool/aixk/filecodebox

方式二：Docker Compose

yaml
services:
  filecodebox:
    image: lanol/filecodebox:latest
    container_name: filecodebox
    restart: unless-stopped
    ports:
      - "12345:12345"
    volumes:
      - ./data:/app/data
    environment:
      - WORKERS=4
      - LOG_LEVEL=info

bash
docker compose up -d

环境变量说明

变量	默认值	说明
`HOST`	`::`	监听地址（支持 IPv4/IPv6 双栈）
`PORT`	`12345`	服务端口
`WORKERS`	`4`	工作进程数（建议设为 CPU 核心数）
`LOG_LEVEL`	`info`	日志级别：`debug` / `info` / `warning` / `error`

反向代理配置

使用 Nginx 时，请添加以下配置以正确获取客户端 IP：

nginx
location / {
    proxy_pass http://127.0.0.1:12345;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 100m;  # 根据需要调整上传大小限制
}

手动部署

bash
# 1. 克隆项目
git clone https://github.com/vastsa/FileCodeBox.git
cd FileCodeBox

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动服务
python main.py

📖 使用指南

基础操作

操作	步骤
分享文件	打开网页 → 选择/拖拽文件 → 设置有效期 → 获取提取码
获取文件	打开网页 → 输入提取码 → 下载文件或查看文本
管理后台	访问 `/#/admin` → 输入密码 `FileCodeBox2023`

命令行使用（curl）

上传文件

bash
# 基础上传（默认 1 天有效期）
curl -X POST "http://localhost:12345/share/file/" \
  -F "file=@/path/to/file.txt"

# 指定 1 小时有效期
curl -X POST "http://localhost:12345/share/file/" \
  -F "file=@/path/to/file.txt" \
  -F "expire_value=1" \
  -F "expire_style=hour"

# 指定下载 10 次后过期
curl -X POST "http://localhost:12345/share/file/" \
  -F "file=@/path/to/file.txt" \
  -F "expire_value=10" \
  -F "expire_style=count"

分享文本

bash
curl -X POST "http://localhost:12345/share/text/" \
  -F "text=要分享的文本内容"

下载文件

bash
curl -L "http://localhost:12345/share/select/?code=提取码" -o filename

有效期参数

`expire_style`	说明
`day`	天数
`hour`	小时
`minute`	分钟
`count`	下载次数
`forever`	永久有效

返回示例

json
{
  "code": 200,
  "msg": "success",
  "detail": {
    "code": "abcd1234",
    "name": "file.txt"
  }
}

需要认证时（管理员关闭游客上传后）

bash
# 1. 获取 token
curl -X POST "http://localhost:12345/admin/login" \
  -H "Content-Type: application/json" \
  -d '{"password": "FileCodeBox2023"}'

# 2. 携带 token 上传
curl -X POST "http://localhost:12345/share/file/" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/file.txt"

</details>

🛠 开发指南

项目结构

FileCodeBox/
├── apps/              # 应用模块
│   ├── admin/         # 管理后台
│   └── base/          # 基础功能
├── core/              # 核心模块
├── data/              # 数据目录（运行时生成）
├── docs/              # 文档
└── main.py            # 入口文件

本地开发

后端

bash
pip install -r requirements.txt
python main.py

前端

bash
# 前端仓库: https://github.com/vastsa/FileCodeBoxFronted
cd fcb-fronted
npm install
npm run dev

技术栈

类别	技术
后端框架	FastAPI 0.128+ / Uvicorn
数据库	SQLite + Tortoise ORM
数据验证	Pydantic 2.x
异步支持	aiofiles / aiohttp / aioboto3
对象存储	S3 协议 / OneDrive / OpenDAL
前端框架	Vue 3 + Element Plus + Vite
运行环境	Python 3.8+ / Node.js 18+
容器化	Docker / Docker Compose

❓ 常见问题

<details> <summary><b>如何修改上传大小限制？</b></summary>

在管理面板中修改 uploadSize 配置项。如果使用 Nginx 反向代理，还需修改 client_max_body_size。

</details> <details> <summary><b>如何配置存储引擎？</b></summary>

在管理面板中选择存储引擎类型并配置相应参数。支持本地存储、S3、OneDrive、OpenDAL 等。

</details> <details> <summary><b>如何备份数据？</b></summary>

备份 data 目录即可，包含数据库和上传的文件。

</details> <details> <summary><b>如何修改管理员密码？</b></summary>

登录管理面板后，在系统设置中修改 adminPassword 配置项。

</details>

更多问题请访问 Wiki 或加入 QQ群: 739673698

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

bash
# 1. Fork 并克隆
git clone https://github.com/your-username/FileCodeBox.git

# 2. 创建分支
git checkout -b feature/your-feature

# 3. 提交更改
git commit -m "feat: add your feature"

# 4. 推送并创建 PR
git push origin feature/your-feature