文件传输服务

一个简单易用的文件和文本临时分享服务，支持生成分享口令，文件自动过期清理。

功能特性

• 🚀 文件上传分享 - 支持任意类型文件上传，生成分享口令
• 📝 文本分享 - 支持纯文本内容分享
• 🔐 口令访问 - 通过8位分享码下载文件
• ⏰ 自动过期 - 文件15分钟后自动过期删除
• 🛡️ 安全可靠 - 支持文件大小限制，自动清理
• 🌐 RESTful API - 完整的API接口
• 💻 命令行工具 - 便捷的CLI工具
• 🐳 Docker支持 - 开箱即用的容器化部署

快速开始

方式1: 一键启动 (推荐)

cd fileshare
./start.sh

方式2: Docker部署

国内用户 (使用阿里云加速)：

cd fileshare
cp .env.example .env

# 构建并启动 (使用阿里云镜像加速)
./build.sh --aliyun
docker-compose -f docker-compose.aliyun.yml up -d

海外用户：

cd fileshare
cp .env.example .env

# 基础部署
docker-compose up -d

访问服务：

• 🌐 Web界面: http://localhost:8000
• 📖 API文档: http://localhost:8000/docs
• ℹ️ API信息: http://localhost:8000/api

方式3: 本地运行

1. 安装Python依赖：

pip install -r requirements.txt

2. 启动服务：

python app.py

使用方法

🌐 Web界面

访问 http://localhost:8000 使用友好的Web界面：

1. 📁 上传文件 - 拖拽或点击选择文件上传
2. 📝 分享文本 - 在线编辑文本内容分享
3. ⬇️ 下载文件 - 输入8位分享码下载
4. 💻 curl命令 - 无需安装工具的命令行使用教程

💻 curl命令行（推荐）

无需安装任何额外工具，使用系统自带的curl命令：

# 上传文件
curl -X POST -F "file=@文件路径" http://localhost:8000/api/upload

# 分享文本（超级简单）
curl -X POST --data "你的文本" http://localhost:8000/api/text

# 下载文件  
curl -O -J http://localhost:8000/api/download/分享码

# 查看文件信息
curl http://localhost:8000/api/info/分享码

📖 完整教程: 访问 http://localhost:8000/curl

🚀 Shell便捷函数（更简单）

一次设置，永久便捷：

# 加载便捷函数
source fileshare_functions.sh

# 现在可以使用超级简单的命令
upload photo.jpg              # 上传文件
share_text "Hello World!"     # 分享文本
download AB12CD34             # 下载文件
info AB12CD34                 # 查看信息
list_shares                   # 列出分享

便捷功能：

• ✅ 自动提取分享码
• ✅ 彩色输出和错误提示
• ✅ 支持批量操作
• ✅ 自动服务器检测

Web API

上传文件

curl -X POST "http://localhost:8000/api/upload" \
  -F "file=@example.txt"

分享文本

curl -X POST "http://localhost:8000/api/share-text" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello World!", "filename": "hello.txt"}'

下载文件

curl -O "http://localhost:8000/api/download/ABCD1234"

获取文件信息

curl "http://localhost:8000/api/info/ABCD1234"

@fileshare/fileshare_functions.sh

便捷的Shell函数库，提供更丰富的功能：

# 加载便捷函数
source fileshare_functions.sh

# 现在可以使用超级简单的命令
upload photo.jpg              # 上传文件
share_text "Hello World!"     # 分享文本
download AB12CD34             # 下载文件
info AB12CD34                 # 查看信息
list_shares                   # 列出分享

# 高级功能
batch_upload *.jpg            # 批量上传
share_file config.txt         # 分享文件内容
set_server https://domain.com # 设置服务器

便捷功能：

• ✅ 自动提取分享码
• ✅ 彩色输出和错误提示
• ✅ 支持批量操作
• ✅ 自动服务器检测
• ✅ 无需安装依赖

环境变量配置

