Mylar3 0.8.3 配置参数详解

目标：把 Mylar3 v0.8.3 的配置文件讲清楚——它在哪、怎么生成、哪些项必须改、改了怎么生效、哪些项只是「看起来能改但会被程序回退」。文中出现的每个键、每个取值和每条回显，均来自本机 Ubuntu 22.04.5 LTS 上的实测（采集日期 2026-10-28）；仅源码可解释、无法用命令行直接观测的结论，会标注「源码位置」。

一、环境信息

本篇的验证环境与《Mylar3 0.8.3 Ubuntu 22.04 安装指南》完全一致，配置值均取自同一套运行实例：

先给出配置文件的真实规模，后文所有「节」「键」都以此为准：

grep -c '^\[' /var/lib/mylar3/config.ini
grep -cE '^[A-Za-z_]' /var/lib/mylar3/config.ini

47
365

即 47 个节、365 个有效键。注意这两个数字会随版本与手工增改变化，不要当成固定常量。

二、配置文件的位置与格式

2.1 文件名不是 mylar.conf

很多旧资料把 Mylar 的配置文件写成 mylar.conf，但 v0.8.3 实际使用的是 config.ini，且位置由启动参数 --datadir 决定，不是由代码目录决定：

ls -l /var/lib/mylar3/config.ini

-rw-rw-r-- 1 mylar mylar 8984 Oct 27 18:24 /var/lib/mylar3/config.ini

改文件名、改目录都会导致「改了不生效」。判断方法很简单：登录 Web 界面改任意一项并保存，然后看哪个文件的修改时间变了。

2.2 文件格式与注释

config.ini 是标准 INI：[节] + 键 = 值，UTF-8 编码，值不加引号。Mylar3 用 configobj 读写，因此：

• 行内注释会被剥离，手工加的 # 注释在程序下次写回时会丢失；
• 值的类型由程序按声明决定（bool / int / str / list），写成 1/True 都可能被接受，但 0/False 混用容易出歧义；
• 键的顺序不保证与源码声明一致，不要依赖顺序做 diff。

2.3 首次启动时自动生成

配置不是安装包自带的模板，而是首次启动时由程序写出。首次启动的日志会先抱怨找不到旧配置，然后从版本 0 升级到当前版本：

27-Oct-2026 17:54:17 - WARNING :: MainThread : maintenance.py:backup_files:422 : [[Errno 2] No such file or directory: '/var/lib/mylar3/config.ini'] Unable to make proper backup of config.ini in /var/lib/mylar3/config.ini
27-Oct-2026 17:54:17 - INFO    :: MainThread : config.py:config_update:699 : Updating Configuration from 0 to 14
27-Oct-2026 17:54:17 - INFO    :: MainThread : config.py:config_update:888 : Configuration upgraded to version 14

这段回显解释了三个事实：

1. 没有独立的安装向导。所谓「向导生成项」在 Mylar3 里其实就是这套默认值，界面上的 Settings 只是默认值的编辑器。
2. config_version = 14 是模式版本号，不是软件版本号。升级 Mylar3 时该值会驱动 config_update() 做键迁移，迁移前的旧文件会被备份。
3. 备份落在数据目录的 backup/ 子目录，命名带模式版本，例如：

ls -l /var/lib/mylar3/backup

-rw-rw-r-- 1 mylar mylar   8989 Oct 27 17:57 config.ini-v14.backup
-rw-r--r-- 1 mylar mylar 155648 Oct 27 17:56 mylar.db.backup

💡 技术拓展：很多自托管项目把「配置」和「状态」放在两个地方，Mylar3 则全部塞进 --datadir：config.ini（配置）、mylar.db（SQLite 库）、cache/（imprints.json 等缓存）、logs/mylar.log、backup/。这带来一个很实用的结论：迁移整站只需要打包这一个目录，不必去翻代码目录。

三、配置项的三种来源

把 365 个键按「谁写的」分类，比按功能分类更能避免踩坑。实测下来只有三类：

一个具体例子说明第二类的陷阱。Mylar3 界面上的 API Key 有一个 Generate 按钮，它请求 /generateAPI：

