copyparty 在 Windows 上部署实战：配置文件详解与 NSSM 服务化完整指南

copyparty 官方在 docs/examples/windows.md 中提供了一份在 Windows 上运行 copyparty 的完整示例，涵盖三种部署形态：控制台前台运行、copyparty.exe 单文件运行、以及 copyparty-sfx.py + Python 解释器运行，并可选地通过 NSSM 注册为开机自启的 Windows 服务。本文以该文档为主线，完整继承其配置文件示例与操作步骤，并结合仓库源码解释每个配置项（lo、e2dsa、e2ts、z、p、theme、lang、accs 权限位）在 copyparty 内部是如何被解析和生效的，帮助读者从零搭建一个带索引、缩略图、Zeroconf 发现和三卷权限管理的局域网文件服务。

准备工作：获取可运行文件与 FFmpeg

文档首先指出，Windows 上运行 copyparty 需要二选一：

• copyparty.exe：打包好的单文件可执行程序，开箱即用、功能更完整；
• copyparty-sfx.py：体积更小、更安全的自解压 Python 脚本，需要额外安装 Python 3 运行环境。

两者的取舍会影响后续 NSSM 注册服务的命令形式（后文会展开）。

其次，文档强烈建议下载 FFmpeg（git 完整构建包），并把 ffmpeg.exe 和 ffprobe.exe 放入 PATH（例如 C:\Windows\System32\）。FFmpeg 是 copyparty 多媒体的后端依赖，启用后带来三项能力：

1. 缩略图生成：图片/音频/视频缩略图；
2. 音频转码：浏览器播放前的按需转换；
3. 音乐元数据索引：让专辑名、曲名等标签可被搜索。

源码层面可以印证这一点：-e2t* 系列的多媒体标签索引（artist/title 等）依赖 ffprobe 提取标签，相关逻辑位于 copyparty/up2k.py 的标签扫描流程中；而缩略图/转码相关的配置项（dthumb、th_qv、convt 等）定义在 copyparty/cfg.py 的参数帮助表中。仓库还附带了一个 Windows 环境修复脚本 contrib/windows/copyparty-ctmp.bat，用于在系统环境变量（TMP）损坏时通过 cmd /v /c "set TMP=\tmp && copyparty.exe" 启动 copyparty.exe——这是 Windows 部署中一个容易踩到的坑。

编写配置文件

文档建议在记事本中把下面的配置保存为 c:\users\you\documents\party.conf。这是 copyparty 的标准 ini 风格配置文件，包含 [global] 全局参数、[accounts] 账号表，以及三个卷定义：

[global]
  lo: ~/logs/cpp-%Y-%m%d.xz  # log to c:\users\you\logs\
  e2dsa, e2ts, z    # sets 3 flags; see explanation
  p: 80, 443  # listen on ports 80 and 443, not 3923
  theme: 2    # default theme: protonmail-monokai
  lang: nor   # default language: viking

[accounts]                  # usernames and passwords
  kevin: shangalabangala    # kevin's password

[/]               # create a volume available at /
  c:\pub          # sharing this filesystem location
  accs:           # and set permissions:
    r: *          # everyone can read/download files,
    rwmd: kevin   # kevin can read/write/move/delete

[/inc]            # create another volume at /inc
  c:\pub\inc      # sharing this filesystem location
  accs:           # permissions:
    w: *          # everyone can upload, but not browse
    rwmd: kevin   # kevin is admin here too

[/music]          # and a third volume at /music
  ~/music         # which shares c:\users\you\music
  accs:
    r: *
    rwmd: kevin

配置文件解析的入口在 copyparty/authsrv.py。从源码结构看，解析器按段识别 [global]、[accounts]、[groups]、[/卷名] 以及卷下的 accs: / flags: 子段（见 copyparty/authsrv.py#L1408-L1459）：[global] 段接受任意命令行参数（dash 可省略），[accounts] 段要求每行是 "username: password"，[/xxx] 卷定义段的第一行必须是共享的本地文件系统路径，否则会报错 the first line after [/xxx] must be a filesystem path。

