分布式文件下发系统

一个基于 Python + FastAPI 的分布式文件下发系统，支持主控端向多个客户端批量下发文件。

🎯 功能特性

新增功能 ⭐v1.3.0

• ✅ 防火墙自动检查 - 首次启动自动检查并申请防火墙权限 🆕
• ✅ 批量打包工具 - 支持从数据库或配置文件批量生成客户端安装包 🆕
• ✅ 用户管理工具 - 命令行工具管理系统用户和权限 🆕

GUI 管理界面 ⭐

• ✅ 服务端 GUI 管理平台 - 功能完整的图形化管理界面
• ✅ 客户端 GUI - 可视化配置和监控
• ✅ 客户端安装包生成 - 一键生成预配置的客户端安装包 🎁
• ✅ 远程更新管理 - 一键推送更新到所有客户端 🚀
• ✅ 后台运行模式 - 系统托盘、开机自启动、任务完成通知
• ✅ 性能优化 - 异步加载、延迟加载、连接复用，流畅不卡顿 🚀
• ✅ 无需命令行 - 所有功能都可通过 GUI 操作
• ✅ 配置管理 - 图形界面修改所有配置

P2P 文件分发 🆕⭐

• ✅ 智能下载策略 - 优先从内网P2P节点下载，失败自动回退到服务器
• ✅ 自动文件共享 - 下载完成的文件自动共享给其他客户端
• ✅ 零配置 - 自动发现内网节点，无需手动配置
• ✅ 远程更新 - 支持客户端自动更新和配置同步
• ✅ 带宽节省 - 大幅减少服务器带宽压力，特别适合内网批量部署

核心功能

• ✅ WebSocket 长连接，支持跨公网通信
• ✅ 断点续传、大文件分片下载
• ✅ 自动重试机制
• ✅ 多客户端并发任务
• ✅ 权限控制（管理员/普通用户）
• ✅ 客户端分组管理
• ✅ 完整的日志记录
• ✅ 任务状态实时反馈

📁 项目结构

