ttup 2.2.0
终端文件上传工具 - 支持网页版和命令行上传
Requires Python: >=3.8

<div align="center">

<img src="https://img.shields.io/badge/ttup-文件上传工具-667eea?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xOSAzSDVjLTEuMSAwLTIgLjktMiAydjE0YzAgMS4xLjkgMiAyIDJoMTRjMS4xIDAgMi0uOSAyLTJWNWMwLTEuMS0uOS0yLTItMnptLTUgMTRIN3YtMmg3djJ6bTMtNEg3di0yaDEwdjJ6bTAtNEg3VjdoMTB2MnoiLz48L3N2Zz4=" alt="ttup" />

**简单高效的终端文件上传工具**

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue?style=flat-square)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
[![Version](https://img.shields.io/badge/version-2.2.0-orange?style=flat-square)](https://codeberg.org/ttup/ttup)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey?style=flat-square)]()

一款轻量级的文件传输工具，支持网页端和命令行，让文件分享变得简单快捷。

[快速开始](#-快速开始) · [功能特性](#-功能特性) · [安装](#-安装) · [使用文档](#-使用文档) · [贡献](#-贡献)

</div>

---

## 🎯 什么是 ttup？

ttup 是一个**开箱即用**的文件传输工具，无需复杂的配置，一行命令即可启动服务端，一行命令即可上传文件。

**适用场景：**
- 📤 临时分享文件给同事/朋友
- 📱 跨设备文件传输
- 🔒 敏感文件阅后即焚
- 🤖 脚本自动化文件分发
- 🏠 家庭/团队私有文件服务

---

## ✨ 功能特性

<table>
<tr>
<td width="50%">

### 🖥️ 多端支持
- **网页版** - 拖拽上传，简洁美观
- **命令行** - 终端快速操作
- **curl** - 脚本友好接口
- **API** - 完整 RESTful 接口

</td>
<td width="50%">

### 🔒 安全可控
- **过期时间** - 1s/1m/1h/1d/1w
- **下载限制** - 阅后即焚模式
- **自动清理** - 过期文件自动删除
- **唯一ID** - 8位取件码

</td>
</tr>
<tr>
<td width="50%">

### 🎯 简洁高效
- **零配置** - 开箱即用
- **真实IP** - 自动识别
- **无数据库** - 文件存储
- **轻量级** - 最小依赖

</td>
<td width="50%">

### 📦 跨平台
- **Linux** - 全面支持
- **macOS** - 原生体验
- **Windows** - 无缝运行
- **Python 3.8+** - 广泛兼容

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

---

## 📦 安装

### 方式一：下载 Wheel 包（推荐）

```bash
# 下载最新的 wheel 包
pip install ttup-2.2.0-py3-none-any.whl
```

### 方式二：源码安装

```bash
git clone https://codeberg.org/ttup/ttup.git
cd ttup
pip install -e .
```

<details>
<summary>📋 系统要求</summary>

| 项目 | 要求 |
|------|------|
| Python | 3.8+ |
| 操作系统 | Linux / macOS / Windows |
| 依赖 | fastapi, uvicorn, click, requests |
| 存储 | 根据文件大小决定 |

</details>

---

## 🚀 快速开始

### 1️⃣ 启动服务端

```bash
ttup-server
```

```
==================================================
ttup 文件上传服务 v2.1.0
==================================================
上传目录: /home/user/.ttup/uploads
监听地址: http://0.0.0.0:7888
==================================================
访问 http://localhost:7888 使用网页版
==================================================
```

<details>
<summary>⚙️ 自定义配置</summary>

```bash
# 指定端口
ttup-server -p 9000

# 指定上传目录
ttup-server -d /path/to/uploads

# 指定绑定地址
ttup-server -H 127.0.0.1

# 组合使用
ttup-server -p 9000 -H 0.0.0.0 -d ~/my-uploads
```

</details>

### 2️⃣ 上传文件

**方式一：网页版** → 浏览器打开 `http://localhost:7888`

**方式二：命令行**
```bash
ttup document.pdf
```

**方式三：curl**
```bash
curl -F "file=@document.pdf" http://localhost:7888/upload
```

### 3️⃣ 下载文件

```bash
# 命令行下载
curl -O http://localhost:7888/file/abc12345

# 或直接浏览器打开链接
```

---

## 📖 使用文档

### 客户端命令 (ttup)

```
用法: ttup [OPTIONS] FILENAME

选项:
  -s, --server TEXT        服务端地址
  -e, --expires-in TEXT    过期时间 (1h, 24h, 7d)
  -n, --max-downloads INT  最大下载次数
  -v, --verbose            详细输出
  -V, --version            显示版本
  -h, --help [cn|en]       显示帮助 (默认中文，en=英文)

环境变量:
  TTUP_SERVER              默认服务端地址
```

<details>
<summary>🌐 English Help</summary>

```
USAGE: ttup [OPTIONS] FILENAME

OPTIONS:
  -s, --server TEXT        Server address (default: from TTUP_SERVER env)
  -e, --expires-in TEXT    Expiration time (e.g., 1h, 24h, 7d)
  -n, --max-downloads INT  Maximum download count
  -v, --verbose            Show detailed output
  -V, --version            Show version
  -h, --help [cn|en]       Show help (cn=Chinese, en=English)

ENVIRONMENT:
  TTUP_SERVER              Default server address
```

</details>

### 服务端命令 (ttup-server)

```
用法: ttup-server [OPTIONS]

选项:
  -p, --port INTEGER   端口 (默认: 7888)
  -H, --host TEXT      地址 (默认: 0.0.0.0)
  -d, --dir TEXT       目录 (默认: ~/.ttup/uploads)
  -V, --version        显示版本
  -h, --help [cn|en]   显示帮助 (默认中文，en=英文)
```

<details>
<summary>🌐 English Help</summary>

```
USAGE: ttup-server [OPTIONS]

OPTIONS:
  -p, --port INTEGER   Server port (default: 7888)
  -H, --host TEXT      Bind address (default: 0.0.0.0)
  -d, --dir TEXT       Upload directory (default: ~/.ttup/uploads)
  -V, --version        Show version
  -h, --help [cn|en]   Show help (cn=Chinese, en=English)
```

</details>

### 使用示例

```bash
# 基本上传
ttup file.pdf

# 1小时后过期
ttup -e 1h file.pdf

# 只能下载3次
ttup -n 3 file.pdf

# 阅后即焚
ttup -n 1 secret.txt

# 组合使用：24小时或下载5次后失效
ttup -e 24h -n 5 bigfile.zip

# 指定服务端
ttup -s http://192.168.1.100:7888 file.pdf

# 使用环境变量
export TTUP_SERVER=http://your-server:7888
ttup file.pdf
```

### 过期时间格式

| 参数 | 说明 | 使用场景 |
|------|------|----------|
| `1s` | 1秒 | 临时分享 |
| `1m` | 1分钟 | 快速传输 |
| `1h` | 1小时 | 短期分享 |
| `24h` | 24小时 | 日常使用 |
| `7d` | 7天 | 一周有效 |
| `30d` | 30天 | 长期存储 |

---

## 🌐 API 接口

### 接口列表

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/upload` | 上传文件 |
| `GET` | `/file/{id}` | 下载文件 |
| `GET` | `/info/{id}` | 文件信息 |
| `DELETE` | `/file/{id}` | 删除文件 |
| `GET` | `/health` | 健康检查 |

### 上传示例

```bash
# 基本上传
curl -F "file=@test.txt" http://localhost:7888/upload

# 带过期时间
curl -F "file=@test.txt" -F "expires_in=24h" http://localhost:7888/upload

# 带下载限制
curl -F "file=@test.txt" -F "max_downloads=5" http://localhost:7888/upload

# 完整参数
curl -F "file=@test.txt" \
     -F "expires_in=24h" \
     -F "max_downloads=5" \
     http://localhost:7888/upload
```

### 响应示例

```json
{
  "file_id": "abc12345",
  "filename": "test.txt",
  "ext": ".txt",
  "size": 1024,
  "url": "http://192.168.1.100:7888/file/abc12345",
  "expires_at": "2026-02-20T10:00:00",
  "max_downloads": 5
}
```

---

## 🚢 生产部署

### 后台运行

```bash
# 使用 nohup
nohup ttup-server > /var/log/ttup.log 2>&1 &

# 查看日志
tail -f /var/log/ttup.log
```

### Nginx 反向代理

```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://127.0.0.1:7888;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        client_max_body_size 100M;
    }
}
```

### HTTPS 配置

```bash
# 使用 Certbot
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
```

### 防火墙配置

```bash
# Ubuntu/Debian
sudo ufw allow 7888/tcp

# CentOS/RHEL
sudo firewall-cmd --add-port=7888/tcp --permanent
sudo firewall-cmd --reload
```

---

## 📁 项目结构

```
ttup/
├── ttup/
│   ├── __init__.py        # 包初始化
│   ├── __main__.py        # 服务端入口
│   ├── cli.py             # 客户端 CLI
│   ├── ttup_server.py     # FastAPI 服务
│   └── static/
│       └── index.html     # 网页界面
├── setup.py               # 安装配置
├── LICENSE                # MIT 许可证
└── README.md              # 说明文档
```

---

---

## 🤝 贡献

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

---

## 📝 更新日志

### v2.2.0 (2026-02-20)
- 🐛 修复网页版接收文件功能

### v2.1.0 (2026-02-20)
- ✨ 添加中英文双语帮助支持
- ✨ 优化帮助文本，移除冗余信息
- 🐛 修复多项问题

### v2.0.0 (2026-02-19)
- 🎉 首次发布
- ✅ 基础文件上传/下载功能
- ✅ 过期时间支持
- ✅ 下载次数限制
- ✅ 自动清理功能
- ✅ 网页界面
- ✅ 命令行工具

---

## 📜 许可证

本项目基于 [MIT License](LICENSE) 开源。

---

## 🔗 相关链接

| 链接 | 地址 |
|------|------|
| 项目主页 | https://codeberg.org/ttup/ttup |
| 问题反馈 | https://codeberg.org/ttup/ttup/issues |

---

<div align="center">

**如果觉得有用，请给个 ⭐ Star 支持一下！**

[![Star History Chart](https://api.star-history.com/svg?repos=ttup/ttup&type=Date)](https://star-history.com/#ttup/ttup&Date)

**Made with ❤️ by ttup**

</div>