3M-UI — Mihomo Management Console

English · 中文

3M-UI is a lightweight web management console for Mihomo Core. It focuses on VPS node management, listener configuration, proxy-user credentials, traffic usage, client subscriptions, configuration lifecycle management, and Telegram operations.

3M-UI 是一个轻量、现代的 Mihomo Core Web 管理面板，主要用于 VPS 节点管理、Listener 入站配置、代理用户凭据、流量统计、客户端订阅、配置生命周期管理以及 Telegram 管理与通知。

---

✨ Features / 功能

Core / 核心管理

• Mihomo start / stop / restart / status
• Listener create, update, validation and configuration regeneration
• SQLite + GORM storage
• JWT-based panel authentication
• Client URI and subscription generation
• Credential-aware Mihomo configuration generation
• Configuration preview and validation before activation
• Safe configuration apply with automatic .bak backup
• Configuration rollback through the Mihomo service layer
• Subscription token enable/disable, expiry and lifecycle management

Telegram / Telegram 机器人

Telegram is more than a notification channel: the built-in Bot supports both notifications and interactive administration.

Telegram 不只是通知渠道，内置 Bot 同时支持通知、查询和交互式管理。

• Bilingual notifications: Chinese + English / 中英双语通知
• User blocked, expired, traffic-limit and restored notifications
• Optional daily usage summary / 可选每日流量摘要
• Telegram Bot Token validation with getMe
• Correct handling of Telegram HTTP 200 + ok=false responses
• Command menu registered automatically at Bot startup
• Inline keyboard menus / Inline 按钮菜单
• Telegram ID → proxy-user binding
• User self-service usage and node links
• Admin views for users, online users, listeners, traffic ranking, blocked users and low-quota users
• Admin /restart for Mihomo through the Mihomo service only
• Admin client creation wizard with listener selection, generated password and binding
• Callback permissions are re-checked before privileged actions
• Wizard state prevents duplicate client-creation flows
• Telegram update offset is persisted across bot restarts

Bot Commands / Bot 命令

Command	English	中文	Permission
/start	Open menu	打开菜单	All
/help	Show help	查看帮助	All
/status	Service status	服务状态	All
/id	Telegram ID	查看 Telegram ID	All
/usage	Own usage; admins can search users	查看自己的用量；管理员可查询客户端	All
/inbound <remark>	View listener	查看入站	Admin
/restart	Restart Mihomo	重启 Mihomo	Admin
/bind <username> <telegram_id>	Bind a client	绑定客户端	Admin
/users	List clients	客户端列表	Admin
/online	Online clients	在线客户端	Admin
/listeners	Listener list	入站列表	Admin
/traffic	Traffic ranking	流量排行	Admin
/cancel	Cancel current wizard	取消当前向导	All

普通用户不能通过 /usage <other-user> 查询其他客户端；/inbound 和 /restart 严格要求管理员权限。

Regular users cannot use /usage <other-user> to inspect another client; /inbound and /restart require administrator privileges.

The Bot also exposes the same major functions through inline keyboards.

Bot 还提供 Inline Keyboard，可直接点击完成主要查询和管理操作。

---

🛡️ P0 Reliability / P0 可靠性

The P0 baseline is designed around one rule: Web UI, Telegram and future API clients must all use the same service layer and never bypass Mihomo lifecycle controls.

P0 基线遵循一个原则：Web UI、Telegram 以及未来的 API/CLI 都必须经过统一 Service Layer，不能绕过 Mihomo 生命周期管理。

• Subscription / 订阅 — secure listener-bound tokens, expiry checks, Mihomo YAML and optional subconverter formats
• Client management / 客户端管理 — credentials, traffic limits, expiry, online state and Telegram binding
• Config preview / 配置预览 — validate a candidate without touching the live configuration
• Config apply / 配置应用 — validate, back up the current configuration, activate, and restore on failure
• Config rollback / 配置回滚 — restore the previous .bak configuration through Mihomo Service
• Mihomo Service / 核心服务 — start, stop, restart, status, logs and guarded configuration activation
• Telegram / Telegram — bilingual notification/admin workflow with permission re-checks and persisted update offset

