@lazycatcloud/lzc-cli 1.3.14 → 2.0.0-pre.0

package/lib/debug_bridge.js

@@ -5,10 +5,14 @@ import fetch from 'node-fetch';
 
 import shellApi from './shellapi.js';
 import { _SYSTEM_ENV_PREFIX } from './config/env.js';
-import { isDebugMode, isTraceMode, resolveDomain, sleep, findSshPublicKey, selectSshPublicKey, isWindows, contextDirname, compareVersions } from './utils.js';
+import { isTraceMode, resolveDomain, sleep, findSshPublicKey, selectSshPublicKey, isWindows, compareVersions } from './utils.js';
 import { t } from './i18n/index.js';
+import { resolveBuildRemoteFromFile } from './build_remote.js';
 
 const bannerfileContent = `˄=ᆽ=ᐟ \\`;
+const DEBUG_BRIDGE_CONTAINER = 'cloudlazycatdevelopertools-app-1';
+const DEBUG_BRIDGE_BINARY = '/lzcapp/pkg/content/debug.bridge';
+const DEBUG_BRIDGE_APP_ID = 'cloud.lazycat.developer.tools';
 
 export function sshBinary() {
 	if (isWindows) {
@@ -22,29 +26,289 @@ export function sshCmdArgs(...args) {
 	return [...defaultOptions, ...args];
 }
 
+export function sshCmdArgsRaw(...args) {
+	const defaultOptions = ['-o', 'StrictHostKeyChecking=no', '-o', 'UserKnownHostsFile=/dev/null', '-o', 'ControlMaster=no', '-q', '-p', '22222'];
+	if (isTraceMode()) {
+		defaultOptions.push('-v');
+	}
+	return [...defaultOptions, ...args];
+}
+
+function stripAnsi(text = '') {
+	return String(text).replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+}
+
+function extractInstallErrorDetail(rawOutput = '') {
+	const text = stripAnsi(rawOutput);
+
+	const detailMatch = text.match(/detail:"((?:\\"|[^"])*)"/);
+	if (detailMatch && detailMatch[1]) {
+		return detailMatch[1].replace(/\\"/g, '"').replace(/\\n/g, '\n').trim();
+	}
+
+	const descMatch = text.match(/rpc error:\s*code\s*=\s*\S+\s*desc\s*=\s*([^\n\r]+)/i);
+	if (descMatch && descMatch[1]) {
+		return descMatch[1].trim();
+	}
+
+	const lines = text
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter((line) => {
+			if (!line) {
+				return false;
+			}
+			if (line.startsWith('Usage:') || line.startsWith('Flags:') || line.startsWith('cmd:')) {
+				return false;
+			}
+			return true;
+		});
+	if (lines.length > 0) {
+		return lines[0];
+	}
+
+	return t('lzc_cli.lib.debug_bridge.install_fail', 'install 失败');
+}
+
+function streamInstallOutput(child, { printStdout = true, printStderr = false } = {}) {
+	let stdout = '';
+	let stderr = '';
+
+	child.stdout?.on('data', (chunk) => {
+		const text = String(chunk ?? '');
+		stdout += text;
+		if (printStdout) {
+			process.stdout.write(text);
+		}
+	});
+	child.stderr?.on('data', (chunk) => {
+		const text = String(chunk ?? '');
+		stderr += text;
+		if (printStderr) {
+			process.stderr.write(text);
+		}
+	});
+
+	return {
+		getStdout: () => stdout,
+		getStderr: () => stderr,
+	};
+}
+
+function normalizeErrorMessage(error) {
+	if (!error) {
+		return '';
+	}
+	if (typeof error === 'string') {
+		return error.trim();
+	}
+	if (typeof error.message === 'string') {
+		return error.message.trim();
+	}
+	return String(error).trim();
+}
+
 export class DebugBridge {
-	constructor() {
-		this.uid = shellApi.uid;
-		this.boxname = shellApi.boxname;
+	constructor(baseDir = process.cwd(), buildRemote = undefined) {
+		this.buildRemote = buildRemote === undefined ? resolveBuildRemoteFromFile(baseDir) : buildRemote;
+		if (this.buildRemote) {
+			this.uid = '';
+			this.boxname = this.buildRemote.boxname;
+		} else {
+			this.uid = shellApi.uid;
+			this.boxname = shellApi.boxname;
+		}
 		this.domain = `dev.${this.boxname}.heiyu.space`;
 		this.checkUseResolve = !!process.env[`${_SYSTEM_ENV_PREFIX}_CHECK_DNS_RESOLVE`];
 	}
 
+	isBuildRemoteMode() {
+		return !!this.buildRemote;
+	}
+
+	remoteSshArgsRaw({ tty = false } = {}) {
+		if (!this.buildRemote) {
+			throw new Error('build remote is not configured');
+		}
+		const args = ['-o', 'StrictHostKeyChecking=no', '-o', 'UserKnownHostsFile=/dev/null', '-o', 'ControlMaster=no', '-q', '-p', String(this.buildRemote.sshPort)];
+		if (isTraceMode()) {
+			args.push('-v');
+		}
+		if (tty) {
+			args.push('-t');
+		}
+		args.push(this.buildRemote.sshTarget);
+		return args;
+	}
+
+	remoteBridgeArgs(commandArgs = [], { tty = false } = {}) {
+		const args = [...this.remoteSshArgsRaw({ tty })];
+		args.push('lzc-docker', 'exec', tty ? '-it' : '-i', DEBUG_BRIDGE_CONTAINER, DEBUG_BRIDGE_BINARY, ...commandArgs);
+		return args;
+	}
+
+	remoteBridgeExec(commandArgs = [], { tty = false } = {}) {
+		return spawn.sync(sshBinary(), this.remoteBridgeArgs(commandArgs, { tty }), {
+			shell: false,
+			encoding: 'utf-8',
+			stdio: ['pipe', 'pipe', 'pipe'],
+		});
+	}
+
+	remoteHostExec(argv = []) {
+		return spawn.sync(sshBinary(), [...this.remoteSshArgsRaw(), ...argv], {
+			shell: false,
+			encoding: 'utf-8',
+			stdio: ['pipe', 'pipe', 'pipe'],
+		});
+	}
+
+	async remoteCommon(commandArgs = []) {
+		const ssh = this.remoteBridgeExec(commandArgs);
+		logger.debug(`run remote command: ${commandArgs.join(' ')}`);
+		if (ssh.status === 0) {
+			return ssh.stdout;
+		}
+		throw new Error(`remote command failed: ${commandArgs.join(' ')}\n${ssh.stdout ?? ''}\n${ssh.stderr ?? ''}`);
+	}
+
+	collectUIDCandidatesFromContainerEnv() {
+		const candidates = new Set();
+		const ps = this.remoteHostExec(['lzc-docker', 'ps', '--format', '{{.Names}}']);
+		if (ps.status !== 0) {
+			return [];
+		}
+		const containers = String(ps.stdout ?? '')
+			.split(/\r?\n/)
+			.map((item) => item.trim())
+			.filter((item) => item);
+		for (const container of containers.slice(0, 48)) {
+			const envResult = this.remoteHostExec(['lzc-docker', 'exec', '-i', container, 'env']);
+			if (envResult.status !== 0) {
+				continue;
+			}
+			String(envResult.stdout ?? '')
+				.split(/\r?\n/)
+				.map((line) => line.trim())
+				.forEach((line) => {
+					if (!line.startsWith('LAZYCAT_USER_ID=') && !line.startsWith('LAZYCAT_APP_DEPLOY_UID=')) {
+						return;
+					}
+					const value = String(line.split('=').slice(1).join('=') ?? '').trim();
+					if (value) {
+						candidates.add(value);
+					}
+				});
+		}
+		return [...candidates];
+	}
+
+	async probeLegacyUID() {
+		const candidates = [];
+		const appendCandidate = (value) => {
+			const uid = String(value ?? '').trim();
+			if (!uid) {
+				return;
+			}
+			if (!candidates.includes(uid)) {
+				candidates.push(uid);
+			}
+		};
+
+		this.collectUIDCandidatesFromContainerEnv().forEach((item) => appendCandidate(item));
+		appendCandidate(process.env.BOX_UID);
+		['c', 'admin', 'root'].forEach((item) => appendCandidate(item));
+		'abcdefghijklmnopqrstuvwxyz0123456789'.split('').forEach((item) => appendCandidate(item));
+
+		for (const uid of candidates) {
+			const probe = this.remoteBridgeExec(['info', '--uid', uid, DEBUG_BRIDGE_APP_ID]);
+			if (probe.status !== 0) {
+				continue;
+			}
+			try {
+				const parsed = JSON.parse(String(probe.stdout ?? '').trim());
+				if (parsed?.appid === DEBUG_BRIDGE_APP_ID) {
+					logger.debug(`resolved legacy uid by probe: ${uid}`);
+					return uid;
+				}
+			} catch {
+				logger.debug(`legacy uid probe got non-json output, use uid candidate: ${uid}`);
+				return uid;
+			}
+		}
+
+		return '';
+	}
+
+	async resolveCurrentUID() {
+		if (!this.isBuildRemoteMode()) {
+			return this.uid;
+		}
+		const cached = String(this.uid ?? '').trim();
+		if (cached) {
+			return cached;
+		}
+
+		const uidReply = this.remoteBridgeExec(['uid']);
+		if (uidReply.status === 0) {
+			const resolved = String(uidReply.stdout ?? '').trim();
+			if (!resolved) {
+				throw new Error('resolve uid failed: empty output');
+			}
+			this.uid = resolved;
+			return resolved;
+		}
+
+		const legacyUID = await this.probeLegacyUID();
+		if (legacyUID) {
+			this.uid = legacyUID;
+			return legacyUID;
+		}
+
+		throw new Error(`resolve uid failed: ${String(uidReply.stderr ?? uidReply.stdout ?? '').trim() || 'unknown error'}`);
+	}
+
+	async remoteCommandWithUID(commandArgs = []) {
+		const uid = await this.resolveCurrentUID();
+		const args = [...commandArgs];
+		args.splice(1, 0, '--uid', uid);
+		return args;
+	}
+
 	async init() {
 		await this.checkDevTools();
 		if (!(await this.canPublicKey())) {
+			if (this.isBuildRemoteMode()) {
+				throw new Error(`ssh login failed for remote ${this.buildRemote.sshTarget}:${this.buildRemote.sshPort}`);
+			}
 			// 如果不能 ssh public key 登录则提示授权申请，否则后面可能会出现 rsync 询问密码的问题
 			await this.sshApplyGrant();
 		}
 	}
 
 	async checkDevTools() {
+		if (this.isBuildRemoteMode()) {
+			try {
+				await this.remoteCommon(['version']);
+				return;
+			} catch (error) {
+				const detail = normalizeErrorMessage(error);
+				if (detail.includes(`No such container: ${DEBUG_BRIDGE_CONTAINER}`)) {
+					throw new Error(`Lazycat Developer Tools is not running on target box "${this.boxname}". Start app "cloud.lazycat.developer.tools" and retry.`);
+				}
+				if (detail.includes('is not running')) {
+					throw new Error(`Lazycat Developer Tools container is not running on target box "${this.boxname}". Start app "cloud.lazycat.developer.tools" and retry.`);
+				}
+				throw new Error(`Failed to check Lazycat Developer Tools in remote mode.\n${detail || 'unknown error'}`);
+			}
+		}
+
 		let domain = this.domain;
 		if (this.checkUseResolve) {
 			try {
 				const _ipv6 = await resolveDomain(this.domain, true);
 				domain = `[${_ipv6}]`;
-			} catch { }
+			} catch {}
 		}
 		const url = `https://${domain}/bannerfile`;
 		return new Promise((resolve, reject) => {
@@ -87,33 +351,76 @@ export class DebugBridge {
 			ssh.status == 0
 				? resolve(ssh.stdout)
 				: reject(
-					t('lzc_cli.lib.debug_bridge.common_exec_fail', `执行命令 {{ cmd }} {{ args }} 出错\n{{ stdout }}\n{{ stderr }}`, {
-						cmd,
-						args: args.join(' '),
-						stdout: ssh.stdout ?? '',
-						stdout: ssh.stderr ?? '',
-						interpolation: { escapeValue: false }
-					}),
-				);
+						t('lzc_cli.lib.debug_bridge.common_exec_fail', `执行命令 {{ cmd }} {{ args }} 出错\n{{ stdout }}\n{{ stderr }}`, {
+							cmd,
+							args: args.join(' '),
+							stdout: ssh.stdout ?? '',
+							stdout: ssh.stderr ?? '',
+							interpolation: { escapeValue: false },
+						}),
+					);
 		});
 	}
 
 	async install(lpkPath, pkgId) {
 		const stream = fs.createReadStream(lpkPath);
+		if (this.isBuildRemoteMode()) {
+			const commandArgs = await this.remoteCommandWithUID(['install']);
+			if (pkgId) {
+				commandArgs.push('--pkgId', pkgId);
+			}
+			const ssh = spawn(sshBinary(), this.remoteBridgeArgs(commandArgs), {
+				shell: false,
+				stdio: ['pipe', 'pipe', 'pipe'],
+			});
+			const output = streamInstallOutput(ssh, { printStdout: false, printStderr: false });
+			stream.pipe(ssh.stdin);
+			return new Promise((resolve, reject) => {
+				ssh.on('error', (error) => {
+					reject(error);
+				});
+				ssh.on('close', (code) => {
+					if (code == 0) {
+						resolve();
+						return;
+					}
+					const detail = extractInstallErrorDetail(`${output.getStdout()}\n${output.getStderr()}`);
+					reject(detail || t('lzc_cli.lib.debug_bridge.install_fail', 'install 失败'));
+				});
+			});
+		}
+
 		const resolvedIp = await resolveDomain(this.domain);
 		const ssh = spawn(sshBinary(), [...sshCmdArgs(`box@${resolvedIp}`), `install --uid ${this.uid}`, pkgId ? `--pkgId ${pkgId}` : ''], {
 			shell: true,
-			stdio: ['pipe', 'inherit', 'inherit'],
+			stdio: ['pipe', 'pipe', 'pipe'],
 		});
+		const output = streamInstallOutput(ssh, { printStdout: false, printStderr: false });
 		stream.pipe(ssh.stdin);
 		return new Promise((resolve, reject) => {
+			ssh.on('error', (error) => {
+				reject(error);
+			});
 			ssh.on('close', (code) => {
-				code == 0 ? resolve() : reject(t('lzc_cli.lib.debug_bridge.install_fail', 'install 失败'));
+				if (code == 0) {
+					resolve();
+					return;
+				}
+				const detail = extractInstallErrorDetail(`${output.getStdout()}\n${output.getStderr()}`);
+				reject(detail || t('lzc_cli.lib.debug_bridge.install_fail', 'install 失败'));
 			});
 		});
 	}
 
 	async canPublicKey() {
+		if (this.isBuildRemoteMode()) {
+			const ssh = spawn.sync(sshBinary(), [...this.remoteSshArgsRaw(), 'true'], {
+				shell: false,
+				encoding: 'utf-8',
+				stdio: ['pipe', 'pipe', 'pipe'],
+			});
+			return ssh.status === 0;
+		}
 		try {
 			await this.common(sshBinary(), [...sshCmdArgs(`box@${this.domain}`)]);
 			return true;
@@ -128,6 +435,9 @@ export class DebugBridge {
 	}
 
 	async sshApplyGrant() {
+		if (this.isBuildRemoteMode()) {
+			throw new Error('build remote mode requires ssh key authorization in host ssh service');
+		}
 		const keys = await findSshPublicKey();
 		logger.info(t('lzc_cli.lib.debug_bridge.ssh_apply_grant_not_exist_tips', '检测到您当前的环境还没有添加 ssh 公钥到 ‘懒猫开发者工具’ 中，请选择您需要添加的公钥类型'));
 		const sshInfo = await selectSshPublicKey(keys);
@@ -146,7 +456,7 @@ export class DebugBridge {
 					boxname: this.boxname,
 					domain: this.domain,
 					pk,
-					interpolation: { escapeValue: false }
+					interpolation: { escapeValue: false },
 				},
 			),
 		);
@@ -154,21 +464,52 @@ export class DebugBridge {
 	}
 
 	async status(appId) {
+		if (this.isBuildRemoteMode()) {
+			return this.remoteCommon(await this.remoteCommandWithUID(['status', appId]));
+		}
 		return this.common(sshBinary(), [...sshCmdArgs(`box@${this.domain}`), `status --uid ${this.uid}`, appId]);
 	}
 
+	async info(appId) {
+		let stdout;
+		if (this.isBuildRemoteMode()) {
+			stdout = await this.remoteCommon(await this.remoteCommandWithUID(['info', appId]));
+		} else {
+			stdout = await this.common(sshBinary(), [...sshCmdArgs(`box@${this.domain}`), `info --uid ${this.uid}`, appId]);
+		}
+		try {
+			return JSON.parse(stdout);
+		} catch (error) {
+			throw new Error(`parse app info failed: ${error.message}`);
+		}
+	}
+
 	async isDevshell(appId) {
 		await this.backendVersion020();
+		if (this.isBuildRemoteMode()) {
+			const stdout = await this.remoteCommon(await this.remoteCommandWithUID(['isDevshellV2', appId]));
+			return stdout.trim() == 'true';
+		}
 		const stdout = await this.common(sshBinary(), [...sshCmdArgs(`box@${this.domain}`), `isDevshellV2 --uid ${this.uid}`, appId]);
 		return stdout == 'true';
 	}
 
 	async resume(appId) {
+		if (this.isBuildRemoteMode()) {
+			return this.remoteCommon(await this.remoteCommandWithUID(['resume', appId]));
+		}
 		return this.common(sshBinary(), [...sshCmdArgs(`box@${this.domain}`), `resume --uid ${this.uid}`, appId]);
 	}
 
+	async pause(appId) {
+		if (this.isBuildRemoteMode()) {
+			return this.remoteCommon(await this.remoteCommandWithUID(['pause', appId]));
+		}
+		return this.common(sshBinary(), [...sshCmdArgs(`box@${this.domain}`), `pause --uid ${this.uid}`, appId]);
+	}
+
 	async version() {
-		const output = await this.common(sshBinary(), [...sshCmdArgs(`box@${this.domain}`), `version`]);
+		const output = this.isBuildRemoteMode() ? await this.remoteCommon(['version']) : await this.common(sshBinary(), [...sshCmdArgs(`box@${this.domain}`), `version`]);
 		logger.debug(`backend version:\n${output}`);
 		try {
 			const data = JSON.parse(output);
@@ -179,6 +520,14 @@ export class DebugBridge {
 	}
 
 	async uninstall(appId, deleteAppData = false) {
+		if (this.isBuildRemoteMode()) {
+			const commandArgs = await this.remoteCommandWithUID(['uninstall']);
+			if (deleteAppData) {
+				commandArgs.push('--delete-data');
+			}
+			commandArgs.push(appId);
+			return this.remoteCommon(commandArgs);
+		}
 		return this.common(sshBinary(), [...sshCmdArgs(`box@${this.domain}`), `uninstall --uid ${this.uid}`, deleteAppData ? '--delete-data' : '', appId]);
 	}
 
@@ -195,16 +544,28 @@ export class DebugBridge {
 			await sleep(100);
 		}
 
-		const resolvedIp = await resolveDomain(this.domain);
-
-		const stream = spawn(
-			sshBinary(),
-			[...sshCmdArgs(`box@${resolvedIp}`), '-t', 'devshell', `--uid ${this.uid}`, isUserApp ? '--userapp' : '', appId, '/bin/sh', '/lzcapp/pkg/content/devshell/exec.sh'],
-			{
-				shell: true,
+		let stream;
+		if (this.isBuildRemoteMode()) {
+			const commandArgs = await this.remoteCommandWithUID(['devshell']);
+			if (isUserApp) {
+				commandArgs.push('--userapp');
+			}
+			commandArgs.push(appId, '/bin/sh', '/lzcapp/pkg/content/devshell/exec.sh');
+			stream = spawn(sshBinary(), this.remoteBridgeArgs(commandArgs, { tty: true }), {
+				shell: false,
 				stdio: 'inherit',
-			},
-		);
+			});
+		} else {
+			const resolvedIp = await resolveDomain(this.domain);
+			stream = spawn(
+				sshBinary(),
+				[...sshCmdArgs(`box@${resolvedIp}`), '-t', 'devshell', `--uid ${this.uid}`, isUserApp ? '--userapp' : '', appId, '/bin/sh', '/lzcapp/pkg/content/devshell/exec.sh'],
+				{
+					shell: true,
+					stdio: 'inherit',
+				},
+			);
+		}
 		return new Promise((resolve, reject) => {
 			stream.on('close', (code) => {
 				code == 0 ? resolve() : reject();
@@ -218,51 +579,481 @@ export class DebugBridge {
 	}
 
 	async buildImage(label, contextTar) {
-		const backendVersion = await this.version();
-
 		const tag = `debug.bridge/${label}`;
-		const resolvedIp = await resolveDomain(this.domain);
 		const stream = fs.createReadStream(contextTar);
-
-		const buildStream = spawn(sshBinary(), [...sshCmdArgs(`box@${resolvedIp}`), `build --tag ${tag}`], {
-			shell: true,
-			stdio: ['pipe', 'inherit', 'inherit'],
-		});
+		let buildStream;
+		const buildArgs = ['build', '--tag', tag];
+		if (this.isBuildRemoteMode()) {
+			buildStream = spawn(sshBinary(), this.remoteBridgeArgs(buildArgs), {
+				shell: false,
+				stdio: ['pipe', 'inherit', 'inherit'],
+			});
+		} else {
+			const resolvedIp = await resolveDomain(this.domain);
+			buildStream = spawn(sshBinary(), [...sshCmdArgs(`box@${resolvedIp}`), ['build', '--tag', tag].join(' ')], {
+				shell: true,
+				stdio: ['pipe', 'inherit', 'inherit'],
+			});
+		}
 		stream.pipe(buildStream.stdin);
 		return new Promise((resolve, reject) => {
 			buildStream.on('close', (code) => {
-				code == 0
-					? resolve(compareVersions('0.1.12', backendVersion) >= 0 ? `127.0.0.1:5000/${tag}` : `dev.${this.boxname}.heiyu.space/${tag}`)
-					: reject(t('lzc_cli.lib.debug_bridge.build_image_fail', `在微服中构建 image 失败`));
+				code == 0 ? resolve(tag) : reject(t('lzc_cli.lib.debug_bridge.build_image_fail', `在微服中构建 image 失败`));
 			});
 		}).finally(() => {
 			fs.rmSync(contextTar);
 		});
 	}
 
+	async buildImageForPack(label, contextTar) {
+		const tag = `debug.bridge/${label}`;
+		const stream = fs.createReadStream(contextTar);
+		let buildStream;
+		const isBuildPackResultLine = (line) => {
+			const trimmed = String(line ?? '').trim();
+			if (!trimmed || !trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+				return false;
+			}
+			try {
+				const parsed = JSON.parse(trimmed);
+				return (
+					parsed &&
+					typeof parsed === 'object' &&
+					typeof parsed.tag === 'string' &&
+					typeof parsed.archiveKey === 'string' &&
+					typeof parsed.imageID === 'string' &&
+					Array.isArray(parsed.diffIDs)
+				);
+			} catch {
+				return false;
+			}
+		};
+		if (this.isBuildRemoteMode()) {
+			buildStream = spawn(sshBinary(), this.remoteBridgeArgs(['build-pack', '--tag', tag]), {
+				shell: false,
+				stdio: ['pipe', 'pipe', 'inherit'],
+			});
+		} else {
+			const resolvedIp = await resolveDomain(this.domain);
+			buildStream = spawn(sshBinary(), [...sshCmdArgsRaw(`box@${resolvedIp}`), 'build-pack', '--tag', tag], {
+				shell: false,
+				stdio: ['pipe', 'pipe', 'inherit'],
+			});
+		}
+		stream.pipe(buildStream.stdin);
+
+		return new Promise((resolve, reject) => {
+			let output = '';
+			let stdoutLineBuffer = '';
+			buildStream.stdout.on('data', (chunk) => {
+				const text = chunk.toString();
+				output += text;
+				stdoutLineBuffer += text;
+				while (true) {
+					const lineEndIndex = stdoutLineBuffer.indexOf('\n');
+					if (lineEndIndex < 0) {
+						break;
+					}
+					const lineWithNewline = stdoutLineBuffer.slice(0, lineEndIndex + 1);
+					stdoutLineBuffer = stdoutLineBuffer.slice(lineEndIndex + 1);
+					const line = lineWithNewline.replace(/\r?\n$/, '');
+					if (!isBuildPackResultLine(line)) {
+						process.stdout.write(lineWithNewline);
+					}
+				}
+			});
+			buildStream.on('error', (error) => {
+				reject(error);
+			});
+			buildStream.on('close', (code) => {
+				if (stdoutLineBuffer) {
+					if (!isBuildPackResultLine(stdoutLineBuffer)) {
+						process.stdout.write(stdoutLineBuffer);
+					}
+					stdoutLineBuffer = '';
+				}
+				if (code !== 0) {
+					reject(new Error('build-pack failed'));
+					return;
+				}
+				try {
+					const line = output
+						.split(/\r?\n/)
+						.map((item) => item.trim())
+						.filter((item) => item !== '')
+						.at(-1);
+					if (!line) {
+						throw new Error('build-pack output is empty');
+					}
+					const payload = JSON.parse(line);
+					resolve(payload);
+				} catch (error) {
+					reject(new Error(`parse build-pack output failed: ${error.message}`));
+				}
+			});
+		}).finally(() => {
+			fs.rmSync(contextTar, { force: true });
+		});
+	}
+
 	async lzcDocker(argv) {
 		await this.backendVersion020();
+		const stream = this.isBuildRemoteMode()
+			? spawn(sshBinary(), this.remoteBridgeArgs(['lzc-docker', ...argv], { tty: true }), {
+					shell: false,
+					stdio: 'inherit',
+				})
+			: spawn(sshBinary(), [...sshCmdArgs(`box@${await resolveDomain(this.domain)}`), '-t', 'lzc-docker', ...argv], {
+					shell: true,
+					stdio: 'inherit',
+				});
+		return new Promise((resolve, reject) => {
+			stream.on('close', (code) => {
+				code == 0 ? resolve() : reject();
+			});
+		});
+	}
+
+	async lzcDockerPipe(argv, stdinStream = null) {
+		await this.backendVersion020();
+		let stream;
+		if (this.isBuildRemoteMode()) {
+			stream = spawn(sshBinary(), this.remoteBridgeArgs(['lzc-docker', ...argv]), {
+				shell: false,
+				stdio: ['pipe', 'inherit', 'inherit'],
+			});
+		} else {
+			const resolvedIp = await resolveDomain(this.domain);
+			stream = spawn(sshBinary(), [...sshCmdArgsRaw(`box@${resolvedIp}`), 'lzc-docker', ...argv], {
+				shell: false,
+				stdio: ['pipe', 'inherit', 'inherit'],
+			});
+		}
 
-		const resolvedIp = await resolveDomain(this.domain);
-		const stream = spawn(sshBinary(), [...sshCmdArgs(`box@${resolvedIp}`), '-t', 'lzc-docker', ...argv], {
-			shell: true,
-			stdio: 'inherit',
+		return await new Promise((resolve, reject) => {
+			let done = false;
+			const fail = (error) => {
+				if (done) {
+					return;
+				}
+				done = true;
+				try {
+					stream.kill('SIGKILL');
+				} catch {}
+				reject(error);
+			};
+			stream.on('error', (error) => fail(error));
+			stream.on('close', (code) => {
+				if (done) {
+					return;
+				}
+				done = true;
+				code == 0 ? resolve() : reject(t('lzc_cli.lib.debug_bridge.lzc_docker_capture_fail', 'lzc-docker command failed'));
+			});
+			if (stdinStream) {
+				stdinStream.on('error', (error) => fail(error));
+				stdinStream.pipe(stream.stdin);
+				return;
+			}
+			stream.stdin.end();
 		});
+	}
+
+	async lzcDockerPull(image) {
+		await this.backendVersion020();
+		let stream;
+		if (this.isBuildRemoteMode()) {
+			stream = spawn(sshBinary(), this.remoteBridgeArgs(['lzc-docker', 'pull', image]), {
+				shell: false,
+				stdio: 'inherit',
+			});
+		} else {
+			const resolvedIp = await resolveDomain(this.domain);
+			stream = spawn(sshBinary(), [...sshCmdArgsRaw(`box@${resolvedIp}`), 'lzc-docker', 'pull', image], {
+				shell: false,
+				stdio: 'inherit',
+			});
+		}
 		return new Promise((resolve, reject) => {
 			stream.on('close', (code) => {
-				code == 0 ? resolve() : reject();
+				code == 0 ? resolve() : reject(t('lzc_cli.lib.debug_bridge.lzc_docker_pull_fail', `lzc-docker pull 失败: ${image}`));
 			});
 		});
 	}
 
-	async lzcDockerCompose(argv) {
+	async lzcDockerSave(images, outputPath) {
+		await this.backendVersion020();
+		if (!images || images.length == 0) {
+			throw t('lzc_cli.lib.debug_bridge.lzc_docker_save_images_empty_fail', 'images 不能为空');
+		}
+		const output = fs.createWriteStream(outputPath);
+		let stream;
+		if (this.isBuildRemoteMode()) {
+			stream = spawn(sshBinary(), this.remoteBridgeArgs(['lzc-docker', 'image', 'save', ...images]), {
+				shell: false,
+				stdio: ['ignore', 'pipe', 'inherit'],
+			});
+		} else {
+			const resolvedIp = await resolveDomain(this.domain);
+			stream = spawn(sshBinary(), [...sshCmdArgsRaw(`box@${resolvedIp}`), 'lzc-docker', 'image', 'save', ...images], {
+				shell: false,
+				stdio: ['ignore', 'pipe', 'inherit'],
+			});
+		}
+		stream.stdout.pipe(output);
+
+		return new Promise((resolve, reject) => {
+			let done = false;
+			const fail = (err) => {
+				if (done) {
+					return;
+				}
+				done = true;
+				try {
+					stream.kill('SIGKILL');
+				} catch {}
+				try {
+					output.destroy();
+				} catch {}
+				try {
+					fs.rmSync(outputPath, { force: true });
+				} catch {}
+				reject(err);
+			};
+
+			stream.on('error', (e) => {
+				fail(e);
+			});
+			output.on('error', (e) => {
+				fail(e);
+			});
+			stream.on('close', (code) => {
+				if (done) {
+					return;
+				}
+				output.end(() => {
+					if (code == 0) {
+						done = true;
+						resolve();
+						return;
+					}
+					fail(t('lzc_cli.lib.debug_bridge.lzc_docker_save_fail', 'lzc-docker image save 失败'));
+				});
+			});
+		});
+	}
+
+	async packImages(imagesSpec, outputPath) {
+		await this.backendVersion020();
+		if (!Array.isArray(imagesSpec) || imagesSpec.length === 0) {
+			throw new Error('imagesSpec cannot be empty');
+		}
+		const spec = Buffer.from(
+			JSON.stringify({
+				images: imagesSpec,
+			}),
+		).toString('base64');
+
+		const output = fs.createWriteStream(outputPath);
+		let stream;
+		if (this.isBuildRemoteMode()) {
+			stream = spawn(sshBinary(), this.remoteBridgeArgs(['pack-images', '--spec', spec]), {
+				shell: false,
+				stdio: ['ignore', 'pipe', 'inherit'],
+			});
+		} else {
+			const resolvedIp = await resolveDomain(this.domain);
+			stream = spawn(sshBinary(), [...sshCmdArgsRaw(`box@${resolvedIp}`), 'pack-images', '--spec', spec], {
+				shell: false,
+				stdio: ['ignore', 'pipe', 'inherit'],
+			});
+		}
+		stream.stdout.pipe(output);
+
+		return new Promise((resolve, reject) => {
+			let done = false;
+			const fail = (err) => {
+				if (done) {
+					return;
+				}
+				done = true;
+				try {
+					stream.kill('SIGKILL');
+				} catch {}
+				try {
+					output.destroy();
+				} catch {}
+				try {
+					fs.rmSync(outputPath, { force: true });
+				} catch {}
+				reject(err);
+			};
+
+			stream.on('error', (e) => {
+				fail(e);
+			});
+			output.on('error', (e) => {
+				fail(e);
+			});
+			stream.on('close', (code) => {
+				if (done) {
+					return;
+				}
+				output.end(() => {
+					if (code == 0) {
+						done = true;
+						resolve();
+						return;
+					}
+					fail(new Error('pack-images failed'));
+				});
+			});
+		});
+	}
+
+	async lzcDockerCapture(argv) {
+		await this.backendVersion020();
+		let stream;
+		if (this.isBuildRemoteMode()) {
+			stream = spawn(sshBinary(), this.remoteBridgeArgs(['lzc-docker', ...argv]), {
+				shell: false,
+				stdio: ['ignore', 'pipe', 'inherit'],
+			});
+		} else {
+			const resolvedIp = await resolveDomain(this.domain);
+			stream = spawn(sshBinary(), [...sshCmdArgsRaw(`box@${resolvedIp}`), 'lzc-docker', ...argv], {
+				shell: false,
+				stdio: ['ignore', 'pipe', 'inherit'],
+			});
+		}
+
+		return await new Promise((resolve, reject) => {
+			let output = '';
+			stream.stdout.on('data', (chunk) => {
+				output += chunk.toString();
+			});
+			stream.on('error', (err) => reject(err));
+			stream.on('close', (code) => {
+				if (code == 0) {
+					resolve(output.trim());
+					return;
+				}
+				reject(t('lzc_cli.lib.debug_bridge.lzc_docker_capture_fail', 'lzc-docker command failed'));
+			});
+		});
+	}
+
+	async lzcDockerComposeCapture(argv) {
 		await this.backendVersion020();
+		let stream;
+		if (this.isBuildRemoteMode()) {
+			stream = spawn(sshBinary(), this.remoteBridgeArgs(['lzc-docker-compose', ...argv]), {
+				shell: false,
+				stdio: ['ignore', 'pipe', 'pipe'],
+			});
+		} else {
+			const resolvedIp = await resolveDomain(this.domain);
+			stream = spawn(sshBinary(), [...sshCmdArgsRaw(`box@${resolvedIp}`), 'lzc-docker-compose', ...argv], {
+				shell: false,
+				stdio: ['ignore', 'pipe', 'pipe'],
+			});
+		}
+
+		return await new Promise((resolve, reject) => {
+			let stdout = '';
+			let stderr = '';
+			stream.stdout.on('data', (chunk) => {
+				stdout += chunk.toString();
+			});
+			stream.stderr.on('data', (chunk) => {
+				stderr += chunk.toString();
+			});
+			stream.on('error', (err) => reject(err));
+			stream.on('close', (code) => {
+				if (code == 0) {
+					resolve(stdout.trim());
+					return;
+				}
+				reject(new Error(`lzc-docker-compose command failed\n${stdout}\n${stderr}`));
+			});
+		});
+	}
+
+	async hostReadFile(pathname) {
+		const target = String(pathname ?? '').trim();
+		if (!target) {
+			throw new Error('hostReadFile path is empty');
+		}
+		if (this.isBuildRemoteMode()) {
+			const result = this.remoteHostExec(['cat', target]);
+			if (result.status === 0) {
+				return String(result.stdout ?? '');
+			}
+			throw new Error(`read remote file failed: ${target}`);
+		}
 
 		const resolvedIp = await resolveDomain(this.domain);
-		const stream = spawn(sshBinary(), [...sshCmdArgs(`box@${resolvedIp}`), '-t', 'lzc-docker-compose', ...argv], {
-			shell: true,
-			stdio: 'inherit',
+		const stream = spawn(sshBinary(), [...sshCmdArgsRaw(`box@${resolvedIp}`), 'cat', target], {
+			shell: false,
+			stdio: ['ignore', 'pipe', 'pipe'],
 		});
+		return await new Promise((resolve, reject) => {
+			let stdout = '';
+			let stderr = '';
+			stream.stdout.on('data', (chunk) => {
+				stdout += chunk.toString();
+			});
+			stream.stderr.on('data', (chunk) => {
+				stderr += chunk.toString();
+			});
+			stream.on('error', (err) => reject(err));
+			stream.on('close', (code) => {
+				if (code === 0) {
+					resolve(stdout);
+					return;
+				}
+				reject(new Error(`read host file failed\n${stderr}`));
+			});
+		});
+	}
+
+	async lzcDockerImageRepoDigests(image) {
+		const inspect = await this.lzcDockerImageInspect(image);
+		const repoDigests = inspect?.RepoDigests;
+		if (!Array.isArray(repoDigests)) {
+			return [];
+		}
+		return repoDigests.filter((item) => typeof item === 'string' && item.trim() !== '');
+	}
+
+	async lzcDockerImageInspect(image) {
+		const output = await this.lzcDockerCapture(['image', 'inspect', image]);
+		if (!output) {
+			throw new Error(`lzc-docker image inspect output is empty: ${image}`);
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(output);
+		} catch (error) {
+			throw new Error(`failed to parse image inspect output for ${image}: ${error.message}`);
+		}
+		if (!Array.isArray(parsed) || parsed.length === 0 || !parsed[0] || typeof parsed[0] !== 'object') {
+			throw new Error(`invalid image inspect output for ${image}`);
+		}
+		return parsed[0];
+	}
+
+	async lzcDockerCompose(argv) {
+		await this.backendVersion020();
+		const stream = this.isBuildRemoteMode()
+			? spawn(sshBinary(), this.remoteBridgeArgs(['lzc-docker-compose', ...argv], { tty: true }), {
+					shell: false,
+					stdio: 'inherit',
+				})
+			: spawn(sshBinary(), [...sshCmdArgs(`box@${await resolveDomain(this.domain)}`), '-t', 'lzc-docker-compose', ...argv], {
+					shell: true,
+					stdio: 'inherit',
+				});
 		return new Promise((resolve, reject) => {
 			stream.on('close', (code) => {
 				code == 0 ? resolve() : reject();