@qpjoy/tunnel-cli 0.1.9 → 0.1.10

package/README.md

@@ -23,6 +23,8 @@ server, enroll into the HDO mesh without installing Electron:
 npm i -g @qpjoy/tunnel-cli
 HDO_PASSWORD='<password>' qp-tunnel-cli hdo enroll \
   --server-url 'https://domestic.example.com' \
+  --internal-url 'http://127.0.0.1:18090' \
+  --product-id h2o \
   --username 'internal-i' \
   --device-id internal-i \
   --label 'Internal I'
@@ -40,6 +42,8 @@ HDO_PASSWORD='<password>' sudo -E qp-tunnel-cli hdo enroll \
 The command:
 
 - logs in with username/password, or uses `--token` when provided
+- requests an MX Launcher Internal product lease when `--internal-url` is set
+- uses that lease as the WireGuard client address and adds the product route CIDR
 - uses `@qpjoy/electron-core-wireguard` to find/install the platform WireGuard engine
 - registers the machine as an HDO device
 - downloads the HDO manifest from `electron-server`
@@ -49,6 +53,22 @@ The command:
   installed by the OS, the CLI writes a compatible systemd unit that uses the
   bundled WireGuard tools from the npm package.
 
+To test the new Internal allocator without applying WireGuard yet, run lease-only
+mode. If `--server-url` is omitted and `--internal-url` is present, the command
+automatically behaves as lease-only:
+
+```bash
+qp-tunnel-cli hdo enroll \
+  --internal-url 'http://127.0.0.1:18090' \
+  --product-id h2o \
+  --identity-kind anonymous \
+  --lease-only
+```
+
+For H2O, Internal assigns logged-in users from `10.90.0.1-10.90.99.254` and
+anonymous users from `10.90.100.1-10.90.254.254`, based on the Product Network
+Registry.
+
 Useful follow-up commands:
 
 ```bash
@@ -81,16 +101,25 @@ Run commands directly through the bundled script:
 
 ```bash
 qp-tunnel-cli status
-qp-tunnel-cli server-on
+qp-tunnel-cli egress-on
 qp-tunnel-cli update-subscription
 ```
 
 For server commands, `qp-tunnel-cli` re-runs itself with `sudo` when root is needed.
-Use `server-on` for public VPS hosts: it keeps Mihomo running as a local outbound
+Use `egress-on` for public VPS hosts: it keeps Mihomo running as a local outbound
 proxy and configures shell, SSH, Docker/containerd/buildkit proxy drop-ins without
 enabling TUN route takeover. Reserve `tun-on` for machines that are not serving
 public inbound traffic.
 
+Domestic bootstrap can install from an Internal-pushed subscription file before
+the WG relay can reach Internal:
+
+```bash
+sudo qp-tunnel-cli install \
+  --file /opt/mx/current/qp-tunnel-cli/domestic-bootstrap-subscription.yaml
+sudo qp-tunnel-cli egress-on
+```
+
 Run any command through the active Mihomo local proxy:
 
 ```bash
@@ -109,7 +138,7 @@ Install the bundled script as a normal Linux command:
 sudo qp-tunnel-cli install-script
 sudo qp-tunnel-cli upgrade-systemd
 sudo mihomo-client status
-sudo mihomo-client server-on
+sudo mihomo-client egress-on
 ```
 
 Use a custom target when needed:

package/README.setup.md

@@ -1,15 +1,18 @@
 ```bash
-npm i -g @qpjoy/tunnel-cli@0.1.4
-HDO_PASSWORD='...' qp-tunnel-cli hdo enroll --server-url 'https://domestic.example.com' --username internal-i
+npm i -g @qpjoy/tunnel-cli@0.1.9
+qp-tunnel-cli hdo enroll --internal-url 'http://127.0.0.1:18090' --product-id h2o --identity-kind anonymous --lease-only
+HDO_PASSWORD='...' qp-tunnel-cli hdo enroll --server-url 'https://domestic.example.com' --internal-url 'http://127.0.0.1:18090' --product-id h2o --username internal-i
 
 qp-tunnel-cli install --url 'http://user:pass@host:3434/peer_xxx.mihomo.yaml'
+# Domestic bootstrap can use an Internal-pushed local YAML before WG relay reaches Internal.
+qp-tunnel-cli install --file '/opt/mx/current/qp-tunnel-cli/domestic-bootstrap-subscription.yaml'
 
 sudo qp-tunnel-cli install-script
 sudo qp-tunnel-cli upgrade-systemd
