MMWX Probe Komari Theme Adapter：一款将妙妙屋 X 主控探针数据转换为 Komari 主题可读格式的自托管只读探针前端

为什么做这个

妙妙屋 X 主控自带独立探针能力，但公开展示页面和主题选择相对有限。Komari 生态里有不少界面美观、功能完整的探针主题，却不能直接读取妙妙屋 X 主控的数据。

这个项目通过一层兼容适配，把妙妙屋 X 主控的探针数据转换成 Komari 主题可以读取的格式，并支持从 GitHub 动态加载主题。部署后，访客只需要访问适配器地址，不需要直接访问主控域名，也不会接触探针访问密钥。

项目适合已经部署妙妙屋 X 主控，同时希望快速搭建一个公开探针页面、复用 Komari 主题的场景。整个服务可以通过 Docker 一条命令启动。

⚠️ 免责声明：

• 本项目与 Komari 官方项目无关
• 本项目与妙妙屋 X 官方项目无关
• 这里的 “Komari 兼容” 只表示 API 形状兼容，不表示上游项目关系或授权关系
• 本项目若使用或兼容 Komari 生态中的第三方主题，相关主题的版权、商标和知识产权均归其原作者所有；本项目与这些第三方主题作者无隶属、合作或背书关系，展示 / 兼容不代表作者认可本项目

功能亮点

• 妙妙屋 X 探针代理：固定代理 /api/probe、/api/series 和 /api/stream，不接受访客指定任意上游地址
• Komari 兼容接口：提供 /api/public、/api/nodes、/api/records/*、/api/rpc2 等只读接口，兼容常见 Komari 主题
• 主题动态加载：启动时从指定 GitHub 仓库拉取主题，自动识别静态主题或需要构建的前端主题
• 主题配置管理：提供 /admin 管理页，支持配置 komari-theme.json 声明的主题选项
• 实时数据展示：支持延迟、丢包率、CPU、内存、网速、流量等历史数据，以及实时探针 WebSocket
• 共享流中继：容器与主控之间维护共享 WebSocket 连接，再向多个访客广播，减少访客数量增加时对主控的连接压力
• 数据字段保留：保留服务器状态、系统指标、流量周期、每日流量、续费信息和回程路由等妙妙屋 X 主控字段
• 只读安全边界：PROBE_TOKEN 只在容器访问主控时使用，不会暴露给浏览器；适配器不提供登录、管理、写入或节点修改能力
• Docker 化部署：提供 GHCR 镜像和 Docker Compose 示例，适合 VPS、NAS 或本地 Docker 环境
• 非官方兼容项目：本项目与 Komari 官方项目、妙妙屋 X 官方项目及第三方主题作者没有隶属、合作或背书关系

主题预览

目前已测试以下 Komari 主题：

• Glassmorphism
• Emerald
• Adhesive Note
• Junimo
• Lumina
• LuminaPlus
• Naive
• Komari Next

不同主题的配置方式可能不同。支持 komari-theme.json 的主题可以直接在 /admin 中配置；Lumina、LuminaPlus、Junimo 等主题可以通过主题提供的前端配置页进行设置。

快速开始

前置要求

• 已部署支持独立探针访问密钥的妙妙屋 X 主控
• 主控具有容器可以访问的 HTTPS 地址
• 一台能访问妙妙屋 X 主控和 GitHub 的 VPS、NAS 或本地 Docker 环境
• Docker 与 Docker Compose
• 一个可公开拉取的 Komari 主题 GitHub 仓库

Docker Compose（推荐）

新建 compose.yaml：

services:
  mmwx-komari-adapter:
    image: ghcr.io/sunnyhmz7010/mmwx-probe-komari-theme-adapter:latest
    container_name: mmwx-komari-adapter
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - MMWX_ORIGIN=https://panel.example.com
      - PROBE_TOKEN=replace-with-probe-token
      - THEME_REPO=https://github.com/example/komari-theme
      - THEME_REF=main
      - ADMIN_TOKEN=replace-with-random-admin-token

启动：

docker compose up -d
docker compose logs -f

启动后访问：

http://服务器IP:8080

管理页面：

http://服务器IP:8080/admin

一行 Docker 命令

docker run -d \
  --name mmwx-komari-adapter \
  --restart unless-stopped \
  -p 8080:8080 \
  -e MMWX_ORIGIN="https://panel.example.com" \
  -e PROBE_TOKEN="replace-with-probe-token" \
  -e THEME_REPO="https://github.com/example/komari-theme" \
  -e THEME_REF="main" \
  -e ADMIN_TOKEN="replace-with-random-admin-token" \
  ghcr.io/sunnyhmz7010/mmwx-probe-komari-theme-adapter:latest

自行构建

git clone https://github.com/sunnyhmz7010/mmwx-probe-komari-theme-adapter.git
cd mmwx-probe-komari-theme-adapter
docker build -t mmwx-komari-adapter .
docker run -d \
  --name mmwx-komari-adapter \
  --restart unless-stopped \
  -p 8080:8080 \
  -e MMWX_ORIGIN="https://panel.example.com" \
  -e PROBE_TOKEN="replace-with-probe-token" \
  -e THEME_REPO="https://github.com/example/komari-theme" \
  -e THEME_REF="main" \
  -e ADMIN_TOKEN="replace-with-random-admin-token" \
  mmwx-komari-adapter

如果使用 Docker Compose 本地构建，把 compose.yaml 中的 image: ghcr.io/... 换成：

build: .

然后执行：

docker compose up -d --build

使用说明

数据流

访客浏览器 ── HTTP / WebSocket ──> 适配器容器
                                      │
                                      └── 携带 PROBE_TOKEN
                                          ▼
                                  妙妙屋 X 主控

适配器只代理固定的探针接口，不接受访客传入任意上游地址，因此不会形成开放代理。

主要接口

主题配置

1. 在部署环境中设置 ADMIN_TOKEN。
2. 访问 /admin，输入管理员 Token 并验证。
3. 如果当前主题声明了配置项，直接在管理页修改并保存。
4. 如果主题提示使用前端配置页，先完成管理员验证，再进入主题提供的配置页面。

适配器不会修改主题源码。没有配置项的主题会显示为不可配置。

常用环境变量

注意事项

• PROBE_TOKEN 只用于容器访问主控，请不要直接写入公开仓库。
• 生产环境建议将 THEME_REF 固定到具体 tag 或 commit，避免主题仓库更新导致页面变化。
• 上游主控没有提供的字段无法由适配器凭空补齐，部分 Komari 主题可能会将这些字段显示为无数据。
• 删除容器后，主题构建产物和主题设置会随容器内部运行目录一起删除；需要长期保留时请结合实际环境设计持久化方案。
• 本项目只提供只读探针展示，不提供主控管理、登录、节点修改等功能。

项目地址

开源地址：https://github.com/sunnyhmz7010/mmwx-probe-komari-theme-adapter

欢迎 Star、提 Issue、提交 PR。