Homer v26.08.3 配置参数详解

Homer v26.08.3 配置参数详解:唯一状态文件 assets/config.yml 的查看与修改方式(热加载实测)、顶层键与卡片键两级总览、页头/布局/主题配色/样式表/消息横幅/导航多页面/服务分组/智能卡/连通检测/externalConfig 十类参数逐项拆解,附 YAML 语法错误实测、CORS 与凭据暴露等常见问题与生产配置模板(Ubuntu 22.04 实测,2026-11-02/03)。

HomerHomer面板自托管2026/11/03

Homer v26.08.3 配置参数详解

目标:把 Homer 唯一的配置来源——assets/config.yml——从"怎么改、怎么校验、怎么生效"到"每一个顶层键与卡片键的含义"讲透,全部参数行为均在一台 Ubuntu 22.04 服务器的实测面板(v26.08.3,HTTP 端口 8129)上验证。面板部署见《Homer Docker Compose 部署指南》。

Homer 没有服务端配置、没有环境变量之外的运行参数、没有数据库——浏览器加载页面后 fetch assets/config.yml,在客户端解析 YAML 并渲染。这个架构决定了本篇的三条主线:改文件即改配置(无需重启任何进程,实测见 3.2)、语法错误只影响浏览器渲染(服务端照常原样吐文件,实测见 7.1)、配置内容对所有访问者可见(/assets/config.yml 直接可 curl,凭据处理见 5.8 与 7.3)。

本篇实测的配置文件宿主路径为 /opt/data/quzuo/tmp/homer/stack/data/assets/(读者替换为自己的部署目录,下文命令均按此路径书写)。

一、环境信息

项目取值
软件版本Homer v26.08.3(CalVer,2026-08-30 发布)
配置文件assets/config.yml(宿主:/opt/data/quzuo/tmp/homer/stack/data/assets/config.yml)
配置格式YAML(支持锚点等全部 YAML 特性,见 5.7)
解析方浏览器端(Vue SPA 客户端 fetch + 解析),无服务端处理
实测面板地址http://127.0.0.1:8129(根路径实例)、http://127.0.0.1:8131/homer/(子路径实例)
同页资源assets/page2.yml(第二页)、assets/custom.css(自定义样式)、assets/logo.png、assets/tools/、assets/icons/、assets/manifest.json、assets/themes/
校验工具python3 + PyYAML(yaml.safe_load)、官方 JSON Schema(见 3.4)
官方文档口径configuration.md / theming.md / customservices.md / tips-and-tricks.md(2026-11-02 main 分支离线件)

二、前置条件

  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/assets/config.yml

回显(实测):

26.08.3
200
  1. 对配置目录有读写权限(改配置就是改文件,本篇命令以 root 在宿主执行);
  2. 本机可用 python3 -c "import yaml"(用于改前语法校验,3.3);
  3. 想改颜色/布局时手边开一个浏览器标签(Homer 生效与否只看浏览器重新 fetch,Ctrl+Shift+R 强刷排除缓存)。

三、参数查看与修改方式

3.1 查看当前生效的配置

配置唯一来源就是 assets/config.yml,两种查看口径:

# 宿主文件视角
cat /opt/data/quzuo/tmp/homer/stack/data/assets/config.yml
# HTTP 视角(与浏览器拉到的内容逐字节一致)
curl -s http://127.0.0.1:8129/assets/config.yml

顶层键结构可以用 PyYAML 直接打印(实测回显):

python3 -c "import yaml; d=yaml.safe_load(open('/opt/data/quzuo/tmp/homer/stack/data/assets/config.yml')); print('config.yml OK, top keys:', list(d.keys()))"
config.yml OK, top keys: ['title', 'subtitle', 'documentTitle', 'logo', 'header', 'footer', 'columns', 'connectivityCheck', 'defaults', 'theme', 'stylesheet', 'colors', 'message', 'links', 'updateIntervalMs', 'services']

第二页 page2.yml 只写覆盖项,其余继承主配置(实测回显):

page2.yml OK, top keys: ['subtitle', 'message', 'links', 'services']

3.2 修改与生效:改文件 + 刷新浏览器,无重启

Homer 无后端解析进程,修改配置不需要重启任何服务。实测热加载序列(改 title → 验证 HTTP 侧内容 → 验证页面服务不受影响 → 改回):

