1. EtherealYz 到底是个什么项目
先交代一下背景。我断断续续维护了一个个人项目,代号叫 EtherealYz,名字很直白:Ethereal 取自"空灵、轻盈、像以太一样渗透在空气里",Yz 是我自己的字母缩写,这项目就是我的个人数字工作台。
说白了,它不是一个能一句话讲清楚的传统软件,而是一套把散落在各种终端、看板、笔记、自动化脚本里的信息,统一收敛到一个自托管仪表盘的组合方案。我把它拆成了三个部分:
- 一个轻量的数据采集端,负责从服务器、本地开发环境、第三方 API 里抓取指标和事件流;
- 一个中间层,做数据清洗、聚合、缓存,顺便把对外暴露的接口全部收敛到这里;
- 一个前端展示层,把所有数据用极简风格渲染成大屏、小组件和日报推送。
我做它的起因很简单:那段时间我同时维护三个服务、一个家庭 NAS、两个内容站,每天要开五六种后台页面去查状态。不同系统有不同 UI、不同账号、不同刷新频率,信息割裂得让人崩溃。我试着用过现成的开源仪表盘,比如 Grafana、Dashy、Homepage,但总有不顺手的地方。Grafana 侧重监控指标,不适合展示内容型信息;Dashy 和 Homepage 又偏向书签导航,数据接入能力弱。我需要的是一个"什么都能接一点、接完还能自由排版、且足够轻"的东西。
于是 EtherealYz 就从"想要一个自己的控制台"这个朴素需求开始,慢慢长到了现在这个规模。这篇文章我不打算做那种从零教写代码的教程,而是想用项目复盘的方式,讲讲它从混乱到收敛的过程中,我做了哪些核心设计决策、踩了哪些坑、哪些经验是可以直接迁移到你自己项目里的。
如果你正在纠结"自己的服务太多、信息太散、想搞一个统一入口但不知道从哪下手",这篇内容应该能帮上忙。哪怕你完全不想用我的方案,里面关于数据接入、接口设计、部署排错的思路,也能套用到很多自托管项目上。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 起名背后的产品定位,以及它和现成方案的差异
很多人觉得项目名只是个代号,无所谓。但 EtherealYz 这个名字其实是我产品定位的浓缩,也直接影响了我后续的每一次技术选型。
2.1 "Ethereal" 意味着什么
我当时给这个项目定了几条原则,全部围绕"空灵"这个词展开:
- 轻:整体运行时内存占用控制在 200MB 以内,不接受动不动就吃 1GB 内存的组件。
- 透明:所有数据流转过程要可视、可查,任何一个数据源断了,系统要能明确告诉我断在哪一步。
- 不打扰:界面默认只显示必要信息,次要内容折叠,避免一打开就是一个满屏数字的"监控机房"。
- 可拆解:任何一个模块坏了,不影响其他模块运行,整个系统可以部分降级。
这套原则直接否决了一批重量级方案。比如 Grafana,它本身很强大,但插件体系、数据源配置、告警规则、面板模型都带有一整套学习成本,对"家庭级"和"个人开发者级"的使用场景来说过于笨重。Dashy 又过于静态,它的定位是"导航页",没法处理 API 动态数据。
我要的是介于两者之间的一种东西:有自取数据的能力,又不像监控平台那样强调指标、告警、时间序列那一套。EtherealYz 的定位更偏向"信息聚合与呈现",而不是"监控"。
2.2 和技术选型的关系
因为定位是"信息聚合",所以我的技术选型也跟传统监控系统不一样。EtherealYz 整体分三层,每层都有明确界限:
| 层级 | 职责 | 选型 |
|---|---|---|
| 采集层 | 对接各种数据源,做格式归一化 | Go 编写独立二进制,支持 HTTP 轮询、Webhook、读取本地文件 |
| 中间层 | 数据校验、聚合、缓存、对外 API | Node.js + Fastify + SQLite,单进程即可跑 |
| 展示层 | 界面渲染、组件交互、用户配置 | Vue 3 + Vite,桌面端和移动端都用同一套响应式布局 |
选 Go 做采集层,是因为采集器经常要部署在多台服务器上,Go 交叉编译方便,扔一个二进制上去就能跑,不需要目标机器装运行时。选 Node.js 做中间层,是考虑到后续如果要写复杂的聚合逻辑或接入新数据源时,JavaScript 的人体工学更好,迭代速度快。SQLite 是整个系统的数据底座,因为个人项目数据量不大,没必要上 PostgreSQL,SQLite 单文件备份也省心。
我见过很多人一上来就 PostgreSQL + Redis + ClickHouse 全家桶,结果自己只有几台机器,数据量每天几千条,纯属给自己找运维负担。EtherealYz 的原则是:数据量没到百万级之前,不要引入需要单独守护进程的存储组件。
3. 第一版架构的致命问题:我把"采集"做成了定时任务
这里我想展开讲讲第一版的设计失误,因为它直接决定了后面整体的重构方向,而且这个坑我相信很多人也踩过。
3.1 最初的定时轮询模型
EtherealYz 一开始的采集层,就是一组 Crontab 定时任务。每个数据源一个脚本,每 5 分钟跑一次,把结果写到 SQLite 里。展示层再轮询中间层接口,每 30 秒刷新一次页面数据。
看起来没问题对吧?实际上跑了两周就裂开了。问题出在数据源的异构性和任务的相互依赖上。
我有几个数据源是链式的:
- 源 A 是某个第三方 API,每天凌晨 3 点更新数据;
- 源 B 需要基于源 A 当天最新数据做二次计算;
- 源 C 则需要把源 A 和源 B 的结果合并,生成一份日报推送。
Crontab 只保证"到点执行",不保证"执行时前一个任务已经成功完成"。于是我经常遇到这样的情况:B 任务跑了,但 A 任务因为网络超时失败了,B 拿到的是昨天的旧数据,计算结果全是错的。更麻烦的是,C 又在 B 的半成品上继续加工,最后推送给我的日报里,指标对不上。
3.2 数据缺失时的静默失败
第二个致命问题是,定时任务失败后没有任何记录。
脚本里我确实写了 try catch 和日志输出,但是日志分散在各个服务器的 /var/log 目录里,我没有统一的日志收集,所以一个任务失败后,唯一的感知路径就是"我看板上的数据不对了"。有时候是几小时后才发现。
有一个印象特别深的例子:某个数据源偶尔会返回一个空数组。我的采集脚本没做校验,直接把这个空数据写进了数据库。结果展示层发现昨天的数据"消失了",显示成空白。我花了一整天排查,最后才发现是采集脚本的问题,不是展示层的