-sudo qp-tunnel-cli server-on
+sudo qp-tunnel-cli egress-on
 
 sudo qp-tunnel-cli tun-off
-sudo qp-tunnel-cli server-on
+sudo qp-tunnel-cli egress-on
 sudo qp-tunnel-cli status
 
 qp-tunnel-cli curl google.com

package/dist/hdo.js

@@ -46,6 +46,11 @@ Usage:
 
 Enroll options:
   --server-url URL       HDO/electron-server base URL
+  --internal-url URL     MX Launcher Internal URL for product IP lease allocation
+  --product-id ID        Product network id. Default: h2o
+  --mode MODE            Launcher mode: embed or standalone
+  --identity-kind KIND   user or anonymous. Default: user when --username is set, else anonymous
+  --lease-only           Only request/store the Internal lease; skip legacy HDO manifest/WireGuard apply
   --username USER        Login username/email/phone
   --password PASS        Login password. Prefer HDO_PASSWORD or --password-file
   --password-file PATH   Read login password from a file
@@ -69,6 +74,8 @@ Enroll options:
 
 Environment:
   HDO_SERVER_URL / QPJOY_HDO_SERVER_URL
+  HDO_INTERNAL_URL / QPJOY_HDO_INTERNAL_URL / MX_INTERNAL_URL
+  HDO_PRODUCT_ID / QPJOY_HDO_PRODUCT_ID
   HDO_USERNAME / QPJOY_HDO_USERNAME
   HDO_PASSWORD / QPJOY_HDO_PASSWORD
   HDO_TOKEN / QPJOY_HDO_TOKEN
@@ -109,20 +116,87 @@ async function enrollCommand(args, refreshOnly) {
         process.env.HDO_SERVER_URL ??
         process.env.QPJOY_HDO_SERVER_URL ??
         previous.serverUrl);
+    const internalUrl = normalizeBaseUrl(options.internalUrl ??
+        process.env.HDO_INTERNAL_URL ??
+        process.env.QPJOY_HDO_INTERNAL_URL ??
+        process.env.MX_INTERNAL_URL ??
+        previous.internalUrl);
     const username = options.username ??
         process.env.HDO_USERNAME ??
         process.env.QPJOY_HDO_USERNAME ??
         previous.username;
