my-singbox 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 3.0.0 (unreleased)
+
+### Breaking changes
+
+- ISP exit selection moves from separate SS/VLESS listeners and client nodes into native sing-box `route` rules. Generated configurations always use the two base listeners on 8388 and 8443 and the corresponding two Clash nodes. Client rules, rule providers, and DNS policy keep their existing behavior.
+- `Model.nodes` no longer includes separate ISP nodes, and the `Node.egress` property is removed. Use the independent `Model.isp` outbound settings and server routing policy instead.
+- Remove the obsolete library helpers `addIspToClash`, `clashHasIsp`, `findCleanBackup`, and `IspService.portsFree`. ISP commands no longer inspect or modify client configuration. Call `IspService.verifyService()` without an ISP flag; listener checks come from the actual server config.
+- `isp-outbound --remove` edits the current server configuration and environment rather than restoring a historical clean backup. It preserves unrelated changes made after ISP was enabled. Transaction backups and rollback manage only `config.json` and `.env` by default.
+
+### Migration
+
+Back up existing deployment files before upgrading. Adding or removing ISP migrates recognized legacy server listeners and their dedicated routing rules. When listeners are actually retired, the command reminds you to regenerate `clash.yaml` and close the old 13839/18444 ports. The command leaves the existing client file untouched.
+
+To replace a legacy four-node client config, back it up and move it out of the deployment directory, run `my-singbox conf-clash`, then re-import the resulting two-node configuration. Keep client customizations in the effective template or merge them into the new file. Generation continues to refuse overwriting an existing file. See [ISP routing and migration](docs/ts/isp-outbound.md).
+
+### Routing and compatibility
+
+The server template owns the optional domain rules selecting `isp-socks`, including the intended Anthropic, Claude, and Datadog defaults. With no ISP credentials, generation omits these optional rules and retains sniffing and a default direct exit. Updating ISP credentials preserves existing route matchers and rule order.
+
+The legacy Shell workflow retains its separate-listener behavior. Its base generator omits optional ISP-targeted rules from the shared template so that it does not reference a missing outbound. It preserves sniffing and unrelated native rules.

package/README.md

@@ -6,6 +6,8 @@ Shadowsocks 2022 and VLESS-Reality-Vision nodes with sing-box in Docker; exports
 
 Supported: Debian and Ubuntu VPS only, x64 or arm64.
 
+Version 3.0.0 changes ISP routing and the library API. See the [breaking changes and upgrade steps](CHANGELOG.md) before upgrading an existing deployment.
+
 ```bash
 curl -fsSLo install.sh https://raw.githubusercontent.com/zht7063/my-singbox/ts-version/install.sh
 sh install.sh && export PATH="$HOME/.local/node/bin:$PATH"
@@ -50,7 +52,11 @@ npx my-singbox isp-outbound --add
 npx my-singbox isp-outbound --remove
 ```
 
-Add an ISP SOCKS5 outbound (it asks for the proxy address and credentials) or remove it. Without an action, the command shows a menu; `--yes` or `-y` skips restart confirmation, and `--help` shows options. Add creates `shadowsocks-isp` on 13839 TCP/UDP and `vless-reality-isp` on 18444 TCP, adding them to `clash.yaml` when it exists. Re-import it in the client. The command saves backups in `.isp-backup`; removal restores a pre-ISP backup, so later edits to managed files are not retained in the restored files. It does not change firewall rules.
+Add or update an ISP SOCKS5 outbound (the command asks for its address and credentials), or remove it. Without an action, the command shows a menu; `--yes` or `-y` skips restart confirmation, and `--help` shows options.
+
+Clash keeps its existing rules, rule providers, and DNS settings: it chooses whether traffic goes directly from the client or enters the VPS. The server's `config.json` independently chooses the VPS's outbound. With ISP configured, sing-box sniffs traffic, sends the template's selected domains through `isp-socks`, and sends other traffic through `direct`. Without ISP, the optional ISP rules are omitted and the final outbound remains `direct`. Both modes use the same two base inbounds and client nodes on ports 8388 and 8443; ISP adds no listening ports or client nodes.
+
+Add and remove manage only `config.json` and `.env`, including backups and failure rollback; they never read or write `clash.yaml`. Removal edits the current config, preserving unrelated routes and later customizations, and does not require a pre-ISP backup. Existing ISP route conditions are preserved when updating credentials. See [ISP routing and migration](docs/ts/isp-outbound.md) for the default domains, custom route ordering, and legacy configuration migration.
 
 ### doctor
 
@@ -81,7 +87,7 @@ npx my-singbox start
 
 ## Firewall and ports
 
-Open 8388/tcp, 8388/udp, and 8443/tcp in the local firewall and cloud security group. For ISP outbound, also open 13839/tcp, 13839/udp, and 18444/tcp. The tool never changes firewall rules.
+Open 8388/tcp, 8388/udp, and 8443/tcp in the local firewall and cloud security group. ISP outbound uses these same listening ports. The tool never changes firewall rules.
 
 ## Install Docker
 
