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 配置

Create a Bot with Telegram's BotFather and copy the Bot Token.
Add the Bot to the target chat and obtain the Chat ID.
Open Settings → Telegram in 3M-UI.
Enable Telegram, enter the Token and Chat ID, then save.
Use Test to verify the Bot connection.
Send /start to open the Bot menu.
使用 Telegram 的 BotFather 创建机器人并复制 Bot Token。
将机器人加入目标聊天，并获取 Chat ID。
打开 3M-UI 的 设置 → Telegram。
开启 Telegram，填写 Token 和 Chat ID 后保存。
点击测试验证机器人连接。
向机器人发送 /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 / 安全建议

The initial administrator credentials remain admin / admin. Do not change the initialization logic. Change the password after first login if your deployment requires it.
Use HTTPS in production, preferably behind Nginx or Caddy.
Use a strong JWT secret of at least 32 random characters.
Restrict CORS origins to trusted administration domains.
Keep the Mihomo binary in an approved system path.
Set public_url correctly when using a reverse proxy.
Never publish your Telegram Bot Token in issues, screenshots or public repositories.
Subscription tokens are bearer credentials; treat them like passwords and revoke them when exposed.
初始管理员账号仍为 admin / admin，不会修改初始化密码逻辑。生产部署建议首次登录后修改密码。
生产环境使用 HTTPS，建议通过 Nginx 或 Caddy 反向代理。
JWT Secret 使用至少 32 位随机字符串。
CORS 仅允许可信的管理域名。
Mihomo 二进制文件放置在受信任的系统路径。
使用反向代理时正确设置 public_url。
不要在 Issue、截图或公开仓库中泄露 Telegram Bot Token。
订阅 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。

README.md Unescape Escape

3M-UI — Mihomo Management Console