Mylar3 0.8.3 常用 CLI 与运维命令详解

目标：把 Mylar3 v0.8.3 的入口命令、维护模式、备份恢复、日志、API 运维动作与常见故障处理写成可直接照抄的清单。所有命令与回显均在本机 Ubuntu 22.04.5 LTS（Python 3.12.16）实测，采集日期 2026-10-28；不能实测的部分会明确说明「仅源码可见」，不写成已验证结论。

一、环境信息

项	值
操作系统	Ubuntu 22.04.5 LTS
Python	3.12.16（`/opt/mylar3/venv/bin/python`）
Mylar3	v0.8.3
代码目录	`/opt/mylar3`
数据目录	`/var/lib/mylar3`（由 `--datadir` 指定）
配置文件	`/var/lib/mylar3/config.ini`
服务单元	`/etc/systemd/system/mylar3.service`
运行账号	`mylar`
监听端口	`8090`
实测日期	2026-10-28

后文所有命令默认以 root 执行，涉及服务时用 systemctl；需要以运行账号执行时用 sudo -u mylar。示例口令统一为 admin / q1w2e3r4。

二、入口脚本与命令总览

Mylar3 只有一个入口：Mylar.py。它既是常驻服务的启动器，也是维护模式的入口。先看它自己的说明：

cd /opt/mylar3
./venv/bin/python Mylar.py --help

usage: Mylar.py [-h] [-v] [-q] [-d] [-p PORT] [-b [BACKUP]] [-w] [-iu]
                [--datadir DATADIR] [--config CONFIG] [--nolaunch]
                [--pidfile PIDFILE] [--safe]
                {maintenance} ...

Automated Comic Book Downloader

options:
  -h, --help            show this help message and exit
  -v, --verbose         Increase console logging verbosity
  -q, --quiet           Turn off console logging
  -d, --daemon          Run as a daemon
  -p PORT, --port PORT  Force mylar to run on a specified port
  -b [BACKUP], --backup [BACKUP]
                        Will automatically backup & keep the last 4 rolling
                        copies.
  -w, --noweekly        Turn off weekly pull list check on startup (quicker
                        boot sequence)
  -iu, --ignoreupdate   Do not update db if required (for problem bypass)
  --datadir DATADIR     Specify a directory where to store your data files
  --config CONFIG       Specify a config file to use
  --nolaunch            Prevent browser from launching on startup
  --pidfile PIDFILE     Create a pid file (only relevant when running as a
                        daemon)
  --safe                redirect the startup page to point to the Manage
                        Comics screen on startup

Subcommands:
  {maintenance}
    maintenance         Enter maintenance mode (no GUI). Additional commands
                        are available (maintenance --help)

先把三件容易搞错的事说清楚，它们在本机都复现过：

第一，没有 -c 参数。 网上资料里常见的 -c 在这里不是「指定配置文件」，而是被当成子命令名解析：

./venv/bin/python Mylar.py -c /tmp/x

Mylar.py: error: argument maintenance: invalid choice: '/tmp/x' (choose from maintenance)

想指定配置文件要用 --config（见第三节）。

第二，没有 --no-restart 参数。

./venv/bin/python Mylar.py --no-restart

Mylar.py: error: unrecognized arguments: --no-restart

重启服务用 systemctl restart mylar3 或 API 的 cmd=restart，不存在「启动脚本自带重启开关」这回事。

第三，也没有 -V / --version。

./venv/bin/python Mylar.py -V

Mylar.py: error: unrecognized arguments: -V

版本信息有两条获取途径：启动日志里的版本行，或 API cmd=getVersion（返回 commit 号）。

三、启动参数逐项说明

参数	作用	适用场景	实测结论
`-h` / `--help`	打印帮助	首次接触	可用，输出见上节
`-v` / `--verbose`	提高控制台日志级别	前台调试	帮助文本明确；仅影响控制台，不改 `log_level`
`-q` / `--quiet`	关闭控制台日志	systemd 托管	托管时本来就无终端，可省略
`-d` / `--daemon`	以守护进程运行	无 systemd 的老式部署	与 `--pidfile` 配合；systemd 场景不要用
`-p` / `--port`	覆盖监听端口	临时换端口、端口冲突排查	可用，实测 `-p 8095` 生效
`-b` / `--backup`	启动前备份配置与数据库	升级前、迁移前	可用，但备份位置跟随 `--datadir`，详见第六节
`-w` / `--noweekly`	跳过启动时的周榜检查	规避 2026 年周榜异常	可用，见第九节 9.3
`-iu` / `--ignoreupdate`	跳过数据库升级检查	降级/回滚后排障	帮助文本明确；破坏性大，仅在明确知道要跳过什么版本时使用
`--datadir`	指定数据目录	生产必加	不加会在代码目录生成一套新配置
`--config`	指定配置文件	多实例、灰度	与 `--datadir` 组合实测可用
`--nolaunch`	不尝试打开浏览器	服务器环境必加	不加时尝试拉起浏览器会报错但服务不受影响
`--pidfile`	写 PID 文件	与 `-d` 搭配	仅在守护模式下有意义
`--safe`	启动页跳到 Manage Comics	库很大、首页加载慢时	仅改启动落点

