Ubuntu 22.04 安装 copyparty 1.20.26 指南

Ubuntu 22.04 从零安装 copyparty 1.20.26 实测：sfx 单文件与 pip 双方案、首个共享目录与多账户配置、curl 上传下载 MD5 校验闭环、ffmpeg/Pillow 可选依赖、systemd 专用账户托管与排障实录。

copyparty文件服务2026/10/26

Ubuntu 22.04 安装 copyparty 1.20.26 指南

目标：在一台 Ubuntu 22.04 服务器上从零安装 copyparty 1.20.26（Python 单文件媒体/文件服务器），完成首个共享目录的创建、多账户权限配置、上传下载闭环验证，并以 systemd 托管为常驻服务。本文所有命令与输出均在真实服务器上执行实测，版本信息检索日期为 2026-10-26。关于项目的定位与同类工具对比，参见《copyparty 1.20.26 介绍与选型指南》。

一、环境准备与版本确认

1.1 系统环境

实测环境：

  • 操作系统：Ubuntu 22.04（x86_64）；
  • Python：3.10.12（Ubuntu 22.04 自带，无需额外安装）；
  • 网络：服务器可访问公网（GitHub 下载不稳定时可用 HTTP 代理）。

确认 Python 版本：

python3 --version

实测输出：

Python 3.10.12

1.2 版本确认

copyparty 官方发布渠道为 GitHub Releases 与 PyPI，检索日期 2026-10-26 时最新稳定版本为 1.20.26（PyPI 发布于 2026-10-14）。官方提供三种安装形态，本文覆盖其中两种：

  • 方案 A：copyparty-sfx.py 单文件自解压脚本——项目主打形态，仅依赖 Python 标准库即可启动，媒体功能按需补依赖；
  • 方案 B：pip install copyparty 标准安装——适合纳入 Python 依赖管理；
  • （另有 zipapp 形态，官方说明性能略差于 sfx，本文不展开。）

二、方案 A：单文件 sfx 安装（推荐）

2.1 创建目录并下载

sudo mkdir -p /opt/copyparty /srv/party
cd /opt/copyparty
sudo curl -fSL --max-time 120 -o copyparty-sfx.py \
  https://github.com/9001/copyparty/releases/download/v1.20.26/copyparty-sfx.py
ls -la copyparty-sfx.py
md5sum copyparty-sfx.py

实测输出：

-rw-r--r-- 1 root root 1206486 Oct 26 08:00 copyparty-sfx.py
a7a5084273b7c3b9539d7334c77f1998  copyparty-sfx.py

两次独立下载的 MD5 均为 a7a5084273b7c3b9539d7334c77f1998，可留作校验基准。若 GitHub 直连失败（实测曾出现 curl: (56) Connection reset by peer），加代理重试：

sudo curl -fSL --max-time 120 -x http://<proxy-host>:<proxy-port> -o copyparty-sfx.py \
  https://github.com/9001/copyparty/releases/download/v1.20.26/copyparty-sfx.py

2.2 创建测试数据并启动

先放一个测试文件，随后启动服务，把 /srv/party 共享为 /files，管理员账户 admin：

echo 'hello copyparty' | sudo tee /srv/party/hello.txt
cd /opt/copyparty
sudo python3 copyparty-sfx.py -v /srv/party:/files -a admin:q1w2e3r4 -p 3923

实测启动输出（截取关键行）：

LOG 08:01:46 copyparty 1.20.26 stand-alone loaded to /root/.cache/pe-copyparty.0.2767.0
LOG 08:01:46 dependencies: OK ['sqlite']  NG ['pillow', 'vips', 'pillow-webp', 'ffmpeg', 'ffprobe', 'bwrap', 'mutagen', 'argon2', 'pyzmq', 'pillow-heif', 'pillow-avif', 'rawpy', 'libraw']
LOG 08:01:46 URL: http://0.0.0.0:3923/
LOG 08:01:46  *  volume cfg: [
LOG 08:01:46  *    [r]: 0 args, 1 flags, 1 discs:
LOG 08:01:46  *      /r  [ 785.7 GiB total,  591.7 GiB free ] <<  /srv/party
LOG 08:01:46  *  ]
LOG 08:01:46 this is the account root and I kindly ask you to change my password
LOG 08:01:46 [copyparty webdav-ftp-tftp-smb-client] now serving @ http://0.0.0.0:3923/
LOG 08:01:46 --db-loc: C.db = /root/.cache/pe-copyparty.0.2767.0/copyparty.db (auto-detected)
LOG 08:01:46 [db] created file-db: 1 volumes, 1 threads

