Mafl 介绍与选型指南

目标：厘清 Mafl（hywax/mafl）的产品定位、架构与功能边界，给出与 Homer/Heimdall/Homepage/Homarr/Dashy 五款同类自托管面板的量化选型对比，帮助读者判断「单文件 YAML 驱动的极简首页面板」是否适合自己的家庭实验室。本文为联网溯源篇，全部数据来自官方仓库、官方文档站与徽章服务，查询日期 2026-11-02；部署与参数实测见本专栏 《Mafl 0.15.4 Docker Compose 部署指南》、《Mafl 0.15.4 配置参数详解》、《Mafl 0.15.4 日常运维手册》。

一、溯源环境信息

• 溯源渠道：GitHub 仓库 hywax/mafl（README 原文与 releases.atom 订阅源）、官方文档站 mafl.hywax.space、shields.io 徽章服务（星数/fork/贡献者/Docker 拉取数）、Docker Hub hywax/mafl 仓库页
• 查询日期：2026-11-02
• 对比组件数据来源：星数/版本为 2026-11-02 实查 shields.io 徽章与 GitHub releases.atom；Homarr/Homepage 行数据与站内 《Homarr 介绍与选型指南》、《homepage 介绍与选型指南》 口径一致
• 版本基线：Mafl 最新稳定版 v0.15.4（2024-07-13 发布）

二、软件概述

Mafl 是开发者 hywax 开源的自托管首页面板（homepage/dashboard），官方 README 开篇定义："Mafl is an intuitive service for organizing your homepage. Customize Mafl to your individual needs and work even more efficiently!"（Mafl 是一个用于组织你首页的直观服务）。在 awesome-selfhosted 目录中它被归入 Personal Dashboards（个人仪表盘） 分类，MIT 许可证，完全免费。

⚠️ 溯源甄别说明：任务立项时 Mafl 曾被描述为「自托管音乐库/流媒体面板」。经 GitHub 与 awesome-selfhosted 双渠道检索（2026-11-02），名为 mafl 的 GitHub 实体只有一个，即 hywax/mafl 首页面板；未发现任何音乐库/流媒体方向的 mafl 项目（音乐类检索命中均为 Navidrome、mStream、Ampache 等无关项目）。本专栏按面板实体开发，与站内 Heimdall/Homarr/Homer/Homepage 等同批面板组件对齐。

关键量化事实（均 2026-11-02 实查）：

版本节奏解读：v0.15.0→v0.15.4 集中在 2024-04~2024-07 三个月内小步快跑，此后 28 个月无新 Release，但 2026-06 仍有代码提交——典型的「功能定型后的低频维护」状态：代码没死，但不要把新特性预期放在它身上。193k 的 Docker 拉取量说明实际用户基数不小，与 760 星的热度基本相称（面板类组件「用的人多、点星少」是常态）。

三、核心架构

Mafl 是一个单进程 Node.js 服务端渲染应用，架构层次（依据官方文档与仓库结构）：

1. 前端：Nuxt 3 / Vue 3 构建，服务端渲染（SSR）输出整页 HTML，静态资源走 /_nuxt/ 前缀；支持 PWA 安装。
2. 服务端：Nitro 服务器（Node.js 运行时，官方 Docker 镜像基于 Alpine + Node.js 20），监听 3000 端口；内置 /api/health 健康检查端点与镜像级健康检查脚本（每 10 秒探测）。
3. 配置模型：一切配置收敛在单个 config.yml，挂载到实例的 /app/data/config.yml；本地图标、站点图标目录可选挂载 /app/public/icons、/app/public/favicons。这是 Mafl 与 Homarr（数据库+GUI）、Heimdall（SQLite+GUI）最大的架构分野。
4. 隐私设计：所有对第三方服务的请求（IP 查询、天气等）在服务端完成，浏览器不直连第三方 API——官方特性列表第一条即 Privacy；天气服务的 API Key 放在 secrets 字段，服务端明确不会把 secrets 下发给前端。
5. 实时性：服务端与页面之间维持 WebSocket 通道（/api/websocket），承担两类推送——服务状态刷新与配置文件变更热更新（实测链路见 《Mafl 0.15.4 日常运维手册》）。
6. 服务卡片体系：卡片分三种类型——base（纯链接卡片）、ip-api（显示出口 IP/归属地）、openweathermap（天气），后两者在 base 全部字段之上扩展 options/secrets。

