@lancewu602/mihomo-dash 0.6.3 → 0.7.0

package/README.md

@@ -46,16 +46,16 @@ macOS 只有用户级 LaunchAgent（`~/Library/LaunchAgents`，`gui/<uid>` 域
 
 ## 面板功能
 
-| 路由           | 页面     | 能力                                                                                                                       |
-| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `/`            | 概览     | 内核信息条、代理概览（订阅/策略组/节点/可用节点）、累计流量 / 活动连接 / 内存占用读数、上下行速率 60s 趋势                 |
-| `/proxies`     | 节点     | 策略组切换与增删改、节点测速、订阅增删/更新/健康检查、每条订阅的「拉取出口」（走哪个策略组 / 节点去拉，直连常被墙）        |
-| `/connections` | 连接     | 连接表、单个/全部关闭、host 搜索                                                                                           |
-| `/rules`       | 规则     | 两张卡片：自定义规则（`DOMAIN-SUFFIX` 增删）+ 系统规则（固定 7 条 GEOSITE/MATCH 启停与选目标）                             |
-| `/logs`        | 日志     | 实时日志流（关键字 / 级别过滤、暂停、自动滚动）                                                                            |
-| `/config`      | 配置     | 快捷设置（allow-lan / log-level / unified-delay / tcp-concurrent / find-process-mode）、GEO 数据库展示与配置、系统代理开关 |
-| `/config-file` | 配置文件 | CodeMirror 直接编辑 `config.yaml` 源文件                                                                                   |
-| `/kernel`      | 内核     | 面板自有内核：上传安装包（.gz / .zip）安装与升级、卸载、日志（进程启停 / 重启在侧栏底部）                                  |
+| 路由           | 页面     | 能力                                                                                                                                                                                          |
+| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/`            | 概览     | 内核信息条、代理概览（订阅/策略组/节点/可用节点）、累计流量 / 活动连接 / 内存占用读数、上下行速率 60s 趋势                                                                                    |
+| `/proxies`     | 节点     | 策略组切换与增删改、节点测速、订阅增删/更新/健康检查、每条订阅的「拉取出口」（走哪个策略组 / 节点去拉，直连常被墙）                                                                           |
+| `/connections` | 连接     | 连接表、单个/全部关闭、host 搜索                                                                                                                                                              |
+| `/rules`       | 规则     | 两张卡片：自定义规则（`DOMAIN-SUFFIX` 增删）+ 系统规则（固定 7 条 GEOSITE/MATCH 启停与选目标）                                                                                                |
+| `/logs`        | 日志     | 实时日志流（关键字 / 级别过滤、暂停、自动滚动）                                                                                                                                               |
+| `/config`      | 配置     | 快捷设置（allow-lan / log-level / unified-delay / tcp-concurrent / find-process-mode）、GEO 数据库展示与配置、系统代理开关（含绕过列表：可自己加域名 / 网段，面板只往系统里补、不动已有条目） |
+| `/config-file` | 配置文件 | CodeMirror 直接编辑 `config.yaml` 源文件                                                                                                                                                      |
+| `/kernel`      | 内核     | 面板自有内核：上传安装包（.gz / .zip）安装与升级、卸载、日志（进程启停 / 重启在侧栏底部）                                                                                                     |
 
 设计要点：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lancewu602/mihomo-dash",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "mihomo 管理工具：CLI + 守护进程 + Web 面板",
   "type": "module",
   "license": "MIT",

package/server/CHANGELOG.md

@@ -5,6 +5,19 @@
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-11-02
+
+### 新功能
+
+- 系统代理的绕过列表可以自己加条目：`POST` / `DELETE /api/system-proxy/bypass`（域名、`*.域名` /
+  `+.域名` 通配、IPv4 / IPv6、CIDR 网段），存状态目录的 `system-proxy.json`；系统代理开着时增删
+  即时写进系统列表（`networksetup -setproxybypassdomains` / GNOME `ignore-hosts`），关着时只记下、
+  下次开启一并写入。写进系统前一律过 `normalizeBypassEntry()` 校验（字符白名单、拒绝前导 `-`、
+  域名逐标签、IP 与网段前缀范围、不收端口），系统里其它条目一条不动
+
+- `GET /api/system-proxy` 多带 `bypassCustom`（配置页加的自定义项），`PUT` 开启时把它们与固定项
+  一起并入绕过列表；增删接口回 `written` 说明系统设置这次是否真的被改了
+
 ## [0.6.3] - 2026-10-31
 
 ### 工程

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mihomo-dash-server",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "private": true,
   "type": "module",
   "description": "mihomo-dash 后端源码（作为 mihomo-dash 的一部分发布，不单独发包）",

package/server/src/http/system-proxy.js

@@ -5,14 +5,25 @@
  * 内核的 mode 决定走不走节点，系统代理决定系统会不会把流量交给内核的端口，两层独立。
  *
  * 开启时除了写地址与端口，还会把 `BYPASS_DEFAULTS`（回环 / 私网 / link-local / 多播 / 本地域名的固定项）
- * **补进**绕过列表 —— 与已有条目求并集、不删手工加的；关闭时不动绕过列表。补了哪些会从 `bypassAdded`
- * 回给前端；GET 还会带上 `bypassDefaults`（值 + 说明），供页面把「固定项 / 自己加的 / 待补」分开展示。
+ * 与**配置页里用户自己加的自定义项**（{@link readBypassCustom}）**补进**绕过列表 —— 与已有条目求并集、
+ * 不删手工加的；关闭时不动绕过列表。补了哪些会从 `bypassAdded` 回给前端；GET 还会带上 `bypassDefaults`
+ * （值 + 说明）与 `bypassCustom`（自定义项），供页面把「固定项 / 自己加的 / 待补」分开展示。
+ *
+ * `/api/system-proxy/bypass` 增 / 删一条自定义项：存状态目录 → 系统代理**开着就即时写进系统绕过列表**
+ * （写失败则回滚，保证「页面上的列表 = 实际生效的列表」），关着就只记下来、下次开启时一并写入。
+ * 删除只移除**这一条**，系统里其它条目（包括用户手工加的）一概不碰。
  *
  * 面板无鉴权（仅监听 127.0.0.1），所以这里的写操作跟别的一样只接受 JSON body
  * （跨站表单发不出 application/json，等于顺手挡掉一类 CSRF）。
  */
 import { resolveKernelProxyTarget } from '../kernel/client.js';
-import { BYPASS_DEFAULTS, createSystemProxy } from '../shared/system-proxy.js';
+import {
+  addBypassCustom,
+  dropBypassCustom,
+  readBypassCustom,
+  removeBypassCustom,
+} from '../shared/bypass-list.js';
+import { BYPASS_DEFAULTS, createSystemProxy, mergeBypass } from '../shared/system-proxy.js';
 
 /**
  * 只读探测系统代理：卸载内核这类「前置检查」用（**不动任何设置**）。
@@ -56,10 +67,34 @@ export async function disableSystemProxyIfOn(opts = {}) {
 export function registerSystemProxyRoutes(app, opts = {}) {
   const proxy = createSystemProxy(opts);
 
+  /** 读状态 + 内核端口 + 面板固定项 / 自定义项（GET 与两条 bypass 写接口共用同一份响形） */
+  async function snapshot() {
+    const [state, target] = await Promise.all([proxy.read(), resolveKernelProxyTarget()]);
+    return {
+      ...state,
+      target,
+      bypassDefaults: BYPASS_DEFAULTS,
+      bypassCustom: readBypassCustom(),
+    };
+  }
+
+  /**
+   * 把系统绕过列表改成「现有 + 自定义 + 固定项」的并集（只增不减）。
+   * 只在系统代理开着时调用：关着时系统本身不走代理，提前写没意义，留着下次开启一并写。
+   * @param {string[]} custom 当前的自定义项
+   */
+  async function applyBypass(custom) {
+    const state = await proxy.read();
+    if (!state.supported || !state.enabled) return [];
+    const { list, added } = mergeBypass(state.bypass, custom);
+    if (!added.length) return [];
+    await proxy.setBypass(list);
+    return added;
+  }
+
   app.get('/api/system-proxy', async (_req, res) => {
     try {
-      const [state, target] = await Promise.all([proxy.read(), resolveKernelProxyTarget()]);
-      res.json({ ...state, target, bypassDefaults: BYPASS_DEFAULTS });
+      res.json(await snapshot());
     } catch (err) {
       res.status(500).json({ error: String(err?.message || err) });
     }
@@ -72,12 +107,66 @@ export function registerSystemProxyRoutes(app, opts = {}) {
       const state = await proxy.read();
       if (!state.supported) throw new Error(state.hint || '本平台不支持改系统代理');
       const target = await resolveKernelProxyTarget();
-      const result = await proxy.setEnabled(enabled, target);
+      const result = await proxy.setEnabled(enabled, { ...target, bypass: readBypassCustom() });
       res.json({
         ...result.state,
         target,
         applied: result.applied,
         bypassAdded: result.bypassAdded,
+        bypassDefaults: BYPASS_DEFAULTS,
+        bypassCustom: readBypassCustom(),
+      });
+    } catch (err) {
+      res.status(400).json({ error: String(err?.message || err) });
+    }
+  });
+
+  /** 新增一条自定义绕过项（body `{ value }`）：校验 → 存盘 → 系统代理开着就即时写入系统列表 */
+  app.post('/api/system-proxy/bypass', async (req, res) => {
+    let value = '';
+    try {
+      const added = addBypassCustom(req.body?.value);
+      value = added.value;
+      let applied;
+      try {
+        applied = await applyBypass(added.entries);
+      } catch (err) {
+        // 系统设置没写进去 → 把刚存的那条撤掉，别让页面显示一条其实没生效的项
+        dropBypassCustom(value);
+        throw err;
+      }
+      res.json({ ...(await snapshot()), applied, written: applied.length > 0, added: value });
+    } catch (err) {
+      res.status(400).json({ error: String(err?.message || err) });
+    }
+  });
+
+  /** 删掉一条自定义绕过项（`?value=`）：系统里有这一条就一并移除，其它条目不动 */
+  app.delete('/api/system-proxy/bypass', async (req, res) => {
+    try {
+      const removed = removeBypassCustom(req.query?.value);
+      const applied = [];
+      try {
+        const state = await proxy.read();
+        const hit = (state.bypass ?? []).find(
+          (v) => String(v).toLowerCase() === removed.value.toLowerCase(),
+        );
+        // 系统里还剩至少一项时才写回（不能把列表清空）；关着也删 —— 那是上次开着时写进去的残留
+        const list = (state.bypass ?? []).filter((v) => v !== hit);
+        if (state.supported && hit && list.length) {
+          await proxy.setBypass(list);
+          applied.push(`绕过列表 -${removed.value}`);
+        }
+      } catch (err) {
+        // 系统设置删不掉：把它放回自定义列表，保持「页面 = 实际」一致，再把错误往上抛
+        addBypassCustom(removed.value);
+        throw err;
+      }
+      res.json({
+        ...(await snapshot()),
+        applied,
+        written: applied.length > 0,
+        removed: removed.value,
       });
     } catch (err) {
       res.status(400).json({ error: String(err?.message || err) });

package/server/src/shared/bypass-list.js

@@ -0,0 +1,86 @@
+/**
+ * 面板管理的**自定义绕过项**：配置页「系统代理」卡片里用户自己加的域名 / 通配 / 网段。
+ *
+ * 为什么单独存一份（`MIHOMO_DASH_DIR/system-proxy.json`，形如 `{ "custom": ["*.corp.example"] }`）：
+ * - 系统绕过列表是**系统说了算**的（用户在系统设置里手工加的那些，面板不接管、也从来不删）；
+ *   面板固定项（`BYPASS_DEFAULTS`）是「开启时补上就行了」，同样不需要记。
+ * - 只有「用户希望加进绕过列表」这件事是面板独有的状态，得跨重启记住 —— 存一份列表，
+ *   页面才能把「面板自定义的」和「系统里本来就有的」分开显示、并给每条一个删除按钮。
+ *
+ * `system-proxy.json` 不是配置契约：文件缺失 / 坏掉都当成「没有自定义项」（不抛错、不拦页面），
+ * 只有写入失败才往外抛 —— 那时用户的操作确实没生效。
+ */
+import fs from 'node:fs';
+import { writeFileAtomic } from './atomic-file.js';
+import { ensureCliDir, SYSTEM_PROXY_FILE } from './paths.js';
+import { normalizeBypassEntry } from './system-proxy.js';
+
+/**
+ * 读自定义绕过项（文件不存在 / 解析失败 → 空数组；只保留非空字符串）。
+ * @returns {string[]}
+ */
+export function readBypassCustom() {
+  let text;
+  try {
+    text = fs.readFileSync(SYSTEM_PROXY_FILE, 'utf8');
+  } catch {
+    return [];
+  }
+  try {
+    const data = JSON.parse(text);
+    const list = Array.isArray(data?.custom) ? data.custom : [];
+    return list.map((v) => String(v ?? '').trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/** 写回（原子替换：写到一半崩掉不会留下半份 JSON） */
+function writeBypassCustom(list) {
+  ensureCliDir();
+  writeFileAtomic(SYSTEM_PROXY_FILE, `${JSON.stringify({ custom: list }, null, 2)}\n`);
+  return list;
+}
+
+/**
+ * 新增一条：校验 → 去重（大小写不敏感）→ 落盘。**写盘前一律过 {@link normalizeBypassEntry}**，
+ * 页面传什么上来都不直接进系统命令。
+ * @param {unknown} raw 用户输入
+ * @returns {{ entries: string[], value: string }} value 是规范化之后的写法
+ */
+export function addBypassCustom(raw) {
+  const value = normalizeBypassEntry(raw);
+  const entries = readBypassCustom();
+  if (entries.some((v) => v.toLowerCase() === value.toLowerCase())) {
+    throw new Error(`已经在自定义绕过项里了：${value}`);
+  }
+  return { entries: writeBypassCustom([...entries, value]), value };
+}
+
+/**
+ * 删除一条（大小写不敏感匹配）。不在列表里就报错 —— 页面据此提示「已经被删掉了，刷新看看」。
+ * @param {unknown} raw
+ * @returns {{ entries: string[], value: string }} value 是实际被删掉的那条（原样返回）
+ */
+export function removeBypassCustom(raw) {
+  const value = String(raw ?? '').trim();
+  if (!value) throw new Error('要删哪一条？value 不能为空');
+  const entries = readBypassCustom();
+  const hit = entries.find((v) => v.toLowerCase() === value.toLowerCase());
+  if (!hit) throw new Error(`自定义绕过项里没有这一条：${value}`);
+  return {
+    entries: writeBypassCustom(entries.filter((v) => v !== hit)),
+    value: hit,
+  };
+}
+
+/**
+ * 撤销式回滚（新增后写系统设置失败时用）：只在列表里还有这一条时移除，别的一律不动。
+ * @param {string} value 已经规范化过的写法
+ */
+export function dropBypassCustom(value) {
+  const entries = readBypassCustom();
+  const rest = entries.filter((v) => v.toLowerCase() !== String(value).toLowerCase());
+  if (rest.length !== entries.length) writeBypassCustom(rest);
+  return rest;
+}

package/server/src/shared/paths.js

@@ -36,6 +36,9 @@ export const KERNEL_LEDGER_FILE = path.join(CLI_DIR, 'kernels.json');
 export const KERNEL_META_FILE = path.join(CLI_DIR, 'kernel-run.json');
 export const KERNEL_PID_FILE = path.join(CLI_DIR, 'kernel.pid');
 export const KERNEL_LOG_FILE = path.join(CLI_DIR, 'kernel.log');
+// 系统代理：面板只记自己在配置页加的那几条**自定义绕过项**（`{ custom: string[] }`）。
+// 系统里那份绕过列表是系统说了算（面板只往里面补，不接管），所以不存这里。
+export const SYSTEM_PROXY_FILE = path.join(CLI_DIR, 'system-proxy.json');
 
 export function ensureCliDir() {
   fs.mkdirSync(CLI_DIR, { recursive: true });

package/server/src/shared/system-proxy.js

@@ -15,6 +15,7 @@
  *   即可写这些设置，不需要 sudo。
  * - `run` 可注入：测试用桩函数断言真实 argv，不会碰本机设置。
  */
+import nodeNet from 'node:net';
 import { defaultRun } from './exec.js';
 
 export { defaultRun };
@@ -82,17 +83,118 @@ export const BYPASS_DEFAULTS = [
 const BYPASS_VALUES = BYPASS_DEFAULTS.map((d) => d.value);
 
 /**
- * 现有绕过列表 + {@link BYPASS_DEFAULTS}：顺序保留，缺失的追加在后面（大小写不敏感去重）。
- * @param {string[]} [current]
- * @returns {{ list: string[], added: string[] }}
+ * 现有绕过列表 + 自定义项 + {@link BYPASS_DEFAULTS}：顺序保留，缺失的追加在后面
+ * （大小写不敏感去重）。**只增不减**：现有条目一条都不删、不改大小写、不重排。
+ * @param {string[]} [current] 系统里已有的条目
+ * @param {string[]} [extra] 用户在面板里加的自定义项（排在固定项前面）
+ * @returns {{ list: string[], added: string[] }} added = 本次真正补进去的项
  */
-export function mergeBypass(current = []) {
+export function mergeBypass(current = [], extra = []) {
   const list = current.map((s) => String(s));
   const have = new Set(list.map((s) => s.trim().toLowerCase()));
-  const added = BYPASS_VALUES.filter((d) => !have.has(d.toLowerCase()));
+  const added = [];
+  for (const raw of extra) {
+    const v = String(raw).trim();
+    if (!v || have.has(v.toLowerCase())) continue;
+    have.add(v.toLowerCase());
+    added.push(v);
+  }
+  for (const d of BYPASS_VALUES) {
+    if (have.has(d.toLowerCase())) continue;
+    have.add(d.toLowerCase());
+    added.push(d);
+  }
   return { list: [...list, ...added], added };
 }
 
+/** 自定义绕过项允许出现的字符（值最终作为 argv 交给 networksetup / gsettings） */
+const BYPASS_CHARS = /^[A-Za-z0-9.*+_:/-]+$/;
+/** 域名标签：不允许以 - 开头/结尾（_ 放行，内网里常见） */
+const HOST_LABEL = /^[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?$/;
+/** 通配前缀：`*.example.com`（Chrome / GNOME 写法）、`+.example.com`（Clash 写法）、`.example.com` */
+const WILDCARD_PREFIX = /^(?:\*|\+)\./;
+
+/** 逐个标签校验主机名（单标签也认，`localhost` / `myhost` 都在用） */
+function checkHostname(name, raw) {
+  if (name.length > 253) throw new Error(`域名过长（≤253 字符）：${raw}`);
+  const labels = name.split('.');
+  // 末级标签可以含数字，但不能全是数字（`1.2.3.4.5.6.7.8` 这种是 IP 打错了，不是域名）
+  if (labels.length > 1 && /^\d+$/.test(labels[labels.length - 1])) {
+    throw new Error(`IP 不合法：${raw}（四段 IPv4 每段 0–255；IPv6 直接写地址或网段）`);
+  }
+  for (const label of labels) {
+    if (!label) throw new Error(`域名不合法：${raw}（有空的标签 / 多余的 .）`);
+    if (!HOST_LABEL.test(label)) {
+      throw new Error(`域名不合法：${raw}（标签只能用小写字母 / 数字 / - / _，不能以 - 开头结尾）`);
+    }
+  }
+}
+
+/**
+ * 校验并规范化**用户手输**的一条绕过项（域名 / 通配域名 / IP / CIDR 网段）。
+ *
+ * 为什么要在写系统设置之前卡一道：这些值会作为**位置参数**进 `networksetup` / `gsettings`
+ * 的 argv（不经 shell，但以 `-` 开头的值会被系统命令当成自己的开关），而且随手打错一条
+ * 就意味着「以为绕过了、其实流量还在走代理」。所以这里既要挡字符，也要挡语义：
+ * - 域名：逐标签校验长度与字符，允许 `*.` / `+.` / `.` 通配前缀，通配只能出现一次且在最前面；
+ * - IP：交给 `net.isIP` 判（IPv4 / IPv6 都认）；
+ * - 网段：`地址/前缀`，前缀范围按地址族（IPv4 0–32、IPv6 0–128）；
+ * - 不收端口（系统绕过列表只认主机 / 域名 / 网段），也不收 `,` `#` `?` 这类分隔符。
+ *
+ * 规范化：去首尾空白、去 FQDN 的尾点、统一小写（IPv6 与域名都不区分大小写）。
+ * @param {unknown} raw
+ * @returns {string} 可以直接写进系统设置的写法
+ */
+export function normalizeBypassEntry(raw) {
+  const text = String(raw ?? '').trim();
+  if (!text) throw new Error('绕过项不能为空');
+  if (text.length > 253) throw new Error(`绕过项过长（≤253 字符）：${text.slice(0, 32)}…`);
+  if (/\s/.test(text)) throw new Error(`绕过项不能含空格：${text}`);
+  if (text.startsWith('-')) {
+    throw new Error(`绕过项不能以 - 开头（系统命令会把它当成开关）：${text}`);
+  }
+  if (!BYPASS_CHARS.test(text)) {
+    throw new Error(
+      `绕过项只能由字母 / 数字 / . - _ * + : / 组成（域名、*.域名、IP、网段），收到：${text}`,
+    );
+  }
+  const v = text.replace(/\.$/, '').toLowerCase();
+  if (!v) throw new Error(`绕过项不能只有一个点：${text}`);
+  if (!/[a-z0-9]/.test(v)) throw new Error(`绕过项里要有域名或地址，不能只有符号：${text}`);
+
+  const slash = v.indexOf('/');
+  if (slash >= 0) {
+    const addr = v.slice(0, slash);
+    const prefix = v.slice(slash + 1);
+    if (!addr || !prefix) throw new Error(`网段写法是 地址/前缀：${text}（示例 10.0.0.0/8）`);
+    if (v.indexOf('/', slash + 1) >= 0) throw new Error(`网段里只能有一个 /：${text}`);
+    const family = nodeNet.isIP(addr);
+    if (!family) throw new Error(`网段里的地址不合法：${text}（示例 192.168.0.0/16、fe80::/10）`);
+    const max = family === 4 ? 32 : 128;
+    if (!/^\d{1,3}$/.test(prefix) || Number(prefix) > max) {
+      throw new Error(
+        `网段前缀不合法：${text}（${family === 4 ? 'IPv4 是 0–32' : 'IPv6 是 0–128'}）`,
+      );
+    }
+    return v;
+  }
+
+  if (nodeNet.isIP(v)) return v;
+  if (v.includes(':')) {
+    throw new Error(`地址不合法：${text}（系统绕过列表不支持端口；IPv6 请写完整地址或网段）`);
+  }
+  // 长得就像 IPv4（四段纯数字）但过不了 isIP：错的是那个 IP 本身，别顺水推舟当成域名
+  if (/^\d+(\.\d+){3}$/.test(v)) {
+    throw new Error(`IP 不合法：${text}（每段 0–255，网段写成 192.168.1.0/24）`);
+  }
+
+  const name = v.replace(WILDCARD_PREFIX, '').replace(/^\./, '');
+  if (!name) throw new Error(`通配后面要跟域名：${text}（示例 *.corp.example）`);
+  if (/[*+]/.test(name)) throw new Error(`通配只能出现在最前面一个（* 或 +）：${text}`);
+  checkHostname(name, text);
+  return v;
+}
+
 /** 地址/端口白名单校验：只有这些字符能出现在 argv 里 */
 export function assertHostPort(host, port) {
   const h = String(host ?? '').trim();
@@ -238,8 +340,8 @@ function macOSProxy(run) {
         if (!r.ok) throw new Error(`设置 ${p.label} 代理失败：${r.stderr || r.status}`);
         applied.push(`${p.label} → ${host}:${port}`);
       }
-      // 固定绕过项：补上缺的（已有的一个不动，所以只写回「并集」）
-      const { list, added } = mergeBypass(before.bypass);
+      // 固定绕过项 + 自定义项：只补缺的（已有的一个不动，所以只写回「并集」）
+      const { list, added } = mergeBypass(before.bypass, target.bypass);
       if (added.length) {
         const r = await net(['-setproxybypassdomains', svc.name, ...list]);
         if (!r.ok) throw new Error(`设置绕过列表失败：${r.stderr || r.status}`);
@@ -250,7 +352,22 @@ function macOSProxy(run) {
     return { service: svc.name, applied, bypassAdded, state: await read() };
   }
 
-  return { read, setEnabled };
+  /**
+   * 用给定的完整列表覆盖系统绕过列表（配置页增删一条自定义项时用）。
+   * 列表由调用方算好（现有 + 自定义 + 固定项的并集），这里不再做合并 / 去重。
+   * @param {string[]} entries
+   */
+  async function setBypass(entries) {
+    const svc = await activeService();
+    if (!svc.name) throw new Error('没找到可用的网络服务（networksetup 没列出任何服务？）');
+    const list = (entries || []).map((s) => String(s).trim()).filter(Boolean);
+    if (!list.length) throw new Error('绕过列表不能是空的：系统会把它当成「没有绕过项」');
+    const r = await net(['-setproxybypassdomains', svc.name, ...list]);
+    if (!r.ok) throw new Error(`设置绕过列表失败：${r.stderr || r.status}`);
+    return { service: svc.name, list };
+  }
+
+  return { read, setEnabled, setBypass };
 }
 
 /** GNOME 实现：gsettings（用户级，不需要 root） */
@@ -320,8 +437,8 @@ function linuxProxy(run) {
         await gs(['set', `${GNOME_PROXY}.${key}`, 'host', host]);
         await gs(['set', `${GNOME_PROXY}.${key}`, 'port', String(port)]);
       }
-      // 固定绕过项（ignore-hosts）：补上缺的，已有的不动
-      const { list, added } = mergeBypass(state.bypass);
+      // 固定绕过项 + 自定义项（ignore-hosts）：补上缺的，已有的不动
+      const { list, added } = mergeBypass(state.bypass, target.bypass);
       if (added.length) {
         const r = await gs(['set', GNOME_PROXY, 'ignore-hosts', gvariantList(list)]);
         if (!r.ok) throw new Error(`设置绕过列表失败：${r.stderr || r.status}`);
@@ -335,7 +452,20 @@ function linuxProxy(run) {
     return { service: state.service, applied, bypassAdded, state: await read() };
   }
 
-  return { read, setEnabled };
+  /**
+   * 覆盖 ignore-hosts（配置页增删一条自定义项时用）：列表由调用方算好（并集），这里不再合并。
+   * @param {string[]} entries
+   */
+  async function setBypass(entries) {
+    const state = await read();
+    if (!state.supported) throw new Error(state.hint);
+    const list = (entries || []).map((s) => String(s).trim()).filter(Boolean);
+    const r = await gs(['set', GNOME_PROXY, 'ignore-hosts', gvariantList(list)]);
+    if (!r.ok) throw new Error(`设置绕过列表失败：${r.stderr || r.status}`);
+    return { service: state.service, list };
+  }
+
+  return { read, setEnabled, setBypass };
 }
 
 /** 不支持的平台：读返回提示，写直接拒 */
@@ -351,6 +481,9 @@ function unsupportedProxy(platform) {
     async setEnabled() {
       throw new Error(hint);
     },
+    async setBypass() {
+      throw new Error(hint);
+    },
   };
 }
 
@@ -364,7 +497,11 @@ function gvariantList(items) {
 
 /**
  * @param {{ run?: typeof defaultRun, platform?: string }} [options]
- * @returns {{ read: () => Promise<Record<string, any>>, setEnabled: (enabled: boolean, target?: { host?: string, port?: number }) => Promise<{ service: string|null, applied: string[], bypassAdded: string[], state: Record<string, any> }> }}
+ * @returns {{
+ *   read: () => Promise<Record<string, any>>,
+ *   setEnabled: (enabled: boolean, target?: { host?: string, port?: number, bypass?: string[] }) => Promise<{ service: string|null, applied: string[], bypassAdded: string[], state: Record<string, any> }>,
+ *   setBypass: (entries: string[]) => Promise<{ service: string|null, list: string[] }>,
+ * }}
  */
 export function createSystemProxy(options = {}) {
   const run = options.run || defaultRun;