[global] 段：等效于命令行参数

文档强调，[global] 段接受 --help 列出的任意配置参数，因此上面示例等价于用这些参数启动 copyparty：

copyparty.exe --lo c:\users\you\logs\copyparty-%Y-%m%d.xz -e2dsa -e2ts -z -p 80,443 --theme 2 --lang nor

逐项解析（结合 copyparty/cfg.py 中的官方参数帮助文本）：

配置	等价参数	作用
lo: ~/logs/cpp-%Y-%m%d.xz	--lo	日志写入 xz 压缩文件（压缩导致日志有延迟刷新），~ 在 Windows 下展开为当前用户目录，即 c:\users\you\logs\
e2dsa	-e2dsa	启动时扫描所有文件夹为新文件建立数据库索引，隐含 -e2ds；启用后文件可搜索，并支持上传撤销（upload-undo）
e2ts	-e2ts	启动时对已存在的媒体文件扫描元数据标签（artist/title/专辑），隐含 -e2t；注意文档特别指出：它不影响 e2dsa 带来的加速上传效果
z	-z	启用 zeroconf（mDNS/SSDP 广播），让局域网内其他设备可以通过 http://HOSTNAME.local/ 发现并访问该服务
p: 80,443	-p 80,443	监听 80 和 443 端口，替代默认的 3923 端口
theme: 2	--theme 2	默认主题设为 protonmail-monokai
lang: nor	--lang nor	默认界面语言设为北欧语（"viking"）

这些参数在源码中的定义可以逐一验证：-e2dsa（"scans all folders on startup; sets -e2ds"）与 -e2ts（"scan newly discovered files for metadata on startup; sets -e2t"）定义于 copyparty/main.py#L1944-L1976，帮助文本与 copyparty/cfg.py#L276-L281 的参数表一致。e2dsa → e2ds、e2tsr → e2ts → e2t 的隐含关系在 copyparty/util.py#L424-L427 中显式列出——即文档中"e2dsa 加速上传、e2ts 只加标签"这一区分的底层依据。

另外注意一个权限前提：从源码结构看，e2dsa 的启动索引行为与卷的写权限存在联动校验逻辑（copyparty/authsrv.py#L2450 处按 e2ds and vol.axs.uwrite 或 e2dsa 判断），若对某些卷启用了基于符号链接的去重但没开索引，copyparty 启动时会发出警告提示启用 -e2dsa（copyparty/authsrv.py#L3055）。本示例中三个卷都给了 kevin rwmd 权限，因此索引功能可完整生效。

[accounts] 段：用户表

[accounts] 段定义全部账号，username: password 一行一个用户。示例中只有一个用户 kevin，其密码是 shangalabangala。这些账号随后被各卷的 accs: 段引用，作为授权对象。源码解析处见 copyparty/authsrv.py#L1476-L1488，格式不合法会直接抛出 lines inside the [accounts] section must be "username: password" 的配置错误。

卷定义与 accs 权限位

文档创建了三个卷：

• / → 共享 c:\pub：所有人可匿名读/下载（r: *），只有登录 kevin 才能写/移动/删除（rwmd: kevin）；
• /inc → 共享 c:\pub\inc：任何人可上传但不能浏览目录（w: *），只有 kevin 能看到里面有什么；
• /music → 共享 ~/music（即 c:\users\you\music）：权限与 / 相同。

accs 权限位的完整集合是 rwmdgGhaA. 加通配 *，其中 A 等价于 rwmda.（读/写/移动/删除/点文件）。这一点可以从 copyparty/authsrv.py#L1530 的校验正则 re.sub("[rwmdgGhaA.]", "", sk) 和错误提示 "accs entries must be 'rwmdgGhaA.: user1, user2, ...'" 得到印证；权限字符 A 的语义（"all; same as 'rwmda.'"）记录在 copyparty/cfg.py#L219。

