copyparty便携式文件服务器

32.1k Github仓库 Gitee仓库

💾🎉 copyparty

使用 any 网页浏览器，将几乎任何设备变成支持断点续传/下载的文件服务器

服务器只需要 Python 2 或 3，所有依赖项可选
🔌 协议：http // webdav // ftp // tftp // smb/cifs
📱 Android 应用 // iPhone 快捷方式

功能

后端内容
☑ IPv6 + Unix 套接字
☑ 多处理（实际多线程）
☑ 卷（挂载点）
☑ 帐户
☑ [FTP 服务器](#FTP 服务器)
☑ [TFTP 服务器](#TFTP 服务器)
☑ [WebDAV 服务器](#WebDAV 服务器)
☑ [SMB/CIFS 服务器](#SMB 服务器)
☑ 二维码用于快速访问
☑ UPNP / Zeroconf / MDNS / SSDP
☑ 事件hooks / 脚本运行器
☑ 反向代理支持
☑ 跨平台 (Windows、Linux、Macos、Android、FreeBSD、arm32/arm64、ppc64le、s390x、risc-v/riscv64)
上传
☑ basic：普通分段上传，支持 IE6
☑ up2k：js，可断点续传，多线程
无文件大小限制！ 即使在 Cloudflare 上也是如此
☑ stash：简单的 PUT 文件拖放器
☑ 文件名随机器
☑ 只写文件夹
☑ unpost：撤消/删除意外上传
☑ self-destruct（指定服务器端或客户端）
☑ race the beam（类似点对点）
☑ 符号链接/丢弃重复项（内容匹配）
下载
☑ 浏览器中的单个文件
☑ 文件夹作为 zip/tar 文件
☑ FUSE 客户端（只读）
浏览器
☑ navpane（目录树侧边栏）
☑ 文件管理器（剪切/粘贴、删除、批量重命名）
☑ 音频播放器（带有 OS 媒体控件和 opus/mp3 转码)
☑ 将视频文件播放为音频（在服务器端转换）
☑ 创建并播放 m3u8 播放列表
☑ 使用 webm 播放器的图片库
☑ 带语法高亮的文本文件浏览器
☑ 实时流式传输不断增长的文件（日志文件等）
☑ 缩略图
☑ ...使用 Pillow、pyvips 或 FFmpeg 处理图像
☑ ...使用 rawpy 处理 RAW 图像
☑ ...使用 FFmpeg 上传视频
☑ ...使用 FFmpeg 上传音频（频谱图）
☑ 缓存回收（最大使用期限；最终可能支持最大大小）
☑ 多语言界面（英语、挪威语、中文，添加您自己的语言))
☑ SPA（上传时浏览）
服务器索引
☑ 按内容定位文件
☑ 按名称/路径/日期/大小搜索
☑ 按 ID3 标签等搜索
客户端支持
☑ 文件夹同步（仅单向；不支持完全同步）
☑ curl-friendly
☑ opengraph (discord 嵌入)
markdown
☑ viewer
☑ 编辑器 (当然可以)
☑ variables

快速入门

只需运行 copyparty-sfx.py —— 就这么简单！ 🎉

ℹ️ sfx 是一个自解压程序，它会将嵌入的 tar.gz 解压到 $TEMP 中——如果这看起来太吓人，你可以使用 zipapp，但性能稍差。

或者通过 pypi 安装：python3 -m pip install --user -U copyparty
或者如果你无法安装 python，可以使用 copyparty.exe
或者在 arch 上安装 ╱ 在 NixOS 上安装 ╱ 通过 nix 安装
或者如果你使用的是安卓系统，在 termux 中安装 copyparty
或者你有一个 [synology nas](#synology nas) / dsm](./docs/synology-dsm.md)
或者如果你安装了 uv，运行 uv tool run copyparty
或者如果你的电脑坏了，其他方法都不管用，试试 pyz
或者如果你的操作系统死机了，试试可启动U盘/光盘
或者如果你还不信任 copyparty，想稍微隔离一下，那么……
...也许可以使用 prisonparty 创建一个小型的 chroot（非常便携），
...或者使用 bubbleparty 来打包它bubblewrap（好多了）
或者如果你更喜欢使用 docker 🐋 你也可以这么做
docker 已经内置了所有依赖项，所以跳过此步骤：

通过安装一些推荐的依赖包来启用缩略图（图片/音频/视频）、媒体索引和音频转码：

Alpine： apk add py3-pillow ffmpeg
Debian： apt install --no-install-recommends python3-pil ffmpeg
Fedora： rpmfusion + dnf install python3-pillow ffmpeg --allowerasing`
FreeBSD： pkg install py39-sqlite3 py39-pillow ffmpeg
MacOS： port install py-Pillow ffmpeg
MacOS（备选方案）： brew install pill ffmpeg
Windows： python -m pip install --user -U Pillow
安装 python 和手动使用 ffmpeg；请勿使用 winget 或 Microsoft Store（它会破坏 $PATH）
copyparty.exe 自带 Pillow，并且仅需要 ffmpeg 来处理 mediatags/videothumbs
请参阅 optional dependency 以启用更多功能

运行 copyparty 时不带参数（例如在 Windows 上双击）将授予所有人对当前文件夹的读写权限；您可能需要帐户和卷

或查看一些使用示例获取灵感，或完整的 Windows 示例

一些推荐选项：

-e2dsa 启用常规文件索引
-e2ts 启用音频元数据索引（需要 FFprobe 或 Mutagen）
-v /mnt/music:/music:r:rw,foo -a foo:bar 将 /mnt/music 共享为 /music，任何人都可读，并且用户 foo（密码为 bar）可读写
将 :r:rw,foo 替换为 :r,foo，使文件夹仅供 foo 读取，其他任何人都无法读取
请参阅帐户和卷（或 --help-accounts）用于语法和其他权限

在家

通过启动 cloudflare quicktunnel 使其可通过互联网访问，如下所示：

首先下载 cloudflared，然后使用 cloudflared tunnel --url http://127.0.0.1:3923 启动隧道。

隧道启动后，它会显示一个 URL，您可以共享该 URL，以便其他人浏览您的存储或上传文件给您。

但如果您有域名，那么您可能希望跳过随机自动生成的 URL，而是创建一个永久 cloudflare 隧道

由于人们将通过 cloudflare 连接，请使用 --xff-hdr 运行 copyparty。 cf-connecting-ip` 正确检测客户端 IP

在服务器上

您可能还需要这些，尤其是在服务器上：

contrib/systemd/copyparty.service 将 copyparty 作为 systemd 服务运行（请参阅内附指南）
contrib/systemd/prisonparty.service 在 chroot 中运行（为了提高安全性）
contrib/openrc/copyparty 在 Alpine / Gentoo 上运行 copyparty
contrib/rc/copyparty 在 FreeBSD 上运行 copyparty
nixos module 在 NixOS 主机上运行 copyparty
contrib/nginx/copyparty.conf 在 nginx 后面进行 reverse-proxy（为了更好地https)

记得打开你需要的端口；这里有一个完整的示例，包含了 copyparty 提供的所有功能：

复制代码

firewall-cmd --permanent --add-port={80,443,3921,3923,3945,3990}/tcp  # --zone=libvirt
firewall-cmd --permanent --add-port=12000-12099/tcp  # --zone=libvirt
firewall-cmd --permanent --add-port={69,1900,3969,5353}/udp  # --zone=libvirt
firewall-cmd --reload

(69:tftp, 1900:ssdp, 3921:ftp, 3923:http/https, 3945:smb, 3969:tftp, 3990:ftps, 5353:mdns, 12000:passive-ftp)

注意事项

一般注意事项：

纸张打印受暗/亮模式影响！使用浅色模式显示彩色，使用深色模式显示灰度
因为目前没有浏览器能够正确实现媒体查询 orz

浏览器相关：

iPhone/iPad：使用 Firefox 下载文件
Android Chrome：增加“并行上传”功能以提高速度（Android 系统 bug）
Android Firefox：选择文件需要一段时间（已修复☝️）
桌面 Firefox：~~如果文件很大，可能会占用数 GB 的内存~~ 现在似乎没问题了
桌面 Firefox：可能会阻止您拔出 USB 闪存盘，直到您访问 about:memory 并点击 Minimize memory usage

服务器操作系统相关：

RHEL8 / Rocky8：您可以使用 /usr/libexec/platform-python 运行 copyparty

服务器注意事项：

pypy受支持，但如果启用数据库，常规 cpython 会更快

帐户和卷

每个文件夹、每个用户的权限 - 如果您的设置变得复杂，请考虑创建一个配置文件，而不是使用参数。

更易于管理，您可以在运行时使用 systemctl reload copyparty 修改配置，或者更方便地使用控制面板中的 [reload cfg] 按钮（如果用户在任何卷中拥有 a/admin 权限）
对 [global] 配置部分的更改需要重启才能生效

使用 --help-accounts 可以查看快速摘要

使用参数配置帐户/卷：

-a usr:pwd 添加帐户 usr 并使用密码 pwd
-v .::r 添加当前文件夹 . 作为 Web 根目录，任何人都可以读取
语法为 -v src:dst:perm:perm:...，因此本地路径， url 路径，以及一个或多个要设置的权限
向多个帐户授予相同的权限：
-v .::r,usr1,usr2:rw,usr3,usr4 = usr1/2 只读，3/4 读写

权限：

r（读取）：浏览文件夹内容、下载文件、下载为 zip/tar 包、查看文件密钥/目录密钥
w（写入）：上传文件、移动/复制文件到此文件夹
m（移动）：从此文件夹移动文件/文件夹
d（删除）：删除文件/文件夹
.（点）：用户可以要求在目录列表中显示点文件
g（获取）：仅下载文件，无法查看文件夹内容或 zip/tar 包
G（上传获取）：与 g 相同，但上传者可以查看自己的文件密钥（请参阅示例中的 fk）。（见下文）
h (html)：与 g 相同，但文件夹会返回其 index.html，且 index.html 无需文件密钥
a (管理员)：可以查看上传时间、上传者 IP、config-reload
A ("all")：与 rwmda 相同（读/写/移动/删除/管理员/dotfiles）

示例：

添加名为 u1、u2、u3 的账户，密码分别为 p1、p2、p3：-a u1:p1 -a u2:p2 -a u3:p3
将文件夹 /srv 设为文件系统的根目录，任何人都可以只读：-v /srv::r
将文件夹 /mnt/music 设为 /music，u1 和 u2 只读，u3 可读写：-v /mnt/music:music:r,u1,u2:rw,u3
访问 webroot 的未授权用户可以看到 music 文件夹存在，但无法打开它
将文件夹 /mnt/incoming 设为 /inc，u1 只写，u2 可读写：-v /mnt/incoming:inc:w,u1:rm,u2
未授权用户访问 webroot 可以看到 inc 文件夹存在，但无法打开它。
u1 可以打开 inc 文件夹，但无法查看其中的内容，只能上传新文件。
u2 可以浏览该文件夹，并将文件从 /inc 移动到 u2 具有写入权限的任何文件夹。
使文件夹 /mnt/ss 在 /i 可用，u1 可读写，其他用户只能读取，并启用文件密钥：-v /mnt/ss:i:rw,u1:g:c,fk=4
c,fk=4 将 fk (filekey) 卷标志设置为 4，这意味着每个文件都将获得一个 4 位字符的访问密钥。
u1 可以上传文件、浏览文件夹并查看生成的文件密钥。
其他用户无法浏览文件夹，但如果他们拥有包含文件密钥的完整文件 URL，则可以访问文件。
替换 g 权限使用 wg 权限将允许匿名用户上传文件，但无法查看访问文件所需的文件密钥。
将 g 权限替换为 wG 权限将允许匿名用户上传文件，并返回一个可用的直接链接。

任何试图暴力破解密码的用户都会根据 --ban-pw 被封禁；默认设置是 1 小时内 9 次尝试失败将被封禁 24 小时。

如果您想使用配置文件而不是命令行参数（好！），以下是与配置文件相同的示例；将其保存为 foobar.conf 并像这样使用：python copyparty-sfx.py -c foobar.conf

您也可以使用 PRTY_CONFIG=foobar.conf python copyparty-sfx.py（在 docker 等环境中很方便）

yaml 复制代码

[accounts]
  u1: p1  # create account "u1" with password "p1"
  u2: p2  #  (note that comments must have
  u3: p3  #   two spaces before the # sign)

[groups]
  g1: u1, u2  # create a group

[/]     # this URL will be mapped to...
  /srv  # ...this folder on the server filesystem
  accs:
    r: *  # read-only for everyone, no account necessary

[/music]       # create another volume at this URL,
  /mnt/music   # which is mapped to this folder
  accs:
    r: u1, u2  # only these accounts can read,
    r: @g1     # (exactly the same, just with a group instead)
    rw: u3     # and only u3 can read-write

[/inc]
  /mnt/incoming
  accs:
    w: u1   # u1 can upload but not see/download any files,
    rm: u2  # u2 can browse + move files out of this volume

[/i]
  /mnt/ss
  accs:
    rw: u1  # u1 can read-write,
    g: *    # everyone can access files if they know the URL
  flags:
    fk: 4   # each file URL will have a 4-character password

点文件

Unix 风格的隐藏文件/文件夹，名称以点开头。

任何人都可以访问这些文件/文件夹，只要知道名称即可。但它们通常不会出现在目录列表中。

如果指定了全局选项 -ed，或者卷带有卷标志 dots，或者用户拥有权限 .，客户端可以请求在目录列表中查看点文件。

除非以上条件之一成立，并且全局选项 / 卷标志 dotsrch 已设置，否则点文件不会出现在搜索结果中。

即使用户有权限查看点文件，它们默认隐藏，除非设置了 --see-dots，并且/或者用户在设置选项卡中启用了 dotfiles 选项。

配置文件示例，其中以两种不同的方式授予相同的点文件查看权限，仅供参考：

yaml 复制代码

[/foo]
  /srv/foo
  accs:
    r.: ed   # user "ed" has read-access + dot-access in this volume;
             # dotfiles are visible in listings, but not in searches
  flags:
    dotsrch  # dotfiles will now appear in search results too
    dots     # another way to let everyone see dotfiles in this vol

浏览器

使用网络浏览器访问 Copyparty 服务器

热键

浏览器有以下热键（始终为 QWERTY 键盘）

? 显示热键帮助
B 切换面包屑导航 / 导航窗格
I/K 上一个/下一个文件夹
M 父文件夹（或取消展开当前文件夹）
V 切换导航窗格中的文件夹/文本文件
G 切换列表 / 网格视图 -- 与右下角的 田 相同
T 切换缩略图/图标
ESC 关闭各种功能
ctrl-K 删除选定的文件/文件夹
ctrl-X 剪切选定的文件/文件夹
ctrl-C 将选定的文件/文件夹复制到剪贴板
ctrl-V 粘贴（移动/复制）
Y 下载选定的文件
F2 重命名选定的文件/文件夹
选定文件/文件夹时（非网格视图）：
Up/Down 移动光标
Shift+Up/Down 选择并移动光标
Ctrl+Up/Down 移动光标并滚动视口
Space 切换文件选择
Ctrl-A 切换全选
打开文本文件时：
I/K 上一个/下一个文本文件
S 切换打开文件的选择
M 关闭文本文件
播放音频时：
J/L 上一个/下一个歌曲
U/O 快进/快退 10 秒
0..9 跳转到 0% 到 90%
P 播放/暂停（同时开始播放文件夹）
Y 下载文件
查看图片/播放视频时：
J/L, Left/Right 上一个/下一个文件
Home/End 第一个/最后一个文件
F 切换全屏
S 切换选择
R 顺时针旋转（Shift=逆时针）
Y 下载文件
Esc 关闭查看器
视频：
U/O 快退/快进 10 秒
0..9 跳转到 0% 到 90%
P/K/Space 播放/暂停
M 静音
C 继续播放下一个视频
V 循环播放整个文件
[ 循环范围（起始）
] 循环范围（结束）
导航窗格打开时：
A/D 调整树状图宽度
在网格视图中：
S 切换多选
Shift+A/D 缩放
在 Markdown 编辑器中：
^s 保存
^h 标题
^k 自动套用表格格式
^u 跳转到下一个 Unicode 字符
^e 切换编辑器/预览
^up, ^down 跳转段落

缩略图

按 g 或 田 切换网格视图而非文件列表，t 切换图标/缩略图

可以使用 --grid 全局设置为默认，或使用卷标记 grid 为每个卷设置默认
通过在链接中添加 ?imgs 启用，或使用 ?imgs=0 禁用

zip 下载

将文件夹（或选定文件）下载为 zip 或 tar 文件

在 [⚙️] config 选项卡中选择所需的归档类型：

名称	url-suffix	描述
`tar`	`?tar`	普通 gnutar，与 `curl \| tar -xv` 配合使用效果很好
`pax`	`?tar=pax`	pax-format tar，面向未来，速度较慢
`tgz`	`?tar=gz`	gzip 压缩的 gnu-tar（速度慢），适用于 `curl \| tar -xvz`
`txz`	`?tar=xz`	带 xz / lzma 压缩的 gnu-tar（速度很慢）
`zip`	`?zip`	在所有平台上均可使用，但在 Win7 及更高版本上文件名可能存在问题
`zip_dos`	`?zip=dos`	传统 cp437（非 unicode）用于修复文件名错误
`zip_crc`	`?zip=crc`	cp437 算法，并提前计算 crc32 以应对真正老旧的软件

gzip 默认级别为 3（0=快速，9=最佳），请使用 ?tar=gz:9 更改
xz 默认级别为 1（0=快速，9=最佳），请使用 ?tar=xz:9 更改
bz2 默认级别为 2（1=快速，9=最佳），请使用 ?tar=bz2:9 更改
隐藏文件（dotfiles）将被排除，除非帐户被允许列出它们
up2k.db 和 dir.txt 始终被排除
bsdtar 支持流式解压：curl foo?zip | bsdtar -xv
很好，因为 copyparty 的 zip 比 tar 压缩小文件更快。
但 ?tar 更适合大文件，尤其是在文件总量超过 4 GiB 的情况下。
zip_crc 的下载时间会更长，因为服务器需要读取每个文件两次。
这仅支持 MS-DOS PKZIP v2.04g（1993 年 10 月）及更早的版本。
您实际上是如何访问 copyparty 的？

您也可以通过在浏览器中点击文件或文件夹来压缩它们，这会在右下角弹出一个选择编辑器和压缩按钮。

上传

将文件/文件夹拖放到网页浏览器中进行上传

推荐使用拖放方式，但您也可以：

在文件资源管理器中选择一些文件（不是文件夹），然后在浏览器窗口中按下 CTRL-V
使用命令行上传器
使用curl、sharex、ishare 等上传

通过拖放或 CTRL-V 上传文件时，会使用 up2k 启动上传；有两个基于浏览器的上传器可用：

[🎈] bup，基础版上传器，支持自 Netscape 4.0 以来的几乎所有浏览器
[🚀] up2k，好用/炫酷版

注意：您可以使用 [🧯] unpost 撤消/删除您自己的上传（您也可以在此处中止未完成的上传，但必须先刷新页面）

up2k 有几个优点：

您可以将文件夹拖放到浏览器中（文件会递归添加）
文件会分块处理，并且每个块都会进行校验和
如果上传因网络问题中断，上传会自动恢复
如果您重启浏览器或电脑，上传会恢复，只需再次上传相同的文件即可
服务器会检测到任何损坏；客户端会重新上传受影响的数据块
客户端不会上传服务器上已存在的任何内容
无文件大小限制，即使代理限制了请求大小（例如 Cloudflare）
由于并行连接，在某些网络连接（主要是美国）上，速度比 ftp/scp/tarpipe 快得多
文件的最后修改时间戳会被保留

专家提示：如果您在 [⚙️] 设置选项卡中启用网站图标（通过在文本框中输入内容），浏览器选项卡中的图标将显示上传进度——此外，[🔔] 和/或 [🔊] 开关可在上传完成时启用视觉和/或声音通知。

up2k 的用户界面是精致直观体验的典范：

“并行上传”指定同时上传的块数
[🏃] 上传文件时应继续分析其他文件
[🥔] 显示更简洁的用户界面，以便从慢速设备更快地上传
[🛡️] 决定何时覆盖服务器上的现有文件
🛡️ = 从不（改为生成新文件名）
🕒 = 如果服务器文件较旧则覆盖
♻️ = 如果文件较新则始终覆盖不同
[🎲] 上传时生成随机文件名
[🔎] 在上传和文件搜索模式之间切换
忽略 [🔎] 如果您通过将文件拖入浏览器来添加文件
然后是其下方的选项卡

[ok] 表示已成功完成的文件
[ng] 表示失败/被拒绝的文件（已存在等）
[done] 显示 [ok] 和 [ng] 的组合列表，按时间顺序排列
[busy] 表示当前正在哈希、待上传或正在上传的文件
以及 [done] 和 [que] 中最多 3 个条目用于上下文
[que] 表示所有仍在排队的文件
请注意，由于 up2k 需要读取每个文件两次，[🎈] 在某些极端情况下，bup 理论上可以提高 2 倍速度（文件大于您的内存，加上互联网连接速度快于您的硬盘读取速度，或者您使用 cuo2duo 上传）。

如果您如果您正在恢复海量上传，并且希望跳过对已完成文件的哈希处理，您可以在 [⚙️] 配置选项卡中启用 Turbo，但请阅读该按钮上的工具提示。

如果服务器使用代理服务器，并且该代理服务器对请求大小有限制，您可以使用服务器选项 --u2sz 配置 up2k，使其低于限制值（默认值为 96 MiB，以支持 Cloudflare）。

如果您想默认用新上传的文件替换服务器上的现有文件，请使用 --u2ow 2 运行（仅在用户拥有删除权限时有效，并且仍然可以在用户界面中使用 🛡️ 禁用）。

file-search

将文件拖放到浏览器中，还可以查看它们是否存在于服务器上

关于项目

便携式文件服务器，具有加速可恢复上传、重复数据删除、WebDAV、FTP、TFTP、零配置、媒体索引器、缩略图等功能，全部包含在一个文件中，无依赖项。将几乎任何设备变成文件服务器，使用任何 Web 浏览器进行可断点续传/下载。

MIT

Python

32,144

1288

113

2019-05-26

2025-10-09