--config 与 --datadir 的组合实测如下（另起一个实例，端口 8095，互不干扰）：

cp /var/lib/mylar3/config.ini /tmp/alt.ini
sed -i 's/^http_port = .*/http_port = 8095/' /tmp/alt.ini
mkdir -p /tmp/mylar-test
cd /opt/mylar3
./venv/bin/python Mylar.py --datadir /tmp/mylar-test --config /tmp/alt.ini --nolaunch
curl -s -o /dev/null -w 'port8095=%{http_code}\n' http://127.0.0.1:8095/home

27-Oct-2026 18:32:10 - INFO    :: MAIN : webstart.py:initialize:73 : Starting Mylar on http://0.0.0.0:8095/
port8095=200

⚠️ 注意：这个测试实例会独立生成 mylar.db，与正式库无关。用完把 /tmp/mylar-test 与 /tmp/alt.ini 删掉，避免以后误连。

四、常驻运行与 systemd 操作

生产环境的正确姿势是 systemd 托管 + --datadir + --nolaunch，启动参数不手敲，写死在单元文件里：

systemctl cat mylar3.service

核心行：

ExecStart=/opt/mylar3/venv/bin/python /opt/mylar3/Mylar.py --datadir /var/lib/mylar3 --nolaunch -p 8090

日常操作命令：

systemctl start mylar3      # 启动
systemctl stop mylar3       # 停止
systemctl restart mylar3    # 改配置后重启
systemctl status mylar3     # 查看状态
systemctl enable mylar3     # 开机自启
journalctl -u mylar3 -f     # 跟随 systemd 日志

状态检查的实测回显（截取关键行）：

Active: active (running)
Main PID: 6762 (python)
Memory: 53.5M

判断「服务活着」不要只看 active，还要打一次健康检查：

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

home=200

如果 active 但 home 返回非 200，说明进程起来了但应用层异常，优先看 logs/mylar.log 的 ERROR 行。

💡 技术拓展：Mylar3 的 -d 守护模式与 systemd 是两套互斥机制。同时用会得到「systemd 认为主进程已退出、实际有个脱离的子进程还在跑」的状态，重启后出现端口占用。托管场景一律 Type=simple + 前台运行，不要加 -d。

五、maintenance 维护模式

维护模式的完整参数：

./venv/bin/python Mylar.py maintenance --help

usage: Mylar.py maintenance [-h] [-xj EXPORTJSON] [-id IMPORTDATABASE]
                            [-ij IMPORTJSON] [-st] [-u] [-fs] [-cp] [-care]

options:
  -h, --help            show this help message and exit
  -xj EXPORTJSON, --exportjson EXPORTJSON
                        Export existing mylar.db to json file
  -id IMPORTDATABASE, --importdatabase IMPORTDATABASE
                        Import a mylar.db into current db
  -ij IMPORTJSON, --importjson IMPORTJSON
                        Import a specified json file containing just
                        {"ComicID": "XXXXX"} into current db
  -st, --importstatus   Provide current maintenance status
  -u, --update          force mylar to perform an update as if in GUI
  -fs, --fixslashes     remove double-slashes from within paths in db
  -cp, --clearprovidertable
                        clear out the provider_searches table in db
  -care, --carepackage  generate a carepackage

关键行为：维护模式并不是纯命令行批处理，它会启动一个占端口的维护 Web 服务。所以执行前必须先停主服务，否则直接撞端口：

[ERROR] Port 8090 is in use on 0.0.0.0.
Failed to start on port: 8090. Is something else running?

5.1 各子命令实测结果

先停服务再执行：

systemctl stop mylar3

-xj（导出 JSON）：

./venv/bin/python Mylar.py maintenance -xj /tmp/export_test.json

27-Oct-2026 18:28:02 - INFO    :: MAIN : maintenance_webstart.py:initialize:72 : [MAINTENANCE-MODE] Starting Mylar in maintenance mode on http://0.0.0.0:8090/
27-Oct-2026 18:28:02 - INFO    :: MAIN : Mylar.py:main:490 : [MAINTENANCE-MODE] file indicated as being written to json format - destination accepted as /tmp/export_test.json
Error in sys.excepthook:
TypeError: RotatingLogger.handle_exception() missing 1 required positional argument: 'exc_traceback'

