diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index f3683b7..f0a586f 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -21,6 +21,7 @@ const guide: Page[] = [ const components: Page[] = [ ['/components/manager', '管理器和命令行', 'The manager and CLI'], + ['/components/app-proxy', '按应用走代理', 'Per-app proxy'], ['/components/bridge', 'arm64 执行桥', 'The arm64 execution bridge'], ['/components/ime', '宿主输入法', 'The host IME'], ] diff --git a/docs/components/app-proxy.md b/docs/components/app-proxy.md new file mode 100644 index 0000000..130be05 --- /dev/null +++ b/docs/components/app-proxy.md @@ -0,0 +1,111 @@ +# 按应用走代理 + +管理器 0.4.0 起，可以让实例里指定的应用（按包名）经这台电脑上的代理软件联网，别的应用照旧直连。比如只让海外服的游戏走代理，国服游戏和系统照常。 + +- 不用 VPN：实例里有一个以 root 运行的小程序（`modavd-proxyd`，随 `modavd.exe` 带着，开机时放进实例），按应用接走名单里应用的 TCP、UDP 和 DNS，应用和系统都看不到 VPN。 +- 代理软件（Clash 系之类）还是要你自己在电脑上开着，ModAVD 只负责把名单里应用的流量送过去。 + +::: warning 代理断了就断网 +代理软件关了或连不上时，名单里的应用**断网**，不会悄悄改走直连。 +::: + +## 要准备什么 + +- 电脑上开着代理软件，最好用它的 SOCKS5 端口或混合端口（Clash 系常见的 7890、7897），TCP、UDP、DNS 都能走。 +- 只有 HTTP 代理也能用，但只转 TCP 和 DNS：名单里应用的 UDP 不通，游戏里的语音、实时对战这类可能用不了。 +- 实例里的 `10.0.2.2` 就是这台电脑的 `127.0.0.1`。代理软件只听本机也行，不用打开「允许局域网连接」。 +- 实例要用管理器或命令行 `modavd` 开机才会挂上代理。不经过 modavd、由别的程序直接拉起的模拟器不会挂上。 + +## 在管理器里设 + +1. 实例卡片右下角的「⋯」→「按应用走代理…」。卡片上已经有「代理」标记时，点标记也能打开。 +2. 打开「名单里的应用走代理」。 +3. 代理地址： + - 点「从系统代理读取」，取这台电脑的代理设置（环境变量 `ALL_PROXY`、`HTTPS_PROXY`、`HTTP_PROXY`，或 Windows「Internet 选项」里手动设的代理）； + - 或者手填 `socks5://127.0.0.1:7890` 这样的地址，不写协议也行，点「检测」看它是什么协议、UDP 能不能用。 + - `127.0.0.1`、`localhost` 会记成实例里看到的 `10.0.2.2`；混合端口写成了 `http://` 时会换成 `socks5://`。换了什么都写在检测结果下面。 +4. 应用名单： + - 实例开着时，列出装了的第三方应用和 Google Play 服务，打勾就行；认得的游戏写中文名。 + - 实例没开时，在下面手填包名（比如 `com.example.game`），回车添加。 + - 名单里有、但实例里还没装的应用标「没装」，装上就生效。名单最多 64 个。 +5. 点「保存」。实例开着就马上生效；没开就下次用管理器或 `modavd` 开机时生效。 + +对话框底下的「现在」一栏写的是保存了的设置现在怎样，和卡片上的标记是同一个意思。 + +::: tip 用 Google 登录的海外游戏 +把「Google Play 服务」（`com.google.android.gms`）也加进名单。名单里没有它时，对话框会提示，点「加进名单」就行。 +::: + +要关掉，取消「名单里的应用走代理」再保存。地址和名单会留着，下次打开不用重填。 + +## 卡片上的「代理」标记 {#mark} + +设置打开、名单不空时，实例卡片的标题旁有「代理」标记，卡片和列表两种视图都有。鼠标停在上面能看到详情，点它打开设置。 + +实例开着时，管理器窗口开着期间大约每 30 秒问一次实例里的状态；开机、关机或改了设置时马上再问。 + +| 颜色 | 意思 | +|---|---| +| 灰 | 实例没开（写着几个应用、走哪个代理，下次开机生效）；正在开机或关机；或者正在问实例里的状态 | +| 绿 | 已生效：几个应用（几个还没装）→ 代理地址。代理不转 UDP 时后面写「UDP 不通」 | +| 黄 | 要留意，名单里的应用多半还能用：规则缺了几条、正在补上；最近一次经代理的连接没成功，但这台电脑能连到代理；这次没问到实例里的状态 | +| 红 | 名单里的应用现在**断网或直连**：代理连不上；实例里的代理程序没在跑；规则挂不上；保存了但没生效 | + +## 命令行 + +```powershell +tools\modavd.exe proxy 3 # 查看 +tools\modavd.exe proxy 3 on --server auto --add com.example.game # 打开，取这台电脑的代理设置 +tools\modavd.exe proxy 3 --add com.google.android.gms # 往名单里加 +tools\modavd.exe proxy 3 test # 在这台电脑上探测代理 +tools\modavd.exe proxy 3 off # 关掉，地址和名单留着 +``` + +- 不带别的参数是查看：开关、地址、名单；实例开着时附上实例里的实际状态（规则在不在、代理连没连上、名单里哪些还没装）。 +- `on` 打开、`off` 关掉；`--server` 改地址，`--add` / `--remove` 增删，`--apps` 整个换掉名单。这几个都能写多次或用逗号隔开，`--apps ""` 清空名单。可以和 `on` 一起给。 +- `--server` 的写法和对话框一样；`auto` 是取这台电脑的代理设置。第一次 `on` 没给地址时也按 `auto`。 +- `test` 在这台电脑上探测设好的代理：是什么协议、经它的 UDP 能不能用。探测不到是退出码 9（`proxy_unavailable`）。 +- 设置存在 `mas-avd.json` 的 `instances..appProxy` 里，删除实例时一起删掉。 +- MCP 里是 `get_app_proxy`、`set_app_proxy` 两个工具。 + +完整的选项和 `--json` 输出见 [ModAVDManager 的 README](https://github.com/ModAVD/ModAVDManager#命令行)。 + +## HTTP 接口 + +管理器页面用的是本机的 HTTP 接口，只听 `127.0.0.1`： + +| 接口 | 做什么 | +|---|---| +| `GET` / `PUT /api/instances/{i}/proxy` | 读、改一台实例的设置；读的时候附上实例里的状态和标记 | +| `GET /api/instances/{i}/packages` | 列出实例里装了的第三方应用和 Google Play 服务（实例要开着） | +| `GET /api/proxy/suggest` | 这台电脑的代理设置，换成实例里看到的地址 | +| `POST /api/proxy/probe` | 在这台电脑上探测一个代理地址 | +| 事件 `proxy` | 各实例的标记有变化时推送 | + +字段、错误码和登录方式见 [API.md](https://github.com/ModAVD/ModAVDManager/blob/main/internal/ui/API.md)。 + +## 常见问题 {#faq} + +### 标记是红的，写着「代理连不上」 + +- 看代理软件开着没有、端口对不对：在对话框里点「检测」，或者跑 `tools\modavd.exe proxy <编号> test`。 +- 这时名单里的应用断网，这是故意的。代理软件恢复以后不用重开实例：名单里的应用下一次连上，标记就变回绿的，在那之前可能是黄的。 + +### 标记是黄的，写着「最近一次经代理的连接没成功」 + +这台电脑能连到代理，只是名单里的应用最近那一次连接没成功。多半是那次要连的服务器没回应，或者代理软件的规则把它拦了。应用能正常用就不用管；一直这样就看代理软件的日志。 + +### 标记是红的，写着代理程序没在跑或者规则挂不上 + +用管理器或 `modavd` 把实例关机再开一次。还是这样就[反馈问题](../guide/feedback)：在实例开着时收集，问题包会收进实例里代理程序的状态和日志。 + +### 游戏还是连不上或者登录不了 + +- 用 Google 登录的：把 Google Play 服务也加进名单。 +- 游戏要用 UDP（语音、实时对战）：换成代理软件的 SOCKS5 或混合端口，别用 HTTP 代理。 +- 名单里的应用没有 IPv6，只走 IPv4。 +- 名单里的应用一直标「没装」：包名可能写错了，或者游戏的包名和你写的不一样。在实例开着时打开对话框，从列出的应用里勾。 + +### 名单外的应用会不会受影响 + +不会，照常直连。 diff --git a/docs/components/manager.md b/docs/components/manager.md index bcb51f2..be7fa78 100644 --- a/docs/components/manager.md +++ b/docs/components/manager.md @@ -13,7 +13,7 @@ ModAVD 0.36.0 起包里带两个管理程序，源码在 [ModAVDManager](https:/ 双击包根的 `ModAVD.exe`：起一个只听 127.0.0.1 的本地服务，再用 Edge 的应用模式开一个窗口（Windows 10 / 11 自带 Edge）；找不到 Edge 时用默认浏览器。页面内嵌在程序里，不联网。 -- 功能：实例卡片（在线时有画面缩略图）、开关机（带进度）、新建、设置、删除、电脑检查、活动面板、画面查看（点击即点按，返回 / 主页 / 最近任务）、日志、安装 APK、打开目录；浅色 / 深色 / 跟随系统。 +- 功能：实例卡片（在线时有画面缩略图）、开关机（带进度）、新建、设置、删除、电脑检查、活动面板、画面查看（点击即点按，返回 / 主页 / 最近任务）、日志、安装 APK、打开目录；浅色 / 深色 / 跟随系统。管理器 0.4.0 起还有[按应用走代理](./app-proxy)。 - 一个根目录只开一个服务，再双击只是把窗口重新打开；日志在 `<根>\logs\modavd-ui.log`。 - 关掉窗口后，等正在跑的任务做完再退出。 @@ -34,6 +34,7 @@ modavd [--root <目录>] [--json] [--quiet] [--verbose] <命令> [参数] | `stop [--force]`、`stop --all` | 关机：先让安卓正常关机，不成再 sync + kill；`--force` 是 sync + 强杀 | | `restart [--window] [--timeout 300] [--force] [--no-bridge]` | 关机再开机 | | `bridge install\|uninstall\|verify` | 装、卸、检查 arm64 执行桥 | +| `proxy [on\|off\|test] [--server URL\|auto] [--add 包名] [--remove 包名] [--apps 包名]` | 管理器 0.4.0 起：[按应用走代理](./app-proxy)，名单里的应用走代理，其余直连 | | `check [--memory M]` | 开机前的电脑检查 | | `window show\|hide`、`install `、`shell <命令>`、`adb -- <参数>` | 窗口、装 APK、客体命令、adb 透传 | | `servers`、`version`、`mcp`、`help [命令]` | | @@ -51,7 +52,7 @@ modavd [--root <目录>] [--json] [--quiet] [--verbose] <命令> [参数] modavd mcp --root D:\ModAVD ``` -工具：`list_instances`、`get_instance`、`check_host`、`create_instance`、`update_instance`、`delete_instance`、`start_instance`（带进度）、`stop_instance`、`set_window_visible`、`shell`、`install_apk`。 +工具：`list_instances`、`get_instance`、`check_host`、`create_instance`、`update_instance`、`delete_instance`、`start_instance`（带进度）、`stop_instance`、`set_window_visible`、`shell`、`install_apk`。管理器 0.4.0 起还有 `get_app_proxy`、`set_app_proxy`（[按应用走代理](./app-proxy)）。 在 Claude Code 里注册（PowerShell 里 `--` 要加引号，否则会被吞掉）： diff --git a/docs/en/components/app-proxy.md b/docs/en/components/app-proxy.md new file mode 100644 index 0000000..379a035 --- /dev/null +++ b/docs/en/components/app-proxy.md @@ -0,0 +1,111 @@ +# Per-app proxy + +Since manager 0.4.0, you can send chosen apps in an instance (by package name) through a proxy program on this computer, while every other app goes direct as before. For example, only the overseas server of a game goes through the proxy, and the domestic games and the system stay as they are. + +- No VPN: a small program in the instance that runs as root (`modavd-proxyd`, carried by `modavd.exe` and put into the instance at boot) takes the TCP, UDP and DNS of the listed apps. Neither the apps nor the system see a VPN. +- You still run the proxy program (a Clash-style one, for example) on your computer yourself; ModAVD only sends the listed apps' traffic to it. + +::: warning No proxy, no network +When the proxy program is closed or cannot be reached, the listed apps **have no network**. They never quietly fall back to direct. +::: + +## What you need + +- A proxy program running on your computer, best through its SOCKS5 port or mixed port (7890 and 7897 are common in Clash-style programs), so TCP, UDP and DNS all go through. +- An HTTP proxy also works, but only carries TCP and DNS: the listed apps' UDP does not work, so in-game voice and real-time matches may fail. +- `10.0.2.2` in the instance is `127.0.0.1` on this computer. The proxy program can listen on the local machine only; you do not need to turn on "allow LAN". +- The instance must be started by the manager or the `modavd` CLI to get the proxy. An emulator that another program starts directly, without modavd, does not get it. + +## Setting it in the manager + +1. On the instance card, click "⋯" at the bottom right, then "按应用走代理…" (per-app proxy). When the card already shows the "代理" mark, clicking the mark opens it too. +2. Turn on "名单里的应用走代理" (the listed apps use the proxy). +3. Proxy address: + - Click "从系统代理读取" (read the system proxy) to take this computer's proxy setting (the environment variables `ALL_PROXY`, `HTTPS_PROXY`, `HTTP_PROXY`, or the proxy set by hand in Windows "Internet Options"); + - or type an address such as `socks5://127.0.0.1:7890` (the protocol can be left out) and click "检测" (probe) to see which protocol it speaks and whether UDP works. + - `127.0.0.1` and `localhost` are stored as `10.0.2.2`, as the instance sees them; a mixed port written as `http://` is changed to `socks5://`. What was changed is shown under the probe result. +4. App list: + - While the instance runs, the installed third-party apps and Google Play services are listed; just tick them. Games the manager knows are shown with their Chinese names. + - While the instance is off, type package names below (such as `com.example.game`) and press Enter to add them. + - Listed apps that are not installed in the instance yet are marked "没装" (not installed); they take effect once installed. The list holds at most 64 apps. +5. Click "保存" (save). A running instance takes it at once; a stopped one at its next boot through the manager or `modavd`. + +The "现在" (now) line at the bottom of the dialog shows what the saved setting does now; it says the same as the mark on the card. + +::: tip Overseas games that sign in with Google +Also list "Google Play 服务" (Google Play services, `com.google.android.gms`). When it is not in the list, the dialog says so; click "加进名单" (add to the list). +::: + +To turn it off, untick "名单里的应用走代理" and save. The address and the list are kept, so you do not need to enter them again next time. + +## The "代理" mark on the card {#mark} + +While the setting is on and the list is not empty, the instance card shows a "代理" (proxy) mark next to its title, in both the card and the list view. Hover over it to see the details; click it to open the setting. + +While the instance runs and the manager window is open, the manager asks the instance for its state about every 30 seconds, and right away after a start, a stop or a change of the setting. + +| Color | Meaning | +|---|---| +| Gray | The instance is off (it shows how many apps go through which proxy from the next boot); it is starting or stopping; or the manager is asking the instance for its state | +| Green | In effect: N apps (M not installed yet) → proxy address. When the proxy does not carry UDP, "UDP 不通" (no UDP) is added | +| Yellow | Worth a look, but the listed apps most likely still work: some rules are missing and being put back; the last connection through the proxy failed, but this computer can reach the proxy; or the state could not be read this time | +| Red | The listed apps have **no network or go direct** right now: the proxy cannot be reached; the proxy program in the instance is not running; the rules cannot be put in place; or the setting was saved but did not take effect | + +## The CLI + +```powershell +tools\modavd.exe proxy 3 # show +tools\modavd.exe proxy 3 on --server auto --add com.example.game # turn on with this computer's proxy setting +tools\modavd.exe proxy 3 --add com.google.android.gms # add to the list +tools\modavd.exe proxy 3 test # probe the proxy from this computer +tools\modavd.exe proxy 3 off # turn off; the address and the list are kept +``` + +- Without other arguments it shows the switch, the address and the list; while the instance runs, it adds the state in the instance (whether the rules are in place, whether the proxy answers, which listed apps are not installed yet). +- `on` turns it on, `off` turns it off; `--server` changes the address, `--add` / `--remove` edit the list, `--apps` replaces it. Each can be given several times or comma-separated; `--apps ""` empties the list. They can be combined with `on`. +- `--server` takes the same addresses as the dialog; `auto` takes this computer's proxy setting. The first `on` without an address also means `auto`. +- `test` probes the configured proxy from this computer: which protocol it speaks and whether UDP works through it. A proxy that cannot be reached is exit code 9 (`proxy_unavailable`). +- The setting is stored in `mas-avd.json` under `instances..appProxy` and goes away with the instance. +- In MCP, the tools are `get_app_proxy` and `set_app_proxy`. + +For every option and the `--json` output, see [the ModAVDManager README](https://github.com/ModAVD/ModAVDManager/blob/main/README.en.md#command-line). + +## The HTTP API + +The manager page uses a local HTTP API that listens only on `127.0.0.1`: + +| Endpoint | What it does | +|---|---| +| `GET` / `PUT /api/instances/{i}/proxy` | Read or change one instance's setting; reading also gives the state in the instance and the mark | +| `GET /api/instances/{i}/packages` | List the third-party apps and Google Play services installed in the instance (it must be running) | +| `GET /api/proxy/suggest` | This computer's proxy setting, as the instance sees the address | +| `POST /api/proxy/probe` | Probe a proxy address from this computer | +| Event `proxy` | Sent when an instance's mark changes | + +For the fields, error codes and how to log in, see [API.md](https://github.com/ModAVD/ModAVDManager/blob/main/internal/ui/API.md) (in Chinese). + +## Common problems {#faq} + +### The mark is red and says the proxy cannot be reached + +- Check that the proxy program is running and the port is right: click "检测" (probe) in the dialog, or run `tools\modavd.exe proxy test`. +- The listed apps have no network meanwhile; that is on purpose. Once the proxy program is back you do not need to restart the instance: the mark turns green after the next connection of a listed app succeeds, and may be yellow until then. + +### The mark is yellow and says the last connection through the proxy failed + +This computer can reach the proxy; only the listed app's last connection failed. Most likely the server it tried did not answer, or a rule in the proxy program blocked it. If the app works, nothing needs to be done; if it stays this way, look at the proxy program's log. + +### The mark is red and says the proxy program is not running or the rules cannot be put in place + +Shut the instance down and start it again with the manager or `modavd`. If it stays this way, [report a problem](../guide/feedback): collect the information while the instance runs, and the package includes the state and the log of the proxy program in the instance. + +### The game still cannot connect or sign in + +- Games that sign in with Google: also list Google Play services. +- Games that use UDP (voice, real-time matches): use the proxy program's SOCKS5 or mixed port, not an HTTP proxy. +- The listed apps get no IPv6; they use IPv4 only. +- An app shown as "没装" (not installed): the package name may be wrong, or the game's package name differs from what you typed. Open the dialog while the instance runs and tick it in the listed apps. + +### Are apps outside the list affected? + +No, they go direct as before. diff --git a/docs/en/components/manager.md b/docs/en/components/manager.md index 0475e6b..63f2ce0 100644 --- a/docs/en/components/manager.md +++ b/docs/en/components/manager.md @@ -13,7 +13,7 @@ Instance files and `mas-avd.json` are written the same way as in AUTO-MAS, so in Double-click `ModAVD.exe` in the package root. It starts a local server that listens only on 127.0.0.1, then opens a window in Edge app mode (Edge comes with Windows 10 / 11); if Edge is not found, it uses the default browser. The page is embedded in the program and does not use the network. -- Features: instance cards (with a screen thumbnail when the instance is online), start and stop (with progress), create, settings, delete, PC check, activity panel, screen view (a click is a tap; Back / Home / Recents), logs, install APK, open folder; light / dark / follow system. +- Features: instance cards (with a screen thumbnail when the instance is online), start and stop (with progress), create, settings, delete, PC check, activity panel, screen view (a click is a tap; Back / Home / Recents), logs, install APK, open folder; light / dark / follow system. Since manager 0.4.0 there is also the [per-app proxy](./app-proxy). - One server runs per root folder; double-clicking again only reopens the window. The log is at `\logs\modavd-ui.log`. - After you close the window, it waits for the running tasks to finish before it exits. @@ -34,6 +34,7 @@ modavd [--root ] [--json] [--quiet] [--verbose] [args] | `stop [--force]`, `stop --all` | Shut down: first ask Android for a clean shutdown; if that fails, sync + kill. `--force` is sync + force-kill | | `restart [--window] [--timeout 300] [--force] [--no-bridge]` | Shut down, then start | | `bridge install\|uninstall\|verify` | Install, uninstall or check the arm64 execution bridge | +| `proxy [on\|off\|test] [--server URL\|auto] [--add pkg] [--remove pkg] [--apps pkg]` | Since manager 0.4.0: the [per-app proxy](./app-proxy); the listed apps use the proxy, the others go direct | | `check [--memory M]` | PC check before starting | | `window show\|hide`, `install `, `shell `, `adb -- ` | Window, install an APK, guest command, adb passthrough | | `servers`, `version`, `mcp`, `help [command]` | | @@ -51,7 +52,7 @@ For machine-readable output (`--json`), exit codes and the full option reference modavd mcp --root D:\ModAVD ``` -Tools: `list_instances`, `get_instance`, `check_host`, `create_instance`, `update_instance`, `delete_instance`, `start_instance` (with progress), `stop_instance`, `set_window_visible`, `shell`, `install_apk`. +Tools: `list_instances`, `get_instance`, `check_host`, `create_instance`, `update_instance`, `delete_instance`, `start_instance` (with progress), `stop_instance`, `set_window_visible`, `shell`, `install_apk`. Since manager 0.4.0 also `get_app_proxy` and `set_app_proxy` (the [per-app proxy](./app-proxy)). To register it in Claude Code (in PowerShell, `--` must be quoted, or it gets swallowed):