curl -s http://127.0.0.1:8129/assets/config.yml | grep -E '^title|^subtitle'
sed -i 's/^title: "Home Lab"/title: "Home Lab C1"/' /opt/data/quzuo/tmp/homer/stack/data/assets/config.yml
curl -s http://127.0.0.1:8129/assets/config.yml | grep '^title'
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8129/
sed -i 's/^title: "Home Lab C1"/title: "Home Lab"/' /opt/data/quzuo/tmp/homer/stack/data/assets/config.yml
sleep 1 && curl -s http://127.0.0.1:8129/assets/config.yml | grep '^title'

回显(实测,全程未重启任何进程):

title: "Home Lab"
subtitle: "G27 面板实测"
title: "Home Lab C1"
200
title: "Home Lab"

💡 说明:浏览器端何时看到新值,取决于 PWA/service worker 缓存策略;排查"改了没生效"时先 Ctrl+Shift+R 强刷(官方 troubleshooting 同款建议),再 curl 对照 3.1 确认服务端内容。

3.3 修改前语法校验(强烈建议)

配置写坏不会让服务挂,但会让面板整页渲染失败(实测见 7.1)。改完先本地校验:

python3 -c "import yaml; yaml.safe_load(open('/opt/data/quzuo/tmp/homer/stack/data/assets/config.yml')); print('OK')"

报错时 PyYAML 直接给出行列号(7.1 有完整实录)。

3.4 编辑器自动补全(官方 JSON Schema)

官方 tips-and-tricks 收录了配置 Schema,在文件首行加注释即可让 VSCode/IntelliJ 系编辑器获得补全与校验:

# yaml-language-server: $schema=https://raw.githubusercontent.com/bastienwirtz/homer/main/.schema/config-schema.json