Original exception was:
Traceback (most recent call last):
TypeError: a bytes-like object is required, not 'str'

导出文件大小为 0，即该子命令在 Python 3.12 下不可用。

-fs（修路径双斜杠）：

TypeError: can only concatenate str (not "bytes") to str

同样不可用。

-cp（清空 provider_searches 表）：

TypeError: unsupported type for timedelta weeks component: str
27-Oct-2026 18:30:21 - INFO    :: MAIN : Mylar.py:main:580 : Received signal: shutdown

-cp 本身执行了，但启动阶段先被周榜异常打断，进程不自行退出（实测需要 timeout 或 Ctrl-C 中断），随后收到 SIGTERM 走正常关闭流程：

27-Oct-2026 18:30:23 - INFO    :: MAIN : __init__.py:halt:1639 : Shutting down the background schedulers...
27-Oct-2026 18:30:27 - INFO    :: SEARCH-QUEUE : helpers.py:search_queue:3500 : [SEARCH-QUEUE] Cleaning up workers for shutdown
27-Oct-2026 18:30:27 - INFO    :: MAIN : __init__.py:shutdown:1666 : Mylar is shutting down...

-st、-u、-id、-ij、-care 这次没有逐条跑完（-st 与 -xj 同样会拉起维护 Web 服务并常驻）。结论按「已实测 / 未实测」分别标注：

子命令	状态	说明
`-cp`	已实测执行	能执行，但进程不自动退出，需手动中断
`-xj`	已实测失败	`bytes`/`str` 类型错误，导出 0 字节
`-fs`	已实测失败	`str`/`bytes` 拼接错误
`-st`、`-u`、`-id`、`-ij`、`-care`	未逐条实测	命令存在（帮助可见），行为以 `maintenance --help` 为准；执行前请先停主服务并先备份

⚠️ 注意：维护模式在最小化环境里还有一个常见坑——日志里会出现 language detected as non-English (C). Forcing specific logging module - errors WILL NOT be captured in the logs。这意味着这次运行的错误不会写进 mylar.log，只能看终端。排查维护模式问题时请务必保留终端输出。

六、备份与恢复

6.1 `-b` 参数与备份位置

-b 会在启动前备份 config.ini 与 mylar.db：

cd /opt/mylar3
./venv/bin/python Mylar.py -b

27-Oct-2026 18:30:35 - INFO    :: MainThread : Mylar.py:main:403 : [AUTO-BACKUP] Backing up mylar.db & config.ini files for safety.
27-Oct-2026 18:30:35 - INFO    :: MainThread : maintenance.py:backup_files:426 : Successfully backed up config.ini to /opt/mylar3/backup/config.ini-v14.backup.
27-Oct-2026 18:30:35 - INFO    :: MainThread : maintenance.py:backup_files:426 : Successfully backed up mylar database to /opt/mylar3/backup/mylar.db.backup.
27-Oct-2026 18:30:35 - INFO    :: MainThread : Mylar.py:main:416 : [AUTO-BACKUP] Successful backup of 2 files [['config.ini', 'mylar.db']]

注意最后两行的路径是 /opt/mylar3/backup/，不是 /var/lib/mylar3/backup/——因为这次执行没有带 --datadir，程序按默认数据目录（代码目录）去找配置，于是在代码目录生成了一套新的 config.ini、mylar.db 和 backup/。

这解释了两件事：

生产环境的备份要通过 systemd 单元里的完整参数执行，或用 sudo -u mylar /opt/mylar3/venv/bin/python /opt/mylar3/Mylar.py --datadir /var/lib/mylar3 -b；
一旦发现代码目录里莫名出现 config.ini / mylar.db，说明某次手工命令漏了 --datadir，这套数据与正式库无关，删掉即可，不要拿去恢复。

6.2 手工备份（推荐）

程序自动备份的保留份数由 backup_retention（默认 4）控制，不够可靠。生产建议自己打包：

systemctl stop mylar3
tar -czf /root/mylar3-$(date +%F).tar.gz -C /var/lib/mylar3 config.ini mylar.db
systemctl start mylar3
ls -lh /root/mylar3-*.tar.gz

停服务是为了保证 mylar.db 的一致性快照。热备份（不停服务）虽然多数时候能成功，但 WAL 未落盘时会得到损坏的库。

6.3 恢复

