copyparty + Portainer 部署实战：Bind Mount 配置、/cfg 与 /w 卷挂载详解

本篇指南讲解如何在 Portainer CE（Docker CE 后端）的可视化界面中手动创建 copyparty 容器，覆盖部署前的宿主机目录准备、端口发布、/cfg 与 /w 两个关键 Bind 卷的映射、交互式控制台设置，以及首启后运行时状态（如自签 TLS 证书）的落盘位置。读完后你可以脱离命令行，完全通过 Portainer 网页界面把一个可持久化配置、可接受上传的 copyparty 文件服务器跑起来，并理解每个参数背后镜像的约定。

适用环境与前提

该方案在 Debian 12 上，以 Portainer CE 搭配 Docker CE 作为后端、以 root 模式（非 rootless）运行 Docker 的场景下得到验证。如果你使用 rootless Podman，容器用户参数会不同（参考 scripts/docker/README.md 中关于 -u 1000 的说明：rootless podman 下应移除 -u 1000）；如果你有 SELinux，给每个 -v 参数追加 :z 后缀（如 docker-compose 示例 中 . /:/cfg:z 的写法）。

创建容器之前，先在宿主机上建好两个目录，它们稍后将被 Bind-mount 进容器：

mkdir /etc/copyparty /srv/pub

• 把 copyparty 的配置文件（*.conf 文件）直接放进 /etc/copyparty；
• 把要对外共享的文件放进 /srv/pub。

这两个路径（/etc/copyparty 和 /srv/pub）只是示例，你可以按自己习惯替换。

容器内两个关键路径：/cfg 与 /w

在 Portainer 里配置卷之前，先弄清镜像对这两个容器内路径的约定：

• /cfg 是 copyparty 查找配置文件的位置。/etc/copyparty 只是宿主机侧映射到它的示例路径。这一约定的实现依据在 Docker 镜像中：Dockerfile.ac 里设置了 ENV XDG_CONFIG_HOME=/cfg，同时 WORKDIR /state、EXPOSE 3923，入口为 ENTRYPOINT ["/bin/ash", "/z/cpp.sh", "-c", "/z/initcfg"]——即镜像默认监听 3923 端口，并把 XDG 配置目录指向 /cfg。
• /w 是 copyparty 默认共享的文件夹（相当于容器内的"当前目录"），/srv/pub 只是宿主机侧映射到它的示例路径。这与 scripts/docker/README.md 的说明一致：/w 是容器内默认被共享的路径，/cfg 是放零个或多个 *.conf 配置文件的可选目录。

为什么要用 Bind Mount 而不是 named volume？ 原始部署笔记给出的理由是需要避免权限问题（原文表述为 "to avoid permission issues (or so the theory goes)"，即这是一种经验性做法而非绝对保证）。

在 Portainer 中逐步创建容器

进入 environments → local → containers → add container，按如下参数填写：

       name = copyparty-ac
   registry = docker hub
      image = copyparty/ac
always pull = no

manual network port publishing:
  3923 to 3923 [TCP]

advanced -> command & logging:
  console = interactive & tty

advanced -> volumes -> map additional volume:
  container = /cfg  [Bind]
  host = /etc/copyparty  [Writable]

advanced -> volumes -> map additional volume:
  container = /w  [Bind]
  host = /srv/pub  [Writable]

逐项说明：

• image = copyparty/ac：官方推荐的镜像版本（见 scripts/docker/README.md 的 editions 一节）。ac 版 = im 版（Pillow 图片缩略图 + mutagen 媒体解析）再加 ffmpeg（视频/音频缩略图、音频转码、更好的标签解析），安装后约 163 MiB（gzip 约 56 MiB）。各版本大小与能力：

  版本	大小（安装后 / gzip）	能力
  min	57 MiB / 20	仅 copyparty 本体
  im	70 MiB / 25	Pillow 图片缩略图、mutagen 媒体解析
  ac	163 MiB / 56	im + ffmpeg（音视频缩略图、转码、标签）
  iv	211 MiB / 73	ac + libvips（更多缩略图格式）
  dj	309 MiB / 104	iv + beatroot/keyfinder（检测音乐调性与 BPM）

  架构支持方面，x86/x86_64/AArch64 支持全部版本，arm32、ppc64le、s390x 支持到 ac 为止。

• always pull = no：创建时不强制拉取，适合已本地缓存镜像或希望手动控制更新时机的场景。

