Skip to content

app-user-guide.md

Latest commit

 

History

History
220 lines (172 loc) · 10.8 KB

app-user-guide.md

File metadata and controls

220 lines (172 loc) · 10.8 KB
Raw

OpenSurge for Mac App User Guide

简体中文 · English

This short guide is for people using the packaged OpenSurge for Mac app. It covers installation, source import, gateway startup, and safe network recovery. CLI and development workflows are intentionally left out.

OpenSurge for Mac dashboard

Install and open the app

  1. Download the package for your Mac from GitHub Releases: use arm64-unsigned.pkg on Apple Silicon or x86_64-unsigned.pkg on Intel.
  2. Double-click the package. If macOS blocks it, open System Settings → Privacy & Security and choose Open Anyway for this package. You do not need to disable Gatekeeper globally.
  3. Open OpenSurge from /Applications; the app opens its menu bar status panel directly.
  4. Later, either open OpenSurge again or click its menu bar icon to show the same panel, then choose 打开 OpenSurge 面板 (Open the OpenSurge panel) to launch the Web GUI.

The menu bar app shows status and recovery warnings and opens the Web GUI. Sources, network settings, devices, and policies are managed in the Web GUI.

The menu bar panel automatically checks once for the latest stable release and also provides a manual 检查更新 (Check for Updates) action. When an update is available, 打开下载页 opens that version's GitHub Release page. The app does not download or install the PKG itself; choose the package for the Mac's architecture and follow the installation steps above. Existing configuration and data are preserved without uninstalling first. Prerelease builds display their complete rc.N version. They are not offered an older stable release, while the stable release with the same base version is still detected when it becomes available.

First-time setup

1. Import a source

Open 来源 (Sources) and import either an HTTPS subscription or a local mihomo YAML file:

  1. Select 导入为草稿 (Import as draft).
  2. Confirm that structural validation succeeds.
  3. If the gateway is stopped, select 设为下次启动版本 (Use on next start). If it is running, you can apply the source and reload the gateway.

Importing a draft does not change the current network. Applying a source while the gateway is running validates the full configuration before briefly restarting gateway services.

Each imported-source card shows the local snapshot managed by OpenSurge. You can copy its full path or select Finder 中显示 (Show in Finder) to reveal the file. Do not edit the managed snapshot because its digest, history, and apply state belong to OpenSurge. Select 导出副本 (Export copy) instead: OpenSurge writes a separate 0600 YAML file under ~/Library/Application Support/OpenSurge/exports/, then opens Finder with the new file selected. Refreshing the source does not overwrite exported copies, and an edited copy must be imported as a local file before it becomes a draft.

2. Choose a network mode

Open 网络设置 (Network Settings) and choose the topology that matches your deployment:

Mode Best for Main requirement
Same-LAN DHCP takeover Automatically routing a home LAN through OpenSurge Follow the guided router-DHCP shutdown and recovery flow
Same-LAN manual gateway Trying OpenSurge with a few devices Keep router DHCP enabled and point device gateway/DNS to the Mac
Isolated downstream LAN A separate AP, SSID, or VLAN Let the Mac serve the dedicated downstream network

Set the downstream and upstream interfaces, Mac gateway IPv4, DHCP pool, and upstream DNS. Keep mihomo TUN enabled for transparent proxying. Enable 每设备策略 (Per-device policies) if devices need independent egress choices, then select 保存网络配置 (Save network configuration).

All three topologies expose the two experimental IPv6 settings. IPv6 DNS queries controls AAAA answers, while Downstream IPv6 takeover establishes the userspace TCP/UDP path. Auto takes over only when the upstream has a public IPv6 address (ULA does not count) and an IPv6 default route. Always can establish the downstream path without it, but real public-IPv6 DIRECT traffic still needs an upstream route.

An isolated downstream LAN publishes RA/SLAAC/RDNSS automatically. Same-LAN DHCP takeover can publish them to the whole LAN after main-router IPv6 RA/DHCPv6 is disabled or RA Guard is in place; the page requires an explicit readiness confirmation. OpenSurge uses the normal Medium router preference. Bypass-router mode sends no RA. Its client setup card shows the stable IPv4, IPv6 ULA, and the same Mac link-local address for the default gateway and DNS on selected clients; remove the competing main-router IPv6 default route on those clients.

If SafeDNS, DNS Proxy, content filtering, or another Network Extension causes local-Mac DNS or connectivity failures with TUN alone, enable Mac local system-proxy coordination in the same form. After the gateway is ready, OpenSurge points HTTP and HTTPS proxy settings for the current upstream network service at the local mihomo mixed-port, then restores the pre-start state on stop, startup rollback, or a failed mihomo restart. This option is off by default, requires TUN, and affects only Mac applications that honor system proxy settings; it does not replace TUN or change downstream devices. Startup is rejected when HTTP/HTTPS proxying, PAC, or proxy auto-discovery is already active, rather than overwriting those settings.