几个要点：

  • dependencies 行列出可选依赖检测：OK 的是 sqlite（核心搜索库，已内置可用），NG 的是 Pillow/ffmpeg 等媒体依赖——不装也能跑基础文件服务，装上后解锁缩略图与转码（见第四节）；
  • sfx 版首次运行会把内嵌依赖解压到 ~/.cache/pe-copyparty.<版本> 目录（README 明确说明该机制）；
  • 未配置账户密码时会有 account root 的默认账户提示，实测建议显式 -a 配置账户。

浏览器打开 http://<服务器IP>:3923/files/ 即可看到文件列表；点击右上角 o 可用 admin / q1w2e3r4 登录。

2.3 命令行上传下载验证

服务器本地用 curl 验证上传与下载闭环（无需打开浏览器）：

# 生成一个 2MB 测试文件
dd if=/dev/urandom of=/tmp/sample.bin bs=1M count=2 2>/dev/null

# admin 登录并上传到 /files
curl -s -T /tmp/sample.bin "http://127.0.0.1:3923/files/sample.bin?pw=q1w2e3r4" -o /dev/null -w '%{http_code}\n'

实测输出（201 Created 表示写入成功）：

201

下载回来做 MD5 校验：

curl -s "http://127.0.0.1:3923/files/sample.bin" -o /tmp/dl.bin
md5sum /tmp/sample.bin /tmp/dl.bin

实测输出（两端一致，文件完整性无损）：

4b6c9630322bf4d21cbb56f41afb720b  /tmp/sample.bin
4b6c9630322bf4d21cbb56f41afb720b  /tmp/dl.bin

2.4 磁盘路径与写权限注意事项

copyparty 启动时会检测挂载点是否为真实磁盘。若共享目录落在 overlay 型文件系统上，会看到类似日志并自动移除写权限（实测回显）：

write-access was removed because not mapped to actual HDD (overlay)

把共享目录放在常规磁盘路径（如 /srv、/data）即可避免。

三、方案 B：pip 安装

3.1 pip 安装

Ubuntu 22.04 需先有 pip（若无则 sudo apt-get install -y python3-pip），然后用户级安装：

python3 -m pip install --user copyparty

实测输出（版本随发布渠道更新，2026-10-26 拉到的即为 1.20.26）：

Successfully installed Pillow-12.3.0 copyparty-1.20.26

值得注意：pip 安装会顺带装上 Pillow（pip 包的推荐依赖），因此媒体图片缩略图天然可用；sfx 单文件版则不带 Pillow，需要手动补。

3.2 命令与附加工具

export PATH=$PATH:/root/.local/bin
copyparty --version
ls /root/.local/bin/

实测输出：

copyparty v1.20.26
copyparty  partyfuse  u2c
  • copyparty：服务端主命令，参数与 sfx 完全一致；
  • partyfuse：把服务端目录通过 FUSE 挂载到本地文件系统；
  • u2c：命令行上传器（浏览器同款分块续传协议）。

两种方案功能完全等价，选一种即可；本文后续章节以方案 A 的路径为准，pip 用户的启动命令把 python3 copyparty-sfx.py 换成 copyparty 即可。

四、可选依赖：解锁媒体功能

4.1 ffmpeg（视频缩略图 + 音频转码）

sudo apt-get install -y ffmpeg
ffmpeg -version 2>/dev/null | head -1

实测输出：

ffmpeg version 4.4.2-0ubuntu0.22.04.1

4.2 Pillow（图片缩略图，sfx 版需手动补装）

python3 -m pip install --user Pillow
python3 -c 'import PIL; print("pillow", PIL.__version__)'

实测输出：

pillow 12.3.0

4.3 重启后复核依赖检测

重启 copyparty（Ctrl-C 后重新执行 2.2 的命令），启动日志中的 dependencies 行变为：

LOG 08:07:20 dependencies: OK ['sqlite', 'pillow', 'pillow-webp', 'ffmpeg', 'ffprobe', 'pillow-avif']  NG ['vips', 'bwrap', 'mutagen', 'argon2', 'pyzmq', 'pillow-heif', 'rawpy', 'libraw']
LOG 08:07:20 decoder preference: pil, ff

