本地实训环境与连接指南

xkat 平台默认支持在网页浏览器中直接完成绝大多数编程练习。
在涉及 Arduino/嵌入式硬件控制或独立隔离虚拟机（Ubuntu Lab VM）的高阶课程中，可通过**本地代理（xkat-cli）**将浏览器与您的电脑安全连接。

安全提示：本地代理不会对外网开放端口，仅在您的电脑本地内部（localhost:127.0.0.1）通信。所有实训命令均在获得您的明确许可后执行。

1. 快速入门 (Quick Start)

打开电脑上的终端（PowerShell、Terminal 或 Bash），执行以下一行命令：

# 1. 无需全局安装，直接运行（推荐）
npx -y xkat-cli@latest up

# 2. 或全局安装后运行
npm install -g xkat-cli@latest
xkat-cli up

命令运行后，xkat 网页播放器的连接状态将在数秒内自动切换为**【在线】**。

终端：打开 PowerShell、Windows Terminal 或命令提示符（CMD）。
运行命令：
npx -y xkat-cli@latest up
虚拟机（Ubuntu Lab VM）实训：
- 推荐使用 64 位 Windows 10/11。
- 打开任务管理器（Ctrl+Shift+Esc）→【性能】选项卡，确认已显示虚拟化：已启用。

若连接过程中遇到异常，请参考以下方案：

1. 提示找不到 'npx' 或 'node' 命令

说明电脑尚未安装 Node.js 运行环境。

Windows：在 Node.js 官网下载并安装 LTS 版本，或在 PowerShell 中执行：
winget install OpenJS.NodeJS.LTS
macOS：在官网下载安装程序，或使用 Homebrew 安装：
brew install node

Linux (Ubuntu/Debian)：

sudo apt update && sudo apt install -y nodejs npm

安装完成后，重启终端窗口并重新执行 npx -y xkat-cli@latest up。

2. 网页持续显示【等待连接】或连接失败

保持终端开启：请确保运行代理的终端窗口未被关闭。
清理端口并重启：若 38000–38050 端口被残留进程占用，请在终端执行：
npx -y xkat-cli@latest down npx -y xkat-cli@latest up
防火墙与安全软件：请确认公司/学校网络的安全软件未拦截 127.0.0.1 本地回环通信。

3. 虚拟机（Ubuntu Lab VM）创建或启动失败

Windows 虚拟化检查：
- 若任务管理器显示虚拟化为“已禁用”，请在开机时进入 BIOS/UEFI 开启 Intel VT-x 或 AMD SVM 虚拟化支持。
完全重置虚拟机：
- 运行以下命令可完全重置并重新创建虚拟机：
  npx -y xkat-cli@latest lab reset

4. 实训结束后如何停止代理

在终端中运行以下命令，即可安全释放后台资源：

npx -y xkat-cli@latest down