file-distribution-system/
├── server/                     # 主控端服务器（命令行版）
│   ├── app/
│   │   ├── main.py            # FastAPI 应用入口
│   │   ├── config.py          # 配置管理
│   │   ├── database.py        # 数据库连接
│   │   ├── models/            # SQLAlchemy 数据模型
│   │   │   ├── user.py        # 用户模型
│   │   │   ├── client.py      # 客户端模型
│   │   │   ├── task.py        # 任务模型
│   │   │   └── log.py         # 日志模型
│   │   ├── schemas/           # Pydantic 数据验证
│   │   ├── api/               # API 路由
│   │   │   ├── auth.py        # 认证相关
│   │   │   ├── files.py       # 文件管理
│   │   │   ├── tasks.py       # 任务管理
│   │   │   ├── clients.py     # 客户端管理
│   │   │   └── websocket.py   # WebSocket 处理
│   │   ├── services/          # 业务逻辑层
│   │   └── utils/             # 工具函数
│   ├── uploads/               # 文件存储目录
│   ├── requirements.txt
│   └── .env.example
├── client/                    # 客户端代理
│   ├── agent/
│   │   ├── main.py           # 客户端入口
│   │   ├── config.py         # 配置
│   │   ├── ws_client.py      # WebSocket 客户端
│   │   ├── downloader.py     # 分片下载器
│   │   ├── p2p_server.py     # P2P服务器 ⭐新增
│   │   ├── p2p_client.py     # P2P客户端 ⭐新增
│   │   ├── updater.py        # 远程更新器 ⭐新增
│   │   └── utils.py          # 工具函数
│   ├── downloads/            # 下载文件存储
│   ├── requirements.txt
│   └── .env.example
├── server-gui/               # 服务端 GUI 管理平台 ⭐新增
│   ├── gui/
│   │   ├── main_window.py   # 主窗口
│   │   ├── login_dialog.py  # 登录对话框
│   │   ├── api_client.py    # API 客户端封装
│   │   ├── config_manager.py # 配置管理
│   │   └── widgets/         # 功能组件
│   │       ├── file_tab.py      # 文件管理
│   │       ├── task_tab.py      # 任务管理
│   │       ├── client_tab.py    # 客户端管理
│   │       ├── group_tab.py     # 分组管理
│   │       └── config_tab.py    # 配置管理
│   ├── main.py              # GUI 入口
│   └── requirements.txt
├── client-gui/              # 客户端 GUI ⭐新增
│   ├── client_gui.py        # 客户端 GUI 主程序
│   └── requirements.txt
├── scripts/
│   └── test_demo.py          # 测试演示脚本
├── utils/                    # 工具模块 ⭐新增
│   └── firewall_manager.py  # 防火墙管理工具 ⭐新增
├── start_server.bat          # 服务端启动（命令行）
├── start_client.bat          # 客户端启动（命令行）
├── start_server_gui.bat      # 服务端 GUI 启动 ⭐
├── start_client_gui.bat      # 客户端 GUI 启动 ⭐
├── build_package.py          # 客户端打包工具 ⭐
├── build_client_package.bat  # 客户端打包脚本 ⭐
├── batch_package_builder.py  # 批量打包工具 ⭐新增
├── batch_package_builder.bat # 批量打包脚本 ⭐新增
├── user_manager.py           # 用户管理工具 ⭐新增
├── user_manager.bat          # 用户管理脚本 ⭐新增
├── install_package_deps.bat  # 打包依赖安装脚本 ⭐
├── CLIENT_PACKAGE_GUIDE.md   # 打包功能使用指南 ⭐
├── PACKAGE_TROUBLESHOOTING.md # 打包故障排查指南 ⭐
├── REMOTE_UPDATE_GUIDE.md      # 远程更新使用指南 ⭐
├── REMOTE_UPDATE_SUMMARY.md    # 远程更新实现总结 ⭐
├── SERVER_API_UPDATES.md       # 服务器端API更新说明 ⭐
├── FEATURES_SUMMARY.md         # 功能总结 ⭐
├── NEW_FEATURES_GUIDE.md       # 新功能使用指南 ⭐新增
├── test_p2p.py                 # P2P功能测试脚本 ⭐
├── test_p2p.bat                # P2P测试批处理 ⭐
├── test_server_api.py          # 服务器API测试脚本 ⭐
├── test_server_api.bat         # API测试批处理 ⭐
├── run_test.bat              # 测试脚本
├── README.md                 # 完整文档
├── QUICKSTART.md             # 快速启动指南
└── GUI_README.md             # GUI 使用指南 ⭐新增

🚀 快速开始

环境要求

• Python 3.9+
• pip

启动方式

本系统提供两种使用方式：

方式一：GUI 图形界面（推荐）

服务端 GUI 管理平台：

# 双击运行或命令行执行
start_server_gui.bat

客户端 GUI：

# 双击运行或命令行执行
start_client_gui.bat

详细使用说明请查看：GUI_README.md

📦 客户端安装包生成 ⭐新功能

系统现在支持一键生成预配置的客户端安装包！

功能亮点

• ✅ 在服务端 GUI 中直接生成
• ✅ 自动嵌入客户端 ID 和 Token
• ✅ 开箱即用，用户无需配置
• ✅ 适合批量部署场景

使用步骤

1. 在服务端 GUI 中创建客户端

   服务端 GUI → 客户端管理 → 创建客户端
   

2. 生成安装包

   选择客户端 → 点击"📦 生成安装包" → 选择保存位置
   

3. 分发给用户

   将生成的 .zip 文件发送给用户
   用户解压后双击 .exe 即可运行
   

详细文档

完整的使用指南请参阅 CLIENT_PACKAGE_GUIDE.md

故障排查

如果打包或运行时遇到问题（如缺少模块错误），请参阅 PACKAGE_TROUBLESHOOTING.md

🌐 P2P 文件分发 ⭐新功能

