Mylar3 0.8.3 Ubuntu 22.04 安装指南

在 Ubuntu 22.04.5 LTS 上从零部署 Mylar3 v0.8.3：Python 3.12 虚拟环境、systemd 托管、Nginx 反向代理与安装后验证（实测回显，2026-10-28）。

Mylar3PythonUbuntu自托管下载2026/10/28

Mylar3 0.8.3 Ubuntu 22.04 安装指南

目标：在 Ubuntu 22.04.5 LTS 上从零安装 Mylar3 v0.8.3（Python 3.12 虚拟环境 + systemd 托管 + 可选 Nginx 反向代理），并完成 Web 界面、认证、API 与「无 ComicVine Key」报错回显的验证。全文命令与回显均在本机 Ubuntu 22.04.5 LTS 服务器实测通过，采集日期 2026-10-28。

一、环境信息

以下是本次实测的基线环境，读者复现时建议对齐版本；版本差异导致的报错已收进「十、常见问题」。

  • 操作系统：Ubuntu 22.04.5 LTS（Jammy Jellyfish），x86_64
  • 内核与资源：2 vCPU / 4 GB 内存 / 40 GB 磁盘
  • Python：3.12.16（deadsnakes PPA 安装，虚拟环境隔离）
  • Mylar3：v0.8.3（GitHub tag v0.8.3，源包 5,994,927 字节）
  • 数据库：SQLite（数据目录内 mylar.db，首启 155,648 字节）
  • Web 服务：CherryPy 18.10.0 + cheroot 11.1.2，监听 0.0.0.0:8090
  • 代码目录：/opt/mylar3
  • 数据目录：/var/lib/mylar3（配置 config.ini、数据库、备份、日志）
  • 日志目录：/var/lib/mylar3/logs（mylar.log）
  • 服务单元：/etc/systemd/system/mylar3.service
  • 可选反向代理：Nginx 1.18.0（Ubuntu 包）

💡 说明：Mylar3 的「数据目录」与「代码目录」分离很关键。代码目录只在升级时替换，数据目录承载 config.ini、mylar.db、backup/、logs/、cache/，备份与迁移只需处理后者。

二、前置条件

安装前先确认四件事：系统版本、网络、端口、运行账号。以下命令逐条实测。

# 1) 系统版本与架构
lsb_release -a
uname -m

实测回显：

Distributor ID:	Ubuntu
Description:	Ubuntu 22.04.5 LTS
Release:	22.04
Codename:	jammy
x86_64

# 2) 端口占用检查（Mylar3 默认 8090）
ss -ltn | grep 8090 || echo "8090 空闲"

实测回显：

8090 空闲

# 3) 出网能力（ComicVine 与 GitHub 都需要）
curl -s -o /dev/null -w 'github=%{http_code}\n' --max-time 10 https://github.com

实测回显：

github=000

⚠️ 网络说明：实测当日本机直连 github.com 超时（curl 返回 000），后续下载源码改用代理通道 192.168.1.62:7897 完成；若你的服务器直连正常，可省略命令中的 -x 参数。PyPI 官方源当次可直连，未降级。

其余前置：

项要求本次实测值
权限root 或可 sudoroot
磁盘代码 + 依赖约 200 MB，另加漫画库容量40 GB 可用
内存主服务常驻约 50 MBsystemctl status 显示 53.5M
账号独立系统用户运行mylar（/var/lib/mylar3）
外部依赖ComicVine API Key未配置（本次刻意保留缺 Key 场景做回显）

三、版本选型说明

Mylar3 的版本节奏与 Python 版本要求是安装前必须对齐的两件事。下表数据取自官方 Releases Atom 源（采集 2026-10-28）：

版本发布时间说明
v0.8.32025-08-17当前最新稳定版，新增 CRC 校验、CBL 导入页、搜索间隔默认 1440 分钟
v0.8.22025-03-11上一稳定版
v0.8.1.12025-01-13v0.8.1 的补丁
v0.8.12025-01-13—
v0.8.02024-03-14—

Python 侧，源码常量 MINIMUM_PY_VERSION = '3.8.1' 明确了最低要求；本次按 Python 3.12.16 部署。为什么不用系统自带的 Python 3.10：Ubuntu 22.04 自带 3.10 也满足最低要求，但 3.12 是当前主流维护版本，且本机其他服务统一使用 3.12；实测主服务在 3.12 下运行正常，仅少数维护子命令存在兼容缺陷（见「十、常见问题」）。

