Homer v26.08.3 配置参数详解
Homer v26.08.3 配置参数详解:唯一状态文件 assets/config.yml 的查看与修改方式(热加载实测)、顶层键与卡片键两级总览、页头/布局/主题配色/样式表/消息横幅/导航多页面/服务分组/智能卡/连通检测/externalConfig 十类参数逐项拆解,附 YAML 语法错误实测、CORS 与凭据暴露等常见问题与生产配置模板(Ubuntu 22.04 实测,2026-11-02/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 分支离线件) |
二、前置条件
- 面板已部署且可访问:
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
- 对配置目录有读写权限(改配置就是改文件,本篇命令以 root 在宿主执行);
- 本机可用
python3 -c "import yaml"(用于改前语法校验,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 / successCodes | Ping 类卡专属(见 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 摄像头最新帧直嵌横幅的玩法。
5.6 导航与多页面(links / #pageN)
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 一致口径):
- 把所有服务收拢到同一域名(同反代不同路径)——最干净;
- 目标服务本身或其前置反代加
Access-Control-Allow-Origin头; - 加代理层补头,官方点名推荐轻量方案 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,而不是指望选中卡片文字。
八、参考链接
- 官方配置文档:https://github.com/bastienwirtz/homer/blob/main/docs/configuration.md
- 官方主题文档:https://github.com/bastienwirtz/homer/blob/main/docs/theming.md
- 智能卡清单与通用选项:https://github.com/bastienwirtz/homer/blob/main/docs/customservices.md
- 官方 Tips & Tricks(锚点/Schema/消息映射):https://github.com/bastienwirtz/homer/blob/main/docs/tips-and-tricks.md
- 官方排障文档:https://github.com/bastienwirtz/homer/blob/main/docs/troubleshooting.md
- 配置 JSON Schema:https://raw.githubusercontent.com/bastienwirtz/homer/main/.schema/config-schema.json
- bulma 修饰语法(tagstyle 取值):https://bulma.io/documentation/start/syntax/
- CORSair(官方推荐的凭据/CORS 代理):https://github.com/bastienwirtz/corsair
- 同系列:《Homer 介绍与选型指南》、《Homer Docker Compose 部署指南》、《Homer 日常运维手册》