copyparty 1.20.26 配置参数详解

copyparty 1.20.26 配置体系逐项实测：-a 账户与同密码限制、-v 卷挂载与权限字母矩阵（r/w/m/d/A 逐项 403/201 验证）、-e2d 索引、缩略图/转码参数、--xau 事件钩子、--ban-pw 封禁实测、--cgen 生成配置文件与 ?reload=cfg 热重载闭环。

copyparty文件服务2026/10/26

copyparty 1.20.26 配置参数详解

目标：逐项拆解 copyparty 1.20.26 的配置体系——命令行参数（账户 -a、卷 -v、索引 -e2d*、媒体、事件钩子、安全）与配置文件（[global]/[accounts]/[/卷]）两大入口，每一项配置都给出"修改后在浏览器/curl 上的可验证结果"。实测环境与安装步骤见《Ubuntu 22.04 安装 copyparty 1.20.26 指南》，版本检索日期 2026-10-26。

一、参数体系总览

1.1 两种配置方式

copyparty 的全部能力都能通过命令行参数表达；当卷和账户多起来后，改用配置文件更易维护。两者关系：

  • 命令行方式：python3 copyparty-sfx.py -a admin:q1w2e3r4 -v /srv/party:/files:r:rwmda,admin；
  • 配置文件方式：把同样的内容写成 /etc/copyparty/cpp.conf，用 -c /etc/copyparty/cpp.conf 加载；
  • 支持多次 -c 叠加多个配置文件（帮助原文：-c PATH: config file to load, REPEATABLE）。

两套写法的对应关系可以自动转换——copyparty 内置 --cgen：用当前命令行参数启动时加上它，就会把等效的配置文件内容打印出来而不是启动服务。实测以 -a admin:q1w2e3r4 -v /srv/party/pub:/pub:r:rwmda,admin -p 3923 调用 --cgen，输出的核心部分（实测回显）：

[global]
  name: fileserver
  ...

[accounts]
  admin: q1w2e3r4

[/pub]
  /srv/party/pub
  accs:
    rg: *
    rwmdga: admin
  flags:
    ...

这个输出就是本文 4.x 节配置文件语法的权威样例来源。

1.2 帮助体系

copyparty 的 CLI 帮助分主题（实测 --help 主题表）：

  • --help：总览（约 1700 行，含全部参数清单）；
  • --help-accounts：权限字母（ACL）详解；
  • --help-auth：客户端登录方式（?pw=、PW: 请求头、Basic Auth）；
  • --help-hooks：事件钩子脚本语法；
  • --help-urlform：URL 与表单参数；
  • --help-thumbs：缩略图参数；
  • --help-deps：可选依赖说明。

1.3 端口与服务开关

  • -p PORT：HTTP 端口，默认 3923；
  • --ftp 3921 / --ftps 3990：FTP/FTPS；
  • --sftp 3922：SFTP；
  • --smb 3945：SMB/CIFS；
  • --tftp 3969：TFTP；
  • -i 0.0.0.0：监听地址；--unix-sock PATH：改用 Unix 套接字；
  • -z / --ztier：日志级别控制（-z 系列减少输出）。

修改端口验证：-p 8080 启动后启动日志出现 now serving @ http://0.0.0.0:8080/，浏览器访问相应端口即生效。

二、账户与卷：-a 与 -v

2.1 -a：账户定义

-a 用户名:密码，可重复出现定义多账户。实测规则：

  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
  3. 通配账户 * 表示"所有人"（含未登录访客），写在 accs 里即匿名权限。

2.2 -v：卷挂载语法

-v 源路径:URL路径:权限组,权限组...，可重复。每个"权限组"是 权限字母集合:账户列表 的组合，用冒号分隔：

-v /srv/party/pub:/pub:r:rwmda,admin
#      磁盘目录  URL  权限组1   权限组2
#                        ↑         ↑
#                   r 给 *     rwmda 给 admin

即"两层结构"：URL 路径之后跟若干个"权限:账户"对，前一组通常给 *（匿名），后一组给具名账户。写权限的额外约束：帮助原文 w = write: upload files; need r to see the uploads——写权限组若不带 r，上传者无法浏览目录内容。

2.3 权限字母逐项验证

--help-accounts 的字母表（节选）与逐项实测结果：

