copyparty 1.20.26 常用 CLI 命令详解

目标：汇总 copyparty 1.20.26 日常运维最常用的三类命令——服务端启动参数矩阵、curl/WebDAV 客户端命令（上传、下载、改名、删除、列目录、转码）、systemd 服务管理，全部命令在 Ubuntu 22.04 上实测并附真实回显。安装与配置推导过程见《Ubuntu 22.04 安装 copyparty 1.20.26 指南》与《copyparty 1.20.26 配置参数详解》。版本检索日期 2026-10-26。

一、服务端启动参数矩阵

1.1 核心参数

参数	作用	默认值	实测说明
`-p PORT`	HTTP 监听端口	3923	`-p 3923` 时日志 `now serving @ http://0.0.0.0:3923/`
`-i ADDR`	监听地址	0.0.0.0	内网服务可绑定 `127.0.0.1` 或内网 IP
`-a user:pass`	定义账户	无	可重复；同密码账户会拒绝启动
`-v src:url:perms`	挂载卷与权限	无	可重复；权限组结构见配置详解篇
`-c PATH`	加载配置文件	无	可叠加多个；配置文件优先表达力更完整
`-e2dsa`	建索引并全量扫描	关闭	搜索/去重/上传撤销的前提
`-e2t`	建缩略图索引	关闭	配合 `--th-size` 使用
`--name NAME`	站点名称	copyparty	浏览器标题与 mDNS 宣告名
`-lo PATH`	日志写文件	仅 stdout	支持 `cpp-%Y-%m%d.txt` 日期模板
`-q`	安静模式	关闭	关闭 stdout 日志（帮助注明可小幅提升性能）
`--cgen`	由当前命令行生成配置文件	无	打印配置文件内容后退出，不启动服务

组合示例（一个含四卷、双账户、索引与钩子的启动命令）：

python3 /opt/copyparty/copyparty-sfx.py \
  -a admin:q1w2e3r4 -a uploader:q1w2e3r5 \
  -v /srv/party/pub:/pub:r:rwmda,admin \
  -v /srv/party/drop:/drop:w:A,admin \
  -v /srv/party/pics:/pics:r:rwmda,admin \
  -v /srv/party/music:/music:r:rwmda,admin \
  -p 3923 -e2dsa --name=fileserver

实测启动回显（关键行）：

LOG 08:04:05 dependencies: OK ['sqlite', 'pillow', 'pillow-webp', 'ffmpeg', 'ffprobe', 'pillow-avif']  NG ['vips', 'bwrap', 'mutagen', 'argon2', 'pyzmq', 'pillow-heif', 'rawpy', 'libraw']
LOG 08:04:05 URL: http://0.0.0.0:3923/
LOG 08:04:05 [copyparty webdav-ftp-tftp-smb-client] now serving @ http://0.0.0.0:3923/
LOG 08:04:05 using http; port 3923 is reachable from the internet

1.2 协议开关

参数	协议	示例
`--ftp 3921`	FTP	`--ftp 3921` 后可用任意 FTP 客户端连 3921
`--ftps 3990`	FTP over TLS	需配置证书
`--sftp 3922`	SFTP	内置 SSH2 文件传输（非 shell）
`--smb 3945`	SMB/CIFS	Windows 资源管理器直连 `\\<host>\r`
`--tftp 3969`	TFTP	读写均可，适合设备固件场景
`-zs` / `-zm`	SSDP/mDNS 宣告	局域网发现；无组播网络时无效（边界：实测环境不组播，标注不启用）

1.3 帮助族命令

python3 copyparty-sfx.py --help           # 总览（约 1700 行）
python3 copyparty-sfx.py --help-accounts  # 权限字母表
python3 copyparty-sfx.py --help-auth      # 登录方式
python3 copyparty-sfx.py --help-hooks     # 事件钩子
python3 copyparty-sfx.py --help-urlform   # URL/表单参数
python3 copyparty-sfx.py --help-thumbs    # 缩略图
python3 copyparty-sfx.py --deps           # 可选依赖检测（注意：无参数时会直接启动服务，需 Ctrl-C）

二、curl 客户端命令（实测闭环）

2.1 三种登录方式

# URL 参数（密码或 用户名:密码）
curl -s "http://127.0.0.1:3923/pub/?pw=q1w2e3r4" -o /dev/null -w '%{http_code}\n'
# Basic Auth
curl -s -u admin:q1w2e3r4 "http://127.0.0.1:3923/pub/" -o /dev/null -w '%{http_code}\n'
# PW 请求头
curl -s -H 'PW: q1w2e3r4' "http://127.0.0.1:3923/pub/" -o /dev/null -w '%{http_code}\n'

三种方式实测均返回 200。

2.2 上传（PUT）

