dsh-mobile 0.5.0 → 0.5.2

package/lib/index.d.mts

@@ -356,6 +356,8 @@ declare class JsonMobileAccessControlStore implements MobileAccessControlStore {
   private readonly file;
   private readonly initiallyEnabled;
   constructor(file: string, initiallyEnabled: boolean);
+  /** Avoid writing an absent already-disabled state without changing recovery of existing files. */
+  disableIfPresent(): Promise<void>;
   load(): Promise<MobileAccessControlState>;
   save(state: MobileAccessControlState): Promise<void>;
 }
@@ -919,6 +921,8 @@ interface FrpConfigurationStatus {
   readonly publicOrigin?: string;
   readonly vhostHttpPort: number;
   readonly storagePath: string;
+  /** Proxy name frpc registers on the shared frps; unique per DSH installation. */
+  readonly proxyName: string;
   readonly errorCode?: string;
   /** Present only when the saved configuration leaves the upstream `deploy` default. */
   readonly mode?: FrpMode;
@@ -976,14 +980,46 @@ declare function mergeSavedFrpTarget(partial: Readonly<Record<string, unknown>>,
   readonly serverAddress: string;
   readonly serverPort: number;
 };
+/**
+ * Legacy proxy name, kept only as the default of {@link createFrpcToml}.
+ *
+ * A shared frps accepts one proxy per name across *all* its clients, so a fixed
+ * name let any other DSH installation — or a not yet reaped session of this one —
+ * own `dsh-mobile` first. frpc then logged `start error: proxy name [dsh-mobile]
+ * is already in use`, kept running without publishing the entry port, and the
+ * start-up self-check ended in `frp_start_timeout` ("the public endpoint did not
+ * become ready"). Product callers therefore pass an installation-derived name
+ * from {@link frpProxyName}; this constant only keeps the exported API and the
+ * byte-for-byte compatibility test working for legacy callers.
+ */
+declare const FRP_DEFAULT_PROXY_NAME = "dsh-mobile";
+/**
+ * Validate a proxy name for the generated frpc configuration.
+ *
+ * frps accepts one proxy per name on the whole server, so the name must be a
+ * single safe token: no whitespace, no quotes, no path or bracket characters.
+ */
+declare function validateFrpProxyName(value: unknown): string;
+/**
+ * Proxy name for one DSH installation.
+ *
+ * Derived from the stable installation identity so two computers sharing one
+ * frps never register the same proxy, while a single installation keeps the
+ * same name across restarts (so its own stale registration is the only possible
+ * conflict, and that one expires with the frps heartbeat).
+ */
+declare function frpProxyName(instanceId: string): string;
 /**
  * Build the single-purpose frpc configuration for the current loopback gateway.
  *
  * The default (public-CA) entry is an HTTP vhost behind Caddy and is emitted byte
  * for byte as before. The self-signed entry cannot use a vhost at all: frps only
  * forwards raw TCP, and the gateway terminates TLS on that connection.
+ *
+ * `proxyName` defaults to the legacy fixed name only for legacy callers; the
+ * provider and the attach preview always pass {@link frpProxyName}.
  */
-declare function createFrpcToml(settings: FrpSettings, localPort: number): string;
+declare function createFrpcToml(settings: FrpSettings, localPort: number, proxyName?: string): string;
 /** Build the matching restricted frps and Caddy templates for one VPS. */
 declare function createFrpServerTemplate(settings: FrpSettings): string;
 /** Owns private FRP settings and generation-specific frpc configuration. */
@@ -991,9 +1027,17 @@ declare class FrpConfigStore {
   readonly stateRoot: string;
   readonly settingsFile: string;
   readonly runtimeConfigFile: string;
+  /**
+   * Proxy name every generated frpc.toml registers.
+   *
+   * Injected by the composing plugin ({@link frpProxyName}) so one frps can
+   * serve several DSH installations; the legacy fixed name stays the default
+   * for direct constructions in tests and for the exported API.
+   */
+  readonly proxyName: string;
   private settingsValue;
   private errorCode;
-  constructor(stateDirectory: string);
+  constructor(stateDirectory: string, proxyName?: string);
   /** Load private settings while rejecting links, oversized files, and unknown fields. */
   initialize(): Promise<void>;
   /**
@@ -1030,6 +1074,14 @@ interface FrpAttachOptions {
   readonly certDir?: string;
   /** Absolute path of the plugin-written frpc.toml, used for the `frpc verify` self-check. */
   readonly configFile?: string;
+  /**
+   * Proxy name the previewed frpc.toml registers.
+   *
+   * Defaults to the legacy fixed name; the panel and the provider pass the
+   * installation-derived {@link frpProxyName} so a preview never describes a
+   * registration that would collide on a shared frps.
+   */
+  readonly proxyName?: string;
   /** Loopback port the gateway will listen on; only a placeholder inside the copied runbook. */
   readonly localPort?: number;
   /**
@@ -1819,5 +1871,5 @@ declare function originGatewayConfig(template: ResolvedGatewayConfig, settings:
 /** Mount the resident control route and its optional authenticated LAN gateway. */
 declare function apply(ctx: Context, config: PluginConfig): Promise<void>;
 //#endregion
-export { AUTH_PREFIX, AccessController, type AccessControllerOptions, AccessError, type AuthoritySpec, type BlockedUpgradePathEntry, BlockedUpgradePathLog, BoundedRateLimiter, CERT_EXPIRING_DAYS, CLOUDFLARED_COMPONENT_RELEASE, CSRF_COOKIE, CSRF_HEADER, type CaddySiteOptions, type CertRenewalStatus, CloudflaredComponentManager, type CloudflaredComponentStatus, CloudflaredController, type CloudflaredControllerOptions, type CloudflaredState, type CloudflaredStatus, type CloudflaredTunnelMode, type CloudflaredTunnelSettings, type CloudflaredTunnelStatus, CloudflaredTunnelStore, Config, DEFAULT_ORIGIN_LISTEN_PORT, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, type DeviceProbeResult, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, EXTENSION_LIMITS, FRP_ATTACH_DISCOVERY_PATH, FRP_ATTACH_LOCAL_DECLARATION, FRP_ATTACH_SELF_SIGNED_DECLARATION, FRP_ATTACH_VPS_DECLARATION, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FRP_DEFAULT_PUBLIC_PORT, FRP_RESERVED_PORTS, type FrpAttachOptions, type FrpAttachPlan, type FrpAttachPlanLocal, type FrpAttachPlanStep, type FrpAttachStepId, type FrpAttachTemplate, type FrpAttachVpsParts, FrpComponentManager, type FrpComponentStatus, FrpConfigStore, type FrpConfigurationStatus, FrpController, type FrpControllerOptions, type FrpEntryTls, type FrpIngressCertificate, type FrpIngressPaths, type FrpIngressSelfCheck, type FrpSettings, type FrpState, type FrpStatus, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, type LocalExtensionManifest, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, type MobileAccessControlState, type MobileAccessControlStore, MobileAccessGateway, MobileAccessGatewayController, type MobileAccessService as MobileAccessRegistry, MobileAccessService, type MobileAccessRuntime, type MobileActionContext, type MobileExtensionClientEntry, type MobileExtensionDefinition, MobileExtensionError, type MobileExtensionManifest, type MobileExtensionStatus, type MobileHostAction, type MobileHostRoute, type MobileRouteRequest, type MobileRouteResponse, OriginConfigStore, type OriginConfigurationStatus, OriginController, type OriginControllerOptions, type OriginSettings, type OriginState, type OriginStatus, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, REMOTE_PROVIDERS, type RemoteProvider, type RemoteProviderController, type RemoteProviderState, type RemoteProviderStatus, type RenewalResult, RequestTrustPolicy, type ResolvedGatewayConfig, SESSION_COOKIE, type ServerCertificateAuthority, type ServerCertificateFiles, type ServerCertificateTarget, type SessionAuthorization, type SessionEndReason, type StoredDevice, TASK_EVENT_DEBOUNCE_MS, type TaskCompletionEvent, type TaskEventContext, TaskEventHub, type TaskEventSession, type TaskEventSink, type TaskEventWatcherOptions, type TaskTurnEvent, type TlsConfig, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpAttachPlan, createFrpAttachTemplate, createFrpAttachTemplateParts, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, ensureFrpIngressCertificate, evaluateCertificateLifetime, frpAttachVpsParts, frpIngressPaths, frpIngressSelfCheck, inject, isCloudflaredRegistration, isFrpSelfSignedIngress, isGloballyRoutableIpv4, isLoopbackAddress, issueServerCertificate, mergeSavedCloudflaredTunnelSettings, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, originGatewayConfig, parseAuthority, parseCidr, parseCloudflaredOrigin, parseCloudflaredTunnelSettings, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseOriginSettings, parseRemoteProviderState, probeOriginCertificate, readCertificateRenewal, resolveAuthority, resolveFrpEntryTls, resolveFrpMode, resolveFrpPublicPort, resolveFrpVhostHttpPort, rewriteMobileIndex, validateAttachSettings, validateCloudflaredTunnelHostname, validateCloudflaredTunnelPort, validateCloudflaredTunnelToken, validateFrpEntryTls, validateFrpMode, validateFrpPublicOrigin, validateFrpPublicPort, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateFrpVhostHttpPort, validateOriginAllowedCidrs, validateOriginListenHost, validateOriginListenPort, validateOriginPublicOrigin, validateWebSocketPath, watchTaskCompletions };
+export { AUTH_PREFIX, AccessController, type AccessControllerOptions, AccessError, type AuthoritySpec, type BlockedUpgradePathEntry, BlockedUpgradePathLog, BoundedRateLimiter, CERT_EXPIRING_DAYS, CLOUDFLARED_COMPONENT_RELEASE, CSRF_COOKIE, CSRF_HEADER, type CaddySiteOptions, type CertRenewalStatus, CloudflaredComponentManager, type CloudflaredComponentStatus, CloudflaredController, type CloudflaredControllerOptions, type CloudflaredState, type CloudflaredStatus, type CloudflaredTunnelMode, type CloudflaredTunnelSettings, type CloudflaredTunnelStatus, CloudflaredTunnelStore, Config, DEFAULT_ORIGIN_LISTEN_PORT, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, type DeviceProbeResult, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, EXTENSION_LIMITS, FRP_ATTACH_DISCOVERY_PATH, FRP_ATTACH_LOCAL_DECLARATION, FRP_ATTACH_SELF_SIGNED_DECLARATION, FRP_ATTACH_VPS_DECLARATION, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FRP_DEFAULT_PROXY_NAME, FRP_DEFAULT_PUBLIC_PORT, FRP_RESERVED_PORTS, type FrpAttachOptions, type FrpAttachPlan, type FrpAttachPlanLocal, type FrpAttachPlanStep, type FrpAttachStepId, type FrpAttachTemplate, type FrpAttachVpsParts, FrpComponentManager, type FrpComponentStatus, FrpConfigStore, type FrpConfigurationStatus, FrpController, type FrpControllerOptions, type FrpEntryTls, type FrpIngressCertificate, type FrpIngressPaths, type FrpIngressSelfCheck, type FrpSettings, type FrpState, type FrpStatus, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, type LocalExtensionManifest, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, type MobileAccessControlState, type MobileAccessControlStore, MobileAccessGateway, MobileAccessGatewayController, type MobileAccessService as MobileAccessRegistry, MobileAccessService, type MobileAccessRuntime, type MobileActionContext, type MobileExtensionClientEntry, type MobileExtensionDefinition, MobileExtensionError, type MobileExtensionManifest, type MobileExtensionStatus, type MobileHostAction, type MobileHostRoute, type MobileRouteRequest, type MobileRouteResponse, OriginConfigStore, type OriginConfigurationStatus, OriginController, type OriginControllerOptions, type OriginSettings, type OriginState, type OriginStatus, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, REMOTE_PROVIDERS, type RemoteProvider, type RemoteProviderController, type RemoteProviderState, type RemoteProviderStatus, type RenewalResult, RequestTrustPolicy, type ResolvedGatewayConfig, SESSION_COOKIE, type ServerCertificateAuthority, type ServerCertificateFiles, type ServerCertificateTarget, type SessionAuthorization, type SessionEndReason, type StoredDevice, TASK_EVENT_DEBOUNCE_MS, type TaskCompletionEvent, type TaskEventContext, TaskEventHub, type TaskEventSession, type TaskEventSink, type TaskEventWatcherOptions, type TaskTurnEvent, type TlsConfig, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpAttachPlan, createFrpAttachTemplate, createFrpAttachTemplateParts, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, ensureFrpIngressCertificate, evaluateCertificateLifetime, frpAttachVpsParts, frpIngressPaths, frpIngressSelfCheck, frpProxyName, inject, isCloudflaredRegistration, isFrpSelfSignedIngress, isGloballyRoutableIpv4, isLoopbackAddress, issueServerCertificate, mergeSavedCloudflaredTunnelSettings, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, originGatewayConfig, parseAuthority, parseCidr, parseCloudflaredOrigin, parseCloudflaredTunnelSettings, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseOriginSettings, parseRemoteProviderState, probeOriginCertificate, readCertificateRenewal, resolveAuthority, resolveFrpEntryTls, resolveFrpMode, resolveFrpPublicPort, resolveFrpVhostHttpPort, rewriteMobileIndex, validateAttachSettings, validateCloudflaredTunnelHostname, validateCloudflaredTunnelPort, validateCloudflaredTunnelToken, validateFrpEntryTls, validateFrpMode, validateFrpProxyName, validateFrpPublicOrigin, validateFrpPublicPort, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateFrpVhostHttpPort, validateOriginAllowedCidrs, validateOriginListenHost, validateOriginListenPort, validateOriginPublicOrigin, validateWebSocketPath, watchTaskCompletions };
 //# sourceMappingURL=index.d.mts.map

package/lib/index.mjs

@@ -1078,6 +1078,25 @@ var JsonMobileAccessControlStore = class {
 		this.file = file;
 		this.initiallyEnabled = initiallyEnabled;
 	}
+	/** Avoid writing an absent already-disabled state without changing recovery of existing files. */
+	async disableIfPresent() {
+		try {
+			await lstat(this.file);
+		} catch (error) {
+			if (error.code === "ENOENT") {
+				if (this.initiallyEnabled) await this.save({
+					version: 1,
+					enabled: false
+				});
+				return;
+			}
+			throw error;
+		}
+		await this.save({
+			version: 1,
+			enabled: false
+		});
+	}
 	async load() {
 		let stat;
 		try {
@@ -6101,13 +6120,51 @@ function tomlString(value) {
 	return JSON.stringify(value);
 }
 /**
+* Legacy proxy name, kept only as the default of {@link createFrpcToml}.
+*
+* A shared frps accepts one proxy per name across *all* its clients, so a fixed
+* name let any other DSH installation — or a not yet reaped session of this one —
+* own `dsh-mobile` first. frpc then logged `start error: proxy name [dsh-mobile]
+* is already in use`, kept running without publishing the entry port, and the
+* start-up self-check ended in `frp_start_timeout` ("the public endpoint did not
+* become ready"). Product callers therefore pass an installation-derived name
+* from {@link frpProxyName}; this constant only keeps the exported API and the
+* byte-for-byte compatibility test working for legacy callers.
+*/
+const FRP_DEFAULT_PROXY_NAME = "dsh-mobile";
+/**
+* Validate a proxy name for the generated frpc configuration.
+*
+* frps accepts one proxy per name on the whole server, so the name must be a
+* single safe token: no whitespace, no quotes, no path or bracket characters.
+*/
+function validateFrpProxyName(value) {
+	if (typeof value !== "string" || value.length < 1 || value.length > 128 || !/^[A-Za-z0-9._-]+$/u.test(value)) throw new Error("frp_proxy_name_invalid");
+	return value;
+}
+/**
+* Proxy name for one DSH installation.
+*
+* Derived from the stable installation identity so two computers sharing one
+* frps never register the same proxy, while a single installation keeps the
+* same name across restarts (so its own stale registration is the only possible
+* conflict, and that one expires with the frps heartbeat).
+*/
+function frpProxyName(instanceId) {
+	if (typeof instanceId !== "string" || !/^[a-f0-9]{64}$/u.test(instanceId)) throw new Error("frp_instance_id_invalid");
+	return `${FRP_DEFAULT_PROXY_NAME}-${instanceId.slice(0, 12)}`;
+}
+/**
 * Build the single-purpose frpc configuration for the current loopback gateway.
 *
 * The default (public-CA) entry is an HTTP vhost behind Caddy and is emitted byte
 * for byte as before. The self-signed entry cannot use a vhost at all: frps only
 * forwards raw TCP, and the gateway terminates TLS on that connection.
+*
+* `proxyName` defaults to the legacy fixed name only for legacy callers; the
+* provider and the attach preview always pass {@link frpProxyName}.
 */
-function createFrpcToml(settings, localPort) {
+function createFrpcToml(settings, localPort, proxyName = FRP_DEFAULT_PROXY_NAME) {
 	if (!Number.isSafeInteger(localPort) || localPort < 1 || localPort > 65535) throw new Error("frp_local_port_invalid");
 	const header = [
 		`serverAddr = ${tomlString(settings.serverAddress)}`,
@@ -6117,7 +6174,7 @@ function createFrpcToml(settings, localPort) {
 		"transport.tls.enable = true",
 		"",
 		"[[proxies]]",
-		"name = \"dsh-mobile\""
+		`name = ${tomlString(validateFrpProxyName(proxyName))}`
 	];
 	if (isFrpSelfSignedIngress(settings)) return [
 		...header,
@@ -6179,13 +6236,22 @@ var FrpConfigStore = class {
 	stateRoot;
 	settingsFile;
 	runtimeConfigFile;
+	/**
+	* Proxy name every generated frpc.toml registers.
+	*
+	* Injected by the composing plugin ({@link frpProxyName}) so one frps can
+	* serve several DSH installations; the legacy fixed name stays the default
+	* for direct constructions in tests and for the exported API.
+	*/
+	proxyName;
 	settingsValue;
 	errorCode;
-	constructor(stateDirectory) {
+	constructor(stateDirectory, proxyName = FRP_DEFAULT_PROXY_NAME) {
 		if (!isAbsolute(stateDirectory)) throw new Error("frp config state directory must be absolute");
 		this.stateRoot = resolve(stateDirectory);
 		this.settingsFile = join(this.stateRoot, "settings.json");
 		this.runtimeConfigFile = join(this.stateRoot, "frpc.toml");
+		this.proxyName = validateFrpProxyName(proxyName);
 	}
 	/** Load private settings while rejecting links, oversized files, and unknown fields. */
 	async initialize() {
@@ -6229,6 +6295,7 @@ var FrpConfigStore = class {
 			},
 			vhostHttpPort: settings === void 0 ? FRP_VHOST_HTTP_PORT : resolveFrpVhostHttpPort(settings),
 			storagePath: this.stateRoot,
+			proxyName: this.proxyName,
 			...this.errorCode === void 0 ? {} : { errorCode: this.errorCode },
 			...mode === void 0 || mode === "deploy" ? {} : { mode },
 			...entryTls === void 0 || entryTls === "public-ip-cert" ? {} : { entryTls },
@@ -6252,7 +6319,7 @@ var FrpConfigStore = class {
 	async writeRuntimeConfig(localPort) {
 		const settings = this.settingsValue;
 		if (settings === void 0) throw new Error("frp_config_missing");
-		await atomicPrivateWrite$2(this.runtimeConfigFile, createFrpcToml(settings, localPort));
+		await atomicPrivateWrite$2(this.runtimeConfigFile, createFrpcToml(settings, localPort, this.proxyName));
 		return this.runtimeConfigFile;
 	}
 	/** Remove only configuration files owned by the FRP provider. */
@@ -6311,7 +6378,7 @@ function redactFrpcTomlToken(frpcToml) {
 * the provider writes stays byte-for-byte identical to the upstream output.
 */
 function createFrpAttachFrpcToml(settings, options = {}) {
-	const frpcToml = createFrpcToml(settings, attachLocalPort(options));
+	const frpcToml = createFrpcToml(settings, attachLocalPort(options), options.proxyName ?? "dsh-mobile");
 	return options.revealToken === true ? frpcToml : redactFrpcTomlToken(frpcToml);
 }
 const DEFAULT_ATTACH_CONFIG_FILE = "<DSH Mobile 私有目录>/remote/frp/config/frpc.toml";
@@ -7503,6 +7570,30 @@ const DISCOVERY_RETRY_MS = 1e3;
 const MAX_DISCOVERY_BYTES = 16384;
 const VHOST_PROBE_TIMEOUT_MS = 1500;
 const INGRESS_CERT_CHECK_MS = 432e5;
+/**
+* frpc start-failure signatures, most specific first.
+*
+* frpc reports a refused proxy registration as a warning and keeps running, so
+* without this mapping the controller only ever saw a healthy child process and
+* an entry port nobody published: the start-up self-check burned its full 45s
+* deadline and reported `frp_start_timeout` ("the public endpoint did not become
+* ready"), which sent users looking at DNS, Caddy, and firewalls.
+*
+* The two real conflicts are a proxy name another client of the same frps holds
+* and an entry port another proxy already owns. Both are reported directly.
+*/
+const CLIENT_FAILURE_CODES = Object.freeze([
+	[/proxy name \[[^\]]*\] is already in use/iu, "frp_proxy_name_in_use"],
+	[/(?:remote )?port (?:\[?[0-9]+\]? )?already (?:used|in use)/iu, "frp_remote_port_in_use"],
+	[/start error:/iu, "frp_proxy_start_failed"]
+]);
+/**
+* Stable error code for a chunk of frpc output, or undefined when it reports no
+* start failure. Exported for the conflict tests.
+*/
+function frpcDiagnosisCode(output) {
+	return CLIENT_FAILURE_CODES.find(([pattern]) => pattern.test(output))?.[1];
+}
 function publicStatus$3(status) {
 	return Object.freeze({
 		enabled: status.enabled,
@@ -7904,15 +7995,37 @@ var FrpController = class {
 			return;
 		}
 		this.child = child;
+		const pending = {
+			stdout: "",
+			stderr: ""
+		};
+		let diagnosed = false;
+		const inspectLine = (line) => {
+			if (diagnosed) return;
+			const code = frpcDiagnosisCode(line);
+			if (code === void 0) return;
+			diagnosed = true;
+			this.enqueue(() => this.failGeneration(generation, code));
+		};
+		const inspect = (stream, chunk) => {
+			if (diagnosed) return;
+			const lines = (pending[stream] + String(chunk)).split(/\r\n|\r|\n/u);
+			pending[stream] = (lines.pop() ?? "").slice(-8192);
+			for (const line of lines) inspectLine(line.slice(-8192));
+		};
+		child.stdout.on("data", (chunk) => inspect("stdout", chunk));
+		child.stderr.on("data", (chunk) => inspect("stderr", chunk));
 		child.stdout.resume();
 		child.stderr.resume();
 		child.once("error", () => {
 			this.enqueue(() => this.failGeneration(generation, "frp_launch_failed"));
 		});
 		child.once("close", (code) => {
+			inspectLine(pending.stdout);
+			inspectLine(pending.stderr);
 			if (generation !== this.generation || this.child !== child) return;
 			this.child = void 0;
-			if (this.enabled) this.enqueue(() => this.failGeneration(generation, code === 0 ? "frp_stopped" : "frp_exited"));
+			if (this.enabled && !diagnosed) this.enqueue(() => this.failGeneration(generation, code === 0 ? "frp_stopped" : "frp_exited"));
 		});
 		this.publish({
 			enabled: true,
@@ -7928,6 +8041,7 @@ var FrpController = class {
 			return;
 		}
 		if (generation !== this.generation || !this.enabled) return;
+		if (diagnosed) return;
 		const controller = new AbortController();
 		this.startupAbort = controller;
 		this.waitForDiscovery(generation, check, gateway.config.instanceId, settings, gateway, controller.signal);
@@ -9552,6 +9666,9 @@ const REMOTE_ERROR_GUIDANCE = Object.freeze({
 	frp_vhost_probe_failed: "确认 VPS 地址可解析后重新连接。",
 	frp_launch_failed: "重新安装 FRP 官方组件后重试。",
 	frp_start_timeout: "确认 frps、Caddy 和域名解析正常后重新连接。",
+	frp_proxy_name_in_use: "该 frps 上已有同名代理：在另一台 DSH 电脑上关闭自建 FRP，或在 frps 上清掉该代理后重新连接。",
+	frp_remote_port_in_use: "公网入口端口被其他代理占用：改用其他入口端口后重新连接。",
+	frp_proxy_start_failed: "查看 frps 日志与 allowPorts，确认它能接受该代理名和入口端口。",
 	frp_discovery_mismatch: "公开域名连接到了另一台电脑，请核对 Caddy 与 frps 配置。",
 	frp_discovery_invalid: "公开域名返回了非 DSH Mobile 响应。",
 	frp_stopped: "点击“重新连接”。",
@@ -9977,7 +10094,7 @@ function buildMobileGuide(state) {
 	const scriptLine = state.hasCustomJs ? "存在（当前生效的自定义脚本）" : "不存在（无自定义脚本）";
 	const extensionLines = state.extensions.length === 0 ? "（无）" : state.extensions.map((entry) => `- ${entry.id}（${entry.name} v${entry.version}）`).join("\n");
 	const failureLine = state.failedExtensionCount > 0 ? `注意：${state.failedExtensionCount} 个扩展的电脑端 host 激活失败，如改动相关扩展请先检查其 host.mjs 与 extension.json。` : "";
-	return `${`## 手机端当前状态（改名前必读，避免覆盖已有定制）
+	return `${`## 手机端当前状态（改动前必读，避免覆盖已有定制）
 
 - 定制目录：${state.directory}（所有改动只允许在这里进行）
 - mobile.css：${styleLine}
@@ -10003,6 +10120,8 @@ const MOBILE_CUSTOMIZATION_GUIDE_BODY = `你在为用户定制 DSH Mobile 的手
    - $DSH_HOME/mobile-access/mobile.js：手机端脚本，用 window.dshMobile.register(({ root }) => { ... }) 把内容挂载到 root，返回清理函数
    - 保存后手机端几秒内自动应用，无需重启
 
+动手前先读已有的定制文件。若要调整 DSH 自带的输入框、侧栏或设置等现有界面，先确认当前 DSH 版本与手机页面模式（专用移动页面或 ?frontend=stock），只读核对运行页面的 DOM、属性和样式；本机有同版本前端源码时可参考相应组件，没有源码时可查看已安装的客户端产物，不必下载源码。优先使用扩展 API、插槽和稳定的 data-* 标记，不凭猜测依赖构建类名。只读查看不改变前述写入范围。
+
 2. 电脑端能力 —— 手机需要读电脑文件、执行命令或访问硬件时，创建扩展：
    - 目录：$DSH_HOME/mobile-access/extensions/<id>/，id 用小写字母数字和连字符（如 media-remote）
    - extension.json：{"schemaVersion":1,"id":"<id>","name":"显示名","version":"0.1.0","description":"说明"}
@@ -10019,6 +10138,7 @@ const MOBILE_CUSTOMIZATION_GUIDE_BODY = `你在为用户定制 DSH Mobile 的手
 
 完成前请自检：
 - 改动涉及 mobile.js 或扩展的 mobile.js / host.mjs 时，先做语法检查再保存（如 node --check <file>），确保没有语法错误
+- 改动 DSH 现有界面后尽可能在实际手机页面核对效果；无法观察运行页面时，明确告诉用户尚未实测
 - 创建或修改扩展后，确认 extension.json 的 schemaVersion 为 1、id 与目录名一致、且 id 只含小写字母数字和连字符
 - 扩展的 host.mjs 若在完成前无法激活，先修正而不是留下损坏的扩展
 - 完成后检查自己实际写入了哪些文件，向用户简要说明改了什么、手机端会有什么变化`;
@@ -12647,6 +12767,36 @@ async function installMobileFileLogger(ctx, stateDirectory) {
 	return file;
 }
 //#endregion
+//#region src/installation-id.ts
+const INSTALLATION_ID_PATTERN = /^[a-f0-9]{64}\n$/u;
+const INSTALLATION_ID_BYTES = 65;
+async function readInstallationId(file) {
+	const entry = await lstat(file);
+	if (!entry.isFile() || entry.isSymbolicLink() || entry.size !== INSTALLATION_ID_BYTES) throw new Error("installation_id_invalid");
+	const contents = await readFile(file, "utf8");
+	if (!INSTALLATION_ID_PATTERN.test(contents)) throw new Error("installation_id_invalid");
+	await restrictPrivateFile(file);
+	return contents.slice(0, -1);
+}
+/** Keep one random plugin identity across setup changes, restarts, and FRP resets. */
+async function loadOrCreateInstallationId(file) {
+	if (!isAbsolute(file)) throw new Error("installation ID path must be absolute");
+	const target = resolve(file);
+	await mkdir(dirname(target), {
+		recursive: true,
+		mode: 448
+	});
+	try {
+		await writeFile(target, `${randomBytes(32).toString("hex")}\n`, {
+			flag: "wx",
+			mode: 384
+		});
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+	}
+	return readInstallationId(target);
+}
+//#endregion
 //#region src/lan-setup.ts
 const FIREWALL_TCP_RULE = "DSH Mobile HTTPS";
 const FIREWALL_UDP_RULE = "DSH Mobile Discovery";
@@ -13044,7 +13194,8 @@ async function apply(ctx, config) {
 	await cloudflaredComponent.initialize();
 	const frpComponent = new FrpComponentManager({ stateDirectory });
 	await frpComponent.initialize();
-	const frpConfig = new FrpConfigStore(join(remoteDirectory, "frp", "config"));
+	const frpIdentity = await loadOrCreateInstallationId(join(stateDirectory, "installation-id"));
+	const frpConfig = new FrpConfigStore(join(remoteDirectory, "frp", "config"), frpProxyName(frpIdentity));
 	await frpConfig.initialize();
 	const originConfig = new OriginConfigStore(join(remoteDirectory, "origin", "config"));
 	await originConfig.initialize();
@@ -13522,7 +13673,10 @@ async function apply(ctx, config) {
 				}
 				if (request.method === "POST" && target.decodedPathname === `/api/mobile-access/remote/frp/attach-plan`) {
 					const settings = mergeSavedFrpSettings(await readJsonObject(request, 8192), frpConfig.settings());
-					const options = { configFile: frpConfig.runtimeConfigFile };
+					const options = {
+						configFile: frpConfig.runtimeConfigFile,
+						proxyName: frpConfig.proxyName
+					};
 					logger.info("frp attach plan requested mode=%s entryTls=%s vhostHttpPort=%d", settings.mode ?? "deploy", settings.entryTls ?? "public-ip-cert", resolveFrpVhostHttpPort(settings));
 					sendJson(response, 200, {
 						...remotePayload(),
@@ -13705,7 +13859,7 @@ async function apply(ctx, config) {
 		const unregister = ctx.webServer.register(adminRoute);
 		const disposeMobileCommand = ctx.commands.register({
 			name: "mobile",
-			description: "按需求修改 DSH Mobile 的手机端界面或添加电脑端能力",
+			description: "定制手机界面或添加电脑能力",
 			input: { hint: "<要做什么>" },
 			handler: async ({ agent, rawInput }) => {
 				const task = rawInput.trim();
@@ -13751,10 +13905,7 @@ async function apply(ctx, config) {
 				frp: frpStore,
 				origin: originStore
 			};
-			await Promise.all(Object.keys(stores).filter((provider) => provider !== remoteProviders.selected).map((provider) => stores[provider].save({
-				version: 1,
-				enabled: false
-			})));
+			await Promise.all(Object.keys(stores).filter((provider) => provider !== remoteProviders.selected).map((provider) => stores[provider].disableIfPresent()));
 			for (const provider of REMOTE_PROVIDERS) await remoteControllers[provider].initialize();
 			const lanDiscovery = lanGateway?.discoveryStatus();
 			if (lanDiscovery !== void 0 && !lanDiscovery.broadcast) logger.warn("broadcast discovery is unavailable (%s); mDNS is still published, so pair manually or free the UDP port", lanDiscovery.errorCode ?? "unknown_cause");
@@ -13795,6 +13946,6 @@ async function apply(ctx, config) {
 	}, "dsh-mobile: independent LAN and selectable remote providers with /mobile command");
 }
 //#endregion
-export { AUTH_PREFIX, AccessController, AccessError, BlockedUpgradePathLog, BoundedRateLimiter, CERT_EXPIRING_DAYS, CLOUDFLARED_COMPONENT_RELEASE, CSRF_COOKIE, CSRF_HEADER, CloudflaredComponentManager, CloudflaredController, CloudflaredTunnelStore, Config, DEFAULT_ORIGIN_LISTEN_PORT, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, EXTENSION_LIMITS, FRP_ATTACH_DISCOVERY_PATH, FRP_ATTACH_LOCAL_DECLARATION, FRP_ATTACH_SELF_SIGNED_DECLARATION, FRP_ATTACH_VPS_DECLARATION, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FRP_DEFAULT_PUBLIC_PORT, FRP_RESERVED_PORTS, FrpComponentManager, FrpConfigStore, FrpController, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, MobileAccessGateway, MobileAccessGatewayController, MobileAccessService, MobileExtensionError, OriginConfigStore, OriginController, REMOTE_PROVIDERS, RequestTrustPolicy, SESSION_COOKIE, TASK_EVENT_DEBOUNCE_MS, TaskEventHub, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpAttachPlan, createFrpAttachTemplate, createFrpAttachTemplateParts, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, ensureFrpIngressCertificate, evaluateCertificateLifetime, frpAttachVpsParts, frpIngressPaths, frpIngressSelfCheck, inject, isCloudflaredRegistration, isFrpSelfSignedIngress, isGloballyRoutableIpv4, isLoopbackAddress, issueServerCertificate, mergeSavedCloudflaredTunnelSettings, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, originGatewayConfig, parseAuthority, parseCidr, parseCloudflaredOrigin, parseCloudflaredTunnelSettings, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseOriginSettings, parseRemoteProviderState, probeOriginCertificate, readCertificateRenewal, resolveAuthority, resolveFrpEntryTls, resolveFrpMode, resolveFrpPublicPort, resolveFrpVhostHttpPort, rewriteMobileIndex, validateAttachSettings, validateCloudflaredTunnelHostname, validateCloudflaredTunnelPort, validateCloudflaredTunnelToken, validateFrpEntryTls, validateFrpMode, validateFrpPublicOrigin, validateFrpPublicPort, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateFrpVhostHttpPort, validateOriginAllowedCidrs, validateOriginListenHost, validateOriginListenPort, validateOriginPublicOrigin, validateWebSocketPath, watchTaskCompletions };
+export { AUTH_PREFIX, AccessController, AccessError, BlockedUpgradePathLog, BoundedRateLimiter, CERT_EXPIRING_DAYS, CLOUDFLARED_COMPONENT_RELEASE, CSRF_COOKIE, CSRF_HEADER, CloudflaredComponentManager, CloudflaredController, CloudflaredTunnelStore, Config, DEFAULT_ORIGIN_LISTEN_PORT, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, EXTENSION_LIMITS, FRP_ATTACH_DISCOVERY_PATH, FRP_ATTACH_LOCAL_DECLARATION, FRP_ATTACH_SELF_SIGNED_DECLARATION, FRP_ATTACH_VPS_DECLARATION, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FRP_DEFAULT_PROXY_NAME, FRP_DEFAULT_PUBLIC_PORT, FRP_RESERVED_PORTS, FrpComponentManager, FrpConfigStore, FrpController, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, MobileAccessGateway, MobileAccessGatewayController, MobileAccessService, MobileExtensionError, OriginConfigStore, OriginController, REMOTE_PROVIDERS, RequestTrustPolicy, SESSION_COOKIE, TASK_EVENT_DEBOUNCE_MS, TaskEventHub, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpAttachPlan, createFrpAttachTemplate, createFrpAttachTemplateParts, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, ensureFrpIngressCertificate, evaluateCertificateLifetime, frpAttachVpsParts, frpIngressPaths, frpIngressSelfCheck, frpProxyName, inject, isCloudflaredRegistration, isFrpSelfSignedIngress, isGloballyRoutableIpv4, isLoopbackAddress, issueServerCertificate, mergeSavedCloudflaredTunnelSettings, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, originGatewayConfig, parseAuthority, parseCidr, parseCloudflaredOrigin, parseCloudflaredTunnelSettings, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseOriginSettings, parseRemoteProviderState, probeOriginCertificate, readCertificateRenewal, resolveAuthority, resolveFrpEntryTls, resolveFrpMode, resolveFrpPublicPort, resolveFrpVhostHttpPort, rewriteMobileIndex, validateAttachSettings, validateCloudflaredTunnelHostname, validateCloudflaredTunnelPort, validateCloudflaredTunnelToken, validateFrpEntryTls, validateFrpMode, validateFrpProxyName, validateFrpPublicOrigin, validateFrpPublicPort, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateFrpVhostHttpPort, validateOriginAllowedCidrs, validateOriginListenHost, validateOriginListenPort, validateOriginPublicOrigin, validateWebSocketPath, watchTaskCompletions };
 
 //# sourceMappingURL=index.mjs.map