💡 技术拓展：Python 虚拟环境方案常见三类——venv（标准库自带，隔离依赖，最轻）、virtualenv（第三方，功能更多，支持更老版本）、Conda（跨语言、可装非 Python 依赖，体积大）。Mylar3 只依赖 PyPI 包，本文选 venv：不与系统 Python 冲突，升级/回滚只需换目录。

四、安装方案 A：源码 tar.gz + Python 3.12 虚拟环境（实测）

这是本次采用的主线方案：从官方 tag 下载源码包，校验哈希，解压到 /opt/mylar3，用 venv 装依赖，再由 systemd 托管。全过程按「建账号 → 装 Python → 下载 → 解压 → 装依赖」推进。

4.1 创建运行用户与目录

Mylar3 不需要 root 运行。先建系统用户，再建代码、数据、日志三个目录。

useradd -r -m -d /var/lib/mylar3 -s /bin/bash mylar
mkdir -p /opt/mylar3 /var/lib/mylar3 /var/log/mylar3
id mylar

实测回显：

uid=999(mylar) gid=999(mylar) groups=999(mylar)

4.2 安装 Python 3.12（deadsnakes PPA）

Ubuntu 22.04 官方源没有 3.12，用 deadsnakes PPA 安装。先装基础编译依赖，再加源、装解释器与 venv 模块。

export DEBIAN_FRONTEND=noninteractive
apt-get update -qq
apt-get install -y software-properties-common ca-certificates curl git \
  build-essential libssl-dev libffi-dev
add-apt-repository -y ppa:deadsnakes/ppa
apt-get update -qq
apt-get install -y python3.12 python3.12-venv python3.12-dev
python3.12 -V

add-apt-repository 的实测回显（节选）：

More info: https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa
Adding repository.
Adding deb entry to /etc/apt/sources.list.d/deadsnakes-ubuntu-ppa-jammy.list
Adding key to /etc/apt/trusted.gpg.d/deadsnakes-ubuntu-ppa.gpg with fingerprint F23C5A6CF475977595C89F51BA6932366A755776

解释器版本验证：

Python 3.12.16

4.3 下载官方源码包并校验

官方发布件在 GitHub tag 下。实测直连超时，改用代理通道下载；下载后必须核对 SHA-256。

cd /tmp
curl -x http://192.168.1.62:7897 -sSL \
  -o mylar-v0.8.3.tar.gz \
  -w 'code=%{http_code} size=%{size_download} time=%{time_total}\n' \
  https://github.com/mylar3/mylar3/archive/refs/tags/v0.8.3.tar.gz
sha256sum mylar-v0.8.3.tar.gz

实测回显：

code=200 size=5994927 time=1.733723
ffb15cfc375590c872d0a6ce5fdc48323a94bdc623688c4598006aaf8edcdaa6  mylar-v0.8.3.tar.gz

⚠️ 网络说明：直连 github.com 时本次请求 60 秒无响应被 curl 超时中断；改走代理后 1.7 秒完成。官方源恢复后可直接去掉 -x 参数；如代理也不可用，可换任何能取到同一 tag 的下载渠道，但哈希必须仍是上面的值，否则包不完整或已被篡改。

4.4 解压并部署到 /opt/mylar3

tar -xzf /tmp/mylar-v0.8.3.tar.gz -C /tmp
cp -a /tmp/mylar3-0.8.3/. /opt/mylar3/
cd /opt/mylar3 && ls -d */

实测回显：

data/
init-scripts/
lib/
mylar/
post-processing/
screens/
utilities/
venv/

再核对关键文件：

cd /opt/mylar3 && ls Mylar.py requirements.txt README.md API_REFERENCE comictagger.py

API_REFERENCE
Mylar.py
README.md
comictagger.py
requirements.txt

💡 说明：Mylar.py 是入口，mylar/ 是业务包，requirements.txt 是依赖清单。上面 ls -d */ 中的 venv/ 是 4.5 步创建虚拟环境后才出现的，首次解压时只有前 7 个目录。API_REFERENCE 与 init-scripts/ 目录对生产部署不是必需，但保留可避免升级时缺文件。

4.5 创建虚拟环境并安装依赖

python3.12 -m venv /opt/mylar3/venv
/opt/mylar3/venv/bin/python -V
/opt/mylar3/venv/bin/pip install --upgrade pip
/opt/mylar3/venv/bin/pip install -r /opt/mylar3/requirements.txt

版本与安装结果实测：