systemctl stop mylar3
cd /var/lib/mylar3
cp config.ini config.ini.before-restore
cp mylar.db mylar.db.before-restore
tar -xzf /root/mylar3-2026-10-28.tar.gz -C /var/lib/mylar3
chown -R mylar:mylar /var/lib/mylar3
systemctl start mylar3
curl -s -o /dev/null -w 'home=%{http_code}\n' http://127.0.0.1:8090/home

本机的恢复验证结论：home=200，系列列表与配置项均保留。恢复后如果界面空白但服务正常，先检查属主是否被 tar 改成了 root——这是最常见的「恢复了却用不了」。

6.4 目录级备份

/var/lib/mylar3 下的完整清单（实测）：

config.ini
mylar.db
logs/mylar.log
backup/config.ini-v14.backup
backup/mylar.db.backup
cache/imprints.json
export.json

迁移整站时把整个目录打包最稳妥，但注意 export.json 是空的占位文件（-xj 失败留下的），不必带走。

七、日志与日志轮转

日志默认位置随数据目录：

ls -l /var/lib/mylar3/logs

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

轮转参数在 [Logs] 节：max_logsize = 10000000（约 10 MB）、max_logfiles = 5、log_level = 1。级别语义：0 仅 WARN/ERROR，1 追加 INFO，2 追加 DEBUG。

常用检索：

tail -f /var/lib/mylar3/logs/mylar.log
grep -nE 'ERROR|Traceback' /var/lib/mylar3/logs/mylar.log | tail -20
grep -n 'ComicVine' /var/lib/mylar3/logs/mylar.log | tail -10

需要注意：journalctl -u mylar3 与 logs/mylar.log 不是同一份内容。前者是 systemd 捕获的 stdout/stderr（含启动期报错与退出码），后者是应用自己写的业务日志。排障时两份都要看：应用崩溃前的最后一行往往只出现在 journal 里。

最小化安装的系统若 journalctl 报 No journal files were found，说明 systemd 日志未持久化，加 -o cat 或直接读 logs/mylar.log。

八、REST API 运维接口

[API] 节开启后（api_enabled = True + 有效 api_key），可以做程序化运维。实测示例：

K=a1b2c3d4e5f60718293a4b5c6d7e8f90
curl -s "http://127.0.0.1:8090/api?cmd=getVersion&apikey=$K"
curl -s "http://127.0.0.1:8090/api?cmd=restart&apikey=$K"

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

cmd=restart 返回 OK 后进程会自行重启，20 秒后再探测：

active
after_restart=200

运维相关命令（来自 api.py 的 cmd_list）：

命令	用途	风险
`getVersion`	版本/commit 查询	无
`getLogs` / `clearLogs`	读/清空内存日志	清空后排查线索丢失
`restart` / `shutdown`	重启/停止服务	高，务必先确认 systemd 会拉起
`update`	触发更新	高，先备份
`recheckFiles` / `refreshSeriesjson` / `regenerateCovers`	库体检	中，注意 API 配额
`checkGithub`	检查新版本	无
`addProvider` / `delProvider` / `listProviders`	索引器管理	中

错误码只有一种：460。不同场景的 message 不同，实测过三种：

{"success": false, "error": {"code": 460, "message": "Missing API key"}}
{"success": false, "error": {"code": 460, "message": "API key not generated correctly"}}
{"success": false, "error": {"code": 460, "message": "Unknown command: getRootFolders"}}

所以「接口 460」不等于「Key 错」，先读 message。

⚠️ 注意：API Key 若通过界面上的 Generate 按钮生成而不点保存，只存在于内存，重启即失效（配置篇第三节已给出完整证据）。程序化调用前请确认 grep '^api_key' /var/lib/mylar3/config.ini 有值。

九、常见故障排查

9.1 服务起不来：端口被占

[ERROR] Port 8090 is in use on 0.0.0.0.
Failed to start on port: 8090. Is something else running?

排查顺序：ss -lntp | grep 8090 看谁占着 → 若是残留的 maintenance 进程，kill 掉 → 若是另一个 Mylar 实例，确认后停掉。临时换端口验证可用 -p 8095。

9.2 启动即退出，日志只有 Python 语法警告

SyntaxWarning: invalid escape sequence 是 Python 3.12 对旧正则写法的提示，不致命，可以忽略。真正的退出原因通常在 banner 之后的最后 3 行，用：

journalctl -u mylar3 -o cat | tail -30

9.3 周榜任务反复抛异常

Job "Weekly Pullist (trigger: interval[4:00:00], next run at: 2026-10-27 21:54:19 UTC)" raised an exception
  File "/opt/mylar3/mylar/helpers.py", line 3164, in weekly_info
    startweek = stweek + timedelta(weeks = weeknumber)
