Glance v0.8.7 配置参数详解（glance.yml）

目标：讲清 Glance v0.8.7 单一配置文件 glance.yml 的完整结构——六个顶层属性逐项详解、pages 列布局模型、组件通用属性、以及监控与信息流类常用组件的参数表；并实测环境变量注入、$include 拆分、YAML 锚点与配置热重载/错误回滚行为。内容依据 v0.8.7 版本官方 configuration.md（2026-10-25 实查）整理，关键行为均在 Ubuntu 22.04 + 官方发布包环境实测验证；部署方式与容器挂载约定见 《Glance v0.8.7 Docker Compose 部署指南》。

一、环境信息

• Glance 版本：v0.8.7（2026-10-15 发布，官方最新稳定版，实查日期 2026-10-25）
• 配置文档基线：官方仓库 docs/configuration.md（2026-10-25 实查于 main 分支，覆盖 v0.8.7）
• 实测环境：Ubuntu 22.04，官方 Linux 二进制部署于 /opt/glance/glance.yml，systemd 托管运行（运行方式详见专栏 CLI 篇）
• 验证工具：glance config:validate（语法校验）、glance config:print（输出解析后的最终配置）
• 配置加载约定：容器部署时入口命令硬编码读取 /app/config/glance.yml；二进制部署默认读取工作目录下的 glance.yml，均可用 -config 显式指定

二、配置体系总览

Glance 全部行为由一份 YAML 文件驱动，无数据库、无管理后台。结构只有三层：顶层属性 → 页面（pages）→ 列（columns）→ 组件（widgets）：

server:      # 监听地址/端口/反向代理约定
document:    # 向页面 <head> 注入自定义 HTML
auth:        # 用户名口令登录与会话签名
branding:    # Logo/页脚/PWA 名称图标
theme:       # 颜色主题与预设
pages:       # 页面、列与全部组件（必填）

其中只有 pages 是必填项。用一份没有 pages 的配置提交校验即可印证：

printf 'server:\n  port: 8080\n' > minimal.yml
./glance -config minimal.yml config:validate; echo "exit=$?"

实测输出：

Config file is invalid: no pages configured
exit=1

围绕这份文件，官方提供四个关键机制（均实测验证，见第十一章）：

热重载行为（官方约定 + 实测印证）

• 服务运行中保存 glance.yml，约 2 秒内生效并打印 Config file changed, reloading...；
• 启动时就非法的配置会直接报错退出、拒绝服务；运行中改坏的配置不会中断服务，日志打印 Config has errors: ... 并继续用旧配置运行，改对后自动恢复（实测回显见第十一章）；
• ⚠️ 每次重载会清空内存中的数据源缓存，所有数据源立即重新抓取——频繁保存配置可能触发上游 API 限流（官方文档明确标注，持久化缓存已列入计划）；
• 改环境变量不触发热重载，必须重启服务（或容器重建）才生效；
• 被监控的配置文件若被删除，文件监听即失效，重新创建同名文件也不会恢复监听，需要重启服务。

环境变量注入

${VAR} 可用于配置中任意位置（顶层值、数组元素、字符串中间，甚至数字类型）：

server:
  host: ${HOST}
  port: ${PORT}
- type: rss
  title: ${RSS_TITLE}
  feeds:
    - url: http://domain.com/rss/${RSS_CATEGORY}.xml
- type: rss
  limit: ${RSS_LIMIT}

三种敏感值传递形态（官方文档约定）：

变量不存在会拒绝启动（或重载被拒），实测：

printf 'server:\n  port: ${MY_PORT}\n' > envtest.yml
./glance -config envtest.yml config:validate; echo "exit=$?"

实测输出：

Config file is invalid: parsing variable: environment variable MY_PORT not found
exit=1

补上变量后同一配置即通过校验。需要原样输出 ${NAME} 字面量时用反斜杠转义：\${NOT_AN_ENV_VAR}。

$include 拆分与 YAML 锚点

$include 支持相对路径（相对主配置文件）与绝对路径，可出现在配置中任何位置（必须独占一行），被包含文件顶层书写、缩进由系统自动补齐，内含的环境变量同样生效，修改被包含文件同样触发热重载：

# glance.yml
pages:
  - $include: home.yml
  - $include: videos.yml
  - $include: homelab.yml

YAML 锚点用于消除重复（比如多个 RSS 组件共享 limit/collapse-after），Glance 在解析层面直接支持。两者的实测验证见第十一章。

💡 官方提示：使用 $include 时如果报 YAML 解析错误，日志里的行号可能不准确（include 先于 YAML 解析发生）。排障用 config:print 查看合并后的完整配置：glance -config glance.yml config:print | less -N。

