使用文档 · 开发文档 · 配置文档

MagicPanel 使用文档

这份文档讲清楚每个页面在做什么、每个按钮点下去会发生什么、遇到问题先看哪里。

目录

先理清几个概念

第一次用先把这几个词对上，后面的页面就好理解了。

概念 一句话 在哪维护
节点来源 一个机场订阅，或一个手写的本地节点 节点来源
规则来源 一份域名/IP 清单（远程抓取或内联维护） 规则来源
策略组 一组节点的聚合方式（手动选、自动测速、故障转移、负载均衡、链式） 策略组
分流策略 什么流量走哪个策略组 分流策略
引擎平台 引擎（Stash / Mihomo）+ 平台（iOS / macOS / Windows……），一类客户端 引擎平台
拓展模块 一段可复用的 YAML 片段（磁贴、DNS 策略、TUN、脚本改写） 拓展模块
基础配置 产物里的顶层键（端口、模式、DNS、TUN……） 基础配置
设备 一台装客户端的机器，一个固定订阅地址 设备管理

产物是编译出来的完整 YAML，也就是客户端真正下载到的那份配置。构建把当前所有设置固化成一份产物；发布决定哪份产物对外生效。改完设置不发布，客户端拿到的还是老配置。

引擎平台 = 引擎 + 平台，一对只能有一个。 想区分不同的人或设备，不要复制引擎平台：策略组和规则可以限定到具体设备，客户端参数用「设备独立配置」。

门户页：订阅中心

地址是站点根路径 /，比如 https://magichub.top:8443/。

PIN 不是密码学意义上的强认证，它是「防止订阅地址被随手翻到」的闸门。真正的访问控制在后台账号。

页面结构：

区块 说明
搜索框 搜订阅、规则、客户端；点「搜索」或回车才生效，输入时不会即时过滤
核心配置 设备订阅卡片。标题右侧一排平台标签，点一下只看该平台、再点取消，筛选对 Stash 与 Mihomo 两个引擎同时生效；标签固定列出全部支持的平台，当前没有设备的平台会压暗
客户端资源 Stash / Mihomo / Clash Verge Rev 等客户端的下载入口
分流策略 按目标策略组分组的个人规则，点组头展开，展开后点规则行即复制
规则来源 下发给客户端的规则集清单，可按行为或按来源仓库分组；每条有「复制地址」与「预览」
拓展模块 按类别分组的配置片段（脚本、面板段等）

三个折叠区块（分流策略 / 规则来源 / 拓展模块）默认都是折叠的，组头一行写清楚名称与条数，点组头展开。搜索时命中的分组会自动展开，清空搜索后回到折叠状态。

「规则来源」的「预览」会拉出这条规则的完整信息：行为、格式、条目数、大小、抓取状态与时间、面板抓取间隔、客户端更新间隔、上游地址（点一下复制），以及规则内容的前 120 行。二进制格式（MRS）没有可读文本，只给大小与指纹。

登录与账号

后台地址 /admin。

系统状态

打开后台第一屏，回答四个问题：现在跑的是哪一版、稳不稳、节点还在不在、测速是不是真的直连。

卡片 看什么
当前版本 当前生产版本、当前测试版本：构建号、发布时间、策略摘要、发布人和备注
运行状态 面板是否正常、数据库剩余空间、最近一次备份时间、测速核心版本
测速链路 面板当前的直连出口 IP 与归属地，检测是不是真的绕过了代理；「重新检测」可刷新
节点来源 每个来源的节点数、最近抓取时间
节点可用率 各来源最近一次测速里可用节点占多少
设备最近下载 每台设备最近一次拉取订阅的时间与 IP
最近操作 最近几条审计记录

测速链路这张卡值得看一眼：面板自己会检测出站 IP，如果 NAS 上有全局代理而面板没排除掉，测速结果会不准（节点看着好，实际在绕代理）。显示「测速走本机直连」才是对的——这里的「本机」指面板所在的 NAS，不是你的开发机。

节点来源

两个区块：节点来源（机场订阅）和本地节点（手写节点）。

节点来源

