Homepage 适合做入口整理，不是监控系统的替代品。

\n
Homepage 在 HomeLab 里的定位很清楚：把常用服务入口、简单状态和说明信息放在一个页面里。它让家里的服务不再靠浏览器收藏夹和记忆端口号维持秩序，但它不是完整监控平台，也不是权限系统。页面越漂亮，越要提醒自己：入口整理只是第一步，健康判断、告警和故障记录还要交给专门工具。

服务入口按使用场景分组

我不喜欢把 Homepage 做成软件展览墙。真正高频使用的入口，一般可以按“日常使用、文件资料、运维管理、监控日志、备份恢复”分组。家人只需要看到少数生活相关入口，管理员才需要看到容器、数据库、日志、监控这些工具。分组的目标是减少误点，不是展示机器上装了多少服务。

每个条目最好写清楚服务名、内网地址、用途和负责人。比如同样是管理页面，一个负责文件交换，一个负责日志查看，一个负责指标面板。名称写得太花，半年后自己也会忘。Homepage 的配置文件本质上就是入口手册，应该能让另一个人看懂每个链接为什么存在。

健康状态只能做轻量提示

Homepage 可以展示 ping、HTTP 状态、容器状态或小组件信息，这些提示很有用，但不能等同于服务真的健康。页面返回 200，不代表登录正常；容器正在运行，不代表后台任务没有卡住；磁盘还有空间，不代表备份可恢复。我的做法是把 Homepage 上的状态看成“第一眼线索”，真正的问题仍然去日志和监控系统确认。

状态项也不要堆太多。对入口页来说，红绿状态的价值在于提醒下一步看哪里。如果一个页面塞满几十个小徽标，异常反而容易被忽略。高价值状态包括服务能否访问、容器是否频繁重启、关键磁盘是否接近阈值、备份任务最近一次是否成功。更细的趋势和告警放到 Grafana 或其他监控面板。

密钥不要写进公开配置

Homepage 的小组件常常需要 API key、token 或账号信息。这里最容易犯的错，是把密钥直接写进公开仓库或截图里。即使只是内网服务，也不该把敏感值散落在 services.yaml、widgets.yaml 里。能用环境变量就用环境变量，不能用时也要确保配置目录不会被同步到公开位置。

另外，配置截图发布前要检查 URL、用户名、内部域名和状态小组件返回内容。HomeLab 文章很容易为了展示效果截一整页，但入口页天然包含资产清单。它会告诉别人你运行了什么服务、入口在哪里、哪些服务可能有管理权限。真正需要分享时，宁愿做脱敏示意，也不要贴完整生产配置。

Docker socket 要谨慎

Homepage 可以通过只读 Docker socket 展示容器状态。只读并不代表没有风险，因为能读取容器名称、镜像、标签、挂载路径和部分运行信息。对于入口页来说，这已经是高价值资产清单。我只会在内网管理入口中使用，并且避免把页面暴露给不需要的人。

如果只是想做导航，完全可以不挂载 Docker socket，手写服务列表就够了。需要容器状态时，也可以限制 Homepage 的访问范围，配合反向入口认证或内网访问策略。便利和暴露面总要取舍；入口页越集中，越不能把它变成无需认证的公开目录。

配置文件就是恢复来源

Homepage 的价值不在页面调得多好看，而在配置可复现。服务列表、图标、分组、说明、状态组件，都应该来自可备份的配置文件。迁移机器时复制配置目录，改少量环境变量，就能恢复入口页。反过来，如果所有调整都靠页面记忆和临时修改，换机器时一定会漏。

我会在维护记录里写清：配置目录位置、是否使用 Docker socket、哪些组件依赖密钥、哪些链接只允许内网访问。每次新增服务，先判断它应该放在哪个分组、谁会使用、是否需要状态提示。Homepage 做得克制一点，HomeLab 的入口反而更可靠。

图标和说明也要服务识别，不要只追求统一风格。两个服务名字相近时，说明里写清“查看日志”“编辑菜谱”“管理仓库”这类动作，比放一个漂亮图标更有用。入口页最终面对的是日常使用场景，点进去之前就应该知道会进入什么系统、是否需要管理员账号、能不能让家人使用。

我也会给外部链接和内部链接分开标识。内网地址、管理入口、家庭成员入口、只读状态页，不应该混在一组里。这样在手机上临时打开时，不会误点到高权限工具，也能快速判断某个服务只是入口失效，还是服务本身已经不可用。

入口失效时，先点直连地址，再看反向入口日志。这样能分清是 Homepage 配置错，还是目标服务真的挂了。