Homer 日常运维手册

目标：给出 Homer v26.08.3 上线后的日常运维完整手册——巡检什么、怎么备份恢复、怎么告警、怎么扩缩、怎么升级回滚、出故障按什么顺序排查。全部命令与回显来自 Ubuntu 22.04 服务器上的实测环境（2026-11-02/03）。

Homer 的运维面由它的架构决定：没有数据库、没有服务端进程状态，唯一要运维的"数据"是 assets 配置目录，唯一要运维的"程序"是一堆静态文件。官方 README 把卖点写成 "Low / No maintenance" 不是营销话术——本手册会把这五个字拆成可执行的巡检项、备份命令和故障树。面板部署与托管形态见《Homer Docker Compose 部署指南》，参数含义见《Homer v26.08.3 配置参数详解》。

一、环境信息

💡 说明：本篇命令均在实测工作目录 /opt/data/quzuo/tmp/homer 执行（提示符回显为相对路径 stack/...），读者替换为自己的部署目录即可；涉及托管形态的完整命令（日志拉取、资源统计、版本切换）在部署篇对应章节逐字实测，本篇从服务器运维视角给出口径与结论。

二、日常巡检

2.1 服务可用性三探针

curl -s http://127.0.0.1:8129/VERSION
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8129/
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8129/assets/config.yml

回显（实测）：

26.08.3
200
200

三个探针分别覆盖：静态服务活着（/VERSION）、页面骨架可取（/）、面板有配置可渲染（config.yml 200）。第三个最关键——前两个 200 而它 404 时，用户看到的是"能打开但空白"的面板（故障树见 7.2）。子路径实例同口径：curl -s http://127.0.0.1:8131/homer/VERSION 返回 26.08.3（实测）。

2.2 托管侧状态与健康

托管形态下的实例状态实测回显（命令见部署篇第十章）：

NAME                 IMAGE                 COMMAND                  SERVICE     CREATED         STATUS                   PORTS
homer-v26.08.3-sub   b4bz/homer:v26.08.3   "/bin/sh /entrypoint…"   homer-sub   4 seconds ago   Up 3 seconds (healthy)   0.0.0.0:8131->8080/tcp, [::]:8131->8080/tcp
homer-v26.08.3-web   b4bz/homer:v26.08.3   "/bin/sh /entrypoint…"   homer       4 seconds ago   Up 3 seconds (healthy)   0.0.0.0:8129->8080/tcp, [::]:8129->8080/tcp

两实例 Up (healthy)、端口发布正常即为稳态。

2.3 配置语法与引用路径

改过配置必做（详细原理见配置篇 3.3/5.1）：

python3 -c "import yaml; yaml.safe_load(open('stack/data/assets/config.yml')); print('config.yml OK')"
curl -s http://127.0.0.1:8129/assets/config.yml | grep -oE 'assets/[A-Za-z0-9._/-]+' | sort -u | while read p; do echo "$p -> $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8129/$p)"; done

实测巡检输出（发现 logo 缺文件时的样子）：

assets/logo.png -> 404
assets/tools/sample.png -> 200
assets/icons/favicon.ico -> 200
assets/manifest.json -> 200
assets/custom.css -> 200
assets/page2.yml -> 200

404 项补齐文件后同名复查变 200（实测 assets/logo.png -> 200）。这一步能抓住"配置引用了不存在的图标/页面"这类只有浏览器打开才会暴露的问题。

2.4 资源水位

静态服务 + 单进程的开销实测（统计命令见部署篇第十章）：

CONTAINER ID   NAME                 CPU %     MEM USAGE / LIMIT     MEM %     NET I/O        BLOCK I/O   PIDS
2d88d21dd626   homer-v26.08.3-web   0.00%     1.055MiB / 15.57GiB   0.01%     3.2kB / 716B   0B / 0B     1

水位基线：CPU 0%、内存约 1 MiB、单进程。这项巡检对 Homer 的意义是"确认没有异常"而非"关注容量"——内存若从 1 MiB 量级涨到百 MiB，基本可以断定进程被换成了别的东西或统计对象搞错了。

2.5 访问日志巡检

服务日志直通 stdout（拉取命令见部署篇第十章），实测节选：

