Glance v0.8.7 CLI 运行与运维实操

目标：在不依赖 Docker 的裸服务器场景下跑通 Glance v0.8.7 的完整 CLI 生命周期——官方发布包下载安装、命令行工具全集逐项实测、systemd 服务托管与崩溃自愈验证、配置热重载日志链路分析，以及一组真实排障实录。容器化部署（Compose 编排）见《Glance v0.8.7 Docker Compose 部署指南》，配置文件语法见《Glance v0.8.7 配置参数详解（glance.yml）》。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Glance 版本：v0.8.7（2026-10-15 发布，官方最新稳定版，实查日期 2026-10-25）
运行形态：官方 Linux 二进制 + systemd 托管（对比形态：官方镜像 + Compose，见 B2 部署篇）
安装目录：/opt/glance/（二进制与 glance.yml 同目录，-config 显式指定）
实测回显采集环境：Go 1.27.1 构建的 v0.8.7 官方发布包（glance diagnose 自报版本信息）

二、CLI 全景

Glance 是静态链接的单文件二进制：官方发布包解压后只有一个 glance 文件，ldd 确认无动态库依赖，天然适合最小化服务器（无额外运行时要求）。全部命令行能力一目了然：

./glance --help

实测输出：

Usage: glance [options] command

Options:

Commands:
  config:validate       Validate the config file
  config:print          Print the parsed config file with embedded includes
  password:hash <pwd>   Hash a password
  secret:make           Generate a random secret key
  sensors:print         List all sensors
  mountpoint:info       Print information about a given mountpoint path
  diagnose              Run diagnostic checks
  -config string
    	Set config path (default "glance.yml")

命令分两类：服务运行（不带子命令，直接启动 HTTP 服务）与七个工具子命令。-config 全局选项指定配置路径，默认取当前目录的 glance.yml。版本自报带 v 前缀：

./glance --version

实测输出：

v0.8.7

三种典型运行形态（后文逐一展开）：

形态	命令形态	场景
systemd 托管	`ExecStart=/opt/glance/glance -config /opt/glance/glance.yml`	生产长驻
前台临时	`./glance -config ./glance.yml`	快速验证、看实时日志
一次性工具	`./glance -config xx.yml config:validate`	校验/生成密钥/诊断

三、下载与安装

从官方 GitHub Releases 下载 v0.8.7 的 Linux amd64 发布包并校验：

mkdir -p /opt/glance && cd /opt/glance
curl -fL -o glance-linux-amd64.tar.gz \
  https://github.com/glanceapp/glance/releases/download/v0.8.7/glance-linux-amd64.tar.gz

⚠️ 网络说明：官方 GitHub Releases 实测可下载，包体约 6.4MB；本写作环境出站受限，实测经出站代理（curl -x http://…）完成下载。

查看压缩包内容并校验完整性：

tar -tzf glance-linux-amd64.tar.gz

实测输出：

glance

sha256sum glance-linux-amd64.tar.gz

实测输出：

b9c169623825753e87f31e89514eefdeda38f51b6c024dcc4348fe087bc3592f  glance-linux-amd64.tar.gz

💡 说明：包内仅含 glance 一个文件——没有配置模板、没有静态资源，配置完全自持（这也是它「单一 YAML 驱动」设计的一致性体现）。升级时替换这一个文件即可。

解压、赋权、验证：

tar -xzf glance-linux-amd64.tar.gz
chmod +x glance
./glance --version

实测输出：

v0.8.7

动态链接验证（官方镜像与发布包同为静态构建）：

ldd glance

实测输出：

	not a dynamic executable

四、配置落位与预检

写入最小可运行配置（生产配置的完整参数见 C1 配置详解篇）：

# /opt/glance/glance.yml
server:
  port: 8080

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

启动前预检是强纪律——校验通过时无输出且退出码 0，出错则给出带行号的精确报错：

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

实测输出：

exit=0

config:print 可查看解析并补齐默认值后的最终配置（实测仅回显 pages 段，适合检查 include 合并结果）：

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

实测输出：

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

五、systemd 服务托管

5.1 编写单元文件

# /etc/systemd/system/glance.service
[Unit]
Description=Glance dashboard
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/glance
ExecStart=/opt/glance/glance -config /opt/glance/glance.yml
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

要点：Restart=on-failure + RestartSec=5 组成崩溃自愈策略（5.3 节实测验证）；WorkingDirectory 与 -config 分离，配置路径永远显式。

5.2 启用与启动

systemctl daemon-reload
systemctl enable --now glance
systemctl is-enabled glance

实测输出：

enabled

服务状态：

systemctl status glance --no-pager -l

实测输出（节选）：

