# QN-FTP **Repository Path**: YuYao-Gith/QN-FTP ## Basic Information - **Project Name**: QN-FTP - **Description**: 一个支持了大量功能的FTP工具 - **Primary Language**: Java - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-20 - **Last Updated**: 2026-08-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # QN FTP > [简体中文](README.md) · [繁體中文](README.zh_TW.md) · [English](README.en.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Español](README.es.md) · [Русский](README.ru.md) --- QN-FTP 是一个用 Java/JavaFX 编写的 FTP/FTPS/SFTP/WebDAV 服务器与客户端一体化平台,面向需要自建文件传输服务但不想拼凑多个工具的场景。 **核心卖点** - 一套代码同时提供服务器与客户端,支持 FTP/FTPS/SFTP/WebDAV 四种协议 - 多租户隔离、集群部署、S3 后端存储,开箱即用 - Prometheus 指标、审计日志、TOTP 双因素认证,满足合规要求 - 三种交互方式:桌面 GUI、Web 浏览器、命令行终端 ## 快速上手 环境要求:JDK 21 及以上,支持 Linux / macOS / Windows。 ```bash # 1. 下载依赖(JavaFX + Apache MINA SSHD) scripts/download_deps.sh # 2. 构建 ./build.sh # 3. 启动服务器(GUI 模式) ./run-server.sh # 或启动 Web 管理界面(无头模式) ./run-server.sh --web ``` 启动后默认监听 `0.0.0.0:21`,Web 管理界面默认端口 `8080`。首次使用可在 GUI 中添加用户,或直接编辑 `ftp-data/users.properties`。 ## 功能概览 ### 文件传输能力 支持 FTP(主动/被动模式)、FTPS(显式 AUTH TLS 与隐式 TLS)、SFTP(基于 Apache MINA SSHD)、WebDAV(含 LOCK/UNLOCK/COPY/MOVE)四种协议。内置断点续传、并行分片上传、传输限速、MODE Z 压缩,覆盖从基础文件共享到高性能传输的全部场景。 ### 安全与合规 TLS 证书管理、IP 黑白名单(CIDR)、暴力破解自动封禁、TOTP 双因素认证、AES-256-GCM 文件加密(RSA 密钥信封 + PBKDF2 密码模式)。审计日志以 TSV 格式自动轮转,记录每一次登录、文件操作与配置变更。 ### 企业级管理 多租户完全隔离(独立存储、配额、ACL、租户管理员),目录级 ACL(最深前缀匹配、deny 优先),用户/用户组配额(磁盘字节 + 文件数),回收站与版本历史,文件标签与操作撤销。支持虚拟主机(HOST 命令)与符号链接。 ### 运维与监控 多实例集群(共享存储、节点注册与心跳),Prometheus 指标端点(`/metrics`),健康检查接口,日志缓冲区实时流式查看。配置热加载,无需重启即可生效大多数变更。 ### 客户端生态 桌面 GUI(JavaFX 25,现代化深色主题)、Web 浏览器客户端(REST API 驱动)、CLI 终端(13 个子命令,支持增量同步、加密/解密、分享链接)。三种方式共享同一套后端,可自由切换。 ### 扩展与集成 S3 兼容对象存储后端(AWS SigV4 签名,支持 MinIO/Ceph),SMTP 邮件通知(零依赖手写实现),Webhook 事件推送,OpenAPI 3.0 文档自动生成(运行时 `/api/openapi.json`,Swagger UI `/api/docs`)。 ## 快速对比 | 特性 | QN-FTP | vsftpd | ProFTPD | FileZilla Server | |------|--------|--------|---------|------------------| | FTPS | 是 | 是 | 是 | 是 | | SFTP | 是 | 否 | 是(需模块) | 否 | | WebDAV | 是 | 否 | 否 | 否 | | Web 管理界面 | 是 | 否 | 否 | 否 | | 多租户 | 是 | 否 | 否 | 否 | | 集群 | 是 | 否 | 否 | 否 | | GUI 客户端 | 是 | 否 | 否 | 是 | | Prometheus | 是 | 否 | 否 | 否 | ## 构建与运行 环境要求:JDK 21+,构建工具可选 javac / Maven / jpackage。 ```bash # 方式一:直接编译(无需 Maven) ./build.sh # 方式二:Maven 构建(生成三个 fat jar) scripts/maven.sh # 方式三:jpackage 原生打包(生成 deb/rpm/msi/exe/dmg/app-image) scripts/package.sh app-image server ``` ```bash # 桌面 GUI 模式 ./run-server.sh # 服务器 ./run-client.sh # 客户端 # Web 模式(无头,浏览器访问) ./run-server.sh --web # 服务器管理界面 ./run-client.sh --web # 客户端 Web 界面 # CLI 模式 ./run-cli.sh --help scripts/install-cli.sh ``` ## 测试 ```bash ./scripts/smoke.sh # 核心 FTP 功能 ./scripts/cli_smoke.sh # CLI 子命令 ./scripts/web_smoke.sh # Web 模式端到端 ./scripts/storage_smoke.sh # 去重/版本/回收站/ACL/TOTP ./scripts/advanced_smoke.sh # 限速/IP 过滤/配额/FTPS/SFTP ./scripts/newfeatures_smoke.sh # 分享/加密/标签/撤销 ``` ## 项目结构 ``` QN-FTP/ ├── src/com/qn/ftp/ # 源码根目录 │ ├── ServerMain.java # 服务器入口 │ ├── ClientMain.java # 客户端入口 │ ├── server/ # 服务器核心 │ ├── client/ # FTP 客户端库 │ ├── web/ # Web 模式 │ ├── cli/ # CLI 终端与子命令 │ └── ui/ # JavaFX GUI 组件 ├── test/ # 冒烟测试 ├── scripts/ # 构建/打包/测试脚本 ├── lib/ # 依赖库(JavaFX, Apache MINA SSHD) ├── ftp-data/ # 运行时数据 ├── pom.xml # Maven 构建定义 ├── build.sh / build.bat # 直接编译脚本 ├── run-server.sh / .bat # 服务器启动脚本 ├── run-client.sh / .bat # 客户端启动脚本 ├── run-cli.sh # CLI 启动脚本 └── LICENSE # MuLanPSL-2.0 许可证全文 ``` ## 作者 - **作者**：YuYao-Gith - **邮箱**：asdf2502@126.com - **GitHub**： - [github.com/YuYao-Gith](https://github.com/YuYao-Gith) - [github.com/QiNian-Gith](https://github.com/QiNian-Gith) - **Gitee**：[gitee.com/YuYao-Gith](https://gitee.com/YuYao-Gith) ## 许可证 本项目采用 [木兰宽松许可证第2版 (MuLanPSL-2.0)](LICENSE) 发布。 木兰宽松许可证第2版为宽松许可,可自由使用、修改与分发,允许闭源商用;分发时需保留版权声明与许可证副本。 ## 新增扩展功能 ### 古董扩展(XSEN / XSEM / XMAS) 基于 RFC 775 子集实现的历史协议扩展: - **XSEN**(Send to terminal):将文件内容通过数据通道发送到终端 - **XSEM**(Send except if terminal):发送到终端,若不可行则发送到邮件 - **XMAS**(Mail Send):通过邮件发送文件(需配置 SMTP,否则回退终端显示) ### LANG 命令(协议层国际化) RFC 2640 兼容,支持 9 种语言: `en`, `zh-CN`, `zh-TW`, `ja`, `ko`, `de`, `fr`, `es`, `ru` 客户端通过 `LANG ` 切换服务器响应语言。 ### HOST 命令(虚拟主机) RFC 7151 兼容,支持 FTP 虚拟主机: - 客户端在 USER 之前发送 `HOST ` 选择虚拟主机 - 每个虚拟主机拥有独立的根目录(`ftp-data/vhost//`) - 支持多域名共用同一 IP ### 符号链接/快捷方式 - LIST/NLST 中显示符号链接(`name -> target`) - `SITE SYMLINK ` 创建符号链接 - 自动解析符号链接(有限递归防循环) ### 磁盘配额组 - 按组分配合额,同组用户共享磁盘/文件数额度 - 个人配额 + 组配额双重校验,取更严格者 - 配置文件:`ftp-data/quota-groups.properties` ### FTP 协议层文件锁定 - **排他锁**(Exclusive):仅一个客户端可持有 - **共享锁**(Shared):多个客户端可同时持有 - `LOCK [timeout]` 锁定文件 - `UNLOCK ` 解锁文件 - 锁超时自动释放,会话断开自动释放,持久化到 `ftp-data/filelocks.properties` ### GridFTP 扩展(ERET / ESTO) RFC 3659 扩展,高效数据传输: - **ERET**(Efficient Retrieve):`ERET ` 部分检索 - **ESTO**(Efficient Store):`ESTO ` 高效存储(追加/填充/覆盖) ### 并行分片上传 与续传(REST/APPE)不同,支持多连接同时传不同分片: 1. `UPLOAD ` — 初始化任务 2. `CHUNK ` — 通过数据连接上传分片 3. `COMMIT ` — 提交合并 - 支持 1-64 并发分片,适合大文件高带宽场景 ### 多租户完全隔离 比基础多租户更强的隔离级别: - 完全独立的存储根目录 - 独立的配额组/权限体系/租户管理员 - 租户级速率限制/功能开关 - 配置文件:`ftp-data/tenants/tenants.properties` ### Prometheus 指标(/metrics) 暴露 Prometheus 监控指标: - FTP 会话指标(活跃会话、登录/登出计数) - 传输指标(上传/下载字节数、文件数) - 系统指标(运行时间、内存、线程) - 配额指标(用户用量) - 访问路径:`http://host:port/metrics` ### Web 管理端 API 文档 - **OpenAPI 3.0 JSON**:`/api/openapi.json` - **Swagger UI**:`/api/docs`(浏览器可视化浏览) - 覆盖全部管理 API 端点 ### 多实例集群 支持多节点共享存储 + 统一管理: - 节点注册与发现(基于共享存储) - 心跳检测与故障转移 - 集群状态查询 API:`/api/cluster` - 配置文件:`ftp-data/cluster/cluster.properties` ## 功能 **服务器端(独立程序,入口 `ServerMain`)** - 用户登录认证(账号存于 `ftp-data/users.properties`,首次运行自动创建默认账号 `admin / admin123`) - 多会话并发,每个连接独立线程;支持被动(PASV/EPSV)与主动(PORT)两种数据连接 - 目录浏览、上传(STOR)、下载(RETR)、**断点续传(REST/APPE)**、删除(DELE)、重命名(RNFR/RNTO) - **FTPS 显式 TLS(AUTH TLS / PBSZ / PROT)**:控制通道与数据通道均可加密 - **FTPS 隐式 TLS(=990 风格)**:连接即开始 TLS 握手 - **SFTP(SSH 文件传输,Apache MINA SSHD)**:配置 `sftp.port` 后随 FTP 一并启动 - **传输限速**:分别限制上传/下载带宽(KB/s,0=不限),令牌桶算法,即时生效 - **IP 黑白名单**:支持 off/black/white 模式,条目支持 CIDR - **用户配额**:按账号设置磁盘上限与文件数上限,超限自动拒绝 - **传输历史 / 审计日志**:全事件记录,自动轮转 - **SSL 证书管理**:一键生成自签名证书,导入 CA 签发证书 - **文件内容去重(SHA-256)**:重复内容硬链接共享 - **文件版本历史**:覆盖上传自动归档旧版本 - **回收站 / 软删除**:误删可找回 - **目录级权限 ACL**:按路径前缀配置 rw/ro/deny - **匿名用户只读**:anon/anonymous 账号 - **连续失败封禁**:IP 封禁保护 - **MODE Z 压缩传输**:数据通道 zlib 压缩 - **TOTP 双因素认证**:RFC 6238 - **AES-256-GCM 加密存储**:.qfenc 格式 - **root 超级账户**:查看密码/解密私钥包封文件 - **在线文件预览**:文本/图片/PDF - **文件标签/分类**:多标签筛选 - **ZIP 在线浏览与解压** - **搜索高级筛选**:类型/大小/日期/标签组合 - **Web 批量操作**:批量删除/复制/移动 - **操作撤销(Undo)**:误操作恢复 - **配置一键导出/导入** - **邮件通知(可选)**:SMTP 客户端 - **FXP 服务器到服务器直传(可选)** - **S3 兼容对象存储后端(可选)** - **Web 端 HTTPS(可选)** - **高可用性支持(可选)**:健康探针 **客户端(独立程序,入口 `ClientMain`)** - 连接任意支持被动/主动模式的 FTP 服务器 - 远程目录浏览、**断点续传开关** - **目录递归上传/下载** - **多任务并发**:最多 4 个传输任务并行 - **FTPS 连接**:显式/隐式 TLS - 实时进度条 + 状态着色 ## 环境要求 - JDK 21+(开发环境为 OpenJDK 25) - Maven 3.9+(`scripts/maven.sh` 会自动下载 Maven 到 `lib/`) - JavaFX 依赖由脚本自动下载 ## 三种构建/运行方式 ### 1. 直接脚本(最快,无需 Maven) ```bash ./scripts/download_deps.sh # 一次性下载 JavaFX(放 lib/) ./build.sh # javac 编译到 out/ ./run-server.sh # 启动服务器端 ./run-client.sh # 启动客户端 ``` ### 2. Maven 构建可执行 fat jar(推荐分发) ```bash ./scripts/maven.sh # 自动下载 Maven → 生成两个 fat jar java -jar target/qnftp-server.jar # 服务器端 java -jar target/qnftp-client.jar # 客户端 ``` ### 3. jpackage 打包原生应用 ```bash ./scripts/package.sh app-image server # 打包服务器端 ./scripts/package.sh app-image client # 打包客户端 ``` ## Web 模式(无界面,浏览器操作) ```bash ./run-server.sh --web # 服务器 Web 管理:http://localhost:8080/ ./run-client.sh --web # 客户端 Web 版:http://localhost:8081/ ``` Web 管理端功能: - 启停 FTP、端口/根目录配置、用户增删(含配额) - 登录鉴权(会话 Cookie 滑动续期) - 在线预览(文本/图片/PDF) - 加密存储(AES-256-GCM) - 批量与撤销 - 标签管理 - ZIP 在线浏览与解压 - 搜索筛选 - 配置导出/导入 - FTPS 与证书管理 - 高级设置(限速/黑白名单/WebDAV) - 文件搜索 - 共享链接(临时访问) - 审计日志 - **API 文档**(/api/docs) - **Prometheus 指标**(/metrics) - **集群状态**(/api/cluster) - **文件锁状态**(/api/filelocks) - **配额组**(/api/quota-groups) - **多租户**(/api/tenants) ## 命令行客户端 (CLI) ```bash qnftp <子命令> [选项] [参数] # 单命令模式 qnftp # 交互式 shell qnftp --script commands.qnftp # 脚本模式 ``` 子命令:`config` / `decrypt` / `encrypt` / `get` / `ls` / `mkdir` / `mv` / `put` / `rm` / `share` / `sync` / `undo` / `version` ## 冒烟测试 ```bash ./scripts/smoke.sh # 基础协议冒烟 ./scripts/web_smoke.sh # Web 模式端到端 ./scripts/advanced_smoke.sh # 进阶特性端到端 ./scripts/storage_smoke.sh # 存储与安全特性 ./scripts/newfeatures_smoke.sh # 新功能端到端 ``` ## 协议说明 实现的 FTP 命令: ``` USER PASS QUIT SYST FEAT OPTS TYPE PWD PASV EPSV PORT REST APPE LIST NLST CWD CDUP MKD RMD DELE RNFR RNTO SIZE MDTM STOR RETR NOOP MODE TOTP ``` 扩展命令: ``` HOST LANG XSEN XSEM XMAS ERET ESTO LOCK UNLOCK UPLOAD CHUNK COMMIT AUTH TLS PBSZ PROT ``` - 数据连接:被动模式(PASV/EPSV)与主动模式(PORT)均支持 - 断点续传:APPE 追加 / REST+STOR 偏移写 / REST 偏移读 - 压缩传输:MODE Z zlib 流式压缩 - 控制连接与文件名编码均为 UTF-8 - SFTP:基于 Apache MINA SSHD 2.15.0 - WebDAV:完整 LOCK/UNLOCK 与 PROPPATCH ## 目录结构 ``` QN-FTP/ ├── src/com/qn/ftp/ │ ├── ServerMain.java # 服务器端入口 │ ├── ClientMain.java # 客户端入口 │ ├── server/ # FtpServer / SessionHandler / UserStore / CertManager │ │ # + ServerSettings / RateLimiter / IpFilter / QuotaManager │ │ # + AuditLog / StorageManager / FailureBan / AclManager │ │ # + Totp / Mailer / FileLockManager / QuotaGroupManager │ │ # + ParallelUpload / TenantIsolation / ClusterManager │ │ # + MetricsProvider / OpenApiDocs / FtpExtensions │ ├── client/ # FtpClient / RemoteFile / ProgressListener │ ├── ui/ # ServerPane / ClientPane / Transfer / Theme │ ├── cli/ # 命令行客户端 │ └── web/ # ServerWebApp / ClientWebApp / DavHandler / WebPages ├── scripts/ # 构建/测试/打包脚本 ├── lib/ # JavaFX / SSHD 依赖 ├── test/ # 冒烟测试 └── ftp-data/ ftproot/ # 运行时数据目录 ``` ## 其他语言版本 - [English](README.en.md) - [日本語](README.ja.md)