feat: docs
This commit is contained in:
Lan
@@ -0,0 +1,263 @@
|
||||
# FileCodeBox API Documentation
|
||||
|
||||
## API Version: 2.1.0
|
||||
|
||||
## Table of Contents
|
||||
- [Authentication](#authentication)
|
||||
- [Share API](#share-api)
|
||||
- [Admin API](#admin-api)
|
||||
|
||||
## Authentication
|
||||
|
||||
Some APIs require `Authorization` header for authentication:
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
## Share API
|
||||
|
||||
### Share Text
|
||||
|
||||
**POST** `/share/text/`
|
||||
|
||||
Share text content and get a share code.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| text | string | Yes | - | Text content to share |
|
||||
| expire_value | integer | No | 1 | Expiration time value |
|
||||
| expire_style | string | No | "day" | Expiration time unit(day/hour/minute) |
|
||||
|
||||
**Response Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"detail": {
|
||||
"code": "abc123",
|
||||
"name": "text.txt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Share File
|
||||
|
||||
**POST** `/share/file/`
|
||||
|
||||
Upload and share a file, get a share code.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| file | file | Yes | - | File to upload |
|
||||
| expire_value | integer | No | 1 | Expiration time value |
|
||||
| expire_style | string | No | "day" | Expiration time unit(day/hour/minute) |
|
||||
|
||||
**Response Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"detail": {
|
||||
"code": "abc123",
|
||||
"name": "example.txt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get File Info
|
||||
|
||||
**GET** `/share/select/`
|
||||
|
||||
Get file information by share code.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| code | string | Yes | File share code |
|
||||
|
||||
**Response Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"detail": {
|
||||
"code": "abc123",
|
||||
"name": "example.txt",
|
||||
"size": 1024,
|
||||
"text": "File content or download link"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Select File
|
||||
|
||||
**POST** `/share/select/`
|
||||
|
||||
Select file by share code.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| code | string | Yes | File share code |
|
||||
|
||||
**Response Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"detail": {
|
||||
"code": "abc123",
|
||||
"name": "example.txt",
|
||||
"size": 1024,
|
||||
"text": "File content or download link"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Download File
|
||||
|
||||
**GET** `/share/download`
|
||||
|
||||
Download shared file.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| key | string | Yes | Download key |
|
||||
| code | string | Yes | File share code |
|
||||
|
||||
## Admin API
|
||||
|
||||
### Admin Login
|
||||
|
||||
**POST** `/admin/login`
|
||||
|
||||
Admin login to get token.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| password | string | Yes | Admin password |
|
||||
|
||||
### Dashboard Data
|
||||
|
||||
**GET** `/admin/dashboard`
|
||||
|
||||
Get system dashboard data.
|
||||
|
||||
**Response Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"detail": {
|
||||
"totalFiles": 100,
|
||||
"storageUsed": "1.5GB",
|
||||
"sysUptime": "10 days",
|
||||
"yesterdayCount": 50,
|
||||
"yesterdaySize": "500MB",
|
||||
"todayCount": 30,
|
||||
"todaySize": "300MB"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### File List
|
||||
|
||||
**GET** `/admin/file/list`
|
||||
|
||||
Get system file list.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| page | integer | No | 1 | Current page |
|
||||
| size | integer | No | 10 | Page size |
|
||||
| keyword | string | No | "" | Search keyword |
|
||||
|
||||
**Response Example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"detail": {
|
||||
"page": 1,
|
||||
"size": 10,
|
||||
"total": 100,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "example.txt",
|
||||
"size": 1024,
|
||||
"created_at": "2024-01-01 12:00:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Delete File
|
||||
|
||||
**DELETE** `/admin/file/delete`
|
||||
|
||||
Delete file from system.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| id | integer | Yes | File ID |
|
||||
|
||||
### Get Config
|
||||
|
||||
**GET** `/admin/config/get`
|
||||
|
||||
Get system configuration.
|
||||
|
||||
### Update Config
|
||||
|
||||
**PATCH** `/admin/config/update`
|
||||
|
||||
Update system configuration.
|
||||
|
||||
## Error Response
|
||||
|
||||
When an error occurs, the API will return corresponding error message:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 422,
|
||||
"detail": [
|
||||
{
|
||||
"loc": ["body", "password"],
|
||||
"msg": "Password cannot be empty",
|
||||
"type": "value_error"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Status Codes
|
||||
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: Not Found
|
||||
- 422: Validation Error
|
||||
- 500: Internal Server Error
|
||||
@@ -0,0 +1,74 @@
|
||||
# Getting Started
|
||||
|
||||
## Introduction
|
||||
|
||||
FileCodeBox is a simple and efficient file sharing tool that supports temporary file transfer, sharing, and management. This guide will help you quickly deploy and use FileCodeBox.
|
||||
|
||||
## Features
|
||||
|
||||
- 🚀 Quick Deployment: Support Docker one-click deployment
|
||||
- 🔒 Secure & Reliable: File access requires extraction code
|
||||
- ⏱️ Time Control: Support setting file expiration time
|
||||
- 📊 Download Limit: Can limit file download times
|
||||
- 🖼️ File Preview: Support preview of images, videos, audio, and other formats
|
||||
- 📱 Responsive Design: Perfect adaptation for mobile and desktop
|
||||
|
||||
## Deployment Methods
|
||||
|
||||
### Docker Deployment (Recommended)
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name filecodebox \
|
||||
-p 12345:12345 \
|
||||
-v /path/to/data:/app/data \
|
||||
vastsa/filecodebox
|
||||
```
|
||||
|
||||
### Manual Deployment
|
||||
|
||||
1. Clone the project
|
||||
|
||||
```bash
|
||||
git clone https://github.com/vastsa/FileCodeBox.git
|
||||
cd FileCodeBox
|
||||
```
|
||||
|
||||
2. Install dependencies
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
3. Start service
|
||||
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
1. Access the System
|
||||
Open browser and visit `http://localhost:12345`
|
||||
|
||||
2. Upload Files
|
||||
- Click upload button or drag files to upload area
|
||||
- Set file expiration time and download limit
|
||||
- Get share link and extraction code
|
||||
|
||||
3. Download Files
|
||||
- Visit share link
|
||||
- Enter extraction code
|
||||
- Download file
|
||||
|
||||
4. Admin Panel
|
||||
- Visit `http://localhost:12345/admin`
|
||||
- Enter admin password: `FileCodeBox2023`
|
||||
- Enter admin panel
|
||||
- View system information, file list, user management, etc.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Storage Configuration](/en/guide/storage) - Learn how to configure different storage methods
|
||||
- [Security Settings](/en/guide/security) - Learn how to enhance system security
|
||||
- [API Documentation](/en/api/) - Learn how to integrate through API
|
||||
@@ -0,0 +1,284 @@
|
||||
<div align="center">
|
||||
|
||||
<img src="https://fastly.jsdelivr.net/gh/vastsa/FileCodeBox@V1.6/static/banners/img_1.png" alt="FileCodeBox Logo">
|
||||
|
||||
<p><em>Share text and files anonymously with a passcode, like picking up a package</em></p>
|
||||
|
||||
[](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://qm.qq.com/q/PemPzhdEIM)
|
||||
[](https://www.python.org)
|
||||
[](https://fastapi.tiangolo.com)
|
||||
[](https://v3.vuejs.org)
|
||||
|
||||
[简体中文](./readme.md) | [Deployment Guide](https://github.com/vastsa/FileCodeBox/wiki/Deployment-Guide) | [FAQ](https://github.com/vastsa/FileCodeBox/wiki/FAQ)
|
||||
|
||||
</div>
|
||||
|
||||
## 📝 Introduction
|
||||
|
||||
FileCodeBox is a lightweight file sharing tool developed with FastAPI + Vue3. It allows users to share text and files easily, where recipients only need a passcode to retrieve the files, just like picking up a package from a delivery locker.
|
||||
|
||||
## 🖼️ Preview
|
||||
|
||||
<div align="center">
|
||||
<h3>
|
||||
<a href="https://github.com/vastsa/FileCodeBoxFronted" target="_blank">
|
||||
<img src="https://img.shields.io/badge/Frontend-FileCodeBoxFronted-blue?style=for-the-badge&logo=github" alt="Frontend Repository">
|
||||
</a>
|
||||
|
||||
<a href="https://share.lanol.cn" target="_blank">
|
||||
<img src="https://img.shields.io/badge/Demo-share.lanol.cn-green?style=for-the-badge&logo=internet-explorer" alt="Demo Site">
|
||||
</a>
|
||||
</h3>
|
||||
</div>
|
||||
|
||||
### New Interface
|
||||
<div align="center">
|
||||
<table>
|
||||
<tr>
|
||||
<td><img src="./.github/images/img_7.png" alt="File Upload" title="File Upload Interface"></td>
|
||||
<td><img src="./.github/images/img_8.png" alt="Text Share" title="Text Share Interface"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><img src="./.github/images/img_10.png" alt="File Management" title="File Management Interface"></td>
|
||||
<td><img src="./.github/images/img_9.png" alt="System Settings" title="System Settings Interface"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><img src="./.github/images/img_11.png" alt="Mobile View" title="Mobile Interface"></td>
|
||||
<td><img src="./.github/images/img_12.png" alt="Dark Mode" title="Dark Mode Interface"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><img src="./.github/images/img_13.png" alt="Internationalization" title="Language Support"></td>
|
||||
<td><img src="./.github/images/img_14.png" alt="Responsive" title="Responsive Design"></td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
### Classic Interface
|
||||
<div align="center">
|
||||
<table>
|
||||
<tr>
|
||||
<td><img src="./.github/images/img.png" alt="Home" title="Home Page"></td>
|
||||
<td><img src="./.github/images/img_1.png" alt="Upload" title="Upload Interface"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><img src="./.github/images/img_2.png" alt="Management" title="Management Interface"></td>
|
||||
<td><img src="./.github/images/img_3.png" alt="Settings" title="Settings Interface"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><img src="./.github/images/img_4.png" alt="Share" title="Share Interface"></td>
|
||||
<td><img src="./.github/images/img_5.png" alt="Download" title="Download Interface"></td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
## 🎯 Use Cases
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<h4>📁 Temporary File Sharing</h4>
|
||||
Quick file sharing without registration
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>📝 Quick Text Sharing</h4>
|
||||
Share code snippets and text content
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>🕶️ Anonymous Transfer</h4>
|
||||
Privacy-protected file transfer
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<h4>💾 Temporary Storage</h4>
|
||||
File storage with expiration time
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>🔄 Cross-platform Transfer</h4>
|
||||
Quick file transfer between devices
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>🌐 Private Share Service</h4>
|
||||
Build your own file sharing service
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## ✨ Core Features
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<h4>🚀 Lightweight</h4>
|
||||
Based on FastAPI + SQLite3 + Vue3 + ElementUI
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>📤 Easy Upload</h4>
|
||||
Support copy-paste and drag-drop
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>📦 Multiple Types</h4>
|
||||
Support text and various file types
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<h4>🔒 Security</h4>
|
||||
|
||||
- IP upload limits
|
||||
- Error attempt limits
|
||||
- File expiration
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>🎫 Passcode Sharing</h4>
|
||||
Random codes with customizable limits
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>🌍 Multi-language</h4>
|
||||
Support for Simplified Chinese, Traditional Chinese, and English
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<h4>🎭 Anonymous</h4>
|
||||
No registration required
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>🛠 Admin Panel</h4>
|
||||
File and system management
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>🐳 Docker</h4>
|
||||
One-click deployment
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<h4>💾 Storage Options</h4>
|
||||
Local, S3, OneDrive support
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>📱 Responsive</h4>
|
||||
Mobile-friendly design
|
||||
</td>
|
||||
<td align="center">
|
||||
<h4>💻 CLI Support</h4>
|
||||
Command-line download
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
```bash
|
||||
docker run -d --restart=always -p 12345:12345 -v /opt/FileCodeBox/:/app/data --name filecodebox lanol/filecodebox:beta
|
||||
```
|
||||
|
||||
### Manual Deployment
|
||||
|
||||
1. Clone the repository
|
||||
```bash
|
||||
git clone https://github.com/vastsa/FileCodeBox.git
|
||||
```
|
||||
|
||||
2. Install dependencies
|
||||
```bash
|
||||
cd FileCodeBox
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
3. Start the service
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
## 📖 Usage Guide
|
||||
|
||||
### Share Files
|
||||
1. Open the website, click "Share File"
|
||||
2. Select or drag files
|
||||
3. Set expiration time and count
|
||||
4. Get the passcode
|
||||
|
||||
### Retrieve Files
|
||||
1. Open the website, enter passcode
|
||||
2. Click retrieve
|
||||
3. Download file or view text
|
||||
|
||||
### Admin Panel
|
||||
1. Visit `/admin`
|
||||
2. Enter admin password
|
||||
3. Manage files and settings
|
||||
|
||||
## 🛠 Development Guide
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
FileCodeBox/
|
||||
├── apps/ # Application code
|
||||
│ ├── admin/ # Admin backend
|
||||
│ └── base/ # Base functions
|
||||
├── core/ # Core functions
|
||||
├── data/ # Data directory
|
||||
└── fcb-fronted/ # Frontend code
|
||||
```
|
||||
|
||||
### Development Environment
|
||||
- Python 3.8+
|
||||
- Node.js 14+
|
||||
- Vue 3
|
||||
- FastAPI
|
||||
|
||||
### Local Development
|
||||
1. Backend development
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
2. Frontend development
|
||||
```bash
|
||||
cd fcb-fronted
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Fork the project
|
||||
2. Create your feature branch `git checkout -b feature/xxx`
|
||||
3. Commit your changes `git commit -m 'Add xxx'`
|
||||
4. Push to the branch `git push origin feature/xxx`
|
||||
5. Open a Pull Request
|
||||
|
||||
## ❓ FAQ
|
||||
|
||||
### Q: How to modify upload size limit?
|
||||
A: Change `uploadSize` in admin panel
|
||||
|
||||
### Q: How to configure storage engine?
|
||||
A: Select storage engine and configure parameters in admin panel
|
||||
|
||||
### Q: How to backup data?
|
||||
A: Backup the `data` directory
|
||||
|
||||
For more questions, visit [Wiki](https://github.com/vastsa/FileCodeBox/wiki/常见问题)
|
||||
|
||||
## 😀 Project Statistics and Analytics
|
||||
|
||||
<div align="center">
|
||||
<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="Featured｜HelloGitHub" style="width: 200px; height: 45px;" width="200" height="45" /></a>
|
||||
|
||||
|
||||
|
||||
[](https://star-history.com/#vastsa/FileCodeBox&Date)
|
||||
</div>
|
||||
|
||||
## 📜 Disclaimer
|
||||
|
||||
This project is open-source for learning 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.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
layout: home
|
||||
|
||||
hero:
|
||||
name: "FileCodeBox"
|
||||
text: "File Express Box"
|
||||
tagline: Share text and files anonymously with access codes, just like picking up a package
|
||||
image:
|
||||
src: /logo_small.png
|
||||
alt: FileCodeBox
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Get Started
|
||||
link: /en/guide/getting-started
|
||||
- theme: alt
|
||||
text: View on GitHub
|
||||
link: https://github.com/vastsa/FileCodeBox
|
||||
|
||||
features:
|
||||
- icon: 🚀
|
||||
title: Quick Deployment
|
||||
details: Supports one-click Docker deployment, simple and fast, no complex configuration needed
|
||||
- icon: 🔒
|
||||
title: Secure & Reliable
|
||||
details: File access requires an access code, supports expiration time and download limit settings
|
||||
- icon: 💻
|
||||
title: Clean Interface
|
||||
details: Clean user interface with drag-and-drop upload support for excellent user experience
|
||||
- icon: 🛠️
|
||||
title: Feature Rich
|
||||
details: Supports file preview, online playback, image processing, and many other features
|
||||
- icon: 📦
|
||||
title: Storage Extensions
|
||||
details: Supports various storage methods including local storage and object storage
|
||||
- icon: 🔌
|
||||
title: API Support
|
||||
details: Provides complete REST API for easy integration with other systems
|
||||
---
|
||||
Reference in New Issue
Block a user