剩余 NG 项均为进阶能力（如 mutagen 读音频标签、pillow-heif 读 HEIC、argon2 哈希加速），缺省不影响核心功能。实测依赖缺失时的降级行为：

  • 无 mutagen 时读音频标签：LOG ... mtag WARN: could not load Mutagen, trying FFprobe instead（自动改用 FFprobe）；
  • 无 Pillow 时请求图片缩略图：服务端返回 SVG 占位图而非报错。

五、systemd 托管

5.1 创建专用账户与配置

生产环境建议用专用低权限账户运行，配置文件放 /etc/copyparty：

sudo useradd -r -s /usr/sbin/nologin copyparty
sudo mkdir -p /etc/copyparty /var/log/copyparty
sudo tee /etc/copyparty/cpp.conf > /dev/null <<'EOF'
[global]
  name: fileserver

[accounts]
  admin: q1w2e3r4

[/files]
  /srv/party
  accs:
    r: *
    rwmda: admin
  flags:
    e2dsa: True
EOF
sudo chown -R copyparty:copyparty /srv/party /var/log/copyparty /etc/copyparty

配置含义：admin 拥有 /files 的读写移动删除与管理权（rwmda），其他所有人（*）只读；e2dsa 表示启动时建立文件索引。

5.2 编写 service 单元

sudo tee /etc/systemd/system/copyparty.service > /dev/null <<'EOF'
[Unit]
Description=copyparty file server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=copyparty
Group=copyparty
ExecStart=/usr/bin/python3 /opt/copyparty/copyparty-sfx.py -c /etc/copyparty/cpp.conf
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now copyparty

实测输出：

Synchronizing state of copyparty.service with SysV service script with /lib/systemd/systemd-sysv-install.
Created symlink /etc/systemd/system/multi-user.target.wants/copyparty.service → /etc/systemd/system/copyparty.service.

5.3 状态与功能验证

systemctl status copyparty --no-pager -n 5

实测输出（内存占用约 39MB）：

● copyparty.service - copyparty file server
     Loaded: loaded (/etc/systemd/system/copyparty.service; enabled; preset: enabled)
     Active: active (running) since Sun 2026-10-26 08:09:41 UTC; 2min 10s ago
   Main PID: 2625 (python3)
      Tasks: 3 (limit: 4551)
     Memory: 39.0M
        CPU: 2.438s
     CGroup: /system.slice/copyparty.service
             └─2625 /usr/bin/python3 /opt/copyparty/copyparty-sfx.py -c /etc/copyparty/cpp.conf

journalctl 查看服务日志：

journalctl -u copyparty --no-pager -n 3 -o cat

实测输出：

LOG 08:10:26 [copyparty webdav-ftp-tftp-smb-client] now serving @ http://0.0.0.0:3923/
LOG 08:10:41 [admin] logged in from 127.0.0.1
LOG 08:10:44 GET(/) - "" | 3923 "curl/7.81.0"

最终功能确认：

curl -s http://127.0.0.1:3923/files/hello.txt
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3923/files/

实测输出：

hello systemd
200

服务已随系统自启动，重启服务器后无需人工干预。日常管理命令：systemctl status|restart|stop copyparty，日志走 journalctl -u copyparty。

六、排障实录

实测过程中遇到的典型报错与处理：

  1. 多个账户使用相同密码，启动直接报错退出。日志回显： 
    LOG 08:03:12 CRIT: accounts [admin] and [uploader] have the same password; this is not supported
    处理：给每个账户设置不同密码。批量建账户时尤其容易踩坑。
  2. 账户未在任何卷定义中出现（不致命，但启动时告警）： 
    LOG 08:03:12 CRIT: account [uploader] is not mentioned in any volume definitions
    处理：在对应卷的 accs: 中引用该账户（哪怕只给只读权限），或确认其只需要匿名级访问。
  3. 共享目录在 overlay 型文件系统上，写权限被自动移除： 
    write-access was removed because not mapped to actual HDD (overlay)
    处理：把共享目录放到真实磁盘路径。
  4. 可选依赖缺失导致的静默降级：无 Pillow 时图片缩略图返回 SVG 占位图、无 mutagen 时自动改用 FFprobe 读音频标签。表现为"功能不生效但不报错"，先查启动日志的 dependencies: OK/NG 行。
  5. GitHub 下载单文件偶发 Connection reset by peer：直连不稳定时换代理，或改用 PyPI 渠道 pip install copyparty。

至此，copyparty 已在 Ubuntu 22.04 上完成从安装、首个共享到 systemd 常驻的完整闭环。下一篇《copyparty 1.20.26 配置参数详解》将逐项拆解 -a 账户、-v 卷挂载与权限语法、媒体与事件钩子等配置。