操作 说明
添加订阅 填名称、订阅 URL、抓取间隔、客户端更新间隔、测速间隔、User-Agent、节点过滤正则；要走代理再填代理地址
上传订阅文件 没有在线地址的订阅：把客户端导出的订阅文件传上来，仍是订阅来源（照常进分组、测速与下发），只是没有在线地址，内容更新靠重新上传
从 curl 命令导入 粘一条 curl 命令，自动填好订阅地址与请求头（Host 由地址决定，忽略）；导入后仍可逐项修改，保存才生效
一键抓取 / 一键测速 立刻跑一轮所有启用的来源
抓取 / 测速（单行） 只处理这一条
已启用 / 已停用 按钮上直接写当前状态，点一下就切换（只改启用状态，别的设置不动）
复制 URL 订阅地址加密存储，列表里不铺开，按需复制
编辑 改名称、URL、间隔、过滤条件、下发方式等
删除 有策略组引用时会被拦下，列出引用来源

几个容易踩的点：

列表上方有搜索与筛选：搜索来源名称，可按启用状态、下发方式（订阅 / 内联）、 抓取方式（自动抓取 / 只用本地快照）、抓取结果（成功 / 失败 / 从未抓取）筛选。 筛选条右侧写清是”共 N 个来源”还是”筛选出 N 个，共 M 个”，点「清空筛选」恢复全部。

本地节点

本地节点的「已启用 / 已停用」按钮同样在操作列里，点一下就切换。

自己搭的节点、家宽、落地都放这里。

规则来源