homer-v26.08.3-web  | Starting webserver
homer-v26.08.3-web  | 2026-11-02 17:06:34: (../src/server.c.1973) server started (lighttpd/1.4.85)
homer-v26.08.3-web  | 10.89.56.1 127.0.0.1:8129 - [02/Nov/2026:17:06:35 +0000] "GET /VERSION HTTP/1.1" 200 7 "-" "curl/8.5.0"
homer-v26.08.3-web  | 10.89.56.1 127.0.0.1:8129 - [02/Nov/2026:17:06:54 +0000] "GET /assets/config.yml HTTP/1.1" 404 158 "-" "curl/8.5.0"

看两件事：server started 之后有无异常重启行；访问行里的 404（上面第二条 404 正是 2.3 抓到的 logo/配置缺文件类问题在日志侧的反映）。注意智能卡的取数请求是浏览器直连目标服务，不经过面板，面板日志里看不到它们——智能卡异常要开浏览器控制台看（见 7.4）。

2.6 巡检清单

三、备份与恢复

3.1 备份：一个 tar 就是全量

Homer 的全部状态在 assets 目录（配置、图标、样式、主题素材），无数据库、无进程内状态，备份即打包：

tar czf homer-assets-backup-$(date +%Y%m%d).tar.gz -C stack/data assets
ls -la homer-assets-backup-*.tar.gz

实测回显：

-rw-r--r-- 1 root root 188985 Nov  3 01:06 homer-assets-backup-20261103.tar.gz

含图标素材在内全量仅 184KB——备份成本可以忽略，建议直接每日 cron：

# crontab -e：每天 03:30 全量打包，保留 30 天
30 3 * * * cd /opt/data/quzuo/tmp/homer && tar czf homer-assets-backup-$(date +\%Y\%m\%d).tar.gz -C stack/data assets && find . -name 'homer-assets-backup-*.tar.gz' -mtime +30 -delete

💡 说明：更工程化的做法是把 assets 目录直接进 git（配置即代码，Homer 官方定位就是单文件 YAML 可评审可回滚），tar cron 退化为兜底。两种方式都改变不了一个事实：恢复 = 把文件放回目录，无需重启任何进程。

3.2 恢复演练（实测：误删 config.yml）

先制造故障——删掉主配置，确认面板侧症状：

rm stack/data/assets/config.yml
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8129/assets/config.yml

404

此时浏览器打开面板：页面骨架 200、卡片区域空白（配置取不到）。从备份恢复：

tar xzf homer-assets-backup-20261103.tar.gz -C stack/data
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8129/assets/config.yml

200

实测恢复全程 10 秒以内，无进程重启、无依赖服务协调。刷新浏览器面板即复原。

3.3 恢复注意事项

• 解包目标目录的属主须与面板服务运行身份一致（本环境 1000:1000），否则文件放回去了服务进程却读不到——恢复后务必跑 2.1 三探针而不是只看文件在不在；
• 备份包里不含 config.yml 之外的"运行状态"（Homer 没有），但用户侧浏览器本地状态（主题/布局切换选择、PWA 缓存）存在访问者浏览器里，恢复面板不影响它们；
• 若配置里写了 API Key，备份包等同凭据文件，存放与传输按密钥管理要求处理（参考配置篇 7.3 的暴露面分析）。

四、监控告警

4.1 外部拨测（推荐主通道）

Homer 最适合拨测的三个信号，全部来自二章探针：

接入任意 HTTP 拨测工具（Uptime Kuma 的 HTTP 关键词监控即可同时覆盖状态码 + 26.08.3 正文匹配）。实测响应体：/VERSION 返回 7 字节 26.08.3，日志行 "GET /VERSION HTTP/1.1" 200 7 可交叉印证。

4.2 面板侧 connectivityCheck（用户自助感知）

配置 connectivityCheck: true（本环境实测配置已开）后面板自己周期 HEAD 探测：VPN/隧道断开时用户看到提示条，鉴权反代会话过期时自动重载回登录页。这是 Homer 给"面板不可达"提供的用户端告警，与服务端拨测互补——拨测知道"挂了"，connectivityCheck 让用户知道"不是我网络的问题"。

4.3 日志侧异常信号

4.4 无需监控的项

