1. 项目概述一个为开发者打造的极简仪表盘如果你和我一样桌面上常年开着十几个终端窗口、浏览器标签页、代码编辑器和一堆系统监控工具那你一定懂那种信息过载的烦躁感。我们总想一眼就看到最关键的信息服务器负载、代码仓库状态、待办事项、甚至是天气预报但现实是这些数据散落在各处需要频繁切换窗口去查看。几年前我开始寻找一个能聚合这些信息的个人仪表盘工具要求很简单要足够轻量、高度可定制、并且能自己掌控数据。市面上很多方案要么太重要么太封闭直到我遇到了acfranzen/glance。glance是一个用 Go 语言编写的、自托管的、模块化的信息仪表盘。它的核心哲学是“只展示你关心的”通过一个个独立的“模块”Widget来聚合不同来源的信息。你可以把它想象成一个数字相框但里面装的不是家庭照片而是你工作流中所有关键指标的实时快照。它不依赖任何云服务所有数据都从你指定的 API 或本地命令获取运行在你自己的服务器或电脑上在隐私和可控性上给了开发者最大的安全感。这个项目特别适合以下几类人需要监控多台服务器状态的运维工程师、想随时关注多个项目 CI/CD 流水线和 Issue 状态的开发团队负责人、以及任何希望将分散的工作信息流集中在一个简洁界面上的效率追求者。它的部署极其简单一个二进制文件加一份配置文件就能跑起来定制过程就像搭乐高选择你需要的模块配置好数据源一个专属的监控中枢就搭建完成了。2. 核心架构与设计哲学解析2.1 模块化设计像搭积木一样构建仪表盘glance的核心魅力在于其彻底的模块化设计。整个仪表盘没有固定的布局和内容完全由用户通过配置文件来声明需要哪些“模块”。每个模块都是一个独立的功能单元负责从特定数据源获取信息并以统一的视觉样式进行渲染。这种设计带来了几个显著优势。首先是灵活性。你今天可能只关心天气和待办事项明天就需要加入服务器监控和 Git 仓库状态。你不需要换一个工具只需在配置文件中增删相应的模块配置即可。其次是可维护性。每个模块的代码和配置都是独立的一个模块的故障或配置错误不会影响其他模块的正常运行。最后是社区驱动的可扩展性。虽然项目自身提供了一批常用模块如系统信息、天气、时间、Git 服务状态等但它的架构鼓励开发者为其编写新的模块。只要遵循简单的接口任何人都可以贡献一个从新奇数据源获取信息的模块比如连接智能家居设备、显示加密货币价格或者聚合多个日志文件的尾部信息。从技术实现上看一个模块通常包含三部分配置结构体定义用户在 YAML 中需要填写的参数、数据获取逻辑调用 API 或执行命令以及渲染逻辑将获取的数据转换为 HTML 片段。这种清晰的职责分离使得阅读和编写新模块的代码都非常直观。2.2 配置驱动与声明式语法glance完全采用配置驱动的方式工作。一切行为都由一个 YAML 配置文件通常是config.yml来定义。这种声明式的语法意味着你只需要告诉它“你想要什么”而不是“如何一步步去实现”。这对于自动化部署和版本控制非常友好。一个典型的配置文件骨架如下server: port: 8080 # 仪表盘服务的监听端口 update_interval: 30s # 全局数据刷新间隔 modules: - name: time # 模块名称 position: [0, 0] # 在网格布局中的位置 (列, 行) config: format: 2006-01-02 15:04:05 # Go 语言特有的时间格式 timezone: Local - name: system position: [1, 0] config: show_cpu: true show_mem: true show_disk: [/] # 监控根分区磁盘使用率 - name: weather position: [0, 1] config: location: Beijing units: metric # 使用公制单位摄氏度 api_key: YOUR_OPENWEATHERMAP_API_KEY # 需要申请的外部 API Key通过这份配置glance就知道需要在8080端口启动一个 Web 服务每30秒更新一次所有模块的数据并在网页上以网格形式展示时间、系统信息和天气三个模块。注意配置中的position采用了[列, 行]的坐标系统从[0, 0]开始。你需要预先规划好仪表盘的布局避免模块位置重叠。一个好的习惯是先画一个简单的草图再填写配置。2.3 技术栈选型为什么是 Go作者选择 Go 语言作为实现语言是一个经过深思熟虑的决定完美契合了glance的项目定位。卓越的并发性能仪表盘需要同时从多个可能缓慢的外部 API如天气、GitHub获取数据。Go 的 goroutine 和 channel 机制使得并发发起这些网络请求变得异常简单和高效可以极大缩短整个仪表盘的页面加载和数据刷新时间避免因为某个模块的 API 响应慢而阻塞其他模块。单二进制文件部署Go 编译后生成的是一个静态链接的单一可执行文件不依赖任何系统库。这意味着你可以在你的开发机比如 macOS上编译然后把二进制文件直接扔到生产服务器比如 Linux上运行无需担心环境依赖问题。这极大地简化了部署和分发流程符合“简单易用”的核心目标。强大的标准库和丰富的生态系统Go 的标准库已经涵盖了 HTTP 服务、JSON 解析、模板渲染等glance所需的大部分功能。对于需要连接的外部服务如 GitHub、GitLab、Prometheus也有成熟稳定的第三方客户端库降低了开发复杂度。内存安全与高性能作为编译型语言Go 在资源利用效率上比解释型语言如 Python、Node.js更有优势这对于一个需要 7x24 小时运行的后台服务来说很重要。同时其内存安全特性也减少了潜在运行时错误。这套技术栈的选择确保了glance在拥有足够功能的同时保持了极致的轻量和运行效率这正是许多自托管工具用户所看重的品质。3. 核心模块详解与实战配置3.1 内置核心模块实战glance自带了一批开箱即用的模块覆盖了最常见的需求。下面我们深入剖析几个最实用的模块并给出详细的配置示例和避坑指南。1. 系统信息模块 (system)这是最基础的模块之一用于监控运行glance的主机本身状态。- name: system position: [0, 0] config: show_hostname: true show_os: true show_cpu: true cpu_warning_threshold: 80 # CPU使用率超过80%时高亮警告 show_mem: true mem_warning_threshold: 85 # 内存使用率超过85%时高亮警告 show_disk: [/, /home] # 监控多个挂载点 disk_warning_threshold: 90 show_network: [eth0] # 监控指定网卡的上下行速率实操心得disk_warning_threshold和mem_warning_threshold非常有用它们会让对应数据在超过阈值时变为醒目的黄色或红色让你一眼就能发现异常。建议根据服务器实际状况设置合理的阈值比如数据库服务器的磁盘 I/O 可能常年较高阈值可以设宽松些。2. 天气模块 (weather)该模块通常依赖外部天气 API如 OpenWeatherMap。- name: weather position: [1, 0] config: location: London,UK # 城市名和国家代码更精确 units: metric # 可选 metric(摄氏度), imperial(华氏度), standard(开尔文) api_key: your_actual_api_key_here # 必须替换 update_interval: 10m # 天气数据无需频繁更新可覆盖全局设置 show_forecast: true # 显示未来几小时预报避坑指南获取api_key是第一步。前往 OpenWeatherMap 官网注册免费账户即可生成一个 Key。免费套餐通常有每分钟调用次数限制因此务必像示例中一样将update_interval设置为10m10分钟或更长避免触发限流导致模块无法获取数据。3. Git 服务状态模块 (github/gitlab)对于开发者这是不可或缺的模块可以展示仓库的 PR/MR 数量、未读通知等。- name: github position: [2, 0] config: access_token: ghp_yourPersonalAccessToken # GitHub Personal Access Token username: your-github-username show_prs: true show_issues: true show_notifications: true repos: [owner/repo1, owner/repo2] # 只监控特定仓库不配置则监控所有安全警告access_token是最高机密绝对不要直接提交到公开的版本控制系统。务必通过环境变量或单独的保密配置文件来注入。在配置文件中可以这样写access_token: “{{ .Env.GITHUB_TOKEN }}”然后在启动glance前设置环境变量export GITHUB_TOKENghp_xxx。配置技巧repos字段非常有用。如果你参与的项目很多不加以过滤会导致 API 请求变慢并且界面信息过载。建议只添加你当前最活跃或最关注的几个仓库。3.2 自定义模块开发入门当内置模块无法满足你的需求时你可以尝试自己编写一个模块。这比想象中要简单。下面我们以创建一个“今日诗词”模块为例演示基本步骤。步骤一理解模块结构在glance的代码结构中每个模块位于modules/目录下的一个子文件夹中例如modules/poetry/。该文件夹至少需要两个文件config.go定义配置结构。module.go实现数据获取和渲染逻辑。步骤二编写配置定义 (config.go)package poetry type Config struct { APISource string yaml:api_source // 配置项诗词API地址 ShowAuthor bool yaml:show_author // 配置项是否显示作者 }这里定义了两个配置项用户可以在 YAML 中通过api_source和show_author来设置。步骤三实现模块逻辑 (module.go)package poetry import ( encoding/json fmt io net/http github.com/acfranzen/glance/modules ) type Module struct { config Config } // 必须实现 modules.Module 接口 func (m *Module) Init(config interface{}) error { m.config config.(Config) // 将通用配置转换为我们的具体配置 if m.config.APISource { m.config.APISource https://v1.jinrishici.com/all.json // 默认API } return nil } func (m *Module) GetData() (interface{}, error) { resp, err : http.Get(m.config.APISource) if err ! nil { return nil, err } defer resp.Body.Close() body, _ : io.ReadAll(resp.Body) var data struct { Content string json:content Author string json:author } json.Unmarshal(body, data) result : map[string]string{content: data.Content} if m.config.ShowAuthor { result[author] data.Author } return result, nil } func (m *Module) Render(data interface{}) (string, error) { d : data.(map[string]string) html : fmt.Sprintf(div classpoetryp%s/p, d[content]) if author, ok : d[author]; ok author ! { html fmt.Sprintf(p classauthor—— %s/p, author) } html /div return html, nil } // 此函数用于模块注册 func New() modules.Module { return Module{} }步骤四注册并使用模块在modules/all.go文件中导入你的新包并注册_ “your-module-path/modules/poetry”。编译整个glance项目。在配置文件中就可以像使用内置模块一样使用它了- name: poetry position: [0, 2] config: api_source: https://v1.jinrishici.com/all.json show_author: true通过这个简单的例子你可以看到扩展glance的功能边界并不困难。核心就是实现Init,GetData,Render这三个方法。4. 完整部署、配置与优化指南4.1 从零开始部署实践假设我们在一台全新的 Ubuntu 22.04 服务器上部署glance并希望通过 Nginx 反向代理提供 HTTPS 访问。第一步获取 glance有两种主要方式直接下载二进制文件推荐从项目的 GitHub Releases 页面下载对应你系统架构的最新版压缩包。wget https://github.com/acfranzen/glance/releases/download/vx.y.z/glance-linux-amd64.tar.gz tar -xzf glance-linux-amd64.tar.gz sudo mv glance /usr/local/bin/从源码编译确保安装了 Go 工具链1.16。git clone https://github.com/acfranzen/glance.git cd glance go build -o glance . sudo mv glance /usr/local/bin/第二步创建配置文件和工作目录sudo mkdir -p /etc/glance sudo mkdir -p /var/lib/glance sudo nano /etc/glance/config.yml将你的 YAML 配置包含前面提到的模块写入/etc/glance/config.yml。第三步配置系统服务以 systemd 为例创建服务文件/etc/systemd/system/glance.service[Unit] DescriptionGlance Personal Dashboard Afternetwork.target [Service] Typesimple Userglance # 建议创建一个专用系统用户 Groupglance WorkingDirectory/var/lib/glance EnvironmentGITHUB_TOKENyour_token_here # 在此处设置敏感环境变量 ExecStart/usr/local/bin/glance -config /etc/glance/config.yml Restarton-failure RestartSec10 [Install] WantedBymulti-user.target然后创建用户并启动服务sudo useradd -r -s /bin/false glance sudo chown -R glance:glance /etc/glance /var/lib/glance sudo systemctl daemon-reload sudo systemctl enable --now glance.service sudo systemctl status glance.service # 检查是否运行正常第四步配置 Nginx 反向代理与 HTTPS安装 Nginx 和 Certbotsudo apt update sudo apt install nginx certbot python3-certbot-nginx为glance创建 Nginx 站点配置/etc/nginx/sites-available/glanceserver { listen 80; server_name dashboard.yourdomain.com; # 替换为你的域名 location / { proxy_pass http://127.0.0.1:8080; # 指向 glance 监听的端口 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }启用配置并获取 SSL 证书sudo ln -s /etc/nginx/sites-available/glance /etc/nginx/sites-enabled/ sudo nginx -t # 测试配置语法 sudo systemctl reload nginx sudo certbot --nginx -d dashboard.yourdomain.comCertbot 会自动修改 Nginx 配置启用 HTTPS 并设置自动续期。完成后你就可以通过https://dashboard.yourdomain.com安全地访问你的仪表盘了。4.2 性能调优与安全加固部署完成后为了长期稳定运行还需要进行一些优化。性能调优调整更新间隔在config.yml的server部分update_interval是全局刷新频率。对于实时性要求不高的模块如天气、日历可以在模块自身的config里设置更长的update_interval来覆盖全局设置减少不必要的 API 调用和前端请求。启用浏览器缓存glance的静态资源CSS JS本身不大但通过 Nginx 可以设置缓存头进一步加快重复访问速度。在 Nginx 的location ~* \.(js|css|png|jpg|jpeg|gif|ico)$块中添加expires 1M;。监控 glance 自身你完全可以用glance的system模块来监控它自身所在服务器的状态形成一个有趣的“自指”监控。安全加固防火墙确保服务器的防火墙如ufw只开放了 80HTTP、443HTTPS和 SSH 端口。glance默认的 8080 端口不应暴露在公网。权限最小化如前所述使用非 root 用户如glance运行服务。确保该用户对配置文件和日志目录只有必要的读写权限。秘密管理这是重中之重。永远不要将 API Token、密码等硬编码在配置文件中。务必使用环境变量或 secrets 管理工具如 Docker Secrets、HashiCorp Vault。在 systemd service 文件中通过Environment指令设置是简单有效的方法。访问控制glance本身不提供用户认证功能。如果你的仪表盘包含敏感信息如服务器内部监控你需要在外层添加访问控制。最简单的方法是利用 Nginx 的 HTTP 基本认证sudo apt install apache2-utils sudo htpasswd -c /etc/nginx/.htpasswd dashboard_user # 创建密码文件然后在 Nginx 配置的location /块中添加auth_basic Restricted Access; auth_basic_user_file /etc/nginx/.htpasswd;5. 高级用法、问题排查与生态整合5.1 与现有监控生态的整合glance的定位是轻量级的个人信息聚合面板它并不试图取代 Grafana、Prometheus 这类专业的监控系统而是可以作为它们的一个补充或快速视图。通过自定义模块你可以轻松地将这些系统的关键数据集成进来。整合 Prometheus 查询结果你可以编写一个模块定期调用 Prometheus 的 HTTP API 执行一个 PromQL 查询并将结果渲染出来。例如显示当前服务的 QPS每秒查询率- name: prometheus_qps position: [3, 1] config: prometheus_url: http://prometheus-server:9090 query: rate(http_requests_total[5m]) # 你的 PromQL 查询 update_interval: 30s在自定义模块的GetData()方法中你需要构造对{{prometheus_url}}/api/v1/query?query{{query}}的 HTTP 请求并解析返回的 JSON 数据。作为 Grafana 的替代或补充对于只需要关注少数几个核心指标的场景在glance上创建一个自定义视图可能比维护一个庞大的 Grafana 仪表盘更快捷。例如团队领导可能只关心每日活跃用户数和当前在线人数那么一个简单的模块就能满足需求无需在复杂的 Grafana 中导航。5.2 常见问题与故障排除实录在实际运行中你可能会遇到以下问题。这里记录了我踩过的一些坑和解决方法。问题一模块显示 “Error fetching data” 或一直处于 “Loading…” 状态。这是最常见的问题根本原因通常是数据获取失败。排查网络连通性首先确认运行glance的服务器能够访问模块配置中的外部 API 地址。可以 SSH 到服务器上用curl命令手动测试一下。检查 API 密钥和令牌对于需要认证的模块如 GitHub、天气确认密钥/令牌有效且未过期。特别是 GitHub 的 Personal Access Token它有细粒度的权限控制请确保它包含了repo访问仓库、notifications访问通知等必要的权限范围。查看日志glance默认将日志输出到标准错误stderr。通过journalctl -u glance.service -f对于 systemd 服务可以实时查看详细的错误信息这能精准定位是配置错误、网络超时还是 API 返回了错误格式。问题二仪表盘布局错乱模块重叠或位置不对。检查position坐标确保所有模块的position坐标是唯一的没有重叠。[列, 行]的坐标从[0,0]开始。如果你希望一个模块占多个格子目前版本需要配置多个相同内容的模块来实现或者修改前端 CSS。清除浏览器缓存有时是浏览器缓存了旧的 CSS 或 JavaScript 文件导致渲染异常。尝试强制刷新CtrlF5或打开浏览器无痕模式访问。问题三更新数据后页面没有自动刷新。确认 WebSocket 连接glance使用 WebSocket 在服务器和浏览器之间建立长连接以实现数据推送。如果页面不更新可能是 WebSocket 连接失败。检查浏览器控制台F12 - Console是否有 WebSocket 相关的错误。如果你使用了 Nginx 反向代理确保代理配置正确传递了Upgrade和Connection头如前文 Nginx 配置示例所示。这是 WebSocket 代理的关键。检查服务器防火墙是否阻止了 WebSocket 使用的端口默认与 HTTP 端口相同但协议不同。问题四系统资源CPU/内存占用过高。检查模块更新频率这是最可能的原因。如果设置了太短的update_interval比如1秒并且模块数量多、外部 API 响应慢会导致glance频繁地进行网络 I/O 和数据处理。将不必要实时更新的模块间隔调至1m或5m。检查自定义模块如果你自己编写了模块确保在GetData()方法中及时关闭 HTTP 响应体defer resp.Body.Close()并避免内存泄漏。可以使用pprof工具对运行中的glance进行性能剖析。5.3 界面自定义与主题切换虽然glance默认的界面已经足够简洁但你可能希望让它更贴合你的桌面环境或公司品牌。这主要通过修改前端资源实现。方法一覆盖 CSS 样式glance的静态资源在编译时被嵌入二进制文件但你可以通过外部文件覆盖默认样式。在glance的工作目录如/var/lib/glance下创建一个static文件夹再在里面创建custom.css文件。在custom.css中编写你的样式。例如将所有模块的背景改为深色.glance-widget { background-color: #2d3748 !important; color: #e2e8f0 !important; }修改glance的 systemd 服务文件或启动命令添加-static-dir参数指向你的static目录ExecStart/usr/local/bin/glance -config /etc/glance/config.yml -static-dir /var/lib/glance/static重启服务。glance会优先加载外部静态目录下的文件。方法二修改模板进阶如果你需要更大的改动可以克隆glance源码直接修改templates/目录下的 HTML 模板文件然后重新编译。这种方式更灵活但维护成本也更高因为每次升级版本都需要重新合并你的修改。经过以上步骤你应该已经能够从零开始部署、配置、定制一个完全属于你自己的glance仪表盘了。它的价值不在于功能的炫酷而在于那种“一切尽在掌握”的简洁和高效。当你把散落各处的信息流汇聚到这一个屏幕上时那种对工作环境的掌控感才是这个工具带来的最大愉悦。