3. Start OpenSurge

For Same-LAN DHCP takeover, gateway start and stop are part of the recovery state machine. Follow the steps shown in Network Settings:

  1. Select 保存网络快照与离线恢复卡 to save the network snapshot and offline recovery card.
  2. Switch the Mac to a fixed IPv4 address.
  3. Disable router DHCP when prompted.
  4. Return to OpenSurge and run the DHCP OFFER probe.
  5. After the probe succeeds, select 启动 OpenSurge (Start OpenSurge).
  6. Reconnect a client and complete the DHCP, DNS, and TUN validation step.

Do not quit immediately after disabling router DHCP. OpenSurge keeps the recovery state active until the network has actually been restored.

Everyday use

  • 总览 (Dashboard) shows gateway state, active devices, and the latest 60 seconds of traffic trends.
  • 来源 (Sources) refreshes subscriptions and shows version differences. A refresh creates a draft that still needs to be applied.
  • 设备 (Devices) switches local-Mac Rule / Global / Direct and lets each downstream device follow gateway rules, use an independent egress, or choose IPv4 direct via the main router during DHCP takeover. Those controls do not affect each other. The last mode blocks IPv6 egress for that device when downstream IPv6 is enabled, although the client may retain SLAAC/RDNSS.
  • 策略 (Policies) tests proxy health and switches applied Selectors immediately.
  • 连通性 (Connectivity) shows latency, matched rules, and egress chains through the applied configuration and current local-Mac mode. It does not represent a downstream-device path.
  • 诊断 (Diagnostics) shows recent operations, connections, providers, and redacted logs.

The menu bar panel and Web GUI sidebar both provide 合盖保持运行 (Keep Running with Lid Closed). It is off by default, applies only to the current OpenSurge run, and is independent of gateway state. Quitting OpenSurge or rebooting the Mac releases it. Lid-closed operation increases heat and battery use; never place a running Mac in an unventilated bag.

The local-Mac mode affects only new connections entering OpenSurge through TUN or the local explicit proxy. The mode switch itself does not rewrite macOS system-proxy settings or downstream behavior; the optional network compatibility setting above owns system-proxy coordination. See local Mac routing modes. Green 即时生效 (Applies immediately) controls switch an already-applied egress. Changes to device identity, candidates, or rules must be saved and then applied through a gateway reload.

Proxy health and connectivity tests originate from the gateway Mac. They help confirm that the proxy configuration works, but they do not replace DHCP, DNS, and TUN validation from a downstream device.

Stop and restore the network

For Same-LAN DHCP takeover, stopping the gateway is also part of the recovery state machine:

  1. Complete client validation or explicitly record that it was skipped.
  2. Select 停止 OpenSurge (Stop OpenSurge).
  3. Re-enable router DHCP when prompted.
  4. Return to OpenSurge and run the DHCP OFFER probe.
  5. Restore automatic DHCP on the Mac, or explicitly keep the static IPv4.
  6. Confirm that recovery is complete before quitting OpenSurge.

The menu bar provides two different quit actions:

  • 只退出菜单栏 App (Quit Menu Bar App Only) closes only the menu bar icon. Gateway and background services keep running.
  • 退出 OpenSurge (Quit OpenSurge) is available only after the gateway is stopped and no recovery action remains. It quits the menu bar app and user Control Service.

Uninstall

Select 卸载 OpenSurge… (Uninstall OpenSurge) at the bottom of the menu bar panel. It becomes available whenever the gateway state is stopped. A DHCP takeover recovery reminder or a system IPv4-forwarding setting that was already enabled does not block uninstall and is not changed by the uninstaller.

The confirmation offers two choices:

  • 保留数据并卸载 (Uninstall and Keep Data) removes the app, Control Service, and root Helper while preserving configuration, subscription credentials, and policy data for reinstallation.
  • 彻底卸载 (Uninstall Everything) also deletes configuration, credentials, runtime records, and logs.

macOS asks for administrator authorization. If the gateway is running, first stop it in 网络设置 (Network Settings). Upgrades do not require uninstall; installing a newer package directly preserves existing data.

Common issues

The Web GUI does not open

Select 重新连接 (Reconnect) from the menu bar. This restarts only the user Control Service and does not stop a running gateway data plane.

The start flow cannot continue

Read the blockers in 网络设置 (Network Settings). Check the interfaces, Mac gateway IPv4, protected addresses, and DHCP pool, and make sure all changes are saved.

A device shows no traffic

Generate new traffic from the device and refresh the Dashboard. The UI shows active sessions and the latest 60-second trend, not long-term traffic history.

Network recovery remains incomplete

Open 网络设置 (Network Settings) and continue the recovery flow. A stopped gateway does not by itself mean that router DHCP and the Mac network settings are restored.