● glance.service - Glance dashboard
     Loaded: loaded (/etc/systemd/system/glance.service; enabled; preset: enabled)
     Active: active (running) since Sun 2026-10-25 03:19:02 UTC; 17min ago
   Main PID: 561 (glance)
      Tasks: 8 (limit: 3852)
     Memory: 5.7M (peak: 6.9M)
        CPU: 26ms

💡 说明：常驻内存 5.7M（峰值 6.9M）、CPU 累计 26ms——Glance 的资源占用对 1C512M 级小机完全无压力。

启动日志与服务可用性验证：

journalctl -u glance --no-pager -n 2 --output=short-iso

实测输出：

2026-10-25T03:19:02+00:00 glance-srv systemd[1]: Started glance.service - Glance dashboard.
2026-10-25T03:19:02+00:00 glance-srv glance[561]: 2026/10/25 03:19:02 Starting server on :8080 (base-url: "", assets-path: "")

curl -sI http://localhost:8080 | head -4

实测输出：

HTTP/1.1 200 OK
Date: Sun, 25 Oct 2026 03:36:49 GMT
Content-Type: text/html; charset=utf-8

curl -s http://localhost:8080 | grep -o "<title>[^<]*</title>"

实测输出：

<title>Home</title>

5.3 崩溃自愈实测（Restart=on-failure）

模拟进程被强杀（kill -9 等价场景），观察 systemd 的完整自愈链路：

systemctl kill -s SIGKILL glance
sleep 7
journalctl -u glance --no-pager -n 5 --output=short-iso

实测输出：

2026-10-25T03:36:49+00:00 glance-srv systemd[1]: glance.service: Main process exited, code=killed, status=9/KILL
2026-10-25T03:36:49+00:00 glance-srv systemd[1]: glance.service: Failed with result 'signal'.
2026-10-25T03:36:54+00:00 glance-srv systemd[1]: glance.service: Scheduled restart job, restart counter is at 1.
2026-10-25T03:36:54+00:00 glance-srv systemd[1]: Started glance.service - Glance dashboard.
2026-10-25T03:36:54+00:00 glance-srv glance[785]: 2026/10/25 03:36:54 Starting server on :8080 (base-url: "", assets-path: "")

时间线：03:36:49 进程被 SIGKILL → 判定 Failed with result 'signal'（失败类别，命中 Restart=on-failure）→ 5 秒后（RestartSec=5）调度重启 → 新 PID 785 接管，systemctl is-active glance 返回 active。配置若配了认证，会话在重启后失效需重新登录（会话签名密钥不持久化进程态）。

六、日常运维

6.1 重启与日志

systemctl restart glance && sleep 1 && journalctl -u glance --no-pager -n 3 --output=short-iso

实测输出：

2026-10-25T03:39:53+00:00 glance-srv systemd[1]: Stopped glance.service - Glance dashboard.
2026-10-25T03:39:53+00:00 glance-srv systemd[1]: Started glance.service - Glance dashboard.
2026-10-25T03:39:53+00:00 glance-srv glance[872]: 2026/10/25 03:39:53 Starting server on :8080 (base-url: "", assets-path: "")

常用命令集合：

命令	用途
`systemctl restart glance`	重启（改环境变量、换二进制后）
`systemctl stop` / `start glance`	停止 / 启动
`journalctl -u glance -f`	跟踪实时日志
`journalctl -u glance --since "1 hour ago"`	回看近一小时日志

6.2 配置热重载（免重启）

直接编辑 /opt/glance/glance.yml 保存，约 2 秒内自动生效，日志链路两行：

2026/10/25 03:29:48 Config file changed, reloading...
2026/10/25 03:29:48 Starting server on :8080 (base-url: "", assets-path: "")

运行中改坏配置的实录（把某组件 type 改成不存在的 broken-widget 后保存）：

2026-10-25T03:29:48+00:00 glance-srv glance[561]: 2026/10/25 03:29:48 Config file changed, reloading...
2026-10-25T03:29:48+00:00 glance-srv glance[561]: 2026/10/25 03:29:48 Config has errors: line 6: unknown widget type: broken-widget

此时 systemctl is-active glance 仍为 active、页面继续可用（旧配置生效）——Glance 的重载语义是「新的失败就继续用旧的」。把配置改对后自动恢复：

2026-10-25T03:29:50+00:00 glance-srv glance[561]: 2026/10/25 03:29:50 Config file changed, reloading...
2026-10-25T03:29:50+00:00 glance-srv glance[561]: 2026/10/25 03:29:50 Starting server on :8080 (base-url: "", assets-path: "")

⚠️ 每次重载清空内存缓存，全部数据源重新抓取；频繁保存可能触发上游 API 限流（官方文档明确约定）。改环境变量（如 systemd Environment=）不触发热重载，必须 systemctl restart。