Python 3.12.16
pip 26.2.2 from /opt/mylar3/venv/lib/python3.12/site-packages/pip (python 3.12)

依赖安装完成后核对包数量与关键组件版本：

/opt/mylar3/venv/bin/pip list | wc -l
/opt/mylar3/venv/bin/pip list | grep -Ei 'cherrypy|cheroot|mako|apscheduler|beautifulsoup|cfscrape|requests|urllib3|pillow|rarfile|pycryptodome|feedparser'

实测回显：

53
APScheduler        3.11.3
beautifulsoup4     4.15.0
cfscrape           2.1.1
cheroot            11.1.2
CherryPy           18.10.0
feedparser         6.0.14
feedparser-sgmllib 2.1.0
Mako               1.4.3
pillow             13.0.0
pycryptodome       4.2.0
rarfile            4.5
requests           2.34.2
urllib3            1.26.20

⚠️ 注意：requirements.txt 里 urllib3<2 是硬约束，pip 会装 1.26.x；如果有人手工 pip install -U urllib3 升到 2.x，Mylar3 的请求栈会出错，升级依赖时不要动这个包。

4.6 首次启动（前台验证）

systemd 托管前先手动跑一次，确认配置生成、端口监听正常。

chown -R mylar:mylar /opt/mylar3 /var/lib/mylar3 /var/log/mylar3
su -s /bin/bash mylar -c \
  'cd /opt/mylar3 && /opt/mylar3/venv/bin/python Mylar.py --datadir /var/lib/mylar3 --nolaunch -p 8090'

首启会在数据目录生成 config.ini、mylar.db、backup/、cache/、logs/。关键日志（节选）：

27-Oct-2026 17:54:17 - INFO :: MainThread : config.py:config_update:888 : Configuration upgraded to version 14
27-Oct-2026 17:54:17 - ERROR :: MainThread : config.py:configure:1315 : No User Comicvine API key specified. I will not work very well due to api limits - http://api.comicvine.com/ and get your own free key.
27-Oct-2026 17:54:18 - INFO :: MAIN : Mylar.py:main:517 : Starting Mylar on forced port: 8090
27-Oct-2026 17:54:18 - INFO :: MAIN : webstart.py:initialize:73 : Starting Mylar on http://0.0.0.0:8090/
27-Oct-2026 17:54:18 - INFO :: MAIN : versioncheck.py:getVersion:225 : [LAST_RELEASE] Version: v0.8.3

数据目录实测结构：

config.ini      # 8824 字节，47 个节、359 个键
mylar.db        # 155648 字节
backup/         # 启动时 -b 备份落盘位置
cache/
logs/mylar.log
.ComicTagger/

验证端口与首页：

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

实测回显：

http=303

303 表示首页重定向到 /home，属正常行为，说明服务已起来。

五、systemd 托管与开机自启

前台进程不适合生产。写一个 Type=simple 的单元，把 --datadir、端口、运行用户固定下来，并用环境变量修正 locale。

5.1 写入服务单元

[Unit]
Description=Mylar3 Comic Book Downloader
Documentation=https://mylarcomics.com
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=mylar
Group=mylar
WorkingDirectory=/opt/mylar3
Environment=PYTHONUNBUFFERED=1
Environment=LANG=C.UTF-8
ExecStart=/opt/mylar3/venv/bin/python /opt/mylar3/Mylar.py --datadir /var/lib/mylar3 --nolaunch -p 8090
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

逐项说明：

  • Type=simple：Mylar3 不加 -d 时前台运行，由 systemd 直接管理主进程。
  • User/Group=mylar：降权运行，数据目录属主一致才能写库与日志。
  • --datadir /var/lib/mylar3：把配置、数据库、日志全部收敛到数据目录，升级时不动这里。
  • --nolaunch：服务端环境没有浏览器，禁止尝试拉起浏览器。
  • LANG=C.UTF-8：避免 Mylar3 把 C 区域判定为「非英文」而强制切换日志模块（对比回显见「十、常见问题」）。
  • Restart=on-failure + RestartSec=10：异常退出 10 秒后重试；正常 systemctl stop 不会触发重启。

5.2 加载、启用并启动

systemctl daemon-reload
systemctl enable mylar3
systemctl start mylar3
systemctl is-active mylar3
systemctl is-enabled mylar3

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/mylar3.service → /etc/systemd/system/mylar3.service.
active
enabled

5.3 服务状态与日志

systemctl status mylar3 --no-pager

实测回显：