curl -s 'http://127.0.0.1:8090/generateAPI'

3bb44ce378d80f4f51837d895eca20c6

看起来成功了，但立刻检查文件会发现：

grep -nE '^api_key ' /var/lib/mylar3/config.ini

143:api_key = None

也就是说，新 Key 只存在于进程内存里：当下用它调接口能通，重启服务后立刻失效（实测重启后同一 Key 返回 API key not generated correctly）。想持久化，必须在 Settings 页点保存，或者手工把 Key 写进 config.ini 再重启：

sed -i 's/^api_key = .*/api_key = a1b2c3d4e5f60718293a4b5c6d7e8f90/' /var/lib/mylar3/config.ini
systemctl restart mylar3
curl -s 'http://127.0.0.1:8090/api?cmd=getVersion&apikey=a1b2c3d4e5f60718293a4b5c6d7e8f90'

{"success": true, "data": {"git_path": null, "install_type": "source", "current_version": "cdc94a44425b6f3f9cdb9b6e5f9d88ae2fee3316", "latest_version": "cdc94a44425b6f3f9cdb9b6e5f9d88ae2fee3316", "commits_behind": null}}

⚠️ 注意：上面这串 Key 是本机演示用的固定值，生产环境请用 /generateAPI 生成后立即保存，或自行生成 32 位十六进制串。不要在公开文档里照抄。

四、配置生效机制：必须重启

Mylar3 的配置在进程启动时整体加载一次，运行期不监听文件变化。这一点用认证开关可以干净地验证。

先把用户名密码从「清空」状态改为 admin / q1w2e3r4，并把 authentication 置 1：

grep -nE '^(authentication|http_username|http_password) ' /var/lib/mylar3/config.ini

127:http_username = admin
128:http_password = q1w2e3r4
136:authentication = 1

此时不重启直接请求：

curl -s -o /dev/null -w 'no_restart=%{http_code}\n' http://127.0.0.1:8090/

no_restart=401

重启后：

systemctl restart mylar3
curl -s -o /dev/null -w 'anon=%{http_code}\n' http://127.0.0.1:8090/
curl -s -o /dev/null -w 'auth=%{http_code}\n' -u admin:q1w2e3r4 http://127.0.0.1:8090/

anon=401
auth=303

303 是认证通过后跳转 /home 的正常响应；把 -L 加上会拿到 200。

反过来，把认证关掉需要同时清空用户名和密码，只改 authentication = 0 是不够的。源码 config.py:1372 有这样一段：

if all([self.AUTHENTICATION == 0, self.HTTP_USERNAME is not None, self.HTTP_PASSWORD is not None]):
    #set it to the default login prompt if nothing selected.
    self.AUTHENTICATION = 1

即「开关关着但账号密码都在」会被强制打开认证。实测把这个状态写进文件并重启，匿名访问仍然是 401；只有把两个账号项都设为 None 才真正放开：

grep -nE '^(authentication|http_username|http_password) ' /var/lib/mylar3/config.ini
curl -s -o /dev/null -w 'home=%{http_code}\n' http://127.0.0.1:8090/home

127:http_username = None
128:http_password = None
136:authentication = 0
home=200

这是配置篇最值得记住的一条：布尔开关不一定说了算，程序里还有「互补逻辑」会覆盖你写的值。

五、[General]：目录、命名模板与后处理开关

[General] 是最大的节，也是装完必须动手术的地方。以下取自本机默认值与实测值：

模板变量是实际生效的，改动前建议先在一两个系列上试：

sed -i 's/^folder_format = .*/folder_format = $Series ($Year)/' /var/lib/mylar3/config.ini
grep -nE '^(folder_format|file_format|destination_dir) ' /var/lib/mylar3/config.ini

15:destination_dir = None
29:folder_format = $Series ($Year)
30:file_format = $Series $Annual $Issue ($Year)

注意 sed 用的是 s/.../.*/ 通配，如果值里本身含 /（例如目录路径）会破坏语法，目录类改动请直接在界面上填，或者用带转义的单引号替换。