配置校验与打印

./glance -config /opt/glance/glance.yml config:validate   # 校验，通过无输出、退出码 0
./glance -config /opt/glance/glance.yml config:print      # 打印解析并补齐默认值后的最终配置

config:validate 的三种典型回显实测：

./glance -config /tmp/notexist.yml config:validate; echo "exit=$?"

Could not parse config file: reading /tmp/notexist.yml: open /tmp/notexist.yml: no such file or directory
exit=1

./glance -config /tmp/bad.yml config:validate; echo "exit=$?"   # bad.yml 第 6 行用了不存在的组件类型

Config file is invalid: line 6: unknown widget type: no-such-widget
exit=1

正常时静默通过（exit=0）。容器部署时可用一次性运行预检：docker run --rm -v /opt/glance/config:/app/config glanceapp/glance:v0.8.7 config:validate。另外社区维护着一份 IDE 校验/自动补全 schema（not-first/glance-schema），官方文档在 Config schema 一节推荐使用。

三、server：监听与代理

顶层 server 属性，5 个参数：

assets-path 两点实用细节：

• 引用资源时用 /assets/文件名，如 icon: /assets/gitea-icon.png——典型用途是给 monitor 组件配自托管图标；
• 容器部署时指向容器内路径：宿主 /home/user/glance-assets 挂载为 /app/assets，配置写 assets-path: /app/assets（官方文档以 IMPORTANT 级别强调，挂载错路径是高频错误）。

proxied 与登录防爆破强关联：Glance 对「5 分钟内连续 5 次登录失败」的来源 IP 自动封禁，反代后不设 proxied: true 会让所有用户共享同一个代理 IP，封禁将全体连坐（见第五章）。

四、document：head 注入

顶层 document 属性目前只有一个 head 参数，用于向所有页面的 <head> 注入自定义 HTML（典型用途：引入自定义 JS/CSS、统计脚本、字体）：

document:
  head: |
    <script src="/assets/custom.js"></script>

配合 theme.custom-css-file 与 server.assets-path，即可在不改镜像的情况下完成前端定制。

五、auth：登录认证

顶层 auth 属性，启用后全站需要登录（部署实操与认证链路实测见 B2 部署篇第四章）：

auth:
  secret-key: ${GLANCE_SECRET_KEY}   # secret:make 生成，勿用明文弱值
  users:
    admin:
      password-hash: $2a$10$...      # password:hash 生成

口令哈希生成：

docker run --rm glanceapp/glance:v0.8.7 password:hash q1w2e3r4

实测输出（bcrypt 带随机盐，每次运行输出不同属正常，任意一次输出均可验证同一明文）：

$2a$10$.OJnFEUkdJKUXCPIfDMQYeQaIndsZbnHaTI1I/UoaV5Wuawzx4E3W

防爆破封禁（官方原文约定）：同一 IP 在 5 分钟内连续 5 次认证失败即被自动封禁。该机制依赖真实客户端 IP——反向代理（Nginx/Traefik/NPM 等）后面部署时必须设 server.proxied: true，Glance 从 X-Forwarded-For 头取来源，且代理需正确转发该头。

六、branding：品牌定制

顶层 branding 属性，8 个参数：

branding:
  custom-footer: |
    <p>Powered by <a href="https://github.com/glanceapp/glance">Glance</a></p>
  logo-url: /assets/logo.png
  favicon-url: /assets/logo.png
  app-name: "My Dashboard"

七、theme：主题

顶层 theme 属性。所有颜色为 HSL 三元组（色相 饱和度 亮度，空格分隔、无需 %），官方推荐用 HSL 拾色器换算：

presets 示例（官方文档原文示例，预设名自定义，light: true 声明亮色预设）：

theme:
  background-color: 100 20 10
  primary-color: 40 90 40
  contrast-multiplier: 1.1
  presets:
    gruvbox-dark:
      background-color: 0 0 16
      primary-color: 43 59 81
      positive-color: 61 66 44
      negative-color: 6 96 59
    zebra:
      light: true
      background-color: 0 0 95
      primary-color: 0 0 10
      negative-color: 0 90 50

💡 官方仓库 docs/themes.md 提供多套现成主题值，不想调色直接抄。

八、pages：页面与列布局

顶层 pages 是数组，第一个页面即首页，全部页面按定义顺序自动出现在导航栏：

pages:
  - name: Home
    columns: ...
  - name: Videos
    slug: feeds
    columns: ...

页面属性