● mylar3.service - Mylar3 Comic Book Downloader
     Loaded: loaded (/etc/systemd/system/mylar3.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-27 18:11:22 UTC; 12s ago
       Docs: https://mylarcomics.com
   Main PID: 6762 (python)
      Tasks: 16 (limit: 19553)
     Memory: 53.5M
        CPU: 406ms
     CGroup: /system.slice/mylar3.service
             └─6762 /opt/mylar3/venv/bin/python /opt/mylar3/Mylar.py --datadir /var/lib/mylar3 --nolaunch -p 8090

systemd 自身的启停记录（-o cat 只输出消息正文）：

journalctl -u mylar3 -n 6 --no-pager -o cat

实测回显：

Started Mylar3 Comic Book Downloader.
Stopping Mylar3 Comic Book Downloader...
mylar3.service: Deactivated successfully.
Stopped Mylar3 Comic Book Downloader.
Started Mylar3 Comic Book Downloader.

应用层日志不在 journald，而在数据目录：

ls -lt /var/lib/mylar3/logs | head -3
tail -5 /var/lib/mylar3/logs/mylar.log

实测回显（节选）：

-rw-rw-r-- 1 mylar mylar 90947 Oct 27 18:11 mylar.log

27-Oct-2026 18:11:23 - INFO    :: MAIN : __init__.py:start:665 : Background Schedulers successfully started...

六、安装后验证

这一节给出四类验证：监听状态、Web 首页、HTTP 认证、REST API。全部为实测回显。

6.1 监听状态

ss -ltnp | grep 8090

实测回显：

LISTEN 0      5            0.0.0.0:8090       0.0.0.0:*    users:(("python",pid=6121,fd=9))

backlog 为 5（cheroot 默认值），个人/小团队使用足够；多人并发场景需评估。

6.2 Web 首页与 HTTP 认证

启用认证的方式是在 config.ini 的 [Interface] 写入用户名与密码（本次使用演示账号 admin / q1w2e3r4）：

[Interface]
http_username = admin
http_password = q1w2e3r4
authentication = 1

重启后未带凭据访问会被 Basic 认证拦截：

curl -s -i http://127.0.0.1:8090/home | head -6

实测回显：

HTTP/1.1 401 Unauthorized
Content-Type: text/html;charset=utf-8
Server: CherryPy/18.10.0
Date: Tue, 27 Oct 2026 17:56:32 GMT
Www-Authenticate: Basic realm="Mylar", charset="UTF-8"
Content-Length: 1723

带正确凭据与错误凭据分别验证：

curl -s -u admin:q1w2e3r4 -o /dev/null -w 'ok=%{http_code}\n' http://127.0.0.1:8090/home
curl -s -u admin:wrong -o /dev/null -w 'bad=%{http_code}\n' http://127.0.0.1:8090/home
curl -s -u admin:q1w2e3r4 http://127.0.0.1:8090/home | grep -o '<title>[^<]*'

实测回显：

ok=200
bad=401
<title>Mylar - Home

6.3 REST API 验证

API 默认关闭。开启需在 [API] 节写入 api_enabled = True 与 32 位 api_key（示例值 0123456789abcdef0123456789abcdef，生产请自行生成随机串）：

[API]
api_enabled = True
api_key = 0123456789abcdef0123456789abcdef

三种调用的实测回显：

curl -s 'http://127.0.0.1:8090/api?cmd=getVersion&apikey=0123456789abcdef0123456789abcdef'
curl -s 'http://127.0.0.1:8090/api?cmd=getVersion'
curl -s 'http://127.0.0.1:8090/api?cmd=getVersion&apikey=deadbeef'

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

6.4 无 ComicVine Key 时的真实回显

Mylar3 的系列检索完全依赖 ComicVine。本次刻意不配置 Key，直接调用添加系列前的检索接口：

curl -s 'http://127.0.0.1:8090/searchit?name=Batman'
grep -E 'ComicVine|Comicvine' /var/lib/mylar3/logs/mylar.log | tail -4

实测回显（HTTP 响应为空，错误只体现在服务日志）：

27-Oct-2026 17:55:26 - WARNING :: CP Server Thread-4 : mb.py:findComic:142 : You have not specified your own ComicVine API key - this is a requirement. Get your own @ http://api.comicvine.com.
27-Oct-2026 17:55:26 - ERROR :: CP Server Thread-4 : webserve.py:searchit:1178 : Unable to retrieve results from ComicVine: 'NoneType' object is not iterable
27-Oct-2026 17:55:26 - ERROR :: CP Server Thread-4 : webserve.py:searchit:1180 : You NEED to set a ComicVine API key prior to adding anything. It's Free - Go get one!

结论：没有 Key 时「添加系列」不可用，界面不会给出友好提示，只有空结果 + 日志报错。Key 需在 [CV] 节配置：

[CV]
comicvine_api = 你的32位ComicVineKey
cvapi_rate = 2

⚠️ 注意：ComicVine Key 属于第三方凭据，不要写进代码仓库或文档；生产环境建议用环境变量注入或在部署时临时写入 config.ini，并在共享截图中打码。

七、反向代理（可选，Nginx）

Mylar3 自带 HTTP 服务，直接暴露 8090 也能用；如果需要统一 80/443 入口、加 TLS 或转发到域名，可在同机加一层 Nginx。

7.1 安装 Nginx

apt-get install -y nginx
nginx -v

实测回显：

nginx version: nginx/1.18.0 (Ubuntu)

7.2 站点配置

server {
    listen 80;
    server_name comic.example.com;

    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

配置逐项说明：proxy_pass 指向本机 8090；三个 X- 头用于让 Mylar3 与后续日志拿到真实客户端 IP 与协议；Host 透传保证页面里的绝对链接正确。

启用站点并检查语法：

ln -sf /etc/nginx/sites-available/mylar3.conf /etc/nginx/sites-enabled/mylar3.conf
rm -f /etc/nginx/sites-enabled/default
nginx -t
systemctl restart nginx

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

7.3 经代理访问验证

curl -s -H 'Host: comic.example.com' -o /dev/null -w 'anon=%{http_code}\n' http://127.0.0.1/
curl -s -u admin:q1w2e3r4 -H 'Host: comic.example.com' -o /dev/null -w 'auth=%{http_code}\n' http://127.0.0.1/
curl -s -u admin:q1w2e3r4 -H 'Host: comic.example.com' http://127.0.0.1/home | grep -o '<title>[^<]*'

实测回显：

anon=401
auth=302
<title>Mylar - Home

auth=302 是登录后首页跳转 /home 的正常表现；带凭据直接取 /home 返回 200 与页面标题。

⚠️ 注意：Mylar3 的认证是 HTTP Basic，反向代理转发时必须保留 Authorization 头（Nginx 默认会保留）。若再叠加一层带认证的网关，注意不要重复弹认证框。

八、方案对比与选择建议

安装 Mylar3 实际只有「源码部署」一条技术路线，差别在获取方式与依赖管理。下表对比常见三种落地方式（本文实测的是方案 A）：

方案获取方式依赖管理升级方式适用场景实测状态
A：tar.gz + venv（本文）官方 tag 包 + 哈希校验venv 隔离换代码目录 + 保留数据目录生产、可复现、离线可打包已实测
B：git clone + venvgit clone 仓库venv 隔离git fetch 切 tag想跟分支/回滚方便未单独实测（同一份代码）
C：发行版打包/第三方脚本系统包或社区脚本系统 Python随包管理器快速试用未实测

选择建议：生产环境选 A，因为发布件带固定 tag 与哈希，升级可控、审计清晰；需要频繁跟进小版本时选 B；方案 C 的包维护滞后且可能改动系统 Python 依赖，不建议用于长期运行。

九、配置说明（最小可用集）

完整参数见 《Mylar3 0.8.3 配置参数详解》。本节只列「装完必须改」的几项，确保开箱后能真正工作。config.ini 位于 /var/lib/mylar3/config.ini，手工修改后需重启服务生效。

节键本次实测值作用
[General]destination_dir/mnt/comics（示例）漫画库根目录，后处理最终落点
[General]create_foldersTrue自动建系列目录
[CV]comicvine_api未配置ComicVine Key，必填
[Providers]provider_order空索引器顺序，需按实际索引器填写
[Client]nzb_downloader3（默认）0=SABnzbd、1=NZBGet、2=Blackhole、3=未启用
[Client]torrent_downloader0（默认）0=监视目录、1=uTorrent、2=rTorrent、3=Transmission、4=Deluge、5=qBittorrent
[Interface]http_port / http_host8090 / 0.0.0.0监听端口与地址
[Interface]http_username / http_passwordadmin / q1w2e3r4演示认证凭据
[Interface]authentication11=开启 Basic 认证
[API]api_enabled / api_keyTrue / 32 位串REST API 开关与密钥
Scheduler]search_interval1440自动搜索间隔（分钟）

配置修改后的重启与验证：

systemctl restart mylar3
systemctl is-active mylar3

实测回显：

active

十、常见问题

10.1 启动日志出现「language detected as non-English (C)」

现象：首次前台启动时打印：

language detected as non-English (C). Forcing specific logging module - errors WILL NOT be captured in the logs

原因：服务端 LANG 未设置，Mylar3 判定为非英文环境后强制切换日志模块，副作用是部分异常不会写入日志文件。解决：在 systemd 单元加 Environment=LANG=C.UTF-8 后重启。实测该行不再出现，systemctl restart 后日志直接进入正常启动序列。

10.2 Python 3.12 下大量 SyntaxWarning

现象：首次运行 --help 或启动时刷出数百行：

/opt/mylar3/mylar/helpers.py:225: SyntaxWarning: invalid escape sequence '\/'

原因：源码里的正则字符串使用了非法的转义序列（如 \/、\$），Python 3.12 会告警提示将来版本可能报错。属上游代码风格问题，不影响功能。若嫌日志噪音大，可在启动参数加 -q（关闭控制台日志）或把警告重定向，但不要为此改源码。

10.3 端口冲突

现象：重复启动时出现：

Failed to start on port: 8091. Is something else running?

原因：上一次进程尚未完全退出（Mylar3 的关闭流程需要数秒清理调度器与队列）。处理：systemctl stop mylar3 后等待 is-active 变为 inactive，或 ss -ltnp | grep 809x 确认端口释放后再启动。

10.4 周榜任务在 2026 年抛异常

现象：启动后后台任务报错：

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

原因：weekly_info() 对非 2025 年份使用 strftime("%U") 取周号，返回字符串，随后参与 timedelta(weeks=weeknumber) 运算时类型不匹配。属源码年份特判遗留缺陷。规避：启动参数加 -w（跳过启动时的周榜检查），实测加上后不再触发该任务；周榜页面数据仍会按调度周期尝试刷新，失败只影响「本周新刊」展示，不影响订阅与下载。

10.5 执行维护子命令报 str/bytes 错误

现象：maintenance -fs 报：

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

maintenance -xj 报：

TypeError: a bytes-like object is required, not 'str'

原因：maintenance.py 中 os.sep.encode('unicode-escape') 与二进制方式写 JSON 的写法在 Python 3 上类型不匹配，3.12 下必现。影响范围仅 -fs（修路径双斜杠）与 -xj（导出 ComicID 清单）；-cp（清空 provider 表）实测正常。日常备份/恢复不受影响（见 《Mylar3 0.8.3 常用 CLI 与运维命令详解》）。

10.6 pip 安装依赖缓慢或超时

现象：pip install -r requirements.txt 长时间卡在下载。处理：换国内 PyPI 源，例如：

/opt/mylar3/venv/bin/pip install -r /opt/mylar3/requirements.txt \
  -i https://pypi.tuna.tsinghua.edu.cn/simple

本次实测 PyPI 官方源可直连，未发生该问题；此命令为备用渠道写法。

十一、卸载与清理

需要彻底移除时按「停服务 → 删单元 → 删目录 → 删用户」顺序执行，避免残留进程占用 8090。

systemctl disable --now mylar3
rm -f /etc/systemd/system/mylar3.service
systemctl daemon-reload
rm -rf /opt/mylar3
rm -rf /var/lib/mylar3
rm -rf /var/log/mylar3
userdel -r mylar

验证清理结果：

systemctl is-active mylar3 || echo "service removed"
ss -ltn | grep 8090 || echo "port free"
id mylar 2>/dev/null || echo "user removed"

实测回显：

inactive
port free
user removed

⚠️ 注意：/var/lib/mylar3 内含 mylar.db 与漫画库的索引关系，卸载前先备份；如果漫画文件本身放在独立磁盘（如 /mnt/comics），删除数据目录不会动到漫画文件，但重新安装后需要重新扫描入库。

十二、参考链接

内容地址
项目仓库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
deadsnakes PPAhttps://launchpad.net/~deadsnakes/+archive/ubuntu/ppa
Nginx 反向代理文档https://nginx.org/en/docs/http/ngx_http_proxy_module.html
站内：认知与选型《Mylar3 介绍与选型指南》
站内：配置参数《Mylar3 0.8.3 配置参数详解》
站内：命令与运维《Mylar3 0.8.3 常用 CLI 与运维命令详解》