规则集是分流规则引用的清单，按来源分三种：远程（抓 URL）、内联（页面里直接写）、 仓库（由「自主维护」页托管，仓库里的 rule/*.yaml 自动进来）。

操作 说明
添加规则来源 名称、行为类型（domain / ipcidr / classical）、格式、间隔
内容 看这个规则集抓到了什么
抓取 立刻更新这一份
复制 URL 远程规则集的地址；仓库来源复制的是仓库内路径
被引用 哪些分流规则用了它，点一下直接跳到那条规则
已启用 / 已停用 按钮上直接写当前状态，点一下就切换（只改启用状态，别的设置不动）
编辑 / 删除 有分流规则引用时删除会被拦下

抓取失败不影响手上的数据：抓取失败时这一份会标成「抓取失败」，并提示「仍用上次内容」—— 上一次抓到的内容原样保留，构建和发布照旧用它，客户端不会突然少规则。定时抓取失败会自动重试， 最多 3 次都失败才记为失败。

抓取走代理：服务端直连抓不到这个规则集时才用，填 Mac mini 的内网地址 （默认 http://10.0.1.8:7890）。面板跑在 NAS 上，别填 127.0.0.1——那会连到 NAS 自己。

内联规则集直接在本页编辑内容，格式跟远程的一致。因为内容由本机维护，没有”抓取”这回事， 所以内联来源不设抓取间隔，只保留客户端更新间隔（客户端多久重新拉一次这份规则集）。

列表上方有搜索与筛选：搜索名称或 URL，可按类型（远程 URL / 内联内容 / 仓库托管）、行为 （域名 / IP 段 / 经典规则）、启用状态、抓取结果、被引用情况筛选。其中”抓取结果”只对远程来源 有意义——内联来源没有抓取这回事，不会出现在这个筛选里。

仓库托管的来源内容只读：它来自「自主维护」页的仓库，改动要去那里做； 这一类来源显示的状态是「同步状态」，不是抓取状态。

策略组

策略组决定流量落到哪些节点上。

类型 行为
select 手动选，默认第一个
url-test 自动测速选最快的
fallback 按顺序挑第一个可用的
load-balance 多节点分担，分配策略可选一致性哈希 / 轮询 / 粘性会话
relay 链式转发，把一个组接到另一个组前面

组里可以放：

拖动左侧手柄可以排序，上下箭头是键盘和触屏的替代。空组会在产物里留下占位，避免客户端把空组改写成别的。

列表上方有搜索与筛选：搜索组名，可按类型、可见性（客户端可见 / 客户端隐藏）、适用范围 （适用于所有平台与设备 / 限定了引擎平台 / 限定了设备）、成员构成（含节点来源 / 含本地节点 / 只靠指定成员）筛选。

“含节点来源”指真的指定了某个来源；勾的是「包含所有来源（含以后新增的）」不算，那等于没指定。

筛选状态下不能拖动排序：筛出来的组在列表里并不相邻，拖一下就会把整体顺序打乱；清空筛选后再拖。

分流策略

规则从上往下匹配，命中即停。

顺序就是优先级：从上往下第一条命中即生效，所以排法是「越具体越靠前、 同一目标组的规则聚成一块」。自己维护的集合（文件名带 magic- 前缀）排在最前面， 其后 119 条规则分十一块：本地与保留地址直连 → 网络层直连 → 广告 → 设备专属直连 → Steam 香港 → 小而明确的直连集合 → 服务分组 → 路由回家 → 通用代理兜底 → 大而泛的直连集合 → MATCH。

两条容易踩的：

「服务分组」块内部又分三层：地区锁服务（Pixiv / DMM / Hulu / BBC 这类按 国家或地区放内容、换 IP 就打不开的）→ 主题细分（Discord / Slack / Vercel / Amazon / 加密货币这类账号风控重、需要固定出口的）→ 宽泛合集（media / disney / social / games 这些上游大集合）。地区锁服务必须在宽泛合集之前， 否则 media 里那 10 条 BBC 域名会先被国际影音组接走，英国版权区就播不了。

本地进程直连已经收成一个集合：qbittorrent / Transmission / deluge / syncthing / Tailscale / UURemote 这 15 个进程名在 process 集合里 （自维护层），面板里只有一条 RULE-SET,process,DIRECT。要加新的下载器， 改那个集合文件即可，不用在界面上建规则。

Stash 专属修饰符（只有 Stash 产物会带上，Mihomo 不受影响）：

开关 作用 注意
不记入连接列表 命中的连接不显示在客户端的连接页，流量统计照常 适合广告、心跳、探测这类高频请求；兜底规则不能开，否则客户端一条连接都不记
提前拒绝 连接还没建立就拒掉（DNS 阶段就空应答），iOS 上最省 CPU 与内存 目标必须直接是 REJECT / REJECT-DROP，用策略组会让客户端加载失败；只对 Stash iOS/tvOS 3.7+、macOS 4.4+ 生效，版本太旧的客户端可能加载失败

这两个开关在「编辑规则」对话框里勾，也可以在表格里选中多条后批量设置。

广告过滤是双轨的：Stash 的 iOS / tvOS / macOS 产物里，广告规则的目标直接是 REJECT 并带「提前拒绝」；Stash-Android / Stash-Windows 和 Mihomo 产物里，广告规则指向 「🛑 广告过滤」策略组，可以临时切「默认代理」或「直连」放行广告。 两边都带「不记入连接列表」，广告请求不会把客户端的连接页刷满。

顺序很重要：把具体的放前面，宽泛的放后面。规则集（RULE-SET）通常放在域名规则之后、兜底之前。

规则类型别选错：面板里能选的一共 13 种（DOMAIN-SUFFIX / DOMAIN / DOMAIN-KEYWORD / DOMAIN-REGEX / IP-CIDR / IP-CIDR6 / GEOIP / GEOSITE / RULE-SET / SRC-IP-CIDR / DST-PORT / PROCESS-NAME / MATCH）。 构建时还会按引擎的官方白名单再查一遍——Stash 与 Mihomo 支持的类型不完全相同，超出白名单客户端会加载失败。

找规则

规则条数多，页面上方有搜索与筛选：

控件 作用
搜索框 按匹配值、目标、备注或类型查找，输入即筛（停一下自动生效）
全部类型 只看某一种规则类型（域名、IP、规则集……）
全部目标 只看指向某个策略组或 DIRECT / REJECT 的规则
全部状态 只看启用或停用的规则
全部适用范围 只看”适用于所有平台与设备”、”限定了引擎平台”或”限定了设备”的规则

筛选条右侧会写清楚当前是”共 N 条”还是”筛选出 N 条，共 M 条”。 点「清空筛选」恢复全部。

筛选状态下不能拖动排序：筛出来的规则在列表里并不相邻，拖一下就会把整体顺序打乱；清空筛选后再拖。

基础配置

页面有两个 tab：引擎平台 与 产物配置。tab 记在网址里 （?tab=targets / ?tab=artifact），可以直接把某个 tab 的链接发给别人。

tab：引擎平台

一类客户端对应一个引擎平台，比如 Stash-macOS、Mihomo-Windows。

可选平台：iOS / macOS / tvOS / Windows / Android / Linux（两个引擎通用，具体能不能用取决于客户端自身）。

tab：产物配置

产物里的顶层键在这里改，分三层，左侧树状结构选作用域：

引擎默认配置          ← 引擎内置的能力基线（可改）
  Stash 默认
  Mihomo 默认
引擎平台配置          ← 按「引擎 + 平台」
  Stash-iOS
  Mihomo-Windows
设备独立配置          ← 按设备
  Astral-iPhone-Stash

继承链显示在标题下方，一眼看清当前这层叠在哪几层之上：

继承链：引擎默认配置 · Stash 默认 → 引擎平台配置 · Stash-iOS → 设备独立配置 · Astral-iPhone-Stash

右栏上半部分是生效配置（键 / 值 / 来源），点值就能改；再往下是按分组排开的参数表单。

本层改动用颜色标在表里：蓝色 = 本层新增（上层没有这个键），橙色 = 本层覆盖（上层有，但值被改了）。 改过的行底色也一并染上，一眼扫过去就知道这层动了什么。改回上层，点行尾的「恢复继承」。

操作 说明
新增参数 挑一个键名填值，只对当前层生效
源码编辑 直接改这一层的 YAML，保存前做键级校验
清除改动 清掉本层对上层的覆盖，回到继承
恢复默认 引擎默认配置专用：回到程序内置内容
预览产物 按当前生效值渲染一份产物，不产生构建
保存 只保存本层，客户端要等新版本发布才拿到
保存并构建发布 保存 + 构建 + 发布，一步到位

三层的分工

列表的合并语义

几个内置功能

结构化内容不能在这里改

节点、策略组、规则、规则集、代理集合是结构化内容，只能在各自页面维护。任何配置层写这几个键都会被拒绝——这是硬校验，不是提示。

拓展模块

可复用的 YAML 片段，启用后与产物深度合并（字典递归、列表追加、标量覆盖）。

预设和引擎默认配置有重叠时，引擎默认配置已经带的能力可以关掉对应模块，产物不变。

设备管理

每台设备一行。

新增设备前先在「引擎平台」里准备好对应的平台。

构建发布

页面有两个 tab：手动构建发布 与 自动运行配置（?tab=builds / ?tab=auto）。 标题行右侧是页面级的 「立即发布」 与 「创建构建」，两个 tab 都能点到。

tab：手动构建发布

三个动作别搞混：标题行的「立即发布」跑一整轮自动任务（抓取 → 测速 → 创建新构建 → 发布）；标题行的「创建构建」只建快照不发布；列表里的「一键发布」发布已有的这个构建。

改完设置要生效，顺序是：改设置 → 创建构建 → 发布。 「基础配置」里的「保存并构建发布」把前两步合在一起。

tab：自动运行配置

服务端定时任务，按开关工作。

自动构建发布的前提是策略没变——策略没动就不会重复构建产物。改完配置想让客户端立刻拿到，要么手动构建发布，要么等下一次检查。

发布到哪个环境由「自动构建发布环境」设置决定，默认就是生产。要保持生产始终是最新版本，保持默认即可——测试环境是给人手验证用的，不发也不影响。

发布前有两道闸门，任一不过这一轮就不发布，页面上的运行记录会写明原因：

  1. 来源测速结果就绪——开了测速的来源都要有可用结果，否则不发布（避免把坏节点发出去）。
  2. Mihomo 目标的核心校验——测速核心已安装时，每个 Mihomo 产物都要过了 mihomo -t 才放行；核心没装则跳过这一关（Mihomo 产物只做了静态校验）。

自主维护

管理面板依赖的文件库（默认是 astralwaveorg/magic-sets）：浏览、编辑、提交、推送 都在这里做，规则内容改完即时生效。

区域 说明
状态条 仓库地址、分支、当前提交；徽标：干净 / 有本地改动 / 领先 / 落后 / 冲突
左侧文件树 按目录分组，每个文件带状态标记：● 本地已改、▲ 远端已更新、⚠ 冲突、○ 干净
右侧编辑器 选中文件后直接改；「保存」只写工作树，「保存并提交」提交并推送
立即同步 拉取仓库并把 rule/*.yaml 同步进规则来源

操作进行中的反馈：提交、推送、同步都是 Git 操作，要花时间（推送走 SSH，可能十几秒）。 这些操作进行时，「保存并提交」「立即同步」会置灰并显示「提交推送中…」「同步中…」， 状态条上出现「⏳ 提交并推送」这类标记；后台有别的操作在跑（另一个标签页或定时同步）时同样置灰， 操作结束后自动恢复。同一时刻只允许一个 Git 操作，第二个请求会被直接挡下， 提示「上一操作还在进行中（提交并推送），等它结束再试」。

规则集合自动成为规则来源：仓库里 rule/<名称>.yaml 会变成一条 kind='repo' 的规则来源， 内容以仓库为准，启用状态归面板（仓库不覆盖它）。集合名 = 文件名去扩展名， 中文展示名写在文件头注释里。script/ 与 rewrite/ 是素材区：面板只管理文件，不消费； 要启用其中某个片段，去「拓展模块」页新建一条「远程 URL」指向它。

改集合内容的固定流程：在自主维护页改文件 → 保存并提交（推送）→ 点「立即同步」 （或等 12 小时定时同步）→ 客户端下一次拉取就是新的。自维护层不经 jsDelivr 中转，没有 12 小时缓存。

冲突（本地与远端改了同一个文件）会停在冲突态：点组头展开冲突条， 三方对照（共同祖先 / 本地 / 远端），可以手工合并，也可以整体用远端或整体保留本地。

仓库设置（右上角）：仓库地址、分支、鉴权方式（SSH 部署密钥 / HTTPS Token / 公开仓库）、 提交身份、同步间隔、保存并提交后是否自动推送、排除路径清单、仓库新增 rule/*.yaml 时是否自动建来源。打开抽屉时会回显当前配置，改完保存即可。 私钥与 Token 只写不读（接口永不回显），只能看到是否已配置，可以点「生成密钥对」 由面板生成一对，再把公钥贴到仓库的 Settings → Deploy keys（要勾 Allow write access）。

排除清单默认 .git,.github,.env,*.bak,.*：点开头的路径（.editorconfig、.gitignore 等） 默认都不纳管，删掉 .* 可放开；.git 永远不可放开。

审计日志

记录谁在什么时候做了什么：登录、增删改、发布、查看订阅地址等。搜索后可以按条件删除。

系统设置

区块 内容
分发设置 对外基础地址、配置更新提示、会话有效期、核心下载代理
WebDAV 远程备份 地址、账号、密码、间隔、保留份数；测试连接、立即备份、查看远端备份、从远端恢复
测速核心 在线安装最新版、本地上传（.gz / .zip / 裸二进制）
Magic Panel 首页访问 门户 PIN 的设置与撤销
我的头像 上传或移除头像
维护者账号 添加、删除其他维护者
修改我的密码 改完密码后其他设备的会话失效
备份与恢复 导出 JSON 备份、从备份恢复

备份含加密后的订阅地址与令牌摘要，必须和 data/secret.key 分开保管——主密钥丢了，加密内容就恢复不出来。

典型操作流程

新增一个机场

  1. 节点来源 → 添加订阅 → 填名称、URL → 保存
  2. 点「抓取」确认有节点
  3. 策略组 → 新建一个组 → 勾选这个来源 → 保存
  4. 分流策略 → 改一条规则的指向，或新建一条 → 保存
  5. 构建发布 → 创建构建 → 校验通过 → 发布至测试 → 在测试设备上验证 → 发布至生产

给某台设备单独加个东西

  1. 设备管理 → 复制地址，确认是哪台设备
  2. 基础配置 → 左侧树选这台设备的「设备独立配置」
  3. 新增参数或用预设，保存
  4. 不用重新发布——设备独立配置是在分发时叠加的，客户端下次拉取就带上了

例外：改了「引擎默认配置」和「引擎平台配置」必须重新构建发布，因为那两层固化在构建产物里。

某台设备要用 MTProto

  1. 基础配置 → 选该设备的「设备独立配置」
  2. 预设 → 选「MTProto 代理（Telegram）」→ 套用
  3. 从生效配置里复制 mtproto.secret（32 位十六进制）
  4. Telegram 代理设置里选 MTProto，填设备的地址、5753、密钥

怀疑节点不通

  1. 系统状态 → 看「测速链路」是不是 NAS 直连
  2. 节点来源 → 对可疑来源点「测速」
  3. 必要时在「设置 → 测速核心」重新安装核心

常见问题

客户端拉到的配置还是旧的 改完设置没发布。引擎默认配置和引擎平台配置要重新构建发布；设备独立配置下次拉取就生效。

客户端提示配置加载失败 多半是规则类型超出该引擎的支持范围，或者策略组被引用成了空组。构建详情里会写明原因。

某台设备收不到规则 检查这条规则的「适用引擎平台」和「适用设备」——两者是取交集的，任一不匹配都不会生效。

订阅地址失效了 令牌被轮换或设备被删除。设备管理里「复制地址」取新的。

节点测速很慢或者结果不准 看系统状态的「测速链路」。面板必须走 NAS 直连，NAS 上的全局代理会影响它。

忘记密码了 用另一个维护者账号登录后重置；只有一个维护者时，需要在服务器上重置数据库里的账号记录。

备份恢复不了 多半是缺 data/secret.key。它和备份文件必须一起保管。

下一篇