copyparty 1.20.26 介绍与选型指南
copyparty 1.20.26 项目全景：Python 单文件六协议文件服务器（HTTP/WebDAV/FTP/SFTP/TFTP/SMB），断点续传+去重+缩略图+音频转码+事件钩子，并与 Gokapi/PsiTransfer/FileBrowser/miniserve/Dufs 五款同类工具做特性矩阵与选型对比（数据检索日期 2026-10-26）。
copyparty 1.20.26 介绍与选型指南
copyparty 是一个用 Python 编写的便携式文件服务器，官方 GitHub 仓库（9001/copyparty）截至 2026-10-26（本文所有版本号、星数等数据的检索日期）已收获 47k Star，采用 MIT 许可证发布，在 PyPI 上的最新稳定版本为 1.20.26（发布于 2026-10-14）。它的核心卖点是"单文件即可运行完整的文件服务"：一个 py 脚本同时提供 HTTP、WebDAV、FTP、SFTP、TFTP、SMB 六种协议，并内置断点续传上传、文件去重、缩略图、音频转码、事件钩子与多用户权限控制，官方给出的性能参考值为下载 8 GiB/s、上传 1 GiB/s。本文基于官方公开资料对 copyparty 1.20.26 进行介绍，并与 Gokapi、PsiTransfer、FileBrowser、miniserve、Dufs 五个同类工具做量化对比，为技术选型提供参考。
一、项目定位与基本信息
1.1 项目是什么
copyparty 由开发者 9001 维护，README 的一句话自述是"a portable file server with resumable uploads, deduplication, videos, images, audio, m3u8 streaming, zip downloads, search, file filters, oidc, well-implemented directory lister, and lots of other features"。从定位上看，它属于"全家桶式"自托管文件服务器：既覆盖了文件浏览器、上传下载这类基础能力，又把媒体播放、转码、索引搜索这些通常需要额外组件的高级功能收进了一个 Python 单文件里。
项目托管在 GitHub（https://github.com/9001/copyparty），官网文档站为 https://copyparty.eu ，官方提供 CLI 参数速查页（https://copyparty.eu/cli/）。截至 2026-10-26，GitHub Star 数为 47k，是同类自托管文件服务器中关注度最高的项目之一。
1.2 版本与运行环境
在 PyPI 上查询到的关键信息如下（检索日期 2026-10-26）：
- 最新稳定版本：1.20.26，发布时间 2026-10-14；
- 运行环境：Python 3，官方兼容较老的 Python 版本（sfx 单文件版依赖 Python 标准库即可启动，媒体功能按需引入可选依赖）；
- 许可证：MIT，商用与二次分发均无障碍；
- 安装形态：官方提供三种形态——
copyparty-sfx.py单文件自解压脚本（内嵌 tar.gz，无需 pip 装依赖）、zipapp 形态（性能略差于 sfx）以及标准 pip 包pip install copyparty。
一个值得注意的细节：sfx 是一个自解压器，运行时会把内嵌的依赖包解压到临时目录（$TEMP）再执行，官方在 README 中明确说明了这一点，供安全审计时参考。
二、核心特性全景
2.1 多协议：一个进程六种协议
copyparty 1.20.26 在服务端协议上的支持情况（README 溯源）：
- HTTP(S)：主入口，自带完整的网页文件浏览器；
- WebDAV：读写双向支持，README 提供了 Windows GUI 挂载指引；
- FTP / FTPS：
--ftp 3921一键开启，被动端口可配； - SFTP：SSH 文件传输协议，官方数据约 700 MiB/s（略慢于 WebDAV 与 FTP）；
- TFTP：
--tftp 3969，支持读写，适合网络设备固件分发等场景； - SMB/CIFS：内置 SMB 服务端，可被 Windows/macOS/Linux 文件管理器直接挂载。
所有启用的服务（WebDAV、FTP、SMB）都会通过 mDNS（--zm）在局域网内自动宣告，KDE、GNOME、macOS 的文件管理器可直接发现设备。
2.2 上传与传输能力
上传侧是 copyparty 的传统强项，README 列出的关键机制包括：
- 断点续传：浏览器上传器支持多线程分块续传，断网或刷新页面后可从断点继续；
- 客户端哈希：浏览器在上传前计算哈希，配合服务端实现秒传与去重（
--dupes卷标志开启符号链接级去重）； - 文件索引（
-e2d）：开启后提供音乐搜索、上传撤销（upload-undo）等能力； - zip 打包下载与目录打包，搜索与文件过滤器。
2.3 媒体处理
- 图片/视频缩略图：依赖 Pillow（图片）与 ffmpeg（视频）；
- 音频转码与流媒体：内置在线播放器支持转码为 opus/mp3 等格式（
--q-opus、--q-mp3可配置码率），支持 m3u8 流式播放； - 音频频谱图：对音频文件生成波形/频谱预览图；
- 音乐库能力：基于索引的音乐搜索，可按 ID3 标签（演唱者、专辑、年份等）过滤，官方另提供专门的音乐搜索前端（copyparty-music-search）。
2.4 权限、账户与安全
- 多账户与卷级 ACL：每个账户按权限字母（读 r、写 w、移动 m、删除 d、管理 a 等）映射到具体目录；
- 匿名与访客权限可按卷单独设定，支持通配符账户（
*表示所有人）； - OIDC 单点登录：README 明确列出 oidc 支持；
- 安全防护：密码错误封禁（
--ban-pw）、HTTP Basic 认证、URL 密码（?pw=）等登录方式； - 反向代理场景有专门配置文档（含性能调优章节）。
2.5 事件钩子与扩展
copyparty 提供基于文件事件的脚本钩子（upload before/after、move、delete 等），可以把"上传完成后触发病毒扫描、转码、通知"这类自动化流程写进服务配置；官方文档收录了病毒扫描（ClamAV）、照片去重、IPTV 直播流等真实 hook 案例。
三、同类工具横向对比
3.1 选型背景
可自托管的开源文件服务器众多，本次选取定位相近、关注度较高的五个项目做对比（星数与版本均来自 shields.io / GitHub 官方仓库，检索日期 2026-10-26）：Gokapi 2.2.4（2.9k Star）、PsiTransfer 2.4（2k Star）、FileBrowser 2.63.23（36k Star）、miniserve 0.35.0（7.9k Star）、Dufs 0.47.0（11k Star）。
3.2 特性矩阵
| 维度 | copyparty 1.20.26 | Gokapi 2.2.4 | PsiTransfer 2.4 | FileBrowser 2.63.23 | miniserve 0.35.0 | Dufs 0.47.0 |
|---|---|---|---|---|---|---|
| 实现语言 | Python（单文件） | Go（单二进制） | Node.js | Go（单二进制） | Rust（单二进制） | Rust（单二进制） |
| 协议数 | HTTP+WebDAV+FTP+SFTP+TFTP+SMB | HTTP | HTTP | HTTP | HTTP | HTTP+WebDAV |
| 上传形态 | 浏览器分块续传+秒传+去重 | 一次性分享链接为主 | 匿名分块上传+分享链接 | 网页管理器上传 | 可选开启上传 | 网页上传/API 上传 |
| 媒体处理 | 缩略图+音频转码+频谱图+音乐搜索 | 可选图片缩略图 | 文件预览 | 图片缩略图/预览 | 无 | 无 |
| 权限模型 | 多账户+卷级 ACL+OIDC | 账户+链接级限制 | 匿名为主+口令保护 | 多用户+共享 | Basic Auth | Basic Auth |
| 事件钩子 | 内置（--xa* 系列） | 无 | 无 | 无 | 无 | 无 |
| 数据过期/分享 | 支持链接有效期 | 支持（过期/次数限制） | 支持（过期/口令） | 分享链接 | 不支持 | 不支持 |
| 部署形态 | py 单文件/pip/Docker | 单二进制+Docker | Node.js 应用+Docker | 单二进制+Docker | cargo/单二进制 | cargo/单二进制 |
| GitHub Star（2026-10-26） | 47k | 2.9k | 2k | 36k | 7.9k | 11k |
3.3 各项目定位分析
copyparty：唯一在协议层做"全家桶"的项目，也是唯一内置音频转码、频谱图、音乐库与事件钩子的项目。适合把一台服务器直接变成"NAS 网页版"：多人多目录、权限分离、在线听歌看图、curl/脚本批量上传都能在一个进程里闭环。代价是 Python 运行时与可选依赖（Pillow/ffmpeg）需要维护，且参数体系非常庞大（CLI 参数数百个，官方做了 cli 速查站）。
Gokapi：定位是"一次性文件分享"（类似 Firefox Send 的自托管替代），核心能力是带过期时间和下载次数限制的分享链接，README 还提到支持 AWS S3 / Backblaze B2 后端与 Cloudflare 隧道。它不适合做常驻文件管理，但适合"把一个大文件安全地发出去"。
PsiTransfer：Node.js 实现的匿名文件传输工具，主打"不注册、直接传"，支持分块大文件上传、口令保护与过期时间，适合临时收发大文件的公开入口。权限模型简单是它的设计取舍而非缺陷。
FileBrowser：最流行的 Web 文件管理器（36k Star），定位是"替代 SFTP 客户端的网页文件面板"，多用户、共享链接、文件编辑能力完整。它不做媒体转码，也不提供 WebDAV/FTP 服务端，与 copyparty 的差异主要在协议广度与媒体能力上。
miniserve：Rust 单二进制的极简 HTTP 服务器，miniserve /path 一行命令即可把目录分享出去，支持可选上传、Basic Auth、tar 打包下载、二维码。适合命令行临时分享，不适合复杂权限场景。
Dufs：同样是 Rust 单二进制，比 miniserve 多了 WebDAV、搜索、zip 下载与 REST 风格 API，权限为 Basic Auth。适合个人开发者的轻量文件服务，介于 miniserve 与 copyparty 之间。
3.4 选型建议
- 需要"一台服务器服务多种客户端协议"（Windows 挂 SMB、Linux 用 WebDAV、手机浏览器上传、脚本用 curl）——copyparty 是唯一把六种协议做进单文件的开源项目，选它；
- 需要媒体库（缩略图、在线播放、音频转码、频谱图、音乐搜索）——copyparty 开箱即得，其余五项要么无此能力，要么只有基础图片预览；
- 只做一次性文件外发（带过期/次数限制）——Gokapi 更聚焦，copyparty 的分享能力属于顺带支持；
- 追求零依赖极简、一行命令临时分享——miniserve 或 Dufs 更合适；
- 已经在用 FileBrowser 且只需要网页文件管理——不必强行迁移，但若开始需要 WebDAV/FTP/SMB 或媒体能力，copyparty 是升级方向。
四、适用场景与边界
4.1 适合的场景
- 团队/家庭内部的多用户文件服务器：按卷划分目录，不同人不同权限，匿名只读、指定人可写；
- 个人音乐库与图片库：转码、频谱图、按标签搜索音乐，浏览器直接当播放器；
- 自动化收发文件：curl 命令行上传、WebDAV 挂载、事件钩子联动病毒扫描或通知；
- 低配设备：Python 标准库即可跑核心功能，官方性能参考（8 GiB/s 下载）说明性能天花板并不低。
4.2 需要注意的边界
- 媒体功能依赖可选组件：无 ffmpeg 则视频缩略图与转码不可用，无 Pillow 则图片缩略图不可用，部署前需要确认依赖；
- 权限字母体系功能强但学习曲线陡，ACL 配置错误可能导致"看起来 200 实际 403"的困惑，需要按官方文档逐项核对；
- 同密码账户不支持：官方实现要求不同账户不得使用相同密码，批量建账户时容易踩坑；
- 官方未提供内置带宽限速参数，流量控制需依赖外部手段（如反代或系统层限制）。
总体来看，copyparty 1.20.26 是目前开源自托管文件服务器中功能覆盖面最广的项目之一：协议最全、媒体能力最强、事件钩子独此一家，47k Star 也代表了社区认可度。如果需要一个"装完即用的私人网盘+Nas 网页面"，它非常值得优先评估；如果诉求极简，再考虑 miniserve/Dufs 这类轻量工具。后续的安装、配置与命令行实战篇将基于 Ubuntu 22.04 实测展开。