copyparty Podman + systemd 部署实战：.container 服务文件的 Root 与 Rootless 双模式配置解析

本篇指南以 contrib/podman-systemd/README.md 为核心，完整讲解如何用 Podman 容器 + systemd 服务的方式托管 copyparty 文件服务器：包括 .container 服务文件与 copyparty.conf 配置文件逐行解析、root 与 rootless 非 root 两种部署模式的完整操作步骤、systemd generator 故障排查方法，以及基于 podman-auto-update 的版本更新策略。读完后你可以直接在 Linux 服务器上复制粘贴完成部署，并能理解每一行配置背后的作用。

1. 方案原理：.container 文件如何变成 systemd 服务

这套部署方案的骨架是 Podman 的 Container unit（.container 文件）。systemd 本身并不认识 .container 文件，而是由 Podman 提供的 systemd-generator 程序把 .container 文件透明地转换为标准的 .service 单元，再交给 systemd 管理。这样做的好处是：容器的生命周期（开机自启、崩溃重启、日志采集、健康检查）完全交给 systemd 处理，可靠性等同于普通系统服务。

需要预先满足一个前提：服务器上已安装 Podman。官方 README 提示，安装方法可参考 Podman 官方安装文档；部署完成后无需手动 systemctl enable，.container 文件中的 [Install] 段实际上就承担了 enable 的作用。

该目录包含两个核心文件：

• copyparty.container：systemd 容器服务单元，定义镜像、端口、卷、健康检查等；
• copyparty.conf：copyparty 应用自身的配置文件，随卷挂载进容器。

2. 逐行解析 copyparty.container 服务文件

以下逐项解析 copyparty.container 中的关键指令：

2.1 镜像与命名

[Container]
# It's recommended to replace :latest with a specific version
# for example: docker.io/copyparty/ac:1.19.15
Image=docker.io/copyparty/ac:latest
ContainerName=copyparty

# Uncomment to enable auto-updates
# AutoUpdate=registry

• Image 指定使用 copyparty/ac 镜像。ac 版是官方推荐的发行版，在 scripts/docker/README.md 的 edition 列表中说明：ac 在基础版之上带 Pillow、FFmpeg，支持图片/音视频缩略图、音频转码和媒体标签解析，体积约 163 MiB（压缩后 56 MiB），是各版本中功能与体积平衡最佳的推荐选择。其构建定义见 scripts/docker/Dockerfile.ac（基于 Alpine，安装 py3-jinja2、py3-paramiko、py3-pillow 等依赖）。
• 注释明确建议把 :latest 换成固定版本号（如 1.19.15）。这是更新策略的关键：README 指出"如果设置为 :latest，Podman 不会自动重新拉取镜像"，固定版本则可预测地控制更新时机（见第 7 节）。
• AutoUpdate=registry 默认被注释，启用后可配合 podman-auto-update 定时器自动更新（见 7.3 节）。

2.2 环境变量：mimalloc 与日志不缓冲

# Environment variables
# enable mimalloc by replacing "NOPE" with "2" for a nice speed-boost (will use twice as much ram)
Environment=LD_PRELOAD=/usr/lib/libmimalloc-secure.so.NOPE
# ensures log-messages are not delayed (but can reduce speed a tiny bit)
Environment=PYTHONUNBUFFERED=1

• LD_PRELOAD 指向 libmimalloc-secure.so.NOPE——注意文件名末尾的 .NOPE 是一个"占位关闭"技巧：把 NOPE 替换为 2（即 libmimalloc-secure.so.2，该库确实存在于镜像中，scripts/docker/Dockerfile.ac 通过 apk add mimalloc2 mimalloc2-insecure 安装）即可启用 mimalloc 内存分配器。scripts/docker/README.md 给出参考数据：启用后下载打包 zip 约提速 3 倍、文件系统索引约提速 1.5 倍，代价是内存占用翻倍；换成 -insecure 变体可再多约 10% 速度但降低内存破坏类漏洞的利用难度缓冲。
• PYTHONUNBUFFERED=1 保证 Python 日志不经过输出缓冲，直接写入 stdout 被 journal 收集，日志实时可见，代价是极轻微的性能损失。

2.3 端口发布

# Ports
PublishPort=3923:3923

把宿主机 3923 映射到容器 3923。3923 是 copyparty 的默认监听端口，源码中 __main__.py 的 -p 参数 default="3923"（见 copyparty/main.py）可以佐证。ac 镜像的 Dockerfile 也声明了 EXPOSE 3923。

2.4 卷挂载：配置目录与共享目录

# Volumes (PLEASE LOOK!)