💡 技术拓展：$Series / $Year / $Issue / $Annual 这套模板与 *arr 系列的命名风格不同，它不提供「质量」「版本」这类变量，所以同一个系列的不同版本只能靠 $Issue 后的扩展名区分。如果你有多版本收藏需求，需要在后处理脚本里自己处理。

六、[Interface]：监听、认证与 HTTPS

认证响应的头部已经实测过：

HTTP/1.1 401 Unauthorized
Www-Authenticate: Basic realm="Mylar", charset="UTF-8"

生产建议：优先在反向代理层做认证与 TLS，把 Mylar3 的 http_host 收窄到 127.0.0.1。内置 HTTPS 需要每 90 天换证书并重启服务，反代方案换证书不必动 Mylar3。反代写法见安装指南第七节。

七、[API]：接口开关与 Key

三种失败/成功回显都在本机复现过：

# 未配置 Key
curl -s 'http://127.0.0.1:8090/api?cmd=getVersion'
# 配置了 Key
curl -s 'http://127.0.0.1:8090/api?cmd=getVersion&apikey=a1b2c3d4e5f60718293a4b5c6d7e8f90'
# Key 长度/内容不对
curl -s 'http://127.0.0.1:8090/api?cmd=getVersion&apikey=deadbeef'

{"success": false, "error": {"code": 460, "message": "Missing API key"}}
{"success": true, "data": {"git_path": null, "install_type": "source", "current_version": "cdc94a44425b6f3f9cdb9b6e5f9d88ae2fee3316", "latest_version": "cdc94a44425b6f3f9cdb9b6e5f9d88ae2fee3316", "commits_behind": null}}
{"success": false, "error": {"code": 460, "message": "API key not generated correctly"}}

code 460 是本接口的通用错误码，具体原因看 message。同一个码会对应「缺 Key」「Key 不对」「未知命令」三种情况，排障时不要只看码。

⚠️ 注意：api_enabled 与 api_key 是两个独立条件。只把 Key 填好但 api_enabled 仍是默认的 False 时接口依旧不可用。改完两项都要重启。

八、[CV]：ComicVine API Key 与元数据

没有 Key 时不只是「搜索变慢」，而是直接不可用。启动日志每轮都会报：

27-Oct-2026 18:24:36 - WARNING :: CP Server Thread-8 : mb.py:findComic:142 : You have not specified your own ComicVine API key - this is a requirement. Get your own @ http://api.comicvine.com.

再调一次 findComic，服务端会因空结果抛异常（本机实测，api.py:1091）：

500 Internal Server Error
TypeError: 'NoneType' object is not iterable

结论：不要把「没 Key 也能用」当作可接受的降级状态。要么申请 Key，要么换用本地标签路线（见选型篇的「元数据两条技术路线」）。

九、[Client] 与各下载器节

[Client] 只有两个键，但它们决定后面哪些节会被读取：

• nzb_downloader：0=SABnzbd、1=NZBGet、2=Blackhole、3=不使用
• torrent_downloader：0=watchfolder、1=uTorrent、2=rTorrent、3=Transmission、4=Deluge、5=qBittorrent

映射关系来自源码 config.py:1597-1643，并附带一条值校验逻辑：

if all([self.NZB_DOWNLOADER ==0, self.SAB_HOST is None]) or all([self.NZB_DOWNLOADER ==1, self.NZBGET_HOST is None]) or all([self.NZB_DOWNLOADER==2, self.BLACKHOLE_DIR is None]):
    logger.info('NZB Downloader detected as invalid entry - defaulting to None')
    self.NZB_DOWNLOADER = 3

本机把 nzb_downloader 改成 0 但没填 sab_host，重启后确实出现：

27-Oct-2026 18:23:42 - INFO    :: MainThread : config.py:configure:1598 : NZB Downloader detected as invalid entry - defaulting to None

关键细节：回退只发生在内存，文件里的值不会改。重启后 grep '^nzb_downloader' 仍然是 0，下次启动会再报一次同样的告警。同理，torrent_downloader = 9 这类越界值会被静默改成 0（watchfolder），文件同样保持 9。所以看到「配置写着 A、行为却是 B」时，先怀疑这条校验逻辑。