---

🏗️ Architecture / 架构

┌──────────────────────────────┐
│ React 19 + Zustand + AntD 6 │
└──────────────┬───────────────┘
               │ HTTP / REST
┌──────────────▼───────────────┐
│ Gin + GORM + JWT             │
└──────────────┬───────────────┘
               │ Unified Service Layer
       ┌───────┼──────────┬────────────┐
       ▼       ▼          ▼            ▼
   Clients  Telegram  Config Engine  Mihomo Service
       │       │          │            │
       └───────┴──────────┴────────────┘
                        │
                        ▼
                 ┌──────────────┐
                 │ Mihomo Core  │
                 └──────────────┘

---

🚀 Quick Start / 快速开始

Requirements / 环境要求

• Go 1.25+
• Node.js 20+
• Linux VPS; Ubuntu/Debian recommended / Linux VPS，推荐 Ubuntu/Debian

Backend / 后端

cd backend
go mod tidy
go build -o ../3m-ui ./cmd/server
../3m-ui --config /etc/3m-ui/config.yaml

Frontend / 前端

cd frontend
npm install
npm run dev
npm run build

Production builds are placed under backend/static/ by the project build process.

生产构建会生成到项目使用的 backend/static/ 目录。

One-line install / 一键安装

curl -fsSL https://raw.githubusercontent.com/kazeyukiro/3m-ui/main/scripts/install.sh | bash

---

⚙️ Configuration / 配置

Example /etc/3m-ui/config.yaml:

server:
  host: "0.0.0.0"
  port: 8080
  public_url: "https://your-domain.com"

database:
  path: "/etc/3m-ui/3m-ui.db"

jwt:
  secret: "change-me-to-a-32-char-random-string"

mihomo:
  binary_path: "/usr/local/bin/mihomo"
  config_path: "/etc/mihomo/config.yaml"

security:
  cors_origins: []

Telegram settings are configured from the panel. Enable Telegram only after providing a valid Bot Token and at least one Chat ID.

Telegram 设置在面板中完成。启用 Telegram 通知前，需要填写有效的 Bot Token，并至少配置一个 Chat ID。

Available notification switches / 可用通知开关：

• notify_on_block — blocked / disabled / traffic-limit notifications / 封禁、禁用、流量耗尽通知
• notify_on_unblock — restored notifications / 恢复通知
• notify_on_expiry — expiry notifications / 到期通知
• notify_daily_digest — daily summary / 每日摘要

---

🔗 Subscription / 订阅

Create a listener-bound access token from the panel. The token is the credential for the public subscription endpoint:

/api/v1/client/sub/<token>

Optional targets include:

?target=mihomo
?target=clash
?target=sing-box
?target=shadowrocket

Subscription tokens can be disabled, expired or deleted without changing the underlying listener configuration.

订阅 Token 可以单独禁用、设置到期时间或删除，不会直接修改底层 Listener 配置。

---

🔐 Telegram Setup / Telegram 配置

1. Create a Bot with Telegram's BotFather and copy the Bot Token.

2. Add the Bot to the target chat and obtain the Chat ID.

3. Open Settings → Telegram in 3M-UI.

4. Enable Telegram, enter the Token and Chat ID, then save.

5. Use Test to verify the Bot connection.

6. Send /start to open the Bot menu.

7. 使用 Telegram 的 BotFather 创建机器人并复制 Bot Token。

8. 将机器人加入目标聊天，并获取 Chat ID。

9. 打开 3M-UI 的 设置 → Telegram。

10. 开启 Telegram，填写 Token 和 Chat ID 后保存。

11. 点击 测试 验证机器人连接。

12. 向机器人发送 /start 打开菜单。

For self-service commands, bind a proxy user to the user's Telegram ID. Administrators can use /bind <username> <telegram_id>.