TypeError: unsupported type for timedelta weeks component: str

规避手段：启动参数加 -w（跳过启动时的周榜检查）。实测加上后不再在启动阶段触发；但调度器到点仍会尝试刷新，页面「本周新刊」可能一直为空。它不影响订阅、搜索与下载。

9.4 添加系列没结果

先确认 [CV] comicvine_api 是否有值。没有 Key 时日志会连续报：

You have not specified your own ComicVine API key - this is a requirement. Get your own @ http://api.comicvine.com.

并且 API findComic 直接 500（TypeError: 'NoneType' object is not iterable）。这不是网络问题，补 Key 即可。

9.5 下载完成但库目录里没有文件

依次核对四件事：

[General] destination_dir 是否非空；
[General] move_files 是否为 True（否则可能只重命名不搬移）；
[Client] 的下载器编号与实际客户端是否匹配；
下载目录与库目录是否在同一个挂载点（跨挂载点时 move 会变成「复制 + 删除」，磁盘不足就会中断）。

后处理是否真的跑过，看日志里的 PostProcessor 行，而不是看下载器显示「完成」。

9.6 磁盘被日志或缓存吃满

du -sh /var/lib/mylar3/* | sort -h

常见大户是 logs/mylar.log（log_level = 2 忘调回）与 cache/。清理前先确认没有下载任务在跑。

十、升级与回滚

升级前标准动作：

sudo -u mylar /opt/mylar3/venv/bin/python /opt/mylar3/Mylar.py --datadir /var/lib/mylar3 -b
tar -czf /root/mylar3-pre-upgrade-$(date +%F).tar.gz -C /var/lib/mylar3 config.ini mylar.db
python3 -c "import sqlite3;print(sqlite3.connect('/var/lib/mylar3/mylar.db').execute('select count(*) from comics').fetchone())"

第三条命令给出系列数量，回滚后用它判断库是否回退到同一状态。

升级路径推荐「换目录 + 改软链」而不是原地覆盖：

systemctl stop mylar3
mv /opt/mylar3 /opt/mylar3.bak-$(date +%F)
# 解压新版本到 /opt/mylar3，重建 venv 并装依赖
systemctl start mylar3

config_version 会在首次启动时自动迁移（实测日志 Updating Configuration from 0 to 14 / Configuration upgraded to version 14）。回滚时把 backup/config.ini-v*.backup 一起带回去，否则新版本写入的键会让旧版本报未知配置。

若要强制跳过数据库升级检查，可用 -iu。这条只用于「明确知道升级脚本误判」的场合，正常升级不要加。

十一、日常巡检清单

每天：

systemctl is-active mylar3
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/home
tail -50 /var/lib/mylar3/logs/mylar.log | grep -E 'ERROR|Traceback' || echo 'no recent errors'

每周：

df -h /var/lib/mylar3
du -sh /var/lib/mylar3/logs /var/lib/mylar3/cache
ls -l /var/lib/mylar3/backup

每月：

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

三条命令覆盖了绝大多数「突然不可用」的场景：服务挂了、磁盘满了、库坏了。

十二、参考链接

内容	地址
项目仓库	https://github.com/mylar3/mylar3
v0.8.3 发布页	https://github.com/mylar3/mylar3/releases/tag/v0.8.3
官方文档站	https://mylarcomics.com/docs/introduction
官方自动备份说明	https://mylarcomics.com/docs/guides/auto_backups
官方 API 文档	https://mylarcomics.com/docs/api/endpoints
站内：认知与选型	《Mylar3 介绍与选型指南》
站内：安装部署	《Mylar3 0.8.3 Ubuntu 22.04 安装指南》
站内：配置参数	《Mylar3 0.8.3 配置参数详解》

Mylar3 0.8.3 常用 CLI 与运维命令详解

Mylar3 0.8.3 常用 CLI 与运维命令详解

一、环境信息

二、入口脚本与命令总览

三、启动参数逐项说明

四、常驻运行与 systemd 操作

五、maintenance 维护模式

5.1 各子命令实测结果

六、备份与恢复

6.1 -b 参数与备份位置

6.2 手工备份（推荐）

6.3 恢复

6.4 目录级备份

七、日志与日志轮转

八、REST API 运维接口

九、常见故障排查

9.1 服务起不来：端口被占

9.2 启动即退出，日志只有 Python 语法警告

9.3 周榜任务反复抛异常

9.4 添加系列没结果

9.5 下载完成但库目录里没有文件

9.6 磁盘被日志或缓存吃满

十、升级与回滚

十一、日常巡检清单

十二、参考链接

6.1 `-b` 参数与备份位置