@@ -112,7 +118,7 @@ Generated `.env`, `config.json`, and `clash.yaml` files use mode 600. They conta
 
 ## Legacy shell version (v1.1.0)
 
-See [v1.1.0](https://github.com/zht7063/my-singbox/releases/tag/v1.1.0) and the [shell-version branch](https://github.com/zht7063/my-singbox/tree/shell-version).
+See [v1.1.0](https://github.com/zht7063/my-singbox/releases/tag/v1.1.0) and the [shell-version branch](https://github.com/zht7063/my-singbox/tree/shell-version). Its ISP workflow uses extra server ports and client nodes; the TypeScript CLI uses independent server routing instead and does not provide the same ISP behavior. Known legacy ISP server inbounds are migrated by their labels. To replace an old four-node client configuration, back up `clash.yaml`, move it aside, run `npx my-singbox conf-clash`, and re-import the generated file. Generation continues to refuse overwriting an existing file; ISP commands do not migrate the client file.
 
 ## For agents
 

package/README_CN.md

@@ -6,6 +6,8 @@
 
 支持：仅限 Debian 和 Ubuntu VPS，x64 或 arm64。
 
+3.0.0 调整了 ISP 路由方式及库 API。升级已有部署前，请阅读[不兼容变更与迁移步骤](CHANGELOG.md)。
+
 ```bash
 curl -fsSLo install.sh https://raw.githubusercontent.com/zht7063/my-singbox/ts-version/install.sh
 sh install.sh && export PATH="$HOME/.local/node/bin:$PATH"
@@ -50,7 +52,11 @@ npx my-singbox isp-outbound --add
 npx my-singbox isp-outbound --remove
 ```
 
-添加 ISP SOCKS5 出站（会询问代理地址和凭据）或移除它。不指定操作时显示菜单；`--yes` 或 `-y` 跳过重启确认，`--help` 显示选项。添加操作创建 13839 TCP/UDP 上的 `shadowsocks-isp` 和 18444 TCP 上的 `vless-reality-isp`，并在 `clash.yaml` 存在时加入其中。请在客户端重新导入该文件。命令将备份保存到 `.isp-backup`；移除时恢复添加 ISP 前的备份，因此受管理文件在此之后的修改不会保留在恢复后的文件中。命令不会修改防火墙规则。
+添加或更新 ISP SOCKS5 出站（会询问代理地址和凭据），或移除它。不指定操作时显示菜单；`--yes` 或 `-y` 跳过重启确认，`--help` 显示选项。
+
+Clash 保留现有规则、规则集和 DNS 设置，决定流量由客户端直连还是进入 VPS。服务端 `config.json` 独立决定 VPS 的出口：配置 ISP 时，sing-box 先嗅探流量，将模板中指定的域名交给 `isp-socks`，其余流量默认走 `direct`；未配置 ISP 时省略可选 ISP 规则，默认出口仍为 `direct`。两种模式都只使用 8388 和 8443 上的两个基础入站及对应客户端节点，ISP 不新增监听端口或客户端节点。
+
+添加和移除只管理 `config.json` 与 `.env`，备份及失败回滚也仅涉及这两个文件，始终不读写 `clash.yaml`。移除直接修改当前配置，保留无关路由和后续自定义修改，无需添加 ISP 前的备份；更新凭据时保留已有 ISP 路由条件。默认域名、自定义路由顺序和旧配置迁移详见 [ISP 路由与迁移说明](docs/ts/isp-outbound.md)。
 
 ### doctor
 
@@ -81,7 +87,7 @@ npx my-singbox start
 
 ## 防火墙和端口
 
-在本机防火墙和云安全组中开放 8388/tcp、8388/udp 和 8443/tcp。使用 ISP 出站时，还需开放 13839/tcp、13839/udp 和 18444/tcp。工具不会修改防火墙规则。
+在本机防火墙和云安全组中开放 8388/tcp、8388/udp 和 8443/tcp。ISP 出站使用相同的监听端口。工具不会修改防火墙规则。
 
 ## 安装 Docker
 
@@ -112,7 +118,7 @@ sudo usermod -aG docker "$USER"
 
 ## 旧版 shell（v1.1.0）
 
-参见 [v1.1.0](https://github.com/zht7063/my-singbox/releases/tag/v1.1.0) 和 [shell-version 分支](https://github.com/zht7063/my-singbox/tree/shell-version)。
+参见 [v1.1.0](https://github.com/zht7063/my-singbox/releases/tag/v1.1.0) 和 [shell-version 分支](https://github.com/zht7063/my-singbox/tree/shell-version)。旧版 ISP 流程使用额外的服务端端口及客户端节点；TypeScript CLI 改为独立服务端路由，ISP 行为不再与旧版完全相同。服务端按已知标签迁移旧 ISP 入站。若要替换旧四节点客户端配置，请先备份 `clash.yaml`，将原文件移走，再运行 `npx my-singbox conf-clash` 并重新导入客户端。生成器仍拒绝覆盖已有文件，ISP 命令不会迁移客户端文件。
 
 ## 给 agent