-    if (!serverUrl) {
-        throw new Error('Missing --server-url or HDO_SERVER_URL.');
+    const productId = sanitizeId(options.productId ??
+        process.env.HDO_PRODUCT_ID ??
+        process.env.QPJOY_HDO_PRODUCT_ID ??
+        previous.productId ??
+        'h2o');
+    const launcherMode = options.mode ?? previous.launcherMode ?? (productId === 'launcher' ? 'standalone' : 'embed');
+    const identityKind = options.identityKind ?? previous.identityKind ?? (username ? 'user' : 'anonymous');
+    const leaseOnly = Boolean(options.leaseOnly || (internalUrl && !serverUrl));
+    if (!serverUrl && !leaseOnly) {
+        throw new Error('Missing --server-url/HDO_SERVER_URL or use --internal-url with --lease-only.');
     }
-    const auth = await resolveAuth(serverUrl, options, previous, username);
     const deviceId = options.deviceId ||
         previous.deviceId ||
         `hdo-${process.platform}-${sanitizeId((0, node_os_1.hostname)())}`;
     const label = options.label || previous.label || `${process.platform} ${(0, node_os_1.hostname)()}`;
     const keys = resolveKeypair(options, previous, installDir);
     const direct = resolveDirectEndpoint(options, previous);
+    const launcherNetworkLease = internalUrl
+        ? await enrollLauncherNetworkLease(internalUrl, {
+            productId,
+            mode: launcherMode,
+            identityKind,
+            installId: deviceId,
+            deviceId,
+            siteId: previous.launcherNetworkLease?.siteId,
+            userId: identityKind === 'user' ? username : undefined,
+            publicKey: keys.publicKey,
+            deviceLabel: label,
+            platform: `${process.platform}-${process.arch}`,
+            requestedBy: '@qpjoy/tunnel-cli',
+            requestId: `qp-tunnel-cli-hdo-enroll-${Date.now()}`,
+        })
+        : undefined;
+    if (leaseOnly) {
+        const now = new Date().toISOString();
+        writeState(stateFile, {
+            ...previous,
+            internalUrl,
+            productId,
+            launcherMode,
+            identityKind,
+            username,
+            deviceId,
+            label,
+            interfaceName,
+            configPath,
+            installDir,
+            privateKey: keys.privateKey,
+            publicKey: keys.publicKey,
+            overlayIp: launcherNetworkLease?.leaseIp ?? previous.overlayIp,
+            launcherNetworkLease: launcherNetworkLease ?? previous.launcherNetworkLease,
+            enrolledAt: previous.enrolledAt || now,
+            updatedAt: now,
+        });
+        process.stdout.write([
+            refreshOnly ? 'HDO Internal lease refreshed.' : 'HDO Internal lease enrolled.',
+            `Product: ${productId}`,
+            `Mode: ${launcherMode}`,
+            `Identity: ${identityKind}`,
+            `Device: ${deviceId}`,
+            `Lease IP: ${launcherNetworkLease?.leaseIp ?? previous.overlayIp ?? 'unassigned'}`,
+            `Lease CIDR: ${launcherNetworkLease?.cidr ?? 'unassigned'}`,
+            `State file: ${stateFile}`,
+            'System tunnel not started (lease-only).',
+            '',
+        ].join('\n'));
+        return;
+    }
+    if (!serverUrl) {
+        throw new Error('Missing --server-url or HDO_SERVER_URL.');
+    }
+    const auth = await resolveAuth(serverUrl, options, previous, username);
     const registered = await apiJson(serverUrl, auth.accessToken, '/api/v1/hdo/devices/register', {
         method: 'POST',
         body: {
@@ -154,6 +228,8 @@ async function enrollCommand(args, refreshOnly) {
     });
     const runtime = hdoRuntimeFromManifest(manifest, registered, keys.privateKey, {
         allowEndpointlessDirectPeers: direct.directListener,
+        launcherNetworkLease,
+        ownPublicKey: keys.publicKey,
     });
     writeWireGuardConfig(configPath, (0, electron_core_wireguard_1.renderHdoClientWireGuardConfig)({
         privateKey: runtime.privateKey,
@@ -168,11 +244,15 @@ async function enrollCommand(args, refreshOnly) {
     const now = new Date().toISOString();
     writeState(stateFile, {
         serverUrl,
+        internalUrl,
         bearerToken: auth.accessToken,
         refreshToken: auth.refreshToken,
         accessExpiresAt: auth.accessExpiresAt,
         refreshExpiresAt: auth.refreshExpiresAt,
         username: auth.username ?? username,
+        productId,
+        launcherMode,
+        identityKind,
         deviceId,
         label,
         interfaceName,
@@ -181,6 +261,7 @@ async function enrollCommand(args, refreshOnly) {
         privateKey: keys.privateKey,
         publicKey: keys.publicKey,
         overlayIp: runtime.overlayIp,
+        launcherNetworkLease: launcherNetworkLease ?? previous.launcherNetworkLease,
         directListener: direct.directListener,
         preferDirectPeers: direct.preferDirectPeers,
         endpointHost: direct.endpointHost,
@@ -215,8 +296,13 @@ function statusCommand(input) {
     });
     process.stdout.write(`State file: ${stateFile}\n`);
     process.stdout.write(`Server URL: ${state.serverUrl || 'unset'}\n`);
+    process.stdout.write(`Internal URL: ${state.internalUrl || 'unset'}\n`);
+    process.stdout.write(`Product: ${state.productId || 'unset'} (${state.launcherMode || 'unset'} / ${state.identityKind || 'unset'})\n`);
     process.stdout.write(`Device: ${state.deviceId || 'unset'}\n`);
     process.stdout.write(`Overlay IP: ${state.overlayIp || 'unset'}\n`);
+    if (state.launcherNetworkLease) {
+        process.stdout.write(`Internal lease: ${state.launcherNetworkLease.leaseIp} ${state.launcherNetworkLease.cidr} (${state.launcherNetworkLease.leaseId})\n`);
+    }
     process.stdout.write(`WireGuard config: ${configPath}\n\n`);
     if (process.platform === 'linux') {
         if (commandAvailable('systemctl')) {
@@ -296,6 +382,7 @@ function parseEnrollOptions(args) {
         interfaceName: defaultInterfaceName,
         role: 'internal',
         start: true,
+        leaseOnly: false,
         rotateKey: false,
         directListener: false,
         preferDirectPeers: false,
@@ -313,6 +400,39 @@ function parseEnrollOptions(args) {
             case '--server-url':
                 options.serverUrl = readValue();
                 break;
+            case '--internal-url':
+            case '--mx-internal-url':
+                options.internalUrl = readValue();
+                break;
+            case '--product-id':
+            case '--app-id':
+                options.productId = readValue();
+                break;
+            case '--mode': {
+                const value = readValue();
+                if (value !== 'standalone' && value !== 'embed')
+                    throw new Error(`Invalid --mode: ${value}`);
+                options.mode = value;
+                break;
+            }
+            case '--identity-kind': {
+                const value = readValue();
+                if (value !== 'user' && value !== 'anonymous')
+                    throw new Error(`Invalid --identity-kind: ${value}`);
+                options.identityKind = value;
+                break;
+            }
+            case '--anonymous':
+                options.identityKind = 'anonymous';
+                break;
+            case '--user-identity':
+            case '--employee':
+                options.identityKind = 'user';
+                break;
+            case '--lease-only':
+                options.leaseOnly = true;
+                options.start = false;
+                break;
             case '--token':
                 options.token = readValue();
                 break;
@@ -498,6 +618,68 @@ async function refreshAuth(serverUrl, refreshToken, username) {
         username,
     };
 }
+async function enrollLauncherNetworkLease(internalUrl, input) {
+    const raw = await apiJson(internalUrl, '', '/internal/v1/launcher-network/enrollments', {
+        method: 'POST',
+        auth: false,
+        body: input,
+    });
+    const root = requireRecord(raw, 'launcher network enroll response');
+    const lease = requireRecord(root.lease, 'launcher network lease');
+    return parseLauncherNetworkLease(lease);
+}
+function parseLauncherNetworkLease(lease) {
+    const leaseId = stringField(lease.leaseId);
+    const productId = stringField(lease.productId);
+    const launcherMode = stringField(lease.launcherMode);
+    const identityKind = stringField(lease.identityKind);
+    const installId = stringField(lease.installId);
+    const deviceId = stringField(lease.deviceId);
+    const siteId = stringField(lease.siteId);
+    const cidr = stringField(lease.cidr);
+    const leaseIp = stringField(lease.leaseIp);
+    if (!leaseId || !productId || !installId || !deviceId || !siteId || !cidr || !leaseIp) {
+        throw new Error('Launcher Network lease response is missing required fields.');
+    }
+    if (launcherMode !== 'standalone' && launcherMode !== 'embed') {
+        throw new Error(`Launcher Network lease response has invalid launcherMode: ${launcherMode ?? 'missing'}`);
+    }
+    if (identityKind !== 'user' && identityKind !== 'anonymous') {
+        throw new Error(`Launcher Network lease response has invalid identityKind: ${identityKind ?? 'missing'}`);
+    }
+    return {
+        leaseId,
+        leaseKey: stringField(lease.leaseKey) ?? undefined,
+        productId,
+        launcherMode,
+        identityKind,
+        sequence: numberField(lease.sequence),
+        installId,
+        deviceId,
+        siteId,
+        userId: stringField(lease.userId),
+        cidr,
+        leaseIp,
+        serviceVip: stringField(lease.serviceVip) ?? undefined,
+        internalControlIp: stringField(lease.internalControlIp) ?? undefined,
+        domesticGatewayIp: stringField(lease.domesticGatewayIp) ?? undefined,
+        domesticSiteId: stringField(lease.domesticSiteId) ?? undefined,
+        overseaSiteId: stringField(lease.overseaSiteId) ?? undefined,
+        publicKey: stringField(lease.publicKey),
+        status: stringField(lease.status) ?? undefined,
+        updatedAt: stringField(lease.updatedAt) ?? undefined,
+    };
+}
+function allowedIpsFromLauncherNetworkLease(lease) {
+    if (!lease)
+        return [];
+    return uniqueStrings([
+        lease.cidr,
+        lease.serviceVip ? `${lease.serviceVip}/32` : '',
+        lease.internalControlIp ? `${lease.internalControlIp}/32` : '',
+        lease.domesticGatewayIp ? `${lease.domesticGatewayIp}/32` : '',
+    ]).filter((value) => value.includes('/'));
+}
 function resolveKeypair(options, previous, installDir) {
     if (!options.rotateKey && previous.privateKey && previous.publicKey) {
         return { privateKey: previous.privateKey, publicKey: previous.publicKey };
@@ -550,6 +732,8 @@ function directPeersFromManifest(wireGuard, ownOverlayIp, options = {}) {
         const overlayIp = stringField(row.overlayIp);
         if (!publicKey || !overlayIp || overlayIp === ownIp)
             return [];
+        if (options.ownPublicKey && publicKey === options.ownPublicKey)
+            return [];
         const allowedIps = stringArray(row.allowedIps);
         const endpoint = stringField(row.endpoint);
         if (!endpoint && options.allowEndpointlessDirectPeers !== true)
@@ -625,8 +809,9 @@ function hdoRuntimeFromManifest(manifest, registered, privateKey, options = {})
     const wireGuard = requireRecord(root.wireGuard, 'manifest.wireGuard');
     const client = requireRecord(wireGuard.client, 'manifest.wireGuard.client');
     const domestic = requireRecord(wireGuard.domestic, 'manifest.wireGuard.domestic');
-    const overlayIp = stringField(client.overlayIp) ||
+    const manifestOverlayIp = stringField(client.overlayIp) ||
         stringField(requireRecord(registered, 'registered device').overlayIp);
+    const overlayIp = options.launcherNetworkLease?.leaseIp || manifestOverlayIp;
     const domesticPublicKey = stringField(domestic.publicKey);
     const domesticEndpoint = stringField(domestic.endpoint);
     if (!overlayIp)
@@ -638,6 +823,7 @@ function hdoRuntimeFromManifest(manifest, registered, privateKey, options = {})
     const domesticOverlay = stringField(domestic.overlayIp);
     const allowedIps = uniqueStrings([
         ...routeCidrs,
+        ...allowedIpsFromLauncherNetworkLease(options.launcherNetworkLease),
         ...(domesticOverlay ? [`${domesticOverlay}/32`] : []),
     ]).filter((value) => value.includes('/'));
     if (allowedIps.length === 0) {

package/dist/index.js

@@ -91,9 +91,10 @@ Usage:
 
 Common commands:
   qp-tunnel-cli install --url http://IP:3434/peer_user01.mihomo.yaml --user download --password pass
+  qp-tunnel-cli install --file /opt/mx/current/qp-tunnel-cli/domestic-bootstrap-subscription.yaml
   qp-tunnel-cli status
   qp-tunnel-cli start
-  qp-tunnel-cli server-on
+  qp-tunnel-cli egress-on
   qp-tunnel-cli tun-on
   qp-tunnel-cli tun-off
   qp-tunnel-cli update-subscription
@@ -113,6 +114,7 @@ QP_TUNNEL_CONTAINER_HTTP_PROXY=http://host.docker.internal:<mixed-port>.
 Install the script as a normal server command:
   sudo qp-tunnel-cli install-script
   sudo mihomo-client status
+  sudo mihomo-client egress-on
 
 Enroll this machine into an HDO mesh:
   HDO_PASSWORD=... qp-tunnel-cli hdo enroll --server-url https://domestic.example.com --username user
@@ -185,7 +187,7 @@ function mixedPortFromConfig() {
     }
     const configFile = process.env.MIHOMO_CONFIG_FILE || defaultMihomoConfigFile;
     if (!(0, node_fs_1.existsSync)(configFile)) {
-        process.stderr.write(`Mihomo config not found: ${configFile}\nRun: sudo qp-tunnel-cli install ... && sudo qp-tunnel-cli server-on\n`);
+        process.stderr.write(`Mihomo config not found: ${configFile}\nRun: sudo qp-tunnel-cli install ... && sudo qp-tunnel-cli egress-on\n`);
         process.exit(1);
     }
     const content = (0, node_fs_1.readFileSync)(configFile, 'utf8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qpjoy/tunnel-cli",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Global QPJoy Tunnel CLI for mihomo-client and cross-platform HDO mesh enrollment.",
   "private": false,
   "type": "commonjs",

package/resources/mihomo-client.sh

@@ -45,8 +45,8 @@ Commands:
   upgrade-systemd      Refresh the installed systemd unit from this script
   server-on            Enable persistent server-safe outbound proxy mode, without TUN
   server-off           Disable server-safe proxy integrations, keeping the service installed
-  egress-on            Alias for server-on
-  egress-off           Alias for server-off
+  egress-on            Preferred server-safe outbound proxy mode for Domestic bootstrap
+  egress-off           Disable server-safe outbound proxy integrations
   proxy-on             Write /etc/profile.d proxy exports for login shells
   proxy-off            Remove /etc/profile.d proxy exports
   tun-on               Enable persistent Mihomo TUN mode with cn-direct and local/private route bypasses
@@ -65,6 +65,7 @@ Commands:
 
 Install options:
   --url URL            Subscription URL, e.g. http://IP:3434/peer_user01.mihomo.yaml
+  --file FILE          Local subscription YAML file, for Internal-pushed bootstrap
   --user USER          Basic Auth username for subscription
   --password PASS      Basic Auth password for subscription
   --version TAG        Mihomo version tag. Default: latest stable release
@@ -73,6 +74,7 @@ Install options:
 
 Update options:
   --url URL            Override saved subscription URL
+  --file FILE          Replace subscription from a local YAML file
   --user USER          Override saved subscription username
   --password PASS      Override saved subscription password
 
@@ -89,9 +91,13 @@ Examples:
     --url http://IP:3434/peer_user01.mihomo.yaml \
     --binary-path /tmp/mihomo
 
+  sudo bash ./scripts/mihomo-client.sh install \
+    --file /opt/mx/current/qp-tunnel-cli/domestic-bootstrap-subscription.yaml
+
   sudo bash ./scripts/mihomo-client.sh update-subscription
+  sudo bash ./scripts/mihomo-client.sh update-subscription --file /opt/mx/current/qp-tunnel-cli/domestic-bootstrap-subscription.yaml
   sudo bash ./scripts/mihomo-client.sh start
-  sudo bash ./scripts/mihomo-client.sh server-on
+  sudo bash ./scripts/mihomo-client.sh egress-on
   sudo bash ./scripts/mihomo-client.sh proxy-on
   sudo bash ./scripts/mihomo-client.sh tun-on
   sudo bash ./scripts/mihomo-client.sh ssh-proxy-on
@@ -575,6 +581,20 @@ fetch_subscription() {
 	render_runtime_config
 }
 
+install_subscription_file() {
+	local file_path="$1"
+
+	[[ -n "$file_path" ]] || die "Subscription file is required."
+	[[ -f "$file_path" ]] || die "Subscription file not found: $file_path"
+	[[ -s "$file_path" ]] || die "Subscription file is empty: $file_path"
+
+	ensure_dirs
+	log "Installing local subscription file: $file_path"
+	cp "$file_path" "$MIHOMO_SUBSCRIPTION_FILE"
+	chmod 600 "$MIHOMO_SUBSCRIPTION_FILE"
+	render_runtime_config
+}
+
 mixed_port_from_config() {
 	if [[ -f "$MIHOMO_CONFIG_FILE" ]]; then
 		awk -F: '/^[[:space:]]*mixed-port[[:space:]]*:/ {gsub(/[[:space:]]/, "", $2); print $2; exit}' "$MIHOMO_CONFIG_FILE"
@@ -682,10 +702,29 @@ update_subscription_command() {
 	local url="${1:-}"
 	local username="${2:-}"
 	local password="${3:-}"
+	local file_path="${4:-}"
 	local -a normalized=()
 
 	load_env
 
+	if [[ -n "$file_path" ]]; then
+		install_subscription_file "$file_path"
+		set_env_value MIHOMO_SUBSCRIPTION_SOURCE "local-file"
+		set_env_value MIHOMO_SUBSCRIPTION_LOCAL_FILE "$file_path"
+		set_env_value MIHOMO_SUBSCRIPTION_URL ""
+		set_env_value MIHOMO_SUBSCRIPTION_USER ""
+		set_env_value MIHOMO_SUBSCRIPTION_PASSWORD ""
+
+		if service_is_active; then
+			log "Restarting Mihomo service after local subscription update"
+			systemctl restart "$MIHOMO_SERVICE_NAME"
+			echo "Subscription updated from local file and service restarted."
+		else
+			echo "Subscription updated from local file."
+		fi
+		return
+	fi
+
 	url="${url:-${MIHOMO_SUBSCRIPTION_URL:-}}"
 	username="${username:-${MIHOMO_SUBSCRIPTION_USER:-}}"
 	password="${password:-${MIHOMO_SUBSCRIPTION_PASSWORD:-}}"
@@ -697,6 +736,8 @@ update_subscription_command() {
 	[[ -n "$url" ]] || die "No subscription URL configured. Use install or pass --url."
 
 	fetch_subscription "$url" "$username" "$password"
+	set_env_value MIHOMO_SUBSCRIPTION_SOURCE "url"
+	set_env_value MIHOMO_SUBSCRIPTION_LOCAL_FILE ""
 	set_env_value MIHOMO_SUBSCRIPTION_URL "$url"
 	set_env_value MIHOMO_SUBSCRIPTION_USER "$username"
 	set_env_value MIHOMO_SUBSCRIPTION_PASSWORD "$password"
@@ -941,24 +982,27 @@ install_command() {
 	local version="${4:-latest}"
 	local autostart="${5:-true}"
 	local binary_path="${6:-}"
+	local file_path="${7:-}"
 	local -a normalized=()
 
 	ensure_dirs
 	load_env
 	log "Starting Mihomo client install/setup"
 
-	if [[ -z "$url" ]]; then
+	if [[ -z "$file_path" && -z "$url" ]]; then
 		url="$(prompt_default "Subscription URL" "${MIHOMO_SUBSCRIPTION_URL:-}")"
 	fi
-	mapfile -t normalized < <(normalize_subscription_inputs "$url" "$username" "$password")
-	url="${normalized[0]}"
-	username="${normalized[1]}"
-	password="${normalized[2]}"
-	if [[ -z "$username" ]]; then
-		username="$(prompt_default "Subscription username (empty if none)" "${MIHOMO_SUBSCRIPTION_USER:-}")"
-	fi
-	if [[ -z "$password" ]]; then
-		password="$(prompt_password "Subscription password (empty if none)")"
+	if [[ -z "$file_path" ]]; then
+		mapfile -t normalized < <(normalize_subscription_inputs "$url" "$username" "$password")
+		url="${normalized[0]}"
+		username="${normalized[1]}"
+		password="${normalized[2]}"
+		if [[ -z "$username" ]]; then
+			username="$(prompt_default "Subscription username (empty if none)" "${MIHOMO_SUBSCRIPTION_USER:-}")"
+		fi
+		if [[ -z "$password" ]]; then
+			password="$(prompt_password "Subscription password (empty if none)")"
+		fi
 	fi
 
 	if [[ -n "$binary_path" ]]; then
@@ -978,8 +1022,8 @@ install_command() {
 	set_env_value MIHOMO_SUBSCRIPTION_USER "$username"
 	set_env_value MIHOMO_SUBSCRIPTION_PASSWORD "$password"
 
-	log "Downloading initial subscription and rendering runtime config"
-	update_subscription_command "$url" "$username" "$password"
+	log "Installing initial subscription and rendering runtime config"
+	update_subscription_command "$url" "$username" "$password" "$file_path"
 
 	systemctl enable "$MIHOMO_SERVICE_NAME" >/dev/null 2>&1 || true
 	if [[ "$autostart" == "true" ]]; then
@@ -1080,9 +1124,11 @@ main() {
 			local version="latest"
 			local autostart="true"
 			local binary_path=""
+			local file_path=""
 			while [[ $# -gt 0 ]]; do
 				case "$1" in
 					--url) url="$2"; shift 2 ;;
+					--file) file_path="$2"; shift 2 ;;
 					--user) username="$2"; shift 2 ;;
 					--password) password="$2"; shift 2 ;;
 					--version) version="$2"; shift 2 ;;
@@ -1091,21 +1137,23 @@ main() {
 					*) die "Unknown install option: $1" ;;
 				esac
 			done
-			install_command "$url" "$username" "$password" "$version" "$autostart" "$binary_path"
+			install_command "$url" "$username" "$password" "$version" "$autostart" "$binary_path" "$file_path"
 		;;
 		update-subscription)
 			local url=""
 			local username=""
 			local password=""
+			local file_path=""
 			while [[ $# -gt 0 ]]; do
 				case "$1" in
 					--url) url="$2"; shift 2 ;;
+					--file) file_path="$2"; shift 2 ;;
 					--user) username="$2"; shift 2 ;;
 					--password) password="$2"; shift 2 ;;
 					*) die "Unknown update-subscription option: $1" ;;
 				esac
 			done
-			update_subscription_command "$url" "$username" "$password"
+			update_subscription_command "$url" "$username" "$password" "$file_path"
 		;;
 		start)
 			start_command