各下载器节的实际键名（默认值全部为 None，必须手工补）：

十、搜索接口：[Providers]、[Newznab]、[Torznab]、[Torrents]、[DDL]、[32P]

这些节控制「去哪里找刊」。默认全部关闭，开一个就必须把对应凭据填全：

[DDL] 还有三个容易被忽略的项：

• enable_flaresolverr + flaresolverr_url：直链站点有 CloudFlare 质询时需要；
• enable_proxy + http_proxy / https_proxy：给直链请求单独走代理（与系统代理相互独立）；
• ddl_location：直链文件落盘位置，None 时会跟随下载器配置。

这三项是本机实测确认存在的键名。若直链站点全部 403，按「FlareSolverr → 代理 → 放弃直链」的顺序排查。

十一、[Scheduler]、[Weekly]、[Logs]：节奏与日志

log_level 的语义来自 logger.py：warn/error 无条件写入，info 要求 LOG_LEVEL > 0，debug 要求 LOG_LEVEL > 1。排障时临时调到 2，复现完立刻调回 1，否则 10 MB 日志很快写满并触发轮转，反而丢掉关键上下文。

周榜这一节还有一个已知缺陷：[Weekly] 相关任务在 2026 年运行会抛异常（weekly_info() 的周号类型问题），详见安装指南「10.4」。它不影响订阅与下载，但会让「本周新刊」页面一直空着。

日志的实际位置可以直接确认：

ls -l /var/lib/mylar3/logs

-rw-rw-r-- 1 mylar mylar 155448 Oct 27 18:24 mylar.log

十二、通知节：统一的三段式结构

通知类配置有 10 个节，全部遵循同一个模式：<通知名>_enabled（开关）、<通知名>_onsnatch（抓取时通知）、凭据项。默认全部关闭、凭据全为 None。

只有 [Email] 的 email_ongrab / email_onpost 默认是 True，其余 onsnatch 默认 False。注意 email_enc 是数字枚举（0 表示不加密），填 ssl 这类字符串不会生效。

⚠️ 注意：这些凭据在 config.ini 中是明文保存的，除非 [General] 的 encrypt_passwords = True。开启加密后，http_password、通知 Token 一类会被替换成密文，此时不要手工编辑这些项，否则会破坏格式；改密码请走界面。

十三、[PostProcess]、[Metatagging]、[Perms]

后处理与元数据是 Mylar3 区别于「纯下载器」的部分：

[Perms] 默认关闭，但一旦开启就会按 0777/0660 强制改写。在多用户共享的库目录上，这会把上级目录的权限结构打乱，建议先用 chmod_dir = 0775 试跑一批。

元数据写标签依赖外部解包工具：CBR 是 RAR 封装，unrar_cmd 为 None 时写标签会失败，CBR 内容只能先转 CBZ。这与「功能列表里有元数据」是两件事，选型时容易误判。

十四、配置的备份、迁移与常见问题

14.1 备份范围

一个完整的配置备份等于「数据目录三件套」：

tar -czf /root/mylar3-$(date +%F).tar.gz -C /var/lib/mylar3 config.ini mylar.db

backup/ 子目录里的 config.ini-v14.backup 与 mylar.db.backup 是程序自动生成的，不能替代手工备份——它们是升级前的快照，保留份数由 backup_retention（默认 4）决定。

14.2 迁移到新机器

顺序建议：装新版本 → 停服务 → 覆盖 config.ini 与 mylar.db → 检查路径类键 → 启服务。

路径类键必须逐一核对，否则会出现「服务正常但后处理失败」：

• [General] destination_dir、grabbag_dir
• [PostProcess] folder_cache_location、manual_pp_folder
• [Logs] log_dir
• [Metatagging] ct_settingspath
• 各下载器的 *_directory

14.3 常见问题

最后一条要特别小心：程序写回 config.ini 会重排并丢弃注释。习惯在文件里写注释记录的团队，应该把注释放到外部文档，而不是 config.ini 里。

十五、参考链接