Homer 无队列、无连接池、无内存增长型状态，不需要容量类告警；智能卡目标服务的存活监控属于那些服务自己的运维（或交给面板上的 Uptime Kuma 卡/健康检查卡去展示），不在本手册范围。

五、扩容缩容

结论先行：单实例 Homer 不存在性能瓶颈，扩容需求几乎总是"逻辑分域"而非"负载分摊"。

• 实测水位（1 MiB 内存、单进程、静态文件 IO）意味着一台最弱的虚拟机也能扛住家庭实验室全部访问量——瓶颈永远在前置反代或带宽，不在 Homer；
• 需要"多个实例"的真实场景：① 按团队/环境分面板（工作/家庭两套配置互不干扰）；② 子路径托管与根路径托管并存——本环境实测就是双实例形态（8129 根路径 + 8131 /homer/ 子路径），两实例各挂各的 assets 目录、互不共享配置；
• 多实例配置一致性：用 externalConfig: 指向同一远端 YAML（配置篇 5.10 实测可用），改一处全端生效；否则各实例独立备份（三章的 tar 按目录各打一份）；
• 缩容：删实例 = 停服务 + 保留 assets 目录（状态与进程天然分离，随时可再拉起）；磁盘占用大头是图标素材，KB~MB 量级，无缩容压力。

六、升级与回滚

6.1 版本节奏与策略

Homer 用 CalVer（YY.MM.patch），近 15 个月发布 10 个版本、无破坏性大版本（A1 选型篇实测口径）。升级心智负担主要在两处：智能卡 type 的增减（新版本新增的卡在旧版本渲染为普通链接卡）与自定义 CSS 选择器（26.09.20 起卡片结构重构，配置篇 7.7）。策略建议：生产固定版本标签，升级走维护窗口，升级前必做三章备份。

6.2 升级/回滚实测（v26.08.3 ↔ v26.08.2）

程序版本切换不动配置目录。实测回滚演练（完整命令序列见部署篇 11.3，本篇给运维口径与验证结果）：

# 1. 备份（回滚前也做）
tar czf homer-assets-pre-rollback-$(date +%Y%m%d).tar.gz -C stack/data assets
# 2. 切换版本并重新加载（托管侧动作）
# 3. 验证版本探针
curl -s http://127.0.0.1:8129/VERSION

实测结果：切到 v26.08.2 后探针返回 26.08.2；按同一流程切回 v26.08.3，探针返回 26.08.3，全程配置目录未动、/assets/config.yml 保持 200，服务日志正常出现 server started (lighttpd/1.4.85) 与业务请求行。

6.3 升级验收清单

1. curl /VERSION == 目标版本；
2. 2.1 三探针全绿；
3. 2.3 引用路径巡检全 200（新版本素材目录结构有变时尤其要跑）；
4. 浏览器强刷（Ctrl+Shift+R）确认 PWA 缓存已换版；
5. 逐张智能卡状态点核对：新版本新增的 type（如 v26.08.3 的 Seerr）在回滚场景会降级为普通卡，验收时确认没有"应该出数却变书签"的卡；
6. 自定义 CSS 生效核对（跨 26.09.20 边界时按配置篇 7.7 的选择器映射表逐项检查）。

七、故障排查手册

按"症状 → 定位 → 处置"组织，命令均可直接执行。

7.1 面板整页空白（有页头无卡片）

定位：配置侧问题居多。跑三探针，看 config.yml 是否 404（→7.2）或语法坏（→7.3）；浏览器控制台（F12）有 YAML 解析报错即后者。

7.2 config.yml 404

定位：curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8129/assets/config.yml 返回 404，且服务日志同步出现 "GET /assets/config.yml HTTP/1.1" 404（实测复现）。原因：文件被删、目录挂载/路径漂移、属主权限。

处置：误删走 3.2 恢复（实测 404→200，10 秒复原）；路径漂移核对托管配置里的目录映射；权限问题核对 assets 目录属主与服务运行身份（1000:1000）一致，详见部署篇 11.2。

7.3 YAML 写坏（服务 200、浏览器不渲染）

定位：Homer 静态服务不校验 YAML——坏文件照常被 200 吐出（实测），只有浏览器端解析失败。本地校验直接给行列号：

python3 -c "import yaml; yaml.safe_load(open('stack/data/assets/config.yml'))"

实测报错样例（未闭合流序列）：