字母含义（帮助原文摘要）实测验证方式与结果
rread: list files匿名 GET /pub/ → 200，列出 readme.txt、sample.bin
wwrite: upload files（需 r 才能看见所传文件）匿名 PUT /drop/anon.txt → 201 Created
mmove/rename/delete；目标卷需 wadmin 对仅有 rw 的 /pub 发起 WebDAV MOVE → 401（无 m 权限）；对含 A 的 /drop MOVE → 201
ddelete filesadmin 对仅有 rw 的 /pub 发 DELETE → 403；对含 A 的 /drop 发 DELETE → 200
gdownload files but cannot see folder contents未实测（只读下载场景）
hupload but cannot see folder contents未实测（收件箱场景可用 w 替代）
.list folder contents but cannot download未实测（目录可见性细分）
aadmin: move/rename/delete + read/write，含隐藏文件组合使用
A全部权限（含隐藏文件管理）admin 在 /drop（A,admin）删除/改名全部成功

一个容易误判的行为实测记录：匿名向 w 权限的 /drop 上传 anon.txt 后，匿名 GET /drop/anon.txt 返回 200——但返回的不是文件内容，而是该目录的上传界面（页面元信息里 perms: ['write']）。写卷对匿名的语义是"能传、能看上传界面、不能列目录也取不到文件内容"，并非传统意义上的"上传后可下载"。

2.4 登录方式与验证

--help-auth 列出三种客户端登录方式，实测全部可用：

  • URL 参数：?pw=q1w2e3r4（不区分账户名时按密码反查账户）；
  • Basic Auth：curl -u admin:q1w2e3r4 ...；
  • PW: 请求头：-H 'PW: q1w2e3r4'。

区分"认证失败"与"无权限"的实测结论：写操作对错误凭据和正确凭据都返回 403（认证失败回退为匿名身份，匿名同样无写权限）。要验证某个密码是否有效，用 ?pw= 建会话后观察是否签发登录 Cookie，或直接用写操作+已知权限矩阵判定。

三、索引与卷标志（volflags）

3.1 -e2d 系列索引

  • -e2d：开启文件数据库索引（搜索、去重、上传撤销的基础）；
  • -e2ds：开启索引 + 启动时扫描变化部分；
  • -e2dsa：开启索引 + 启动时全量扫描。

实测：-e2dsa 启动后日志出现 [db] created file-db: N volumes, N threads；管理员在 URL 追加 ?scan 可触发重扫（需要管理员权限，匿名调用实测返回 403）。

3.2 常用卷标志

卷标志可写在 -v 的最后（CLI 形式）或配置文件 flags: 段。常用的有：

  • --nodupe：关闭上传去重（默认开启时同哈希文件以符号链接复用，节省磁盘）；
  • --share：允许生成分享链接；
  • d2d（目录项展示相关）、--dots（显示隐藏文件）等。

钩子类卷标志见第五节。

四、媒体参数与资源限制

4.1 缩略图参数

  • --th-size：缩略图分辨率档位（如 256）；
  • --th-fov：缩略图生成数量上限策略；
  • --th-clear-db：清空缩略图缓存库。

实测：安装 Pillow + ffmpeg 后（安装步骤见 B1 篇），对 /pics/test.png 请求 ?th=x：

th: 200 type: image/webp size: 2412

对音频文件 /music/test.mp3 请求 ?th=x 得到频谱图：

th: 200 type: image/webp size: 9552

未装 Pillow 时同一请求返回 SVG 占位图（type: image/svg+xml，368 字节）——这是判断依赖是否就绪的快速探针。

4.2 音频转码参数

  • --q-opus 128：opus 转码码率；
  • --q-mp3 q2：mp3 转码质量档。

实测：单文件转码统一走缩略图端点，URL 参数 ?th=opus / ?th=mp3：

th=opus: 200 type: audio/ogg; codecs=opus size: 57912
th=mp3:  200 type: audio/mpeg size: 16741

下载文件头 OggS 魔数确认真实 opus 流。注意 ?ab=opus 这类猜测写法无效（实测返回原 mp3 文件）。

4.3 资源限制

copyparty 的"资源限制"不包含带宽限速——实测遍历 --help 全文，无 rate/speed/throttle 类参数。实际可用的限制手段：

  • --nc NUM：单 IP 最大并发连接数（默认 64）；
  • --df 10Gi：磁盘剩余空间低于阈值时拒绝写入；
  • --ban-pw 9,60,1440：密码错误封禁（次数,最短封禁秒数,最长封禁秒数）；
  • --ban-url / --ban-scan：对恶意路径/扫描行为的封禁。

4.4 封禁实测