6.3 升级流程

单二进制设计的升级只有三步：下载新版 → 替换 → 重启，配置数据零迁移：

cd /opt/glance
curl -fL -o glance-linux-amd64.tar.gz https://github.com/glanceapp/glance/releases/download/v<新版本>/glance-linux-amd64.tar.gz
tar -xzf glance-linux-amd64.tar.gz && chmod +x glance
./glance --version          # 确认新版本号
systemctl restart glance

回滚即用旧包覆盖后 restart。升级前建议 cp glance.yml glance.yml.bak 留一份配置快照（0.x 版本线偶有配置项废弃，先跑 config:validate 再重启更稳）。

七、工具子命令实测

7.1 secret:make / password:hash（认证凭据生成）

./glance secret:make

实测输出：

ofR/hybF7qJXk7HQWwZSDSScB99Mrf6pG8jgfRhIBvBJcP0HB9CyAZ8NhBViiM8/MbItaLs0MqGevN9LXpY/qA==

./glance password:hash q1w2e3r4

实测输出：

$2a$10$WBnaDgpnpHGqYqXBgIL.0OdtHXS6Ym3slG4Jxquxl5or5m/E.4Gpi

💡 说明：bcrypt 每次运行生成带随机盐的不同哈希（同一明文每次输出都不同属正常现象），任意一次输出都能通过同一明文的登录校验。两命令配合 auth 配置的用法见 C1 配置详解篇第五章。

7.2 mountpoint:info / sensors:print（资源视图）

./glance mountpoint:info /
./glance mountpoint:info /tmp

实测输出：

Path: /
FS type: unknown
Used percent: 15.5%

Path: /tmp
FS type: tmpfs
Used percent: 0.0%

./glance sensors:print; echo "exit=$?"

实测输出：

No sensors found
exit=0

💡 说明：mountpoint:info 用于确认 server-stats 组件将看到的挂载点与磁盘用量（路径是文件系统中的真实视图）；sensors:print 列出 CPU 温度传感器，本实测环境无传感器故返回 No sensors found（退出码 0）。有传感器时，把名字填入 server-stats 的 cpu-temp-sensor。

7.3 diagnose（一键体检）

./glance diagnose

实测输出（节选）：

Glance version: v0.8.7
Go version: go1.27.1
Platform: linux / amd64 / 6 CPUs

Checking network connectivity, this may take up to 15 seconds...

