pyLoad 配置参数详解

目标：把 pyLoad（pyload-ng）的全部配置体系讲透：两个配置文件（pyload.cfg 核心配置与 plugins.cfg 插件配置）的存放位置、逐节参数含义、默认值与实测值对照，容器环境变量（PUID/PGID/TZ）的实测效果，以及三种修改途径（WebUI / REST API / 直接改文件）的行为差异与生效规则。全部参数表基于 2026-10-28 在真实容器上的逐节读回（非转抄文档），部署过程见本专栏《pyLoad Docker Compose 部署实战》。

一、环境信息

二、配置体系总览

pyLoad 的配置分散在四类载体上，各管一摊，先建立全局地图：

两个关键实测结论，决定你的修改姿势：

1. pyload.cfg / plugins.cfg 是"声明式快照"：文件里每行都带类型与描述（int max_downloads : "Maximum parallel downloads" = 3），由核心在启动时解析、修改时整体重写。直接手改文件必须停服进行，否则运行中的核心随时会用内存值重写文件、覆盖你的修改（本次实测中两次 restart 均观察到 cfg 被重写）；
2. WebUI 与 REST API 改配置是"即时生效 + 立即落盘"：实测 set_config_value 修改 download.max_speed 后立刻读回文件已变为新值，无需重启。

💡 配置文件采用 pyLoad 自定义 INI 变体：节头是 Name - "Public Name":（没有方括号），键行格式 类型 键名 : "描述" = 默认值，节与节之间空行分隔。手工编辑时保持原格式，不要加 [ ]。

三、pyload.cfg 核心配置逐节详解

以下为 /config/settings/pyload.cfg 全量 7 节的逐节读回（2026-10-28 实测，默认值列即实测首启值；首启值为 trace 调试线等少数项与官方 pip 安装默认略有差异，以实测为准）。

3.1 general —— 全局行为

3.2 download —— 下载行为

3.3 log —— 日志

3.4 permission —— 权限（容器场景重点）

实测提醒：容器以 PUID/PGID=1000 运行时，下载产物天然属主 1000，与宿主普通用户一致，无需开启 change_dl；只有当下载目录被多个不同 uid 的服务共享读写时才需要动这一节。

3.5 proxy —— 出站代理

实测提示：pyLoad 的插件下载全部走此代理；国内服务器拉取境外网盘/直链卡顿时，把 enabled=True 指向本机代理是第一优先排查手段。

3.6 reconnect —— 路由器重连

3.7 webui —— Web 界面

四、容器环境变量（PUID / PGID / TZ）

官方 Dockerfile（lsiobase 系）通过 s6 的 init 容器阶段消费这三个变量，实测效果：

三条实测经验：

1. PUID/PGID 必须与宿主上你对 /config、/downloads 两个目录有读写权的 uid/gid 一致，否则首启即报权限错误（现象：日志反复 Permission denied 或 WebUI 502）；
2. 改 PUID/PGID 后需重建容器（docker compose up -d）才重新映射身份；已有配置文件属主不会自动 chown，必要时手动 chown -R；
3. TZ 只影响日志展示与时段类配置（start_time/end_time）的语义，务必与服务器实际所在时区一致，否则"错峰下载"窗口会整体偏移。

五、plugins.cfg 插件配置（339 节）结构与代表性节

plugins.cfg 由插件管理器在首次启动时按插件源码内的 __config__ 声明自动生成，2026-10-28 实测共 339 节。结构规律（以实测节为例）：

hoster 节（站点下载插件，如 YoutubeCom）—— capability 开关为主：

YoutubeCom - "YoutubeCom":
	bool .3gp : "Allow .3gp" = False
	bool .flv : "Allow .flv" = True
	bool .mp4 : "Allow .mp4" = True
	...

addon 节（自动化插件，如 ExternalScripts）—— 核心是 enabled：

ExternalScripts - "ExternalScripts":
	bool enabled : "Activated" = True
	bool unlock : "Execute script concurrently" = False

extractor 适配器节（如 UnRar）—— 后端行为参数：

UnRar - "UnRar":
	bool ignore_file_attributes : "Ignore File Attributes" = False
	bool ignore_warnings : "Ignore unrar warnings" = False