客户端现在支持P2P（点对点）文件分发，大幅减少服务器带宽压力！

功能亮点

• ✅ 智能下载 - 优先从内网P2P节点下载，失败自动回退到服务器
• ✅ 自动共享 - 下载完成的文件自动共享给其他客户端
• ✅ 零配置 - 自动发现内网节点，无需手动配置
• ✅ 远程更新 - 支持客户端自动更新和配置同步

快速启用

编辑客户端配置文件 .env：

# 启用P2P功能
P2P_ENABLED=True
P2P_PORT=9000
P2P_PRIORITY=True

# 启用自动更新
AUTO_UPDATE_ENABLED=True
UPDATE_CHECK_INTERVAL=3600

使用场景

场景: 100台内网机器需要下载同一个1GB文件

传统方式: 服务器需要传输 100GB 数据

P2P方式:

• 第1台从服务器下载（1GB）
• 其他99台从第1台或其他已下载的机器获取
• 服务器仅传输 1GB，节省 99% 带宽！

详细文档

完整的使用指南请参阅 P2P_FEATURE_GUIDE.md

快速开始请参阅 P2P_QUICKSTART.md

🚀 远程更新管理 ⭐新功能

主控端现在支持一键远程更新，管理员可以通过GUI界面推送更新到所有客户端！

功能亮点

• ✅ 可视化管理 - 通过GUI界面管理更新包
• ✅ 一键推送 - 选择客户端，一键推送更新
• ✅ 批量更新 - 支持推送到所有在线客户端或指定客户端
• ✅ 自动应用 - 客户端自动下载并应用更新

快速使用

1. 添加更新包

   服务端GUI → 客户端管理 → 远程更新 → 添加更新包
   

2. 推送更新

   选择更新包 → 推送更新 → 选择目标客户端 → 立即推送
   

3. 客户端自动更新

   • 自动下载更新包
   • 自动校验完整性
   • 自动应用更新
   • 自动重启

详细文档

完整的使用指南请参阅 REMOTE_UPDATE_GUIDE.md

🎯 客户端后台运行 ⭐新功能

客户端现在支持完整的后台运行模式！

功能亮点

• ✅ 系统托盘 - 最小化到托盘，不占用任务栏
• ✅ 开机自启动 - 一键设置，系统启动时自动后台运行
• ✅ 任务完成通知 - 下载完成自动弹出提示
• ✅ 静默运行 - 关闭窗口不退出，后台持续工作

快速设置

1. 启动客户端 GUI
2. 配置服务器信息
3. 右键托盘图标 → 勾选"开机自启动"
4. 关闭窗口（自动最小化到托盘）
5. 完成！以后开机自动运行

后台启动

# 直接后台启动，不显示窗口
client_gui.exe --minimized

详细文档

完整的使用指南请参阅 BACKGROUND_MODE_GUIDE.md

🔧 新功能工具 ⭐v1.3.0

用户管理工具

命令行工具，用于管理系统用户和权限：

# 双击运行或命令行执行
user_manager.bat

功能：

• 列出所有用户
• 添加新用户（管理员/普通用户）
• 删除用户
• 修改密码
• 修改角色

批量打包工具

从数据库或配置文件批量生成客户端安装包：

# 双击运行或命令行执行
batch_package_builder.bat

功能：

• 从数据库批量生成（所有客户端或指定客户端）
• 从配置文件批量生成
• 自动生成预配置的安装包
• 适合大规模部署

防火墙自动检查

首次启动时自动检查并申请防火墙权限：

• ✅ 自动检测防火墙规则
• ✅ 智能提示管理员权限
• ✅ 支持服务端和客户端
• ✅ 支持 P2P 端口检查

使用方法： 以管理员身份运行启动脚本，系统会自动配置防火墙。

详细使用说明请查看：NEW_FEATURES_GUIDE.md

方式二：命令行模式

1. 启动服务端

# 进入服务端目录
cd server

