fileshare/README.md

# 文件传输服务

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

## 功能特性

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

## 快速开始

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

```bash
cd fileshare
./start.sh
```

### 方式2: Docker部署

**国内用户 (使用阿里云加速)：**
```bash
cd fileshare
cp .env.example .env

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

**海外用户：**
```bash
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依赖：
```bash
pip install -r requirements.txt
```

2. 启动服务：
```bash
python app.py
```

## 使用方法

### 🌐 Web界面

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

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

### 💻 curl命令行（推荐）

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

```bash
# 上传文件
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便捷函数（更简单）

**一次设置，永久便捷**：

```bash
# 加载便捷函数
source fileshare_functions.sh

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

**便捷功能**：
- ✅ 自动提取分享码
- ✅ 彩色输出和错误提示
- ✅ 支持批量操作
- ✅ 自动服务器检测

### Web API

#### 上传文件
```bash
curl -X POST "http://localhost:8000/api/upload" \
  -F "file=@example.txt"
```

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

#### 下载文件
```bash
curl -O "http://localhost:8000/api/download/ABCD1234"
```

#### 获取文件信息
```bash
curl "http://localhost:8000/api/info/ABCD1234"
```

### @fileshare/fileshare_functions.sh

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

```bash
# 加载便捷函数
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. 安装开发依赖：
```bash
pip install -r requirements.txt
```

2. 启动开发服务器：
```bash
python app.py
# 或使用uvicorn
uvicorn app:app --reload --host 0.0.0.0 --port 8000
```

3. 测试便捷函数：
```bash
source fileshare_functions.sh
fileshare_help
```

### 国内加速部署

**使用阿里云镜像加速构建：**
```bash
# 构建优化镜像
./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镜像源  
- 容器镜像使用阿里云容器镜像服务
- 多阶段构建减少镜像体积

## 故障排除

### 🔧 快速诊断

遇到问题时，可以检查服务状态：
```bash
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已安装
   - 检查端口映射配置

### 🧪 测试工具

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

# 功能测试
source fileshare_functions.sh
fileshare_help
```

### 日志查看

```bash
# Docker日志
docker-compose logs -f

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

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！