💡 技术拓展：面板类组件的「服务在线状态检查」常见三种探测策略——

策略	原理	特点/取舍
TCP 端口探测	对目标主机端口发起 TCP 连接	快、无需应用层配合；但端口通≠服务真健康
HTTP 健康检查	GET 指定 URL 判断状态码	能验证应用层，但需服务暴露健康端点、开销略大
ICMP ping	网络层可达性	常被防火墙丢弃，且无法区分端口级状态

Mafl 实际采用 TCP 端口探测（从卡片 link 解析主机与端口，默认 80），这也是选型时要意识到的精度边界。

四、功能特性

官方 README 特性列表逐项展开：

五、快速开始（最小可用示例）

以下示例摘自官方 README/文档站（2026-11-02 查询），完整实测过程见 《Mafl 0.15.4 Docker Compose 部署指南》。

Docker Compose（官方推荐形态）：

# docker-compose.yml（官方 README 原样）
services:
  mafl:
    image: hywax/mafl
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - ./mafl/:/app/data/

最小 config.yml（services 是必填项，缺失则首页报错）：

title: My Home Page
services:
  - title: Home Assistant
    description: Home automation
    link: https://home-assistant.home.local/
    icon:
      name: simple-icons:homeassistant
      wrap: true

其他官方部署渠道：Node 源码方式（git clone → yarn install && yarn build → yarn preview）；Proxmox VE 一键 LXC（community-scripts 仓库的 ct/mafl.sh 脚本，配置落 /opt/mafl/data/config.yml）。

六、适用场景与限制

适用场景：

1. 家庭实验室统一入口：把 NAS、路由器、各服务收进一页，配状态灯快速判断哪个服务挂了；
2. 单文件配置洁癖：不想引入数据库、不想开 GUI 配置后台，一个 config.yml 全搞定、可 Git 版本化；
3. 中文用户友好：原生 lang: zh，无需翻译补丁；
4. 低资源占用：单 Node 进程、镜像内容层约 48MB，树莓派级别设备即可运行。

限制与风险（选型前必读）：

1. 无内置认证：面板本身没有任何登录体系，暴露到公网必须自行加反向代理认证层（对比：Homarr 有多用户+SSO）；
2. 状态检查仅 TCP 层：端口通即「在线」，HTTPS 站点若不显式写端口会探测 80 而非 443（实测见 《Mafl 0.15.4 配置参数详解》）；
3. 发布停滞：最新 Release 停在 2024-07（v0.15.4），新特性预期要放低；
4. 配置校验宽松：官方 schema 对拼错的键不报错（如 titel），坏配置以「静默空卡片」形式呈现，排障要靠 /api/settings 回读；
5. 服务生态小：内置卡片类型只有 3 种（base/ip-api/weather），没有 Homepage 那样的百种 widget 生态。

七、同类选型对比

六款站内已收录/在库的自托管面板量化对比（星数/版本/日期均 2026-11-02 实查 shields.io 与 releases.atom；Heimdall/Homer/Homepage/Homarr 四列与 《Homarr 介绍与选型指南》 第七章口径一致）：

解读与选择建议：

• Mafl 星数在本组垫底，但它是唯一同时做到「单 YAML 配置 + 内置状态灯 + 中文原生 + PWA + 配置热更新」 的组件——功能组合而非热度是它的卖点；
• 只要书签墙、零后端 → Homer；要海量 widget 集成 → Homepage（见 《homepage 介绍与选型指南》）；要多用户/管容器 → Homarr；要主题玩法与自带鉴权 → Dashy（见 《Dashy 4.9.0 介绍与选型指南》）；
• 单用户、一台小主机、一个 YAML 管全部、想要状态灯和中文界面 → Mafl 是这组里最贴合的；
• 需要公网多用户访问的场景请直接排除 Mafl（无认证），或必须搭配反代认证层。

八、参考链接

• 官方仓库：https://github.com/hywax/mafl （查询日期 2026-11-02）
• 官方文档站：https://mafl.hywax.space/ （Getting Started / Configuration / Services 章节）
• Docker Hub：https://hub.docker.com/r/hywax/mafl
• GHCR：https://ghcr.io/hywax/mafl
• awesome-selfhosted 收录条目（Personal Dashboards 分类）：https://github.com/awesome-selfhosted/awesome-selfhosted
• 站内延伸阅读：《Homarr 介绍与选型指南》、《homepage 介绍与选型指南》、《Dashy 4.9.0 介绍与选型指南》