yaml.parser.ParserError: while parsing a flow sequence
  in "stack/data/assets/config.yml", line 77, column 10
expected ',' or ']', but got '<stream end>'
  in "stack/data/assets/config.yml", line 78, column 1

处置：按行列号修文件，或从备份恢复（3.2）；恢复后 config.yml OK + 200 + 强刷浏览器三连确认。

7.4 智能卡不出数 / 显示 offline

定位：浏览器 F12 控制台。出现 blocked by CORS policy: No 'Access-Control-Allow-Origin' header 即跨域被拦（Homer 智能卡是浏览器直连目标 API，跨域名/跨端口必触发）。注意这类失败不体现在面板服务日志里（请求根本没到面板）。

处置（官方三选一，配置篇 7.2）：同域反代聚合（最干净）；目标服务或其反代补 CORS 头；上 CORSair 类代理。OpenWeatherMap 卡另有新 Key 需数小时激活的已知坑（配置篇 7.5）。

7.5 鉴权反代后面板提示离线/反复跳登录

定位：connectivityCheck 未开或反代未按要求行为——预期是未登录访问返回 302 跳转登录页；若返回 401 裸拒绝，面板探测逻辑无法识别为"会话过期"。

处置：配置置 connectivityCheck: true；核对反代认证插件的重定向行为；需要携带凭据取智能卡数据时同步开 proxy.useCredentials: true（配置篇 5.9）。

7.6 图标不渲染 / 自定义样式失效

• 单个图标空白方块且是 fa-vector-square：Font Awesome 7 已移除该免费图标，换 object-group/crop-simple（配置篇 7.6）；
• 升级后自定义 CSS 整体失效：卡片结构重构导致选择器失配，按配置篇 7.7 的映射表改选择器；
• 图片类图标 404：素材没进 assets 目录，走 2.3 巡检补文件。

7.7 服务反复重启（起不来）

定位：拉服务日志，出现 Assets directory not writable 字样即 assets 目录对服务运行身份不可写（INIT_ASSETS=1 首启落示例配置时写不进去会反复重启）。

处置：chown -R 1000:1000 <assets目录> 对齐属主，或配置自备后关 INIT_ASSETS；不要用 root 身份运行规避（官方明确警告，部署篇 11.2）。

八、常见问题

8.1 改配置要重启服务吗？

不要。实测热加载序列（配置篇 3.2）：改 title → curl 立即见新值 → 页面服务全程 200 未重启。浏览器侧看不到变化时先强刷排除 PWA 缓存。

8.2 备份到底要备哪些东西？

assets 目录整体（实测全量 tar 仅 184KB）。程序本体（静态文件）不需要备份——版本探针能定位，重新部署即恢复；托管编排文件（compose）建议随配置一起进 git。

8.3 面板能否自带登录？

不能。Homer 无任何鉴权能力，/assets/config.yml 对所有能访问它的人可读。访问控制只能外置：反代 Basic Auth/Authelia/Authentik，或网络隔离。这也是示例账号 root/q1w2e3r4 只适用于前置反代、面板自身没有账号体系的原因。

8.4 多实例怎么同步配置？

externalConfig: 指向同一远端 YAML（配置篇 5.10 实测源可达 200）；注意启用后本文件其余键全部失效。没有集中源时，把主配置纳入 git、CI 分发到各实例目录同样可靠。

8.5 IPv6 监听要不要关？

纯 IPv4 内网可关（托管侧环境变量 IPV6_DISABLE=1，实测关后 IPv6 回环探测 Connection refused、IPv4 正常，见部署篇第九章）；默认保持双栈即可。

九、参考链接

• 官方 README（Low/No maintenance 定位、环境变量）：https://github.com/bastienwirtz/homer
• 官方排障文档：https://github.com/bastienwirtz/homer/blob/main/docs/troubleshooting.md
• 官方配置文档：https://github.com/bastienwirtz/homer/blob/main/docs/configuration.md
• 智能卡清单与 CORS 约束：https://github.com/bastienwirtz/homer/blob/main/docs/customservices.md
• CORSair（官方推荐代理）：https://github.com/bastienwirtz/corsair
• 同系列：《Homer 介绍与选型指南》、《Homer Docker Compose 部署指南》、《Homer v26.08.3 配置参数详解》