NextWeb4/lan-file-transfer

# 局域网文件传输 一个 Windows 桌面文件共享服务器，包含 Tkinter 启动器、FastAPI 后端、浏览器客户端、角色/组权限以及可审计的本地数据模型。      ## 概述 Tkinter 窗口会启动一个本地的 uvicorn 服务，显示用户/管理员 URL 和二维码，并允许您选择保存目录。然后，在同一受信任的 Wi-Fi 或 LAN 下的手机、平板电脑和计算机可以通过原生的 HTML/CSS/JavaScript 页面上传、浏览、下载和打包文件。 默认情况下，该服务监听 `0.0.0.0`。这使得局域网访问成为可能，但同时也将服务暴露给每个可访问的网络。请仅在受信任的网络上运行它。 ## 功能 - 流式传输上传的字节，无需转码、重新压缩、图像/视频重写、EXIF 更改或扩展名更改。 - 存储文件大小和 SHA-256；尝试保留浏览器提供的 `File.lastModified` 值。 - 支持原始下载、单文件 ZIP、选中/批量 ZIP、搜索以及服务器端排序。 - 使用访客、用户和管理员角色。访客只能看到 `public` 组中的文件。 - 登录用户可以上传和删除自己的文件；管理员可以管理所有文件、用户、组、可见性和审计历史。 - 为新的保存目录创建内置的 `public` 和 `everyone` 组。 - 创建一个初始管理员账户：`admin / 12345678`。 - 从审计元数据中递归脱敏 password、token、session、authorization、cookie 和 secret 字段。 - 提供中文/英文浏览器界面，偏好设置保存在 `localStorage` 中。 - 使用 Tkinter 桌面生命周期控制器，而不是后台系统服务。 **首次启动后请立即更改默认的管理员密码。** 默认密码仅用于初始化新的本地保存目录。 ## 安装与运行 ### 使用 Windows 发布版本 [GitHub Release v1.0.0](https://github.com/NextWeb4/lan-file-transfer/releases/tag/v1.0.0) 提供了三个资源： - `LANFileTransfer.exe`：单文件 Windows 应用程序； - `lan-file-transfer-v1.0.0-windows.zip`：包含可执行文件的便携式压缩包； - `SHA256SUMS.txt`：已发布文件的 SHA-256 值。 对照 `SHA256SUMS.txt` 验证 EXE 或 ZIP，然后运行 `LANFileTransfer.exe`。不会创建任何安装程序或后台服务。该可执行文件未经过数字签名，因此 Windows 可能会显示未知发布者的警告。 ### 从源码运行 ``` py -m venv .venv .\.venv\Scripts\python.exe -m pip install --upgrade pip .\.venv\Scripts\python.exe -m pip install -r requirements.txt .\.venv\Scripts\python.exe -m lan_transfer.desktop ``` 桌面应用程序会显示两个地址： - **用户 URL**：供访客和普通用户使用。 - **管理 URL**：供管理员登录和管理使用。 请等待桌面状态显示为 `Running`，然后从同一局域网内的设备打开 URL 或扫描其二维码。 ## 典型工作流程 1. 启动桌面应用程序并选择一个保存目录。 2. 打开管理 URL，并在新目录上使用初始账户登录。 3. 在共享用户 URL 之前更改管理员密码。 4. 创建个人用户，或通过一次验证批处理创建最多 200 个普通用户；创建组并分配成员资格。 5. 上传文件或文件夹，并选择它们的可见性组。 6. 从其他局域网设备使用搜索/排序以及原始或 ZIP 下载。 7. 查看关于登录、登出、上传、下载、删除、权限、账户和组更改的审计事件。 移动浏览器并不总是将 HTTP `Last-Modified` 值应用于磁盘上的下载文件。当保留归档条目的 mtime 很重要时，请使用 ZIP 下载。 ## 权限模型 - 访客只能列出/下载 `public` 文件，不能上传或删除。 - 普通用户可以查看分配给其组的文件、上传文件，并且只能删除自己上传的文件。 - 管理员可以管理账户/组、设置文件的 `allowed_groups`、检查审计记录以及删除所有文件。 - 内置的 `public` 和 `everyone` 组以及内置的 `admin` 账户无法被删除。 - 删除用户会将该用户现有的文件转移给 `admin`，这样未来的同名账户就无法继承删除权限。 - 如果有用户或文件引用了某个组，则该组无法被删除。 用户和管理员的端点是刻意分开的。同源的管理员 cookie 绝不能扩大用户页面可以列出或下载的范围。 ## 存储与完整性 选定的保存目录包含上传的文件和本地控制数据： ``` manifest.json .lan-transfer-auth.json .lan-transfer-audit.jsonl ``` 这些控制名称、它们的临时变体以及不安全的绝对/父路径都会被路径验证保留。上传使用分块的 `.part` 文件、大小验证、SHA-256、不冲突的命名、mtime 应用以及原子发布。清单和身份验证更新使用隐藏的随机临时文件和原子替换。 经过严格审计的操作是事务性的： - 在其审计条目和清单发布都成功之前，挂起的上传是不可见的； - 审计失败将回滚登录/登出、密码、账户、组、上传、删除和权限更改； - 删除操作使用可恢复的逻辑删除标记（tombstone），直到清单和审计工作可以提交； - 在进行列出、下载、ZIP、删除或回滚使用之前，不安全或过时的清单路径会被重新验证。 ## 测试与验证 ``` .\.venv\Scripts\python.exe -m pytest node --check .\lan_transfer\static\user.js node --check .\lan_transfer\static\admin.js ``` 测试涵盖了身份验证、锁定、账户/组权限、批量创建、可见性、搜索/排序、字节完整性、mtime、响应标头、ZIP 行为、路径、重复名称、事务回滚、审计脱敏、桌面生命周期、日志记录、发布元数据和前端契约。 没有声明专门的 lint 或格式化命令。这两个 `node --check` 命令是 JavaScript 语法检查。 ## 打包 Windows 发布版本 ``` powershell -ExecutionPolicy Bypass -File .\scripts\build_exe.ps1 ``` 该脚本会安装依赖项、运行测试，并使用 PyInstaller 构建一个带窗口的单文件可执行程序。 ``` dist\LANFileTransfer.exe release-assets\LANFileTransfer.exe release-assets\lan-file-transfer-v1.0.0-windows.zip release-assets\SHA256SUMS.txt ``` 因为没有 WiX、Inno Setup 或 NSIS 定义，所以不会生成 MSI。发布的二进制文件未经过数字签名；Windows 可能会显示未知发布者的警告。请从项目的 Release 页面下载并验证 `SHA256SUMS.txt`。 ## 项目结构 | 路径 | 职责 | | --- | --- | | `lan_transfer/desktop.py` | Tkinter 窗口、二维码、保存目录选择和服务生命周期 | | `lan_transfer/server.py` | uvicorn 线程启动、健康检查、超时和关闭 | | `lan_transfer/api.py` | FastAPI 路由、角色/会话边界、可见性、排序、下载和错误映射 | | `lan_transfer/auth.py` | 账户、组、PBKDF2 密码哈希、会话、IP 锁定和身份验证持久化 | | `lan_transfer/storage.py` | 流式文件、清单、哈希/mtime、ZIP、所有权、可见性、事务和逻辑删除标记 | | `lan_transfer/security.py` | 上传和存储清单的路径规范化/包含检查 | | `lan_transfer/audit.py` | 经过脱敏的 JSONL 审计跟踪 | | `lan_transfer/config.py` | 保存目录、可用端口、LAN 地址和 URL | | `lan_transfer/static/` | 原生用户/管理员浏览器应用程序 | | `tests/` | 后端、桌面、发布和前端契约的回归测试套件 | ## 安全说明 - 密码在本地使用 PBKDF2 进行哈希处理；会话值和密码绝不能在 JSON、验证错误、日志或审计元数据中返回。 - 来自同一 IP 的五次登录失败将触发长达三小时的锁定。 - 该服务在局域网上使用的是 HTTP，而不是 HTTPS。网络上的对等方可能能够观察流量；请仅在受信任的网络上使用。 - 访客可见的 `public` 文件名和文件是故意设计为无需登录即可访问的。 - 原始下载标头包含完整性/缓存/mtime 元数据，但最终文件系统时间戳由浏览器控制。 - 请勿通过端口转发、公共 Wi-Fi、公共防火墙规则或不受信任的 VPN 暴露监听器。 ## 作者 - HaoXiang Huang - [Rays688888@Gmail.com](mailto:Rays688888@Gmail.com) - - ## 许可证 [MIT](LICENSE) © 2026 HaoXiang Huang.

标签：AV绕过, FastAPI, Python, 局域网, 文件传输, 无后门, 权限管理, 桌面应用, 模型越狱, 漏洞挖掘, 逆向工具