如需用户自助查询，需要将代理用户与 Telegram ID 绑定。管理员可以使用 /bind <username> <telegram_id> 完成绑定。

---

🧩 Configuration Lifecycle / 配置生命周期

Recommended production workflow / 推荐生产流程：

Edit / 编辑
   ↓
Preview / 预览
   ↓
Validate / 校验
   ↓
Apply / 应用
   ↓
Backup current config / 备份旧配置
   ↓
Restart or start Mihomo / 重启或启动核心
   ↓
Health check / 健康检查
   ↓
Success → keep / 成功 → 保留
Failure → rollback / 失败 → 回滚

API endpoints / API：

Method	Endpoint	Description / 说明
POST	/api/v1/config/preview	Validate candidate without applying / 仅预览校验
POST	/api/v1/config/validate	Validate YAML / 校验 YAML
POST	/api/v1/config/apply	Generate, validate and safely activate / 安全生成、校验并应用
POST	/api/v1/config/rollback	Restore previous .bak / 恢复上一份配置
GET	/api/v1/config/download	Download generated YAML / 下载配置

---

🛡️ Security / 安全建议

1. The initial administrator credentials remain admin / admin. Do not change the initialization logic. Change the password after first login if your deployment requires it.

2. Use HTTPS in production, preferably behind Nginx or Caddy.

3. Use a strong JWT secret of at least 32 random characters.

4. Restrict CORS origins to trusted administration domains.

5. Keep the Mihomo binary in an approved system path.

6. Set public_url correctly when using a reverse proxy.

7. Never publish your Telegram Bot Token in issues, screenshots or public repositories.

8. Subscription tokens are bearer credentials; treat them like passwords and revoke them when exposed.

9. 初始管理员账号仍为 admin / admin，不会修改初始化密码逻辑。生产部署建议首次登录后修改密码。

10. 生产环境使用 HTTPS，建议通过 Nginx 或 Caddy 反向代理。

11. JWT Secret 使用至少 32 位随机字符串。

12. CORS 仅允许可信的管理域名。

13. Mihomo 二进制文件放置在受信任的系统路径。

14. 使用反向代理时正确设置 public_url。

15. 不要在 Issue、截图或公开仓库中泄露 Telegram Bot Token。

16. 订阅 Token 属于 Bearer 凭据，泄露后应立即禁用或删除。

---

📡 API Overview / API 概览

Method	Endpoint	Auth	Description / 说明
POST	/api/v1/auth/login	No	Login / 登录
POST	/api/v1/auth/password	Yes	Change password / 修改密码
GET	/api/v1/auth/me	Yes	Current user / 当前用户
GET	/api/v1/dashboard	Yes	System and Mihomo status / 系统与核心状态
GET	/api/v1/nodes	Yes	List listeners / 入站列表
POST	/api/v1/nodes	Yes	Create listener / 创建入站
GET	/api/v1/nodes/:id/uri	Yes	Export node URI / 导出节点 URI
GET	/api/v1/client/sub/:token	Token	Client subscription / 客户端订阅
GET	/api/v1/telegram/settings	Yes	Telegram settings / Telegram 设置
POST	/api/v1/telegram/test	Yes	Test Telegram / 测试 Telegram
POST	/api/v1/mihomo/start	Yes	Start Mihomo / 启动核心
POST	/api/v1/mihomo/stop	Yes	Stop Mihomo / 停止核心
POST	/api/v1/mihomo/restart	Yes	Restart Mihomo / 重启核心
POST	/api/v1/config/apply	Yes	Safe config activation / 安全应用配置
POST	/api/v1/config/rollback	Yes	Restore previous config / 回滚配置

---

🧪 Development / 开发

Backend tests:

cd backend
go test ./...

Frontend:

cd frontend
npm run build

Before submitting changes, verify both backend tests and the production frontend build.

提交修改前，请至少验证后端测试和前端生产构建。

---

📄 License / 许可证

MIT License. See LICENSE.

MIT License，详见 LICENSE。