通用节骨架（绝大多数 hoster/account 插件共有，与 pyLoad 对接站点的方式强相关）：

ExtmatrixCom - "ExtmatrixCom":
	bool chk_filesize : "Check file size" = True
	bool enabled : "Activated" = True
	bool fallback : "Fallback to free download if premium fails" = False
	int max_wait : "Reconnect if waiting time is greater than minutes" = 10
	bool use_premium : "Use premium account if available" = True

四个高频实操点（全部实测验证）：

1. 解包全链路的开关组合：ExtractArchive（addon 总开关，默认关）+ UnZip/UnRar/SevenZip/UnTar（适配器，默认关）必须同时置 enabled = True 才会自动解包——这是新装 pyLoad 最常见的"为什么不解压"根因；
2. 改 enabled 的正规姿势是 API/WebUI：set_config_value（section 传 plugin）写入即持久化，实测回显 null 且文件即时更新；直接手改文件则必须停服；
3. 插件配置会随插件更新而演进：插件管理器启动时按插件源码重新生成缺省节（bool enabled : "Activated", False 是 addon 类的兜底），旧节不会被删除，升级后新参数以默认值出现；
4. 一节一插件、节名即插件名：service_call、账号绑定、日志标签里的插件名与节名严格一致（如 ExtractArchive、UnZip），排障时可以按名对齐。

六、accounts.cfg 账户配置

首启时按全部账户类插件生成空节骨架（实测节选）：

version: 1

AccioDebridCom:

AlldebridCom:

ArchiveOrg:

绑定真实账户后，对应节内写入凭据（WebUI → Accounts 页或 POST /api/add_account）。实测注意：凭据为明文落盘，accounts.cfg 权限为 0600（实测 -rw-------），备份该文件时一并注意保管；主机被入侵等同于全部高级账户泄露。

七、修改途径对比与生效规则（实测结论）

API 读写的完整实测回路（2026-10-28 真实回显）：

# 读 webui 端口
curl -s -H "X-API-Key: $KEY" 'http://127.0.0.1:8133/api/get_config_value?category=webui&option=port&section=core'
# 实测回显：8000

# 读并行下载数
curl -s -H "X-API-Key: $KEY" 'http://127.0.0.1:8133/api/get_config_value?category=download&option=max_downloads&section=core'
# 实测回显：3

# 改总限速为 512 KiB/s
curl -s -H "X-API-Key: $KEY" -X POST http://127.0.0.1:8133/api/set_config_value \
  -H 'Content-Type: application/json' \
  -d '{"category":"download","option":"max_speed","value":512,"section":"core"}'
# 实测回显：null   （cfg 文件同步落盘）

八、排障实录

1. 改了 pyload.cfg 不生效：运行中手改被覆盖（本文第二节机制）。实测中两次 restart 均观察到 cfg 被核心重写。正确姿势：API 修改或停服手改。
2. PUID 改了但配置文件属主没变：s6 只在新文件创建时应用 uid；存量文件需手动 chown -R 1000:1000 /config /downloads 后重启。
3. 时区不对导致下载时段错位：TZ 未设置时容器回退 UTC，start_time/end_time 窗口整体偏移 8 小时（东八区）；实测设置 TZ=Asia/Shanghai 后 date 即回显 CST。
4. 解包不触发：优先检查 ExtractArchive 与对应适配器两层的 enabled（第五节第 1 点）；若曾用错误参数手动触发过解包，还需清理 pyload.db 中 storage 表的残留队列（详见部署篇排障实录坑 4）。
5. 插件节丢失：plugins.cfg 手工删节后重启会按插件源码自动再生（配置快照机制），想永久关一个插件应改 enabled=False 而不是删节。

九、参考链接

• 部署与目录挂载：本专栏《pyLoad Docker Compose 部署实战》
• 命令行与 API 运维：本专栏《pyLoad 常用命令与运维实战（核心篇）》
• 版本与生态背景：本专栏《pyLoad 介绍与选型指南》
• 官方源码（配置解析：src/pyload/core/config/；插件管理器：src/pyload/core/managers/plugin_manager.py）：https://github.com/pyload/pyload