2023-09-06 11:40:13 +08:00
<div align="center">
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
# FileCodeBox
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
### Anonymous File & Text Sharing with Passcode
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
<img src="https://fastly.jsdelivr.net/gh/vastsa/FileCodeBox@V1 .6/static/banners/img_1.png" alt="FileCodeBox Logo" width="400">
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
Share files like picking up a package — no registration required, just enter the passcode
[](https://github.com/vastsa/FileCodeBox/stargazers)
[](https://github.com/vastsa/FileCodeBox/network)
[](https://github.com/vastsa/FileCodeBox/issues)
[](https://github.com/vastsa/FileCodeBox/blob/master/LICENSE)
[](https://hub.docker.com/r/lanol/filecodebox)
[](https://www.python.org)
[](https://fastapi.tiangolo.com)
[](https://vuejs.org)
[简体中文 ](./README.md ) | [Live Demo ](https://share.lanol.cn ) | [Documentation ](https://github.com/vastsa/FileCodeBox/wiki/Deployment-Guide ) | [FAQ ](https://github.com/vastsa/FileCodeBox/wiki/FAQ )
```bash
# 🚀 Quick Deploy
docker run -d -p 12345:12345 -v /opt/FileCodeBox:/app/data --name filecodebox lanol/filecodebox:latest
# China Mirror (if slow): docker.cnb.cool/aixk/filecodebox
```
2025-01-26 10:57:46 +08:00
2023-09-06 11:40:13 +08:00
</div>
2026-01-25 14:12:20 +08:00
---
## Table of Contents
- [Introduction ](#-introduction )
- [Features ](#-features )
- [Screenshots ](#-screenshots )
- [Quick Start ](#-quick-start )
- [Usage Guide ](#-usage-guide )
- [Development ](#-development )
- [FAQ ](#-faq )
- [Contributing ](#-contributing )
- [Statistics ](#-statistics )
- [Disclaimer ](#-disclaimer )
---
2025-01-26 10:57:46 +08:00
## 📝 Introduction
2023-09-06 11:40:13 +08:00
2026-01-25 14:12:20 +08:00
FileCodeBox is a lightweight file sharing tool built with **FastAPI + Vue3** . Users can anonymously share text and files, and recipients only need to enter a passcode to retrieve the content — just like picking up a package from a locker.
2023-09-06 11:40:13 +08:00
2026-01-25 14:12:20 +08:00
### Use Cases
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
| Scenario | Description |
|----------|-------------|
| 📁 **Temporary File Sharing** | Quick file sharing without registration |
| 📝 **Code Snippet Sharing** | Share code, config files, and text content |
| 🕶️ **Anonymous Transfer** | Privacy-protected peer-to-peer transfer |
| 🔄 **Cross-Device Transfer** | Quickly sync files between devices |
| 💾 **Temporary Storage** | Cloud storage with custom expiration |
| 🌐 **Private Service** | Build your own enterprise or personal sharing service |
2023-09-06 11:40:13 +08:00
2026-01-25 14:12:20 +08:00
---
2025-05-28 23:29:13 +08:00
2026-01-25 14:12:20 +08:00
## ✨ Features
<table>
<tr>
<td width="33%" valign="top">
### 🚀 Lightweight & Fast
- FastAPI + SQLite3 backend
- Vue3 + Element Plus frontend
- One-click Docker deployment
- Minimal resource usage
</td>
<td width="33%" valign="top">
### 🔒 Secure & Reliable
- IP upload rate limiting
- Passcode attempt limiting
- Auto file expiration cleanup
- Admin authentication support
</td>
<td width="33%" valign="top">
### 📤 Easy Upload
- Drag & drop upload
- Copy & paste upload
- Command line curl upload
- Batch file upload
</td>
</tr>
<tr>
<td width="33%" valign="top">
### 🎫 Flexible Sharing
- Random / custom passcodes
- Set expiration (time/count)
- Permanent validity support
- Unified text & file management
</td>
<td width="33%" valign="top">
### 💾 Multiple Storage
- Local file system
- S3-compatible storage
- [OneDrive ](./docs/guide/storage-onedrive.md )
- [OpenDAL ](./docs/guide/storage-opendal.md )
</td>
<td width="33%" valign="top">
### 🌍 Internationalization
- Simplified Chinese
- Traditional Chinese
- English
- Responsive design / Dark mode
</td>
</tr>
</table>
---
## 🖼️ Screenshots
> Frontend repositories: [2024 Theme](https://github.com/vastsa/FileCodeBoxFronted) | [2023 Theme](https://github.com/vastsa/FileCodeBoxFronted2023)
<details open>
<summary><b>🎨 New Interface (2024)</b></summary>
<br>
2025-01-26 10:57:46 +08:00
<div align="center">
<table>
<tr>
2026-01-25 14:12:20 +08:00
<td><img src="./.github/images/img_7.png" alt="File Upload"></td>
<td><img src="./.github/images/img_8.png" alt="Text Share"></td>
2025-01-26 10:57:46 +08:00
</tr>
<tr>
2026-01-25 14:12:20 +08:00
<td><img src="./.github/images/img_10.png" alt="File Management"></td>
<td><img src="./.github/images/img_9.png" alt="System Settings"></td>
2025-01-26 10:57:46 +08:00
</tr>
<tr>
2026-01-25 14:12:20 +08:00
<td><img src="./.github/images/img_11.png" alt="Mobile View"></td>
<td><img src="./.github/images/img_12.png" alt="Dark Mode"></td>
2025-01-26 10:57:46 +08:00
</tr>
</table>
</div>
2026-01-25 14:12:20 +08:00
</details>
2023-09-06 11:40:13 +08:00
2026-01-25 14:12:20 +08:00
<details>
<summary><b>📦 Classic Interface (2023)</b></summary>
<br>
2025-01-26 10:57:46 +08:00
<div align="center">
<table>
<tr>
2026-01-25 14:12:20 +08:00
<td><img src="./.github/images/img.png" alt="Home"></td>
<td><img src="./.github/images/img_1.png" alt="Upload"></td>
2024-06-15 21:40:56 +08:00
</tr>
2025-01-26 10:57:46 +08:00
<tr>
2026-01-25 14:12:20 +08:00
<td><img src="./.github/images/img_2.png" alt="Management"></td>
<td><img src="./.github/images/img_3.png" alt="Settings"></td>
2025-01-26 10:57:46 +08:00
</tr>
</table>
</div>
2026-01-25 14:12:20 +08:00
</details>
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
---
2023-09-06 11:40:13 +08:00
2025-01-26 10:57:46 +08:00
## 🚀 Quick Start
2023-09-06 11:40:13 +08:00
2026-01-25 14:12:20 +08:00
### Docker Deployment (Recommended)
2023-09-06 11:40:13 +08:00
2026-01-25 14:12:20 +08:00
**Option 1: Docker CLI**
2025-05-28 23:29:13 +08:00
2025-01-26 10:57:46 +08:00
```bash
2026-01-25 14:12:20 +08:00
# Docker Hub (Recommended)
docker run -d --restart always -p 12345:12345 -v /opt/FileCodeBox:/app/data --name filecodebox lanol/filecodebox:latest
# China Mirror (if Docker Hub is slow)
docker run -d --restart always -p 12345:12345 -v /opt/FileCodeBox:/app/data --name filecodebox docker.cnb.cool/aixk/filecodebox
2025-01-26 10:57:46 +08:00
```
2023-09-06 11:40:13 +08:00
2026-01-25 14:12:20 +08:00
**Option 2: Docker Compose**
2025-05-28 23:29:13 +08:00
2026-01-25 14:12:20 +08:00
```yaml
2026-01-24 11:58:23 +08:00
services :
2026-01-25 14:12:20 +08:00
filecodebox :
2025-03-12 18:56:27 +08:00
image : lanol/filecodebox:latest
2026-01-25 14:12:20 +08:00
container_name : filecodebox
2025-03-12 18:56:27 +08:00
restart : unless-stopped
ports :
- "12345:12345"
2026-01-25 14:12:20 +08:00
volumes :
- ./data:/app/data
2026-01-24 11:58:23 +08:00
environment :
- WORKERS=4
- LOG_LEVEL=info
2025-03-12 18:56:27 +08:00
```
2026-01-25 14:12:20 +08:00
```bash
docker compose up -d
```
**Environment Variables**
2026-01-24 11:58:23 +08:00
| Variable | Default | Description |
|----------|---------|-------------|
2026-01-25 14:12:20 +08:00
| `HOST` | `::` | Listen address (supports IPv4/IPv6 dual-stack) |
2026-01-24 11:58:23 +08:00
| `PORT` | `12345` | Service port |
2026-01-25 14:12:20 +08:00
| `WORKERS` | `4` | Worker processes (recommended: CPU cores) |
| `LOG_LEVEL` | `info` | Log level: `debug` / `info` / `warning` / `error` |
2026-01-24 11:58:23 +08:00
2026-01-25 14:12:20 +08:00
### Reverse Proxy Configuration
2026-01-24 11:58:23 +08:00
2026-01-25 14:12:20 +08:00
When using Nginx, add the following configuration to properly obtain client IP:
2025-05-28 23:29:13 +08:00
```nginx
location / {
2026-01-25 14:12:20 +08:00
proxy_pass http://127.0.0.1:12345 ;
proxy_set_header Host $host ;
proxy_set_header X-Real-IP $remote_addr ;
2026-01-24 11:58:23 +08:00
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for ;
2026-01-25 14:12:20 +08:00
proxy_set_header X-Forwarded-Proto $scheme ;
client_max_body_size 100m ; # Adjust upload size limit as needed
2025-05-28 23:29:13 +08:00
}
```
2025-01-26 10:57:46 +08:00
### Manual Deployment
2023-09-06 11:40:13 +08:00
2025-01-26 10:57:46 +08:00
```bash
2026-01-25 14:12:20 +08:00
# 1. Clone the repository
2025-01-26 10:57:46 +08:00
git clone https://github.com/vastsa/FileCodeBox.git
cd FileCodeBox
2026-01-25 14:12:20 +08:00
# 2. Install dependencies
2025-01-26 10:57:46 +08:00
pip install -r requirements.txt
2026-01-25 14:12:20 +08:00
# 3. Start the service
2025-01-26 10:57:46 +08:00
python main.py
```
2026-01-25 14:12:20 +08:00
---
2025-01-26 10:57:46 +08:00
## 📖 Usage Guide
2026-01-25 14:12:20 +08:00
### Basic Operations
2025-05-28 23:29:13 +08:00
2026-01-25 14:12:20 +08:00
| Operation | Steps |
|-----------|-------|
| **Share File** | Open website → Select/drag files → Set expiration → Get passcode |
| **Retrieve File** | Open website → Enter passcode → Download file or view text |
| **Admin Panel** | Visit `/#/admin` → Enter password `FileCodeBox2023` |
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
### Command Line Usage (curl)
2025-05-28 23:29:13 +08:00
2026-01-25 14:12:20 +08:00
<details>
<summary><b>Click to expand curl examples</b></summary>
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
**Upload File**
2026-01-07 20:28:06 +08:00
```bash
2026-01-25 14:12:20 +08:00
# Basic upload (default 1 day expiration)
2026-01-07 20:28:06 +08:00
curl -X POST "http://localhost:12345/share/file/" \
2026-01-25 14:12:20 +08:00
-F "file=@/path/to/file.txt"
2026-01-07 20:28:06 +08:00
2026-01-25 14:12:20 +08:00
# Set 1 hour expiration
2026-01-07 20:28:06 +08:00
curl -X POST "http://localhost:12345/share/file/" \
2026-01-25 14:12:20 +08:00
-F "file=@/path/to/file.txt" \
2026-01-07 20:28:06 +08:00
-F "expire_value=1" \
-F "expire_style=hour"
2026-01-25 14:12:20 +08:00
# Set expiration after 10 downloads
2026-01-07 20:28:06 +08:00
curl -X POST "http://localhost:12345/share/file/" \
2026-01-25 14:12:20 +08:00
-F "file=@/path/to/file.txt" \
2026-01-07 20:28:06 +08:00
-F "expire_value=10" \
-F "expire_style=count"
```
2026-01-25 14:12:20 +08:00
**Share Text**
```bash
curl -X POST "http://localhost:12345/share/text/" \
-F "text=Text content to share"
```
**Download File**
```bash
curl -L "http://localhost:12345/share/select/?code=PASSCODE" -o filename
```
**Expiration Parameters**
| `expire_style` | Description |
|----------------|-------------|
| `day` | Days |
| `hour` | Hours |
| `minute` | Minutes |
| `count` | Download count |
| `forever` | Never expire |
**Response Example**
2026-01-07 20:28:06 +08:00
```json
{
"code" : 200 ,
"msg" : "success" ,
"detail" : {
"code" : "abcd1234" ,
"name" : "file.txt"
}
}
```
2026-01-25 14:12:20 +08:00
**When Authentication Required** (after admin disables guest upload)
2026-01-07 20:28:06 +08:00
```bash
2026-01-25 14:12:20 +08:00
# 1. Get token
2026-01-07 20:28:06 +08:00
curl -X POST "http://localhost:12345/admin/login" \
-H "Content-Type: application/json" \
-d '{"password": "FileCodeBox2023"}'
2026-01-25 14:12:20 +08:00
# 2. Upload with token
2026-01-07 20:28:06 +08:00
curl -X POST "http://localhost:12345/share/file/" \
2026-01-25 14:12:20 +08:00
-H "Authorization: Bearer <token>" \
-F "file=@/path/to/file.txt"
2026-01-07 20:28:06 +08:00
```
2026-01-25 14:12:20 +08:00
</details>
---
## 🛠 Development
2025-01-26 10:57:46 +08:00
### Project Structure
2025-05-28 23:29:13 +08:00
2025-01-26 10:57:46 +08:00
```
FileCodeBox/
2026-01-25 14:12:20 +08:00
├── apps/ # Application modules
│ ├── admin/ # Admin backend
│ └── base/ # Base functionality
├── core/ # Core modules
├── data/ # Data directory (generated at runtime)
├── docs/ # Documentation
└── main.py # Entry point
2025-01-26 10:57:46 +08:00
```
### Local Development
2025-05-28 23:29:13 +08:00
2026-01-25 14:12:20 +08:00
**Backend**
2025-05-28 23:29:13 +08:00
2025-01-26 10:57:46 +08:00
```bash
2026-01-25 14:12:20 +08:00
pip install -r requirements.txt
2025-01-26 10:57:46 +08:00
python main.py
```
2026-01-25 14:12:20 +08:00
**Frontend**
2025-05-28 23:29:13 +08:00
2025-01-26 10:57:46 +08:00
```bash
2026-01-25 14:12:20 +08:00
# Frontend repo: https://github.com/vastsa/FileCodeBoxFronted
2025-01-26 10:57:46 +08:00
cd fcb-fronted
npm install
npm run dev
```
2026-01-25 14:12:20 +08:00
### Tech Stack
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
| Category | Technology |
|----------|------------|
| **Backend Framework** | FastAPI 0.128+ / Uvicorn |
| **Database** | SQLite + Tortoise ORM |
| **Data Validation** | Pydantic 2.x |
| **Async Support** | aiofiles / aiohttp / aioboto3 |
| **Object Storage** | S3 Protocol / OneDrive / OpenDAL |
| **Frontend Framework** | Vue 3 + Element Plus + Vite |
| **Runtime** | Python 3.8+ / Node.js 18+ |
| **Containerization** | Docker / Docker Compose |
---
2025-01-26 10:57:46 +08:00
## ❓ FAQ
2026-01-25 14:12:20 +08:00
<details>
<summary><b>How to modify upload size limit?</b></summary>
2025-05-28 23:29:13 +08:00
2026-01-25 14:12:20 +08:00
Modify the `uploadSize` configuration in the admin panel. If using Nginx reverse proxy, also modify `client_max_body_size` .
</details>
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
<details>
<summary><b>How to configure storage engine?</b></summary>
2025-05-28 23:29:13 +08:00
2026-01-25 14:12:20 +08:00
Select the storage engine type and configure parameters in the admin panel. Supports local storage, S3, OneDrive, OpenDAL, etc.
</details>
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
<details>
<summary><b>How to backup data?</b></summary>
2025-05-28 23:29:13 +08:00
2026-01-25 14:12:20 +08:00
Backup the `data` directory, which contains the database and uploaded files.
</details>
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
<details>
<summary><b>How to change admin password?</b></summary>
2025-01-26 10:57:46 +08:00
2026-01-25 14:12:20 +08:00
After logging into the admin panel, modify the `adminPassword` configuration in system settings.
</details>
For more questions, visit [Wiki ](https://github.com/vastsa/FileCodeBox/wiki/FAQ )
---
## 🤝 Contributing
Issues and Pull Requests are welcome!
```bash
# 1. Fork and clone
git clone https://github.com/your-username/FileCodeBox.git
# 2. Create branch
git checkout -b feature/your-feature
# 3. Commit changes
git commit -m "feat: add your feature"
# 4. Push and create PR
git push origin feature/your-feature
```
---
## 📊 Statistics
2025-01-26 10:57:46 +08:00
<div align="center">
2026-01-25 14:12:20 +08:00
<a href="https://hellogithub.com/repository/75ad7ffedd404a6485b4d621ec5b47e6" target="_blank">
<img src="https://api.hellogithub.com/v1/widgets/recommend.svg?rid=75ad7ffedd404a6485b4d621ec5b47e6&claim_uid=beSz6INEkCM4mDH" alt="HelloGitHub" width="200">
</a>
2025-01-26 10:57:46 +08:00

[](https://star-history.com/#vastsa/FileCodeBox &Date)
2026-01-25 14:12:20 +08:00
2025-01-26 10:57:46 +08:00
</div>
2026-01-25 14:12:20 +08:00
---
## 🗓 Roadmap
- [ ] 2025 New Theme
- [ ] File Collection Feature
---
2025-01-26 10:57:46 +08:00
## 📜 Disclaimer
2026-01-25 14:12:20 +08:00
This project is open-source for learning and communication purposes only. It should not be used for any illegal purposes. The author is not responsible for any consequences. Please retain the project address and copyright information when using it.
---
<div align="center">
**If you find this project helpful, please give it a ⭐ Star!**
Made with ❤️ by [vastsa ](https://github.com/vastsa )
</div>