# Rootful setup:
#   Leave as-is
# Non-root setup:
#   Change /etc/copyparty to /home/<USER>/copyparty/config
Volume=/etc/copyparty:/cfg:z

# Rootful setup:
#   Change /mnt to the directory you want to share
# Non-root setup:
#   Change /mnt to something owned by your user, e.g., /home/<USER>/copyparty/sharing:/w:z
Volume=/mnt:/w:z

两条 Volume 是整个部署中最需要按环境修改的部分（文件内注释甚至用 "PLEASE LOOK!" 强调）：

• /cfg 是容器内的配置目录。为什么是 /cfg？因为镜像构建时设置了 ENV XDG_CONFIG_HOME=/cfg（scripts/docker/Dockerfile.ac），而 copyparty 的运行时状态与配置发现逻辑优先读取 XDG_CONFIG_HOME 环境变量——这在 copyparty/main.py 的 get_unixdir() 中可以看到：它首先检查 XDG_CONFIG_HOME，将其视为最高优先级的可信配置位置。把 *.conf 文件放进宿主机挂载到 /cfg 的目录，即可被容器加载。
• /w 是容器内默认共享的"当前目录"（工作目录），把想分享的文件系统目录挂进来即可。
• 挂载选项 :z 是 SELinux 场景必需的标签共享标志（scripts/docker/README.md 中同样建议：有 SELinux 时给所有卷追加 :z）；非 SELinux 系统保留也无害。

2.5 停止超时

# Give the container time to stop in case the thumbnailer is still running.
# It's allowed to continue finishing up for 10s after the shutdown signal, give it a 5s buffer
StopTimeout=15

copyparty 的缩略图/索引进程（thumbnailer）在收到关闭信号后还允许继续工作 10 秒收尾，因此 StopTimeout 设为 15 秒（10 秒收尾 + 5 秒余量），避免 systemd 过早强杀容器导致索引写入不完整。

2.6 健康检查

# hide it from logs with "/._" so it matches the default --lf-url filter
HealthCmd="wget --spider -q 127.0.0.1:3923/?reset=/._"
HealthInterval=1m
HealthTimeout=2s
HealthRetries=5
HealthStartPeriod=15s

每分钟执行一次 wget --spider（只发 HEAD 类探测、不下载内容）请求容器内 127.0.0.1:3923 的健康探测。URL 路径刻意写成 ?reset=/._：/._ 前缀命中 copyparty 默认的 --lf-url 日志过滤规则，使这条周期性探测请求不会污染访问日志。HealthStartPeriod=15s 给容器启动留出宽限期，HealthRetries=5 表示连续 5 次失败才判定不健康。

2.7 单元元数据与启动超时

[Unit]
After=default.target

[Install]
# Start by default on boot
WantedBy=default.target

[Service]
# Give the container time to start in case it needs to pull the image
TimeoutStartSec=600

[Install] 段的 WantedBy=default.target 就是开机自启的依据——这也是 README 特别说明"不能对这种 Podman 服务执行 systemctl enable"的原因：.container 文件本身已承担 enable 语义。TimeoutStartSec=600 把 systemd 判定的启动超时放宽到 10 分钟，覆盖首次部署时拉取镜像的时间。

3. 逐行解析 copyparty.conf 应用配置

contrib/podman-systemd/copyparty.conf 是随仓库提供的示例配置，分三个段落：

[global]
  e2dsa  # enable file indexing and filesystem scanning
  e2ts   # and enable multimedia indexing
  ansi   # and colors in log messages

• e2dsa 启用文件系统扫描与文件索引（建立 .hist 索引库）；
• e2ts 启用多媒体索引；
• ansi 让日志消息带颜色。日志默认进 stdout/journal，因此 journald 中可见彩色日志。

  # q, lo: ${LOGS_DIRECTORY}/%Y-%m%d.log

被注释掉的 q, lo: 行演示了"改为写文件日志"的方式：$LOGS_DIRECTORY 由 systemd 注入（通常是 /var/log/copyparty），copyparty 会把 %Y-%m%d 替换为"年-月日"格式日期，最终路径形如 /var/log/copyparty/2023-1130.txt；在路径末尾加 .xz 可开启日志压缩。

  # p: 80,443,3923   # listen on 80/443 as well (requires CAP_NET_BIND_SERVICE)
  # i: 127.0.0.1     # only allow connections from localhost (reverse-proxies)
  # ftp: 3921       # enable ftp server on port 3921
  # p: 3939         # listen on another port
  # df: 16          # stop accepting uploads if less than 16 GB free disk space
  # ver             # show copyparty version in the controlpanel
  # grid            # show thumbnails/grid-view by default
  # theme: 2        # monokai
  # name: datasaver # change the server-name that's displayed in the browser
  # stats, nos-dup  # enable the prometheus endpoint, but disable the dupes counter (too slow)
  # no-robots, force-js  # make it harder for search engines to read your server