列布局规则（官方明确约束）

• 每页最多 3 列；
• 列只有两种宽度：small（固定 300px）与 full（占满剩余宽度）；
• 必须包含 1 或 2 个 full 列（0 个或 3 个 full 都不合法）；
• width: slim 页面最多允许 2 列；
• 并非所有组件适配所有列宽，部分组件提供多 style 变体（如 RSS 的 vertical-list / horizontal-cards / horizontal-cards-2）。

pages:
  - name: Home
    columns:
      - size: small
        widgets: ...
      - size: full
        widgets: ...
      - size: small
        widgets: ...

九、组件通用属性与组件总览

每个组件（widgets 数组元素）都有 type，并共享以下 6 个通用属性：

v0.8.7 全部 27 类组件总览（按用途分组，均为官方 configuration.md 章节名）：

group 组件要点：将多个组件收进同一卡片的标签页（tabs），子组件用 widgets 属性照常定义；group 与 split column 不能再嵌入 group；子组件间重复属性可用 YAML 锚点共享（官方文档即以此为例）。

十、常用组件参数详解

以下组件参数表均摘自 v0.8.7 官方 configuration.md，示例可直接粘贴到 widgets 数组。

10.1 monitor：服务在线监控

- type: monitor
  cache: 1m
  title: 服务监控
  sites:
    - title: Glance
      url: http://localhost:8080
      check-url: http://localhost:8080

每个 site 支持：title（必填）、url（点击跳转）、check-url（探测地址，省略则用 url）、icon、allow-insecure（容忍自签证书）、skip-cdn-check、alt-status-codes（视作成功的附加状态码，如 200|403）、same-tab、hide-arrow。组件自身抓取失败不影响监控结果展示；结合 assets-path 用 /assets/xx.png 自托管站点图标。

10.2 docker-containers：容器状态

- type: docker-containers
  hide-by-default: true

需要只读挂载 Docker socket。容器展示名/图标/描述/链接通过容器标签配置（B2 部署篇实测示例）：

labels:
  glance.hide: "false"
  glance.name: Glance
  glance.icon: sh:glance
  glance.description: 自托管仪表盘

10.3 server-stats：主机资源

- type: server-stats
  servers:
    - type: local
      name: Services

servers 数组元素分 local（本机）与 remote（远程需另装 Glance Agent）两类，公共属性 name（默认取主机名）、hide-swap。CPU 取 1 分钟负载均值相对逻辑核数（弹窗显示 15 分钟均值），磁盘 I/O 繁重的 NAS 负载值会偏高属正常；CPU 温度超 80°C 显示火焰图标。local 专属：cpu-temp-sensor（指定温度传感器，可用 sensors 命令查可用项）、hide-mountpoints-by-default + mountpoints（容器场景挂载了大量无关文件系统时，先隐藏再逐个 hide: false 放行，官方文档即为此场景设计）。

10.4 rss：订阅源

- type: rss
  limit: 10
  collapse-after: 3
  cache: 12h
  feeds:
    - url: https://selfh.st/rss/
      title: selfh.st

每个 feed 可单独覆盖 limit/collapse-after，并可设 title 覆盖源标题。

10.5 clock / calendar

- type: clock
  hour-format: 24h
  timezones:
    - timezone: Asia/Tokyo
      label: Tokyo
- type: calendar
  first-day-of-week: monday

clock：hour-format（12h/24h，默认 24h）、timezones[]（timezone 用 IANA 标识、label 自定义显示）。calendar：first-day-of-week（默认 monday，任意星期值）；旧版 calendar-legacy 官方已标注废弃，勿再选用。

10.6 bookmarks：书签导航

- type: bookmarks
  groups:
    - title: 常用
      color: 10 70 50
      links:
        - title: GitHub
          url: https://github.com/
          icon: sh:github

groups[]：title、color（HSL，默认主题主色）、links[]、same-tab/hide-arrow/target（可设组级，链接级覆盖）；每个 link：title/url 必填，description、icon（支持自托管与内置图标）、same-tab、hide-arrow、target。

10.7 search：搜索框

- type: search
  search-engine: duckduckgo
  bangs:
    - title: YouTube
      shortcut: "!yt"
      url: https://www.youtube.com/results?search_query={QUERY}

内置键盘快捷键：S 聚焦、Enter 本页搜索、Ctrl+Enter 新标签页、Up 回填上次查询。

10.8 custom-api：自定义数据源

通过 JSONPath 从任意 JSON API 取数渲染成表格/列表，是最灵活的扩展点（支持 method/headers/body、template 自定义渲染、options 传参等，参数较多，详见官方文档 Custom API 章节）。适合对接内部系统 API 做状态卡片。