dd if=/dev/urandom of=/tmp/sample.bin bs=1M count=2 2>/dev/null
curl -s -T /tmp/sample.bin -u admin:q1w2e3r4 \
  http://127.0.0.1:3923/pub/sample.bin -o /dev/null -w 'PUT: %{http_code}\n'

实测输出：

PUT: 201

2.3 下载与校验（GET）

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

实测输出（两端一致）：

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

2.4 列目录（PROPFIND，WebDAV）

curl -s -X PROPFIND -u admin:q1w2e3r4 \
  http://127.0.0.1:3923/pub/ -H 'Depth: 1' | grep -oE '<href>[^<]+</href>' | head -4

实测输出（URL 编码的目录清单）：

<href>/pub/</href>
<href>/pub/readme.txt</href>
<href>/pub/sample.bin</href>
<href>/pub/try.txt</href>

2.5 改名/移动（MOVE）

curl -s -X MOVE -u admin:q1w2e3r4 http://127.0.0.1:3923/drop/mv-src.txt \
  -H 'Destination: http://127.0.0.1:3923/drop/mv-dst.txt' -o /dev/null -w 'MOVE: %{http_code}\n'

实测输出：

MOVE: 201

前提：账户在源卷有 m 权限。实测在仅有 rw 的 /pub 卷上执行同样的 MOVE 返回 401。

2.6 删除（DELETE）

curl -s -X DELETE -u admin:q1w2e3r4 \
  http://127.0.0.1:3923/drop/anon.txt -o /dev/null -w 'DELETE: %{http_code}\n'

实测输出：

DELETE: 200

前提：账户有 d 权限。实测在仅有 rw 的 /pub 卷上返回 403（权限字母逐项生效）。

2.7 音频转码（?th=opus）

curl -s -u admin:q1w2e3r4 "http://127.0.0.1:3923/music/test.mp3?th=opus" -o /tmp/t.opus \
  -w 'th=opus: %{http_code} type: %{content_type} size: %{size_download}\n'
python3 -c "print(open('/tmp/t.opus','rb').read(4))"

实测输出：

th=opus: 200 type: audio/ogg; codecs=opus size: 57912
b'OggS'

同系列可用 ?th=mp3（实测 type: audio/mpeg）。图片缩略图用 ?th=x（实测 image/webp）。

2.8 u2c：命令行上传器

pip 安装后附带 u2c 工具，走与服务端 up2k 相同的分块续传协议，适合大文件脚本化上传：

u2c http://127.0.0.1:3923/pub/ /tmp/sample.bin

浏览器网页上传器同样支持断点续传与秒传（哈希命中即完成，需服务端开启 -e2d 索引）。

三、systemd 服务管理

3.1 日常命令

sudo systemctl start copyparty     # 启动
sudo systemctl stop copyparty      # 停止
sudo systemctl restart copyparty   # 重启
systemctl status copyparty --no-pager -n 5   # 状态
systemctl enable --now copyparty   # 开机自启并立即启动

实测 status 关键回显：

● 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)
     Memory: 39.0M

3.2 日志

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"

若在配置里加了 -lo /var/log/copyparty/cpp-%Y-%m%d.txt，日志会按天写文件，与 journalctl 并行不冲突。

3.3 改配置后的生效方式

卷标志、账户增删、密码修改：访问 ?reload=cfg&pw=<管理员密码> 热重载（实测新增账户 reload 后立即可用，返回 201），无需重启；
监听端口、协议开关这类全局网络参数：热重载不覆盖，走 systemctl restart copyparty。

四、速查卡片

场景	命令
启动（前台调试）	`python3 copyparty-sfx.py -c /etc/copyparty/cpp.conf`
上传	`curl -T 文件 -u admin:q1w2e3r4 http://host:3923/pub/`
下载	`curl -s http://host:3923/pub/文件 -o 本地`
列目录	`curl -X PROPFIND -u ... http://host:3923/pub/ -H 'Depth: 1'`
改名	`curl -X MOVE ... -H 'Destination: 新URL'`
删除	`curl -X DELETE -u ... http://host:3923/pub/文件`
转码播放	`curl "http://host:3923/music/x.mp3?th=opus" -o out.opus`
缩略图	`curl "http://host:3923/pics/x.png?th=x" -o th.webp`
热重载配置	浏览器/curl 访问 `?reload=cfg&pw=<管理员密码>`
服务状态	`systemctl status copyparty`
服务日志	`journalctl -u copyparty -f`
生成配置	命令行末尾追加 `--cgen`

边界说明：本篇命令均在 HTTP 明文端口上实测（局域网/本机场景）；公网部署请务必走 HTTPS 反向代理。至此本系列四篇（介绍与选型、安装、配置参数、CLI 命令）全部完结。