这段注释是一个参数速查表：监听端口（80/443 需要 CAP_NET_BIND_SERVICE 能力）、仅回环监听以配合反向代理、启用 FTP 服务端、磁盘剩余不足 16 GB 时拒绝上传（df: 16）、Prometheus 指标端点等。

  #vc-url: https://api.github.com/repos/9001/copyparty/security-advisories?per_page=9
  #vc-url: https://api.copyparty.eu/advisories
  vc-exit  # panic and shutdown instead of just showing the warning

版本检查（version-checking）部分：取消注释某条 vc-url 即可开启漏洞通告检查，控制面板出现已知漏洞警告横幅；vc-exit 则把"显示警告"升级为"恐慌并关机"，适合作为无人值守服务器的安全姿态。

[accounts]
  ed: wark  # username: password

[accounts] 段以 用户名: 密码 形式声明账号，示例账号为 ed / wark，生产环境应替换。

[/]            # create a volume at "/" (the webroot), which will
  /w           # share the contents of the "/w" folder
  accs:
    rw: *      # everyone gets read-write access, but
    rwmda: ed  # the user "ed" gets read-write-move-delete-admin
  flags:
    e2ds       # enable filesystem-scanning for this volume only
    # uid: 1000  # If you're running as root, you can change the owner of this volume here
    # gid: 1000  # If you're running as root, you can change the group of this volume here

[/] 段在 webroot 根路径创建卷，映射到容器内的 /w（即 2.4 节挂载进来的共享目录）。accs: 声明访问控制：rw: * 表示所有登录用户可读写的同时，rwmda: ed 给 ed 用户额外授予 move/delete/admin 权限。flags: 段的 uid:/gid: 用于 root 模式运行容器时调整该卷内文件的属主归属——README 中"可以通过修改 copyparty.conf 中卷的 uid: 和 gid: 来选择卷属主"指的就是这里；非 root 模式下由容器内用户天然决定属主，无需设置。

4. Root 模式部署（简单，安全性较低）

README 明确指出：以 root 运行容器"容易配置但安全性较低"。适用场景是信任度高、配置简单的服务器。

4.1 修改共享目录

先把 copyparty.container 中的默认共享目录从 /mnt 改成你要分享的目录：

# Change /mnt to something you want to share
Volume=/mnt:/w:z

并按 2.4 节说明，如需调整卷属主，修改 copyparty.conf 中卷的 uid:/gid:（默认按 root:root 处理）。

4.2 安装并启动

sudo mkdir -pv /etc/containers/systemd/ /etc/copyparty/
sudo cp -v copyparty.container /etc/containers/systemd/
sudo cp -v copyparty.conf /etc/copyparty/
sudo systemctl daemon-reload
sudo systemctl start copyparty

要点：

• 系统级 .container 单元放在 /etc/containers/systemd/，generator 会将其转换后的 .service 注入 systemd；
• 配置文件放到 /etc/copyparty/，与 .container 中 Volume=/etc/copyparty:/cfg:z 对应；
• daemon-reload 是必需的，让 systemd 重新运行 generator 并识别新单元；
• 如 README 所强调：不要试图 systemctl enable copyparty，[Install] 段已负责开机自启。

4.3 状态与日志

sudo systemctl status -a copyparty

sudo podman logs -f copyparty

# -a 参数必须带上，否则会看到 copyparty[549025]: [649B blob data] 这类截断输出
sudo journalctl -a -f -u copyparty

README 特别提示 journalctl 必须加 -a：彩色日志（ansi 标志）中的控制字节会被 journald 按"二进制 blob"折叠，-a（--all 的短形式，此处实际起展开显示作用的是 journalctl 的完整输出模式）避免 [649B blob data] 式的截断显示。

5. Rootless 非 root 模式部署（更安全，步骤更多）

README 评价此模式"更安全，但更繁琐，需要确保文件权限正确，且部分设置需要 root 账号"。

5.1 创建运行容器专用用户

示例创建一个 UID=1001、GID=1001 的 podman 用户：

sudo groupadd -g 1001 podman
sudo useradd -u 1001 -m podman
sudo usermod -aG podman podman
sudo loginctl enable-linger podman
# Set a strong password for this user
sudo -u podman passwd

loginctl enable-linger 是关键一步：它允许该用户的 systemd user 服务在没有任何会话登录时持续运行（否则用户注销后容器服务会被终止）。README 说明也可以复用系统已有的用户，只要对其执行 loginctl enable-linger USERNAME。