✓ Can resolve cloudflare.com through Cloudflare DoH | 259 bytes, {"Status":0,"TC":false,"RD":true,"RA":true,"AD":tr... | 315ms
✓ Can resolve cloudflare.com through Google DoH | 318 bytes, {"Status":0,"TC":false,"RD":true,"RA":true,"AD":tr... | 321ms
✓ Can resolve github.com | 20.205.243.166 | 6ms
✓ Can resolve reddit.com | 174.132.167.252, 2001::1 | 20ms
✓ Can resolve twitch.tv | 104.244.46.165, 2a03:2880:f11c:8083:face:b00c:0:25de | 12ms
✗ Can't fetch data from YouTube RSS feed | 1613 bytes, <!DOCTYPE html><html lang=en>  <meta charset=utf-8... | 355ms
└╴ error: expected status code 200, got 404
✓ Can fetch data from Twitch.tv GQL | 0 bytes | 445ms
✓ Can fetch data from GitHub API | 2262 bytes, {"current_user_url":"https://api.github.com/user",... | 323ms
✓ Can fetch data from Open-Meteo API | 3414 bytes, {"results":[{"id":2643743,"name":"London","latitud... | 1277ms
✓ Can fetch data from Yahoo finance API | 36770 bytes, {"chart":{"result":[{"meta":{"currency":"USD","sym... | 551ms
✓ Can fetch data from Hacker News Firebase API | 4501 bytes, [50227892,50225695,50227356,50224100,50227356,5022... | 1122ms
✓ Can fetch data from Docker Hub API | 4257 bytes, {"creator":7,"id":2343,"images":[{"architecture":"... | 530ms

三点解读：

它逐项检查 Glance 各数据源依赖的外部服务连通性（DoH 解析、GitHub API、YouTube RSS、Twitch、行情、天气等），每项给出字节数、内容前缀与耗时，是「组件全红点」类故障的第一排查工具；
上例中的 ✗ 项是本写作环境出站受限所致（YouTube RSS 请求经代理返回 404），正常出网环境该项应为 ✓——这正是 diagnose 的价值：用 ✓/✗ + error 行直接定位是哪一环断了；
实测 v0.8.7 中即使存在失败项，进程退出码仍为 0，判断依据看输出中的 ✓/✗ 符号与 └╴ error: 行，不要依赖退出码。

八、一次性运行与在线调用

除裸二进制外，CLI 子命令还有两种调用形态，均实测验证：

① 官方镜像一次性运行（不落盘安装，适合校验与凭据生成）：

docker run --rm glanceapp/glance:v0.8.7 secret:make
docker run --rm glanceapp/glance:v0.8.7 password:hash q1w2e3r4
docker run --rm -v /opt/glance/config:/app/config -e GLANCE_SECRET_KEY=<密钥值> glanceapp/glance:v0.8.7 config:validate

实测注意点：若配置里用了 ${GLANCE_SECRET_KEY} 而一次性运行忘记传该环境变量，校验会失败：

Config file is invalid: parsing variable: environment variable GLANCE_SECRET_KEY not found

补上 -e GLANCE_SECRET_KEY=<密钥值> 后重新运行即通过（退出码 0）。这不是故障，是环境变量注入语义（配置里 ${VAR} 必须存在，见 C1 第二章）——但它足以让新手误判「配置坏了」。

② 在运行中的服务实例内执行（容器化部署排障用，不动运行状态）：

docker exec glance-v0.8.7-web /app/glance -config /app/config/glance.yml config:validate; echo "exit=$?"

实测输出：

exit=0

九、排障实录

案例 1：端口被占用

前台启动时目标端口已有服务（本例即 systemd 托管的常驻实例占用 8080）：

2026/10/25 03:39:12 Starting server on :8080 (base-url: "", assets-path: "")
2026/10/25 03:39:12 Failed to start server: listen tcp :8080: bind: address already in use

处置：ss -ltnp | grep 8080 找到占用者，换 server.port 或停掉冲突服务。实测 v0.8.7 打印该错误后进程未立即自行退出，务必确认报错后手动清理进程再重试。

案例 2：配置文件缺失/非法，启动即退

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

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

Config file is invalid: parsing variable: environment variable MY_PORT not found

三类报错对应三种根因：路径不存在、组件类型拼错（带精确行号）、环境变量未定义。全部先过 config:validate 再启动。运行中改错则不会中断服务（见 6.2 节实录），修正后自动恢复。

案例 3：组件全部显示红色错误点

面板上组件标题旁红点 = 该数据源抓取失败。第一动作跑 diagnose（7.3 节），按 ✗ 项定位网络断点；若是 RSS 类数据源，日志会给出具体 URL 与错误（如出站受限环境的 context deadline exceeded）。服务器出网策略修复后，组件在下个抓取周期自动恢复，无需重启。

案例 4：误判「配置坏了」

症状：config:validate 报 parsing variable: environment variable GLANCE_SECRET_KEY not found，但配置本身没改过。根因：换了个执行环境（如一次性校验、新的 systemd 单元）而新环境没注入该变量。处置：补环境变量而非改配置——systemctl edit glance 加 Environment=GLANCE_SECRET_KEY=… 或用 EnvironmentFile=/etc/glance/glance.env 托管。

十、注意事项

预检纪律：任何配置变更先 config:validate（无输出 + 退出码 0 才算通过），再靠热重载或重启生效；
热重载清缓存：频繁保存会重新抓取全部数据源，可能触发上游限流；改环境变量必须重启；
崩溃自愈不等于永远健康：Restart=on-failure 处理进程级死亡，配置性故障（每次启动都报错）会反复重启失败，journalctl -u glance 看日志才是正道；systemd 默认有启动频率限制，连续快速失败会进入 failed 状态，此时 systemctl reset-failed glance 后再修配置；
会话不跨重启：重启服务后所有登录会话失效（签名密钥进程内生效），用户需重新登录——运维窗口避开使用高峰；
升级保持版本意识：0.x 版本线小版本偶有配置项废弃，升级先看 Release Notes，替换二进制后先 config:validate 再 restart；
diagnose 退出码恒为 0（v0.8.7 实测）：健康与否看 ✓/✗ 与 error 行；
日志与轮转：输出走 stdout，journald 自动轮转（默认按磁盘配额），无需额外日志切割配置；
最小权限：服务以 root 运行时可用 systemd 硬化（User=/NoNewPrivileges=/ProtectSystem=strict + ReadWritePaths=/opt/glance），Glance 本身只需要读配置、写无状态运行。

十一、参考链接

官方仓库与安装说明（README「Running without Docker」）：https://github.com/glanceapp/glance
官方 Releases 页面（版本与资产下载）：https://github.com/glanceapp/glance/releases
官方配置文档（configuration.md）：https://github.com/glanceapp/glance/blob/main/docs/configuration.md
本专栏相关文档：《Glance v0.8.7 介绍与选型指南》、《Glance v0.8.7 Docker Compose 部署指南》、《Glance v0.8.7 配置参数详解（glance.yml）》