/inc 卷是本例的亮点：w: * 授予匿名上传但不授予读，形成"只进不出"的收件箱——陌生人可投递文件，但目录内容对未登录者不可见，这是纯权限位组合就能实现的典型用法，无需任何脚本。

控制台运行与测试

文档建议先以控制台前台方式测试配置，便于观察输出：

使用 copyparty.exe：

copyparty.exe -c party.conf

或使用 copyparty-sfx.py（需替换 python311 为实际安装的 Python 版本目录名）：

%localappdata%\programs\python\python311\python.exe copyparty-sfx.py -c party.conf

-c 即 --config，指向配置文件路径。启动后按配置，服务将监听 80/443 端口，日志滚动写入 c:\users\you\logs\cpp-*.xz，并在局域网内通过 zeroconf 以 HOSTNAME.local 广播。首次启动耗时偏长是正常的：e2dsa 会索引全部文件夹、e2ts 会对媒体文件提取标签（依赖已装好的 FFmpeg）。

注册为 Windows 服务（NSSM 开机自启）

要让 copyparty 随系统自启，文档采用的方案是 NSSM（Non-Sucking Service Manager）。先把 nssm.exe 放入 PATH，然后按所用运行形态二选一：

形态 A：基于 copyparty.exe

nssm install cpp %homedrive%%homepath%\downloads\copyparty.exe -c %homedrive%%homepath%\documents\party.conf

形态 B：基于 copyparty-sfx.py（把解释器作为可执行程序参数传入）

nssm install cpp %localappdata%\programs\python\python311\python.exe %homedrive%%homepath%\downloads\copyparty-sfx.py -c %homedrive%%homepath%\documents\party.conf

服务名统一取 cpp。安装完成后，文档要求将服务的运行账号改为你自己的 Windows 账户并附密码，这是两个关键动机：

1. 文件权限：服务进程需要以你的账户身份访问 c:\pub、~/music 等用户目录，避免默认的 SYSTEM/LOCAL SERVICE 账户遇到权限异常；
2. 路径展开：配置里的 ~、%homedrive%、%homepath% 等只有在用户会话下才能正确展开。

nssm set cpp ObjectName .\yourAccoutName yourWindowsPassword
nssm start cpp

服务不启动时的排查

文档给出了最后的排查手段：为服务开启 stderr 日志，观察具体报错：

nssm set cpp AppStderr %homedrive%%homepath%\logs\cppsvc.err
nssm set cpp AppStderrCreationDisposition 2

AppStderrCreationDisposition 2 表示以"打开或创建"模式写日志文件，便于反复启动时追加错误信息。由于本例 [global] 已经配置了 lo: ~/logs/cpp-%Y-%m%d.xz，copyparty 自身的运行日志会同时写入 xz 文件；NSSM 捕获的 stderr 则专门用于诊断"进程根本没起来"这类启动期故障（例如配置解析失败、端口 80/443 被占用——80/443 在 Windows 上经常被 IIS/World Wide Web Publishing Service 抢占，这是该示例选 80/443 时最需要留意的现实约束）。

小结与可深挖的仓库资源

按以上流程，你在 Windows 上获得的是一个监听 80/443、三卷权限隔离、支持文件与音乐标签搜索、缩略图生成与局域网自动发现的 copyparty 服务，且已随系统自启。后续若想调整行为，可直接参考仓库中的这些材料：

• 全量参数速查：copyparty/cfg.py 内嵌的参数帮助表（与 --help 输出同源）；
• 更复杂的配置范式（含 flags: 子段、[groups] 用户组、上传限额 maxb/maxn 等）：docs/example.conf 与 docs/example2.conf；
• 配置文件解析与 accs 权限校验的实现：copyparty/authsrv.py；
• 命令行参数定义：copyparty/main.py；
• 同类部署文档可对照 docs/examples/docker 下的 Docker 示例，以及 contrib/windows/copyparty-ctmp.bat 提供的 Windows 环境修复启动方式。