十一、实测案例

11.1 完整部署配置校验

以下为本系列部署实例的 glance.yml（B2 部署篇第四章逐项讲过），先过校验再打印解析结果：

./glance -config /opt/glance/glance.yml config:validate; echo "exit=$?"

实测输出：

exit=0

./glance -config /opt/glance/glance.yml config:print

实测输出（页面组件默认值已填齐；实测该命令仅回显 pages 段，server/auth 等顶层段不在输出中）：

pages:
  - name: Home
    columns:
      - size: full
        widgets:
          - type: clock
            hour-format: 24h
          - type: calendar
          - type: monitor
            cache: 1m
            sites:
              - title: Glance
                url: http://localhost:8080
                check-url: http://localhost:8080

11.2 $include 与 YAML 锚点

cat > main.yml <<'EOF'
pages:
  $include: pages-home.yml
EOF
cat > pages-home.yml <<'EOF'
- name: Home
  columns:
    - size: full
      widgets:
        - type: clock
          hour-format: 24h
        - type: calendar
EOF
./glance -config main.yml config:validate; echo "exit=$?"

实测输出：

exit=0

锚点合并（多个组件共享 limit/collapse-after）同样通过校验：

cat > anchor.yml <<'EOF'
server:
  port: 8080
x-common: &default-rss
  limit: 10
  collapse-after: 3
pages:
  - name: Home
    columns:
      - size: full
        widgets:
          - type: rss
            cache: 12h
            <<: *default-rss
            feeds:
              - url: https://selfh.st/rss/
EOF
./glance -config anchor.yml config:validate; echo "exit=$?"

实测输出：

exit=0

11.3 运行中改错配置：不中断、带行号报错、改对自动恢复

服务运行中把某组件 type 改成不存在的 broken-widget，约 2 秒后日志：

2026/10/25 03:29:48 Config file changed, reloading...
2026/10/25 03:29:48 Config has errors: line 6: unknown widget type: broken-widget

同时 systemctl is-active glance 仍为 active，页面继续可用（旧配置生效）。恢复正确配置后自动重载：

2026/10/25 03:29:50 Starting server on :8080 (base-url: "", assets-path: "")

正常变更的重载回显同样两行：Config file changed, reloading... + Starting server on :8080 (base-url: "", assets-path: "")。这就是官方「启动时非法即退出、运行中非法则保旧配置」语义的完整实测。

十二、注意事项

1. pages 缺失拒绝启动：no pages configured，最小可用配置也要有一个带列的页面；
2. 环境变量缺失拒绝启动：${VAR} 未定义即 parsing variable: environment variable VAR not found，密钥类值先在 .env/systemd 环境里备好再改配置；
3. 重载清空缓存：频繁保存会重新抓取全部数据源，可能触发上游限流，编辑时避免反复保存；改环境变量不走热重载，需重启；
4. calendar 与 weather 的 cache 不可修改：固定整点更新，写了也会被忽略（官方文档 NOTE 明确）；
5. hide-header 会藏掉报错红点：组件抓取失败的红点显示在标题旁，隐藏标题栏后排查只能靠日志；
6. $include 报错行号可能不准：include 先于 YAML 解析，排障用 config:print 看合并结果；被删掉的包含文件不会恢复监听，需重启服务；
7. 反向代理三件套要配齐：子路径托管设 base-url（代理侧剥前缀）、取真实 IP 设 proxied: true（否则防爆破封禁连坐）、静态资源挂载与 assets-path 指向容器内同一路径；
8. 容器配置路径硬编码：/app/config/glance.yml，挂载别的路径等于没配；
9. calendar-legacy 已废弃：新配置一律用 calendar；
10. 提交前先校验：config:validate 三种回显（静默/带行号报错/文件不存在）应烂熟于心，容器场景用一次性运行预检不占端口。

十三、参考链接

• 官方配置文档 configuration.md（本文基线）：https://github.com/glanceapp/glance/blob/main/docs/configuration.md
• 官方预配置页模板 glance.yml：https://github.com/glanceapp/glance/blob/main/docs/configuration.md（Preconfigured page 一节引用的模板文件）
• 官方主题值集合 themes.md：https://github.com/glanceapp/glance/blob/main/docs/themes.md
• 社区配置 schema（IDE 校验/补全）：https://github.com/not-first/glance-schema
• 本专栏相关文档：《Glance v0.8.7 介绍与选型指南》、《Glance v0.8.7 Docker Compose 部署指南》