常见问题
短答案;长的在 README 的功能说明里。
装之前想知道的
会不会弄坏服务器上已有的 sing-box、Xray 或别的面板?
不会。m-ui 的 sing-box 内核跑在 m-ui 自己的进程里,不会安装、停止或改动系统里的 sing-box / Xray、它们的配置文件,或者别的面板。唯一共用的是端口 —— 给线路挑空闲端口(新建线路的表单已经帮你挑好)就能共存。
需要 Docker、Node 或数据库服务吗?
不需要。安装脚本只放一个静态 Go 二进制到 /usr/local/bin/m-ui,一个 SQLite 文件在 /etc/m-ui/m-ui.db,加一个 systemd 单元。没有 Docker、Node、nginx,也没有 MySQL / PostgreSQL。
安装脚本到底写了哪些文件?
/usr/local/bin/m-ui、目录 /etc/m-ui/(数据库、cert/、backups/)和 /etc/systemd/system/m-ui.service。没有别的。安装命令后面加 --dry-run,它会先按你的机器把这份计划打印出来,什么都不改。
会和 nginx、Caddy 这类 Web 服务冲突吗?
默认不会:面板在 2053,订阅在 2056,代理面板在 2054。只有用 HTTP-01 签证书时才短暂需要 80 端口;80 被占着就用 Cloudflare DNS-01 或自签。
卸载会删数据吗?
不主动删。install.sh --uninstall(或 SSH 菜单)只删服务和程序,保留 /etc/m-ui,重新安装就能接着用原来的用户、线路和证书。要连数据一起删,加 --purge。
不装能先试试吗?
能。在线演示就是真实的面板界面在浏览器里跑示例数据:不用登录、没有后端,改动刷新即恢复。它和发布版用的是同一套前端文件,看到什么装出来就是什么。
安装与配置
一定要有域名吗?
不用。证书 → 自签一键就有 TLS,订阅会自动告诉客户端允许不安全证书。有域名可以签 Let's Encrypt 证书、去掉那个提示 —— 推荐,但不是必须。
要放行哪些端口?
面板 2053/tcp、订阅 2056/tcp、开了代理面板再加 2054/tcp,以及每条线路的端口(TCP 或 UDP 看协议)。用 HTTP-01 签证书还需要 80/tcp;Cloudflare DNS-01 不需要。副机的面板端口只需对主机的 IP 放行。
能改面板端口和路径吗?
能,在设置里改;把自己锁在外面了就用 SSH 菜单(m-ui)。路径带不带结尾斜杠都能打开。设成 443(HTTPS)或 80(HTTP)后,地址和订阅链接都不带端口;面板和订阅不能同用一个端口。端口保存前会校验,面板不会重启到一个被线路或别的程序占着的端口上。
系统要求?
Linux amd64 或 arm64,带 systemd;推荐 Debian 11+ / Ubuntu 20.04+,Rocky / CentOS 等其它 systemd 发行版也行。安装脚本依赖 systemd,所以 Alpine(OpenRC)不支持。安装需要 root。面板本身 1 核 1 GB 足够。CI 真正跑过的平台见自动测试过的平台。
纯 IPv6 的机器能用吗?
能:面板、订阅、线路都监听 IPv6,订阅自动给 IPv6 地址(云厂商的安全组要单独放行 IPv6 来源 ::/0)。有三处受限:GitHub 不支持 IPv6,检查更新与一键更新要先在运维页装 WARP(装好后自动经它下载),一键安装脚本也下载不了,要手动上传安装包;直连出口打不开只有 IPv4 的网站,线路上游选 WARP 才能访问全网(客户端常用的远程 DNS 如 1.1.1.1、8.8.8.8、9.9.9.9、223.5.5.5,面板会在直连线路上自动改连它们的 IPv6 地址,解析不受影响);大陆连通检测只测 IPv4,IPv6 入站另有一项检测(从境外测点测)。双栈机器默认在订阅里给 IPv4,服务器编辑里「自动地址用」可改成 IPv6。
为什么新建线路的表单里已经填了端口?
它挑了一个没被其它线路、面板和本机任何程序占用的五位端口,还真的绑定了一次确认。可以改;保存时冲突会被拦下。
用户与订阅
客户端里订阅名显示的是域名,不是我设的标题。
去 设置 → 订阅 → 订阅标题 填(代理在自己面板的订阅页填)。nextin、sing-box 这类每次刷新都读标题的客户端刷新即可。小火箭和 Clash Verge 是在添加订阅那一刻定名的,之后不改 —— 用落地页的一键导入按钮(会带上标题),或者让用户删掉重加。
设备数怎么算?
按不同的源 IP 算,跨所有服务器合在一起,由主机统一判定。手机连 Wi-Fi 和连流量是两个 IP。IPv4 地址与 IPv6 /64 各自计数、各自不超过上限(IPv6 下同一宽带里的设备同在一个 /64,和 IPv4 下同一路由器后面算一台一样),所以同一台双栈设备不会被算成两台;反过来,上限 3 时最多能有 3 个 IPv4 地址加 3 个 IPv6 /64 同时在线。设备满了只拒新设备,已连着的不受影响,别的设备下线约 1 分钟后名额空出来;被拒的连接在概览的「最近入站连接」里标红,点「被拒」筛选可以单看。
续费会把我手动停用的用户也启用吗?
会。用套餐续费、延期、换套餐(面板里的「续费…」「换套餐…」、批量套用套餐,外部 API 的 /plan、/renew、/change)是明确的开通动作,不管之前因什么停用都会启用,手动停用的也一样;面板执行前会先提示。「只归入这个套餐」不动启停;「延长 30 天」只恢复因到期停用的,手动停用的仍停着。不想让某人恢复,就别给他续费。
续费能一次续几个月吗?换套餐怎么折算?
「续费…」的期数一次可以续 1–120 期,月付套餐按季、按年卖就填 3、12。「换套餐…」有三种方式:立即替换(从现在算新套餐,旧的剩余作废)、叠加(保留旧订阅剩下的时间再加 N 期;已过期的不结转)、按价值折算(按两个套餐填的参考价,把剩余价值折成新套餐的时长)。对话框先预览变更前后,让用户吃亏的影响要勾确认才执行。外部 API 也能做,并且支持先预览、防重复提交。
落地页能放自己的 logo、在公告里放链接吗?
能。设置 → 订阅页 上传 logo(代理在自己的 账号 → 订阅页),上传即生效,深色模式下自动垫浅色底;透明底的白色 logo 两种背景都看不清,换一张。公告和页脚联系方式里写 文字(https://example.com)、[文字](https://example.com)、裸地址、Tg: @username 都会变成可点的链接,只认 http(s)、tg、mailto、tel。
踢线后 Hysteria2 / TUIC 客户端还连着?
不会了。踢线、停用、删除、换凭据时,QUIC 连接和 TCP 连接一样当场断开。客户端界面上可能还显示"已连接",那是它自己在重连;被停用的用户重连会被拒绝。
用户说连不上,怎么查?
看概览的「最近入站连接」。他的 IP 在「连接」筛选里,说明连进来了、走的哪条线路;在「握手失败」筛选里,是证书、密码或 SNI 不对,原因写在「原因」一列;两处都没有,先查安全组、防火墙和客户端网络;但有几类失败不会被记录(Hysteria2、TUIC 的 QUIC 握手失败和混淆密码不对,Shadowsocks、SOCKS 这类线路,版本较旧的副机等,鼠标停在卡片标题旁的「?」上能看到全部),所以不能据此断定包没到,最准的是在服务器上抓包确认。
用户能临时把订阅共享给别人吗?
你开启共享后,落地页上能生成一条临时共享地址,用的是另一套凭据。取消即刻只断借用者,本人不掉线;用量、设备、到期都算在本人头上。共享地址打开的是精简版落地页(一键导入、订阅地址、二维码、节点、你的公告和选购按钮),不显示本人的用量与到期:对方用浏览器打开就能一键导入,也可以把地址直接粘贴到客户端。
用户订阅用完了看到什么?
浏览器里仍是他的落地页,顶部多一张状态卡(已到期 / 流量已用完 / 已停用,读的是面板数据),链接和二维码不变,带你的公告与联系方式;设置了选购链接就有「选购 / 续费」按钮(代理可填自己的)。只有对不上任何用户的地址才是"订阅地址无效"页。用户被停用期间客户端拿到的是纯 404。
订阅地址能不暴露用户名吗?
能。取消勾选 设置 → 订阅 → 用户名用作订阅链接,之后新建的用户拿到 32 位随机令牌。已有用户的地址不受影响。
多服务器
副机要自己的证书吗?
要,各自签发(自签就行)、各自续期。线路带着主机的 TLS 设置下发,每台副机用自己的证书文件跑。副机一般不配通知:它的证书续期失败、快到期由主机代发提醒,主机的服务器页也会标出来。
升级时先升主机还是副机?
先升副机,再升主机。主机用到新功能后,版本不够的副机会整份拒收同步、按旧配置继续服务,直到升级为止:外部节点的隐藏和改名要副机 v0.7.17 及以上,上游组、线路作上游、外部节点的排除关键词要 v0.7.16 及以上,按规则分流要 v0.6.14 及以上;主机容灾的备用要副机 v0.7.17 及以上。副机先升上来,主机升级后推的第一份快照就能全部接收。服务器页标着「版本与主机不同」的就是还没升的。
sing-box 订阅里有的外部节点名字后面多了个「2」?
从 v0.7.17 起,sing-box 订阅和 Clash 一样,部署在多台服务器上的线路各出一个按延迟自动选的测速组,组名就是线路名,本站节点的名字和顺序不变。线路名始终留给本站:外部订阅里和用户某条线路同名的节点改叫「X 2」(Clash 与 sing-box 订阅都是),哪怕这次线路没出组(用户只分到一台、线路只部署在一台)也一样,选过线路组的客户端不会被悄悄落到第三方节点上。升级后改名一次,只改名字、出站参数不变;客户端里选着那个外部节点的用户要重新选一次。不想撞名,就给外部订阅加个前缀。
主机挂了怎么办?
副机拿着手里的配置照常转发,已经连上的用户不受影响。没开主机容灾时,主机提供的订阅在它回来前打不开;把用户指向副机的话,副机也能提供订阅。开了主机容灾,由备用接任为主机,见下一条。
副机能自动顶替挂掉的主机吗?
能,在主机的 设置 → 主机容灾 里打开(默认关闭)。打开后服务器列表里排在前面的几台副机(默认 2 台,可设 1–3)当备用,保存数据副本:每 5 分钟一份、有改动后 30 秒内补一份,用备用自己的公钥加密、主机签名。接任方式三选一:关闭;先确认再接任(默认,推荐):备用确认主机失联 3 分钟后发 Telegram,回复消息里的确认码,或到备用的面板上点「接任为主机」;主机失联后自动接任:失联 10 分钟后自己接任,三台以上要过半副机同意,一主一副时还要境外测点也连不上主机。只是国内到主机被墙、某一台和主机之间断网、主机在升级重启,都不算失联。接任后它就是主机;最后一份副本之后在原主机上做的改动、原主机自己线路上那几分钟的流量和流量图表补不回来。原主机回来后自动变为副机。副机都要升级到 v0.7.17 或更新;和副机的链接是明文 http 的,默认不当备用(链接上的中间人能拿到并改写副本),确实可信时在设置的「高级」里打开。SSH 上也能操作:m-ui ha status 看状态,takeover 在备用上接任,set-master 设为主机,pause / resume 在升级维护前后暂停、恢复接任。
想把主机换到另一台服务器,怎么做最省事?
用设为主机。新机装好 m-ui,像副机一样接入,显示「已同步」后在服务器页点它的角色标签(如「副机 ▾」)→「设为主机」,输一次管理员密码。主机的全部数据端到端加密后交给那台,它成为主机,原来的主机自动变为副机,不用备份、还原;账号、密码都不变。交接期间写操作暂停,通常一两分钟,两台各重启一次,连在这两台上的用户断开几秒后自动重连。和那台的链接是明文 http 时,要先勾选风险确认才能点(链接上的主动中间人能拿到并改写整库),能换 https 就先换。设为主机不保证一字节流量都不漏:交接那一两分钟里这两台自己线路上的流量不计入用户用量,其它副机的照常补回。
把主机的备份还原到另一台机器会怎样?
还原并启动后,那台就成了主机:它以更高的纪元接管全部副机,旧主机之后若又被启动(比如服务商重启了 VPS),会自动变为副机,不会和它抢。所以只想看看备份里有什么,别在联网的机器上还原并启动它。旧机不要了就在它上面执行 systemctl disable --now m-ui。旧主机还在运行时,用上一条的「设为主机」更省事。
主机换了,订阅域名怎么跟过去?
订阅的域名、端口、路径跟着主机走,把订阅域名的解析改到新主机就行;新 IP 写在页面顶部和 Telegram 通知里。域名托管在 Cloudflare 的,可以在 主机容灾 → 高级 里打开自动改 DNS(默认关闭):单独建一个只管这个域名 DNS 的令牌 —— Cloudflare 控制台 → 我的个人资料 → API 令牌 → 创建令牌,用「编辑区域 DNS」模板,区域资源选「包括 → 特定区域 → 你的域名」(输入框下的「去 Cloudflare 创建」打开已预填权限的创建页),和签证书用的令牌分开。之后主机变了,只把指向原主机 IP 的 A / AAAA 记录改到新主机,橙云和 TTL 不动;改不成只告警,写明哪些要你手动改。订阅地址里是 IP 的,主机变了用户要重新导入订阅,最好先换成域名。
副机掉线了会怎样?
主机在服务器页把它标成离线(配了 Telegram 机器人会收到提醒),其它服务器照常。只部署在这台副机上的线路,在它回来前连不上。重连后主机重新推一次完整快照,流量从存好的游标接着算,不会重复计。
副机重连后流量会重复计吗?
不会。副机保存单调计数器,主机为每台副机存游标,只加增量。见多服务器。
代理
新建的代理登不进去。
新代理没有密码。在代理面板输入名字,密码留空直接点登录,面板会要求设一个。首登窗口过期了可以在主面板重置。
代理能看到我的用户或线路吗?
不能。代理只看到自己的用户与套餐,只能用你授权的线路。隔离在服务端强制,不是靠界面藏起来。
运维
更新怎么做?会丢数据吗?
GitHub 有新版本时侧栏会出现箭头。点一下:下载压缩包、用 Release 里的 SHA256SUMS 校验、替换程序、重启。数据库、证书、备份、设置都不动。再跑一遍安装命令效果一样。v0.4.9 起更新是一次事务:旧程序留着、先做升级前备份,新版本 90 秒内起不来就自动换回旧程序(必要时连备份一起还原),面板会明确提示。
备份里有什么?
数据库(做过检查点,自洽)和证书文件,打成一个 zip;设置里引用的数据目录外的证书(比如 certbot 签的)也在里面。面板里就能还原;换机向导能把整套搬到新服务器。
换机还原后证书怎么办?
数据目录外的证书,新机原路径上有能用的同一张就接着用;没有就把备份里的副本放进 /etc/m-ui/cert/restored/ 并改好设置,面板顶部会提示一次。这些副本没有 certbot 之类的工具再续,到证书页重新签发,或在新机装好原来的工具后重新添加。面板、订阅、代理面板的证书万一还是缺了,先用临时自签证书启动并告警,不会起不来;顶着临时证书期间客户端更新订阅会报证书错误,照提示把证书补上即可。
面板里有说明书吗?
有。面板右上角「帮助说明」(在「建议 / 支持」左边)在新标签页打开内嵌的使用说明,定位到你当前所在页面的那一章,带目录和页内搜索;代理面板里打开的是代理视角的版本。说明书随程序一起发布,不用联网。
能从旧面板迁移吗?
能 —— 导入器读兼容格式的旧面板数据库,保留端口、凭据、面板路径与订阅地址,既有客户端不用刷新就能继续连。安装时加 --import /path/to/旧面板.db,或者用 用户 → 从旧面板导入 只搬用户。
m-ui 会上报什么吗?
不会,m-ui 没有遥测,不收集任何使用数据。对外连接只有你自己配置的(ACME、Cloudflare、WARP、Telegram)、每 6 小时向 GitHub Releases 查一次新版本,以及功德箱和在线设备数:打开「建议与支持」页时读一份公开名单,每天从 GitHub 下载一次空文件计数,都不带标识。这两样在设置里一个开关就能关。此外还有几项功能本身要联网,都不带使用数据:大陆连通与 IPv6 入站检测会把服务器地址和端口发给 Globalping 公共测点(自动巡检默认开,可关),上游测速默认连 www.gstatic.com。完整清单见面板「帮助说明」里的「面板会连哪些外部地址」。
去哪提问、报 Bug?
提问和想法:GitHub Discussions。确定的 Bug:用表单提 Issue。日志里的令牌、UUID、订阅地址请先打码。