# 创建虚拟环境（可选）
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 复制环境变量配置
copy .env.example .env  # Windows
# cp .env.example .env  # Linux/Mac

# 初始化数据库并启动服务
python run.py

服务端默认运行在 http://localhost:8000

2. 启动客户端

# 进入客户端目录
cd client

# 创建虚拟环境（可选）
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 复制环境变量配置并修改
copy .env.example .env  # Windows
# cp .env.example .env  # Linux/Mac

# 启动客户端
python run.py

📖 API 文档

启动服务端后访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🔑 默认账户

系统初始化时会创建默认管理员账户：

• 用户名: admin
• 密码: admin123

📡 WebSocket 协议

连接地址

ws://localhost:8000/ws/{client_id}?token={auth_token}

消息格式

任务下发消息（服务端 -> 客户端）:

{
    "type": "task",
    "task_id": "uuid",
    "file_id": "uuid",
    "filename": "example.zip",
    "file_size": 1048576,
    "chunk_size": 1048576,
    "sha256": "abc123..."
}

状态上报消息（客户端 -> 服务端）:

{
    "type": "status",
    "task_id": "uuid",
    "status": "downloading|completed|failed",
    "progress": 50,
    "message": "下载中..."
}

🗄️ 数据库表结构

users（用户表）

字段	类型	说明
id	UUID	主键
username	VARCHAR(50)	用户名
password_hash	VARCHAR(255)	密码哈希
role	ENUM	admin/user
created_at	DATETIME	创建时间

clients（客户端表）

字段	类型	说明
id	UUID	主键/客户端ID
name	VARCHAR(100)	客户端名称
group_id	UUID	所属分组
token	VARCHAR(255)	认证令牌
is_online	BOOLEAN	在线状态
last_seen	DATETIME	最后在线时间

groups（分组表）

字段	类型	说明
id	UUID	主键
name	VARCHAR(100)	分组名称
description	TEXT	描述

files（文件表）

字段	类型	说明
id	UUID	主键
filename	VARCHAR(255)	文件名
file_path	VARCHAR(500)	存储路径
file_size	BIGINT	文件大小
sha256	VARCHAR(64)	文件哈希
uploaded_by	UUID	上传用户ID
created_at	DATETIME	上传时间

tasks（任务表）

字段	类型	说明
id	UUID	主键
file_id	UUID	文件ID
client_id	UUID	目标客户端ID
status	ENUM	pending/downloading/completed/failed
progress	INT	下载进度(0-100)
retry_count	INT	重试次数
created_at	DATETIME	创建时间
completed_at	DATETIME	完成时间

logs（日志表）

字段	类型	说明
id	UUID	主键
level	ENUM	info/warning/error
source	VARCHAR(50)	日志来源
message	TEXT	日志内容
created_at	DATETIME	记录时间

🔧 配置说明

服务端配置 (server/.env)

# 服务配置
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
DEBUG=true

# 数据库配置
DATABASE_URL=sqlite:///./data.db

# JWT 配置
JWT_SECRET=your-secret-key-change-in-production
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=24

# 文件配置
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=1073741824
CHUNK_SIZE=1048576

客户端配置 (client/.env)

# 服务端地址
SERVER_URL=http://localhost:8000
WS_URL=ws://localhost:8000

# 客户端配置
CLIENT_ID=your-client-uuid
CLIENT_TOKEN=your-client-token

# 下载配置
DOWNLOAD_DIR=./downloads
MAX_RETRIES=3
RETRY_DELAY=5

📝 使用示例

1. 上传文件

curl -X POST "http://localhost:8000/api/files/upload" \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/file.zip"

2. 创建分发任务

curl -X POST "http://localhost:8000/api/tasks" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file-uuid",
    "client_ids": ["client-uuid-1", "client-uuid-2"]
  }'

3. 按分组分发

curl -X POST "http://localhost:8000/api/tasks/by-group" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file-uuid",
    "group_id": "group-uuid"
  }'

📄 License

MIT License