(IntelliJ 写法为 # $schema: <同 URL>。Schema 地址:https://raw.githubusercontent.com/bastienwirtz/homer/main/.schema/config-schema.json)

3.5 多页面与外部配置的加载关系

  • links: 中 url: "#page2" → 浏览器加载 assets/page2.yml,以主配置为基底做字段覆盖(page2 未写的键沿用 config.yml,实测 3.1 的 page2 顶层键只有 4 个);
  • 顶层 externalConfig: <URL> → 从远端拉 YAML,写了它,本文件其余内容全部被忽略(官方 configuration.md 原文 "Using this will ignore remaining config in this file"),实测见 5.10。

四、参数总览

顶层键 16 个(实测清单见 3.1),按职责分组总览:

组键类型默认行为
页头title / subtitle / documentTitle / logo / icon / header / footer字符串/布尔不写 documentTitle 用 title;logo 与 icon 同给时 icon 优先
布局columns / defaults.layout / defaults.colorTheme / defaults.iconWidth / hotkey.search字符串columns: "3"、layout: columns、colorTheme: auto、iconWidth: auto、搜索热键 /
主题theme / colors.light.* / colors.dark.*字符串/映射theme: default;colors 缺项回落主题默认值
样式stylesheet列表不加载
消息message.*(style/title/icon/content/url/mapping/refreshInterval)映射无横幅
导航links[](name/icon/url/target)列表无导航链接
智能卡updateIntervalMs + services[].items[].type 等数值/列表不自动刷新(默认禁用)
连通connectivityCheck / proxy.useCredentials / proxy.headers布尔/映射connectivityCheck 默认关;凭据默认不发
外部externalConfig字符串 URL不启用
内容services[](组:name/icon/logo/class/items)列表空面板

卡片(items[])级键总览:

键作用键作用
name卡片标题(必填)url点击跳转目标,也是智能卡 API 基址
subtitle副标题;会覆盖智能卡自动状态行logo / icon卡片图标(图片路径 / Font Awesome 类名,同给 icon 优先)
tag / tagstyle角标文字 / bulma 样式(is-info/success/warning/danger 等)keywords模糊搜索隐藏关键词
target链接 target(_blank/_self/_top)class / background卡片自定义 CSS 类 / 直接给背景色
quick[]卡片底部快捷小链接(name/url/icon/target/color)type启用智能卡(见 5.8)
endpoint / useCredentials / headers / hide智能卡通用项(见 5.8)timeout / method / successCodesPing 类卡专属(见 5.8)

五、核心参数分类详解

5.1 页头与标题(title / subtitle / documentTitle / logo / icon / header / footer)

title: "Home Lab"
subtitle: "G27 面板实测"
documentTitle: "HomeLab Dashboard"   # 浏览器标签页文字,不写则用 title
logo: "assets/logo.png"              # 页头图片
# icon: "fas fa-skull-crossbones"    # 或改用 Font Awesome 图标;logo/icon 同给时 icon 优先
header: true                         # false 隐藏整个页头
footer: '<p>Homer v26.08.3 实测 // <a href="https://github.com/bastienwirtz/homer">GitHub</a></p>'
# footer: false                      # 隐藏页脚

footer 接受 HTML。logo 指向的路径是浏览器相对面板根的 URL——实测教训:配置里写了 logo: "assets/logo.png" 但目录里没有该文件时,curl 检查返回 404(页头图标裂开,其余功能正常):

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

把图片放进 assets/ 后同名复查即 200(实测 assets/logo.png -> 200)。改完配置用 curl 逐个核对引用路径是 Homer 特有的"配置验收"手段。

5.2 布局与列数(columns / defaults.layout / defaults.iconWidth / hotkey)

columns: "4"          # "auto" 或 12 的因数:1/2/3/4/6/12
defaults:
  layout: columns     # columns(网格)或 list(清单)
  iconWidth: auto     # auto 按图标实际宽度;fixed 等宽对齐(Font Awesome 7 新默认,Homer 保持旧行为)
hotkey:
  search: "Shift"     # 可选,改搜索热键(默认 "/")

layout 与配色主题一样可在页面右上角即时切换(用户选择存浏览器本地,defaults 只是初始值)。columns 写非 12 因数的数字会按浏览器渲染回退,官方示例只列合法值。

5.3 主题与配色(theme / colors)

theme 取值为发行包 assets/themes/ 下的目录名。实测本环境主题目录:

ls /opt/data/quzuo/tmp/homer/stack/data/assets/themes/
walkxcode

官方内置 default / walkxcode / neon 三主题,另有社区主题(Catppuccin、DietPi、Dracula、Homer Theme v2,见 theming.md 链接)。切换实测(改 theme: default → theme: walkxcode 再改回,curl 验证文件内容变化即生效路径正确,浏览器强刷看效果):

sed -i 's/^theme: default/theme: walkxcode/' /opt/data/quzuo/tmp/homer/stack/data/assets/config.yml
curl -s http://127.0.0.1:8129/assets/config.yml | grep '^theme'
sed -i 's/^theme: walkxcode/theme: default/' /opt/data/quzuo/tmp/homer/stack/data/assets/config.yml
curl -s http://127.0.0.1:8129/assets/config.yml | grep '^theme'
theme: walkxcode
theme: default

colors: 按 light/dark 两套分别覆盖,全部键与 CSS 变量一一对应(theming.md 权威表):

YAML 键CSS 变量作用
highlight-primary--highlight-primary页头背景、分组标题图标
highlight-secondary--highlight-secondary导航栏背景、默认 tag 颜色
highlight-hover--highlight-hover导航悬停、搜索框背景
background--background页面背景色
card-background--card-background卡片背景色
text / text-header / text-title / text-subtitle同名 --text*正文/页头/卡片标题/副标题文字色
card-shadow--card-shadow卡片 box-shadow
link / link-hover--link / --link-hover页脚与消息链接色、卡片图标色
background-image--background-image页面背景图 URL(CSS 里要写 url(...) 包一层)

状态点与徽标另有 13 个可覆盖色(status-online/offline/warning/busy/unknown、badge-info/success/warning/danger/accent/neutral/text),卡片几何尺寸走 CSS 变量(--card-height 85px、--card-icon-size 48px、--card-radius 0.75rem 等,默认值在 assets/components/base.scss,只能在 stylesheet 里覆盖,不在 colors: 内)。

本方案实测配置只覆盖 5 个键,其余回落主题默认(官方明确"所有键可选,未设即回落"):

colors:
  light:
    highlight-primary: "#3367d6"
    background: "#f5f5f5"
  dark:
    highlight-primary: "#1f6f54"
    background: "#131313"
    card-background: "#2b2b2b"

⚠️ 注意:子路径托管时 background-image 的路径要带前缀(如 /homer/assets/...)。实测子路径实例(http://127.0.0.1:8131/homer/)资源引用由 SUBFOLDER 环境变量改写,但 colors: 里手写的图片 URL 属于配置内容,需自己加前缀。

5.4 自定义样式与 PWA 素材(stylesheet / icons / manifest.json)

stylesheet:
  - "assets/custom.css"

custom.css 实测内容(官方 theming.md 的加宽页面主体示例):

/* Homer 自定义样式:加宽主容器 */
body #main-section .container {
    max-width: 2000px;
}

加载验证:curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8129/assets/custom.css → 200(实测)。Favicon 与 PWA 安装图标放 assets/icons/(同名替换即可),应用名称/描述改 assets/manifest.json——这两个文件实测均可 HTTP 直达(见 5.1 回显)。

5.5 消息横幅(message)

静态文案:

message:
  style: "is-info"          # bulma 修饰:is-info/is-success/is-warning/is-danger
  title: "实验环境"
  icon: "fas fa-flask"
  content: "Homer v26.08.3 配置实测进行中"   # 接受 HTML

动态端点:url: 拉 JSON,字段名不合时用 mapping: 映射,refreshInterval: 定时刷新。官方示例(chucknorris.io 冷笑话)的端点返回格式实测(截取):

{"categories":[],"created_at":"2020-01-05 13:42:20.262289","icon_url":"https://api.chucknorris.io/img/avatar/chuck-norris.png","id":"Ph-efwMsR0qU48CAmX6Zyw","updated_at":"2020-01-05 13:42:20.262289","url":"https://api.chucknorris.io/jokes/Ph-efwMsR0qU48CAmX6Zyw","value":"Chuck Norris once demonstrat

Homer 期望的格式是 {"style": null, "title": "...", "content": "..."},映射写法:

message:
  url: https://api.chucknorris.io/jokes/random
  mapping:
    content: 'value'      # 端点 value 字段 → 横幅 content
  title: "Chuck Norris Facts!"   # 端点缺该字段时保留本地值
  content: "Message could not be loaded"  # 端点失败时的兜底

合并语义(configuration.md 权威):端点里 null 或缺失的键忽略、用本地值;空串会隐藏对应元素("title": "" 即去掉标题条)。content 支持 HTML,官方 tips 收录了 Frigate 摄像头最新帧直嵌横幅的玩法。

links:
  - name: "GitHub"
    icon: "fab fa-github"
    url: "https://github.com/bastienwirtz/homer"
    target: "_blank"
  - name: "第二页"
    icon: "fas fa-file-alt"
    url: "#page2"        # 锚点式页面链接:加载 assets/page2.yml

url: "#page2" 与 assets/page2.yml 文件名对应(#xxx → xxx.yml),可无限扩展页面数;页面配置只写要覆盖的顶层键(实测 page2 只含 subtitle/message/links/services 四键,页头标题、主题、配色全部继承主配置)。page2 里再放 url: "#" 的 Home 链接即可回主页。

5.7 服务分组与卡片(services)

结构:services[] 第一层是分组(name/icon/logo/class/items),items[] 是卡片。分组 name/icon/logo 可省(只留 items 即无标题段落)。本方案实测分组示例:

services:
  - name: "基础设施"
    icon: "fas fa-server"
    class: "highlight-purple"    # 分组级自定义 CSS 类
    items:
      - name: "本面板"
        logo: "assets/tools/sample.png"
        subtitle: "Homer 自身"
        tag: "panel"
        tagstyle: "is-success"   # bulma 修饰色
        keywords: "homer dashboard 面板"
        url: "http://127.0.0.1:8129/"
        target: "_self"
        quick:
          - name: "配置"
            url: "http://127.0.0.1:8129/assets/config.yml"
            icon: "fas fa-file-code"
            target: "_blank"
            color: "#4285f4"     # 可选,覆盖小药丸底色

tagstyle 用 bulma 修饰语法,常用四色:is-info(蓝)/is-success(绿)/is-warning(黄)/is-danger(红)。

YAML 锚点复用(官方 tips 收录):tag/样式定义一次、多卡片引用——

tags:
  Apps: &Apps
    - tag: "App"
      tagstyle: "is-medium is-info"
services:
  - name: "开发工具"
    items:
      - name: "VS Code"
        <<: *Apps          # 展开等价于逐行写 tag/tagstyle
        url: "https://vscode.example.com/"

💡 技术拓展:tags: 顶层键不是 Homer 的功能参数,只是借 YAML 锚点做变量池——Homer 解析时会忽略未知顶层键。同类"配置即代码"复用手段还有 JSON Schema 补全(3.4)与 externalConfig 集中管理(5.10)。

5.8 智能卡(type / endpoint / headers / hide / updateIntervalMs)

卡片加 type: 即启用对应智能组件,取值必须精确匹配 src/components/services/ 下的文件名(不含扩展名)。v26.08.3 官方清单约 54 种,按域归类摘选:

域type 取值
网络/广告AdGuardHome、PiHole、Traefik、Gatus、Healthchecks、NetAlertx、PiAlert、SpeedtestTracker、Ping
媒体Emby、Jellyfin、Plex、Tautulli、Tdarr、Jellystat、Olivetin
下载/索引qBittorrent、rTorrent、SABnzbd、Transmission、Lidarr、Radarr、Sonarr、Prowlarr、Readarr、Mylar、Medusa
基础设施Proxmox、Docker Socket Proxy、What's up Docker、Portainer、Glances、Prometheus、Scrutiny、PeaNUT
自托管应用HomeAssistant、Immich、Nextcloud、FreshRSS、Miniflux、Wallabag、Mealie、Paperless-ngx、Linkding、Docuseal、Matrix、Gitea/Forgejo、Gotify、HomeAssistant、Seerr(v26.08.3 新增)、Vaultwarden、OpenHAB、Octoprint、OpenWeatherMap、CopyToClipboard

通用选项(customservices.md "Common options"):

- name: "My Service"
  type: "<type>"
  url: https://my-service.url        # 卡片链接 + 智能卡 API 基址
  endpoint: https://my-service-api.url  # 数据 API 基址与 url 不同时用它
  useCredentials: false              # 覆盖全局 proxy.useCredentials
  headers:                           # 卡片级请求头,叠加并覆盖全局 proxy.headers
  hide: [badgeKey, ...]              # 移除该卡片的某些徽标/字段
  updateIntervalMs: 5000             # 卡片级刷新间隔,覆盖全局

行为要点(官方原文口径 + 实测佐证):

  • subtitle 覆盖状态行:智能卡默认在副标题位置显示实时数据(如 PiHole 拦截数、Ping 的 RTT),写了 subtitle 就会被你的静态文案顶掉(本方案 Ping 卡故意不写 subtitle,实测显示往返时延);
  • 状态点/徽标语义:绿=健康、红=宕机、黄=需关注、脉冲绿=忙、灰=未知;徽标 99+ 封顶(重要总数除外),API 不可达显示 ?;
  • 轮询:全局 updateIntervalMs: 30000(最小 1000,0/删除即禁用),仅实现了刷新能力的卡参与;只读版本号的 8 种卡(Docuseal、Gitea、Matrix、OliveTin、Traefik、TrueNAS Scale、Vaultwarden、Wallabag)取一次不再轮询;
  • CORS 硬约束:智能卡在浏览器端直连目标 API,跨域名/跨端口即触发 CORS 拦截——要么同域反代聚合,要么目标服务加 Access-Control-Allow-Origin,要么走代理(官方推荐 CORSair)。详见 7.2。

Ping 卡(本方案实测在用):

- name: "Wikipedia 连通测试"
  type: Ping
  icon: "fas fa-network-wired"
  url: "https://www.wikipedia.org/"
  # method: "head"          # 默认 HEAD,可改 GET
  # successCodes: [200, 418] # 默认全部 2xx 视为可达
  # timeout: 500             # 毫秒,默认 2000
  # endpoint: "https://www.wikimediastatus.net"  # ping 目标与 url 不同时

5.9 连通性检测与请求代理(connectivityCheck / proxy)

connectivityCheck: true
proxy:
  useCredentials: false   # 取智能卡数据时携带 Cookie/Authorization(配鉴权反代时置 true)
  headers:                # 全局自定义请求头,可被卡片级 headers 覆盖
    Test: "Example"

connectivityCheck 周期性对面板自身发 HEAD(绕过 PWA 缓存):VPN/隧道断开时页面给出提示;配合鉴权反代时,检测到 302 重定向即自动重载页面回登录页。官方明确要求用鉴权代理时必须开此项。

5.10 外部配置源(externalConfig)

externalConfig: "http://127.0.0.1:8129/assets/page2.yml"

用途:多台 Homer 实例共享同一份配置源(集中管理)。实测在 config.yml 顶部注入该行:

sed -i 's|^title: "Home Lab"|externalConfig: "http://127.0.0.1:8129/assets/page2.yml"\ntitle: "Home Lab"|' /opt/data/quzuo/tmp/homer/stack/data/assets/config.yml
grep -n externalConfig /opt/data/quzuo/tmp/homer/stack/data/assets/config.yml
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8129/assets/page2.yml

回显(实测):

2:externalConfig: "http://127.0.0.1:8129/assets/page2.yml"
200

外部源可达即浏览器改从该 URL 取配置;注意文件里其余键全部失效(含 title),演示完删除该行恢复(实测 grep -c externalConfig 归 0)。

六、生产配置模板

适用场景:家庭实验室 / NAS 统一入口,30–80 个服务,面板置于鉴权反向代理之后,配置目录进 git;资源要求可忽略(常驻内存约 1 MiB,实测见部署篇第十章)。凭据原则见文末 ⚠️。

---
# homer-prod/assets/config.yml —— 生产模板(同域反代 + 鉴权之后)
title: "Home Lab"
subtitle: "ops.example.net"
documentTitle: "Home Lab"
logo: "assets/logo.png"
header: true
footer: '<p>Home Lab // <a href="https://github.com/bastienwirtz/homer">Homer v26.08.3</a></p>'

columns: "4"
connectivityCheck: true          # 鉴权反代下必须 true(会话过期自动重载)
proxy:
  useCredentials: true           # 同域反代 + 鉴权时携带 Cookie 取智能卡数据
defaults:
  layout: columns
  colorTheme: auto
theme: default
stylesheet:
  - "assets/custom.css"

# 锚点池:tag 统一定义(官方 tips 玩法)
tags:
  Apps: &Apps
    - tag: "App"
      tagstyle: "is-medium is-info"
  Net: &Net
    - tag: "Net"
      tagstyle: "is-medium is-warning"

links:
  - name: "状态页"
    icon: "fas fa-signal"
    url: "https://status.example.net/"
    target: "_blank"
  - name: "第二页"
    icon: "fas fa-file-alt"
    url: "#page2"

updateIntervalMs: 30000

services:
  - name: "网络"
    icon: "fas fa-network-wired"
    items:
      - name: "Pi-hole"
        type: PiHole
        logo: "assets/tools/pihole.png"
        <<: *Net
        url: "https://network.example.net/pihole/"
        # API 凭据不要写这里,见下方注意
      - name: "外网连通"
        type: Ping
        icon: "fas fa-globe"
        url: "https://www.wikipedia.org/"
        timeout: 1000
  - name: "虚拟化"
    icon: "fas fa-server"
    items:
      - name: "Proxmox"
        type: Proxmox
        logo: "assets/tools/proxmox.png"
        <<: *Apps
        url: "https://pve.example.net/"
  - name: "媒体"
    icon: "fas fa-film"
    items:
      - name: "Jellyfin"
        type: Emby
        logo: "assets/tools/jellyfin.png"
        <<: *Apps
        url: "https://media.example.net/"

⚠️ 注意(凭据红线):config.yml 会原样暴露在 http://<面板>/assets/config.yml,任何写进配置的 API Key(如 PiHole 的 ${PIHOLE_API_TOKEN}、OpenWeatherMap 的 ${OWM_API_KEY})对所有能访问面板的人可见。生产做法二选一:① 面板整体套鉴权(反代 Basic Auth/Authelia),Key 只暴露给已登录者;② 用 CORSair 一类代理在服务端注入凭据(环境变量落代理侧),Homer 配置里不出现 Key。模板中 ${PIHOLE_API_TOKEN} 等占位符的注入方式即②:在代理服务的 env 里配置真实值,面板 YAML 永远不落密钥。

七、常见问题

7.1 YAML 写坏了会怎样?——服务照常,页面空白

实测注入一处未闭合流序列(bad_key: [unclosed 追加到文件尾):

printf 'bad_key: [unclosed\n' >> /opt/data/quzuo/tmp/homer/stack/data/assets/config.yml
python3 -c "import yaml; yaml.safe_load(open('/opt/data/quzuo/tmp/homer/stack/data/assets/config.yml'))"
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8129/assets/config.yml
curl -s http://127.0.0.1:8129/assets/config.yml | tail -2

回显(实测):

yaml.parser.ParserError: while parsing a flow sequence
  in "/opt/data/quzuo/tmp/homer/stack/data/assets/config.yml", line 77, column 10
expected ',' or ']', but got '<stream end>'
  in "/opt/data/quzuo/tmp/homer/stack/data/assets/config.yml", line 78, column 1
200
        url: "#"
bad_key: [unclosed

三个结论:① 静态服务不做 YAML 校验,坏文件照样 200 原样吐出;② 浏览器端解析失败,面板渲染不出(浏览器控制台会报 YAML 错误);③ 定位靠 PyYAML 的行列号最快捷。恢复实测:备份文件拷回后 config.yml OK、HTTP 200、刷新即复原。改前 cp config.yml config.yml.bak + 改后 safe_load 校验应当成为肌肉记忆(备份策略见运维篇)。

7.2 智能卡不显示 / 一直 offline

大概率是 CORS:目标服务与面板不同域名或不同端口时,浏览器拒绝跨源取数,控制台出现 blocked by CORS policy: No 'Access-Control-Allow-Origin' header 字样。官方给的三条出路(troubleshooting/customservices 一致口径):

  1. 把所有服务收拢到同一域名(同反代不同路径)——最干净;
  2. 目标服务本身或其前置反代加 Access-Control-Allow-Origin 头;
  3. 加代理层补头,官方点名推荐轻量方案 CORSair。

7.3 配置里的 API Key 泄不泄露?

泄露——/assets/config.yml 对任何能访问面板的人可读(curl 实测 200 直出全文)。官方 customservices.md 顶部 WARNING 原文口径:要么给 Homer 套鉴权/访问控制,要么用 CORSair 在服务端注入凭据。这也是六章模板把 Key 全部留给代理侧的原因。

7.4 智能卡的状态被自己写的 subtitle 顶掉了

官方行为:subtitle 一旦提供就覆盖智能卡的实时状态行(5.8)。想要实时数据就别写 subtitle;想要固定文案则接受状态不显示。

7.5 OpenWeatherMap 卡填了 Key 不出数

官方 troubleshooting 专条:新建账号/新 Key 常需等待数小时激活;先换大城市(如 Amsterdam)验证 location 有效性;改配置后浏览器 Ctrl+Shift+R 强刷;控制台看 api.openweathermap.org 报错。

7.6 Font Awesome 7 升级后某个图标不渲染

v26.08.3 已带 Font Awesome 7.3.1。配置里的 fas/fa/far/fab 旧语法与自定义样式表里的 "Font Awesome 6" 字体族名都保持兼容(官方做了别名映射)。唯一被移除的免费图标:fa-vector-square(FA 改名 draw-square 且转 Pro),表现为空白方块——换 object-group 或 crop-simple。

7.7 自定义样式在升级后失效(卡片结构重构)

官方 troubleshooting:自 26.09.20 起卡片统一新布局,旧选择器失配——.media/.media-left/.media-content 移除(图标改 .card-icon、标题副标题进 .card-body);.card-wrapper 多了一层;.card > .card-content > a.card-link;.tag 改用 max-width 收起;.quicklinks 变底部 flex;状态点动画更名 status-pulse。.card:hover 仍有效。写自定义 CSS 前先确认目标版本(curl /VERSION)。

7.8 卡片文字选不中、部分 tooltip 不弹

预期行为(官方 troubleshooting):整张卡片是一个透明链接覆盖层,指针被链接接管,卡片正文不可选中、体内元素的原生 title 提示不弹出;徽标与 tag 的 tooltip 不受影响。需要"可复制的配置链接"之类内容时,放 quick: 小链接或页脚 HTML,而不是指望选中卡片文字。

八、参考链接

Homer v26.08.3 配置参数详解 - Quzuo