• 端口 3923 → 3923 [TCP]：copyparty 的默认 HTTP(S) 服务端口，与 Dockerfile.ac 中的 EXPOSE 3923 对应。

• console = interactive & tty：保持容器交互式运行、分配 TTY，方便查看实时日志。

• 两个 Bind 卷均设为 Writable：/cfg 必须可写，因为 copyparty 首启会在其中创建运行时状态；/w 必须可写，因为默认共享是读写权限的。

首启行为与运行时状态落盘

首次启动时，copyparty 会在 /etc/copyparty 内部创建一个名为 copyparty 的子目录，在其中存放运行时状态。这解释了为什么 /cfg 一侧必须挂成 Writable：容器内 XDG_CONFIG_HOME=/cfg，首启时程序会在 $XDG_CONFIG_HOME/copyparty/ 下写入证书、会话数据库等状态文件（例如 changelog 提到 docker 环境下 sessions.db 落在 /cfg/sessions.db，与其他运行时配置同目录）。

一个实用的技巧：用你自己的 TLS 证书替换 /etc/copyparty/copyparty/cert.pem，是获得有效 HTTPS 的一种快速方式——前提是确实希望由 copyparty 自己处理 TLS，而不是交给反向代理。如果前面已有 Nginx/Traefik 等反代，通常不需要这一步。

验证部署与后续配置

容器启动后验证三件事：

1. 浏览器访问 http://<服务器IP>:3923，能看到文件列表界面（默认共享 /w，即宿主机 /srv/pub）；
2. 上传一个文件，确认它出现在 /srv/pub 中，证明 Writable 绑定生效；
3. 观察 /etc/copyparty 下出现了 copyparty 子目录（含 cert.pem 等首启产物），证明配置持久化生效。

后续如需定制行为，编辑 /etc/copyparty 中的 *.conf 文件即可（配置文件必须命名为 something.conf 才会被加载）。一个贴合 docker 场景的完整示例见 basic-docker-compose/copyparty.conf，其中展示了：

• [global] 段的 e2dsa（文件系统索引）、e2ts（多媒体索引）；
• p: 3939 换监听端口、ipa: 10.89. 或 ipa: lan 限制来源 IP、df: 16 在剩余磁盘低于 16 GB 时停止接受上传；
• [accounts] 段定义 用户名: 密码 账号，[/] 段把 /w 挂到 Web 根并设置 rw: *（所有人读写）、rwmda: ed（管理员）。

另外两点 docker 专属建议（来自 scripts/docker/README.md）：

• copyparty 默认会在每个卷顶部创建 .hist 目录存放文件系统索引与缩略图；为保持共享目录整洁并提升性能，可在 [global] 段加 hist: /cfg/hists/，把索引数据挪进配置目录；
• 若愿意用双倍内存换取性能，可设置环境变量 LD_PRELOAD=/usr/lib/libmimalloc-secure.so.2 启用 mimalloc（下载打包 zip 约 3 倍速、文件系统索引约 1.5 倍速）。

常见问题与边界说明

• named volume 替代 Bind Mount 是否可行：理论上可以，但原文作者建议用 Bind Mount 以避免权限问题；该部署笔记的验证范围是 Debian 12 + Portainer CE + Docker CE（root，非 rootless）组合，换环境（如 rootless、SELinux 开启）时需按 scripts/docker/README.md 的 FAQ 调整。
• always pull 的选择：设为 no 时镜像不会自动更新，安全更新需手动在 Portainer 中拉取新镜像并重建容器；copyparty 的镜像 tag 为 :latest，仓库中 Dockerfile.ac 显示基础镜像为 alpine:latest。
• 本文只覆盖 HTTP 服务（3923 端口）；若在容器内启用 FTP（ftp: 3921 等配置），还需额外发布被动模式端口区间（如 12000-12099）并配合 ftp-nat 设置，详见 scripts/docker/README.md 的 "enabling the ftp server" 一节，Portainer 界面中对应"端口范围发布"操作，此处不展开。

参考路径

• 本文对应的原始部署笔记：docs/examples/docker/portainer.md
• 镜像版本与通用 docker 说明：scripts/docker/README.md
• ac 镜像构建定义（XDG_CONFIG_HOME=/cfg、EXPOSE 3923、入口脚本）：scripts/docker/Dockerfile.ac
• 可直接复用的 compose 与配置示例：docs/examples/docker/basic-docker-compose/docker-compose.yml、docs/examples/docker/basic-docker-compose/copyparty.conf