5.2 修改卷路径

编辑 copyparty.container，把两个卷指向非 root 用户的主目录（README 默认示例为 /home/podman/copyparty/ 下）：

# Change to reflect your non-root user's home directory
Volume=/home/podman/copyparty/config:/cfg:z

# Change to the directory you want to share
Volume=/home/podman/copyparty/sharing:/w:z

并确认 podman 用户对这两个目录都有读写权限（属主应为该用户）。

5.3 以 podman 用户身份安装

必须先登录到服务器上的 podman 用户（su - podman 或 SSH 登录），然后执行（全程不加 sudo）：

mkdir -pv /home/podman/.config/containers/systemd/ /home/podman/copyparty/config
cp -v copyparty.container /home/podman/.config/containers/systemd/copyparty.container
cp -v copyparty.conf /home/podman/copyparty/config
systemctl --user daemon-reload
systemctl --user start copyparty

与 root 模式的差异在于：用户级单元放在 ~/.config/containers/systemd/，systemd 操作全部加 --user。README 加粗警告：systemctl --user 永远不要配 sudo 使用——sudo 会切换到 root 的 user manager，操作的就不是 podman 用户的单元了。

5.4 状态与日志

systemctl --user status -a copyparty

podman logs -f copyparty

journalctl --user -a -f -u copyparty

6. 故障排查：调试 systemd-generator

如果容器启动失败、且你修改过 .container 文件，最常见的原因是 .container 文件没有成功翻译成 .service 文件（例如语法写错）。用 generator 自带的 dryrun 模式调试：

sudo /usr/lib/systemd/system-generators/podman-system-generator --dryrun

该命令会打印 generator 的解析过程与翻译结果，能直接定位是哪一行指令不被识别。非 root 模式对应的是用户空间 generator，排查思路相同。

7. 网络放行、更新与自动更新

7.1 放行外部流量

容器只把 3923 发布到本机，服务器防火墙（示例基于 firewalld）必须额外放行，否则只有服务器本机能访问：

sudo firewall-cmd --permanent --add-port=3923/tcp
sudo firewall-cmd --reload

7.2 手动更新

# If root:
sudo podman pull docker.io/copyparty/ac:latest
sudo systemctl restart copyparty

# If non-root:
podman pull docker.io/copyparty/ac:latest
systemctl --user restart copyparty

或者，直接把 .container 文件 [Container] 段中的镜像 tag 改成想要的固定版本（如 docker.io/copyparty/ac:1.19.15），然后重载并重启：

# If root:
sudo systemctl daemon-reload
sudo systemctl restart copyparty

# If non-root:
systemctl --user daemon-reload
systemctl --user restart copyparty

README 解释了一个关键机制：重启时 Podman 会按 Image 指定的 tag 拉取镜像；但若 tag 是 :latest 且本地已有缓存，Podman 并不知道要重新拉取——这正是官方建议"用固定版本 pin 住镜像"的原因。

7.3 启用自动更新（AutoUpdate）

在 copyparty.container 中取消注释：

# AutoUpdate=registry

再启用 podman 的 auto-updater 定时服务（官方文档见 podman-auto-update 手册）：

# If root:
sudo systemctl enable podman-auto-update.timer podman-auto-update.service

# If non-root:
systemctl --user enable podman-auto-update.timer podman-auto-update.service

auto-updater 每 24 小时运行一次，适合"永远要用最新版 copyparty"的场景。README 提醒：这种模式意味着更新是无人值守的，copyparty.conf 中配置好的 vc-exit（发现已知漏洞版本即关机）可以作为一道安全兜底。

8. 落地清单小结

环节	Root 模式	Rootless 模式
.container 位置	/etc/containers/systemd/	~/.config/containers/systemd/
配置卷 Volume=...:/cfg:z	/etc/copyparty	/home/<USER>/copyparty/config
共享卷 Volume=...:/w:z	如 /mnt	用户自有的如 /home/<USER>/copyparty/sharing
systemd 前缀	sudo systemctl	systemctl --user（禁止 sudo）
附加前提	—	loginctl enable-linger <USER>
日志	sudo journalctl -a -f -u copyparty	journalctl --user -a -f -u copyparty

部署时把 contrib/podman-systemd/ 下两个文件拷入目标服务器，按第 4 或第 5 节操作即可；所有镜像侧行为（/cfg 配置目录、3923 端口、mimalloc 开关、缩略图收尾时间）都能在本仓库的 scripts/docker/Dockerfile.ac 与 scripts/docker/README.md 中找到对应实现与说明，方便进一步定制镜像或排查行为差异。