对 -a admin:q1w2e3r4 的服务连续用错误密码访问（默认第 9 次错误后封禁）：

try 1: 200
try 2: 200
...
try 9: 200
try 10: 403

第 10 次起直接 403（封禁生效，IP 进入临时黑名单）。生产环境建议保留默认值或按需收紧。

五、事件钩子（--xa* 系列）

5.1 钩子类型与参数

--help-hooks 的类型清单：--xau（上传后）、--xab（上传前）、--xam（移动后）、--xar（重命名后）、--xad（删除后）、--xco（复制后）等。脚本第 1 个参数为事件对象（上传后场景为落盘文件的绝对路径）。

5.2 实测：上传后钩子

写一个记录脚本：

cat > /opt/copyparty/on-upload.sh <<'EOF'
#!/bin/bash
echo "$(date +%T) UPLOADED: $1" >> /tmp/hook.log
EOF
chmod +x /opt/copyparty/on-upload.sh

以 --xau '/opt/copyparty/on-upload.sh' 启动，随后上传一个文件，/tmp/hook.log 实测出现：

08:05:41 UPLOADED: /srv/party/drop/hook-test.txt

5.3 配置文件方式的坑

把 --xau 写在配置文件 [global] 段（或 CLI 全局）时，实测启动日志出现：

LOG 08:06:43 CRIT: cannot enable [xau] for volume "/" because this requires e2d/e2ds/e2dsa

原因是全局钩子要挂到内部根卷 / 上，而根卷没有开索引。处理：为承载卷开启 -e2d 系列索引，或把钩子以卷标志形式写进具体卷的 flags: 段（同样需该卷开启索引）。

六、配置文件实战与热重载

6.1 配置文件结构

--cgen 生成 + 手工整理后的生产配置（实测可用）：

[global]
  name: fileserver

[accounts]
  admin: q1w2e3r4
  uploader: q1w2e3r5

[/pub]
  /srv/party/pub
  accs:
    r: *
    rwmda: admin

[/drop]
  /srv/party/drop
  accs:
    w: *
    rwmda: admin

[/pics]
  /srv/party/pics
  accs:
    r: *
    rwmda: admin

[/music]
  /srv/party/music
  accs:
    r: *
    rwmda: admin

结构要点：[global] 放全局参数；[accounts] 一行一个账户；[/URL] 段第一行是磁盘路径，accs: 下每行"权限字母: 账户列表"，flags: 下放卷标志。启动：python3 copyparty-sfx.py -c /etc/copyparty/cpp.conf。

6.2 热重载

修改配置文件后无需重启服务：管理员访问 http://<host>:3923/?reload=cfg&pw=<管理员密码> 即可。实测在 [accounts] 新增 admin2 并将其加入 /pub 的 rwmda 组，触发 reload 后日志回显：

LOG 08:07:41 reloading config
LOG 08:07:41 reload #1 scheduled: first scan before writing the new db - this may take a while
LOG 08:07:41 reload #1 running

随后用新账户上传验证：

=== admin2 写 /pub（reload 前不存在，成功即证明热重载生效）===
201

密码修改同样即时生效（新密码可登录、旧密码失效），无需重启服务。

七、参数速查清单

参数作用实测要点
-a user:pass定义账户不同账户密码必须不同；账户需被卷引用
-v src:url:perms挂载卷与 ACL权限组结构 字母组:账户；写权限默认不可见所传文件
-p PORTHTTP 端口（默认 3923）修改后日志 now serving @ http://0.0.0.0:PORT/
-e2d / -e2ds / -e2dsa文件索引搜索/去重/钩子的基础；?scan 触发重扫
--th-size 等缩略图参数缩略图策略无 Pillow 时返回 SVG 占位图
--q-opus / --q-mp3转码码率/质量?th=opus 请求转码流，?ab= 无效
--xau 脚本 等事件钩子需所在卷开启 e2d 索引
--nc NUM单 IP 并发连接上限默认 64
--df 10Gi磁盘预留水位低于阈值拒绝写入
--ban-pw 9,60,1440密码错误封禁实测第 10 次错误起 403
-c PATH加载配置文件可叠加；配合 ?reload=cfg 热重载
--cgen由命令行参数生成配置文件学习配置语法的最快途径

带宽限速方面再次强调：copyparty 1.20.26 未提供限速参数，流量管控需在系统层或反向代理层实现。下一篇《copyparty 1.20.26 常用 CLI 命令详解》给出服务端参数矩阵与 curl/WebDAV 客户端命令的完整清单。