可以通过环境变量或.env文件配置：

变量名	默认值	说明
HOST	0.0.0.0	服务器监听地址
PORT	8000	服务器端口
MAX_FILE_SIZE	104857600	最大文件大小(字节)
EXPIRE_MINUTES	15	文件过期时间(分钟)
FILESHARE_SERVER	http://localhost:8000	客户端服务器地址

API接口

完整API文档

启动服务后访问 http://localhost:8000/docs 查看自动生成的API文档。

主要接口

接口	方法	说明
/	GET	服务信息
/api/upload	POST	上传文件
/api/share-text	POST	分享文本
/api/download/{code}	GET	下载文件
/api/info/{code}	GET	获取分享信息
/api/shares	GET	列出所有分享
/api/shares/{code}	DELETE	删除分享
/api/cleanup	POST	手动清理过期文件

部署建议

生产环境

1. 数据持久化：

   • 上传文件会保存在./data/uploads
   • 可以备份该目录

2. 监控和日志：

   • 日志输出到./data/logs
   • 支持健康检查

安全建议

1. 设置合适的文件大小限制
2. 定期清理过期文件
3. 限制访问IP（如需要）

开发

项目结构

fileshare/
├── app.py                    # 主应用程序
├── requirements.txt          # Python依赖
├── Dockerfile               # Docker镜像 (标准版)
├── Dockerfile.multi         # Docker镜像 (多阶段构建优化版)
├── docker-compose.yml       # Docker编排 (标准版)
├── docker-compose.aliyun.yml # Docker编排 (阿里云优化版)
├── .dockerignore            # Docker构建忽略文件
├── .env.example             # 环境变量示例
├── start.sh                 # 一键启动脚本
├── build.sh                 # Docker构建脚本
├── README.md                # 项目说明
├── static/                  # 前端文件
│   ├── index.html          # 主页面
│   ├── style.css           # 样式表  
│   ├── app.js              # 前端逻辑
│   └── curl-guide.html     # curl命令教程页面
├── uploads/                 # 上传文件目录
├── fileshare_functions.sh  # Shell便捷函数
└── data/                   # 数据目录
    ├── uploads/            # 持久化上传目录
    └── logs/               # 日志目录

开发模式

1. 安装开发依赖：

pip install -r requirements.txt

2. 启动开发服务器：

python app.py
# 或使用uvicorn
uvicorn app:app --reload --host 0.0.0.0 --port 8000

3. 测试便捷函数：

source fileshare_functions.sh
fileshare_help

国内加速部署

使用阿里云镜像加速构建：

# 构建优化镜像
./build.sh --aliyun

# 使用阿里云compose文件启动
docker-compose -f docker-compose.aliyun.yml up -d

# 或指定镜像仓库
./build.sh --aliyun --push --registry registry.cn-hangzhou.aliyuncs.com/yourname

加速特性：

• apt使用阿里云Debian镜像源
• pip使用阿里云PyPI镜像源
• 容器镜像使用阿里云容器镜像服务
• 多阶段构建减少镜像体积

故障排除

🔧 快速诊断

遇到问题时，可以检查服务状态：

docker-compose ps
docker-compose logs -f

常见问题

1. CSS/JS文件404错误

   • 检查static目录是否存在
   • 确认静态文件路径正确

2. 文件上传失败

   • 检查文件大小是否超过限制
   • 确认磁盘空间充足

3. 下载失败

   • 确认分享码正确
   • 检查文件是否已过期

4. 服务无法启动

   • 检查端口是否被占用
   • 确认Python版本>=3.8
   • 运行: pip install -r requirements.txt

5. Docker问题

   • 确认Docker和docker-compose已安装
   • 检查端口映射配置

🧪 测试工具

# 服务验证
curl http://localhost:8000/api

# 功能测试
source fileshare_functions.sh
fileshare_help

日志查看

# Docker日志
docker-compose logs -f

# 单个服务日志
docker-compose logs fileshare

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！