懒猫微服 LightOS WebShell

本项目是懒猫微服 LightOS 的 WebShell Provider，用于在浏览器中连接、管理和使用 LightOS 实例内的终端环境。

它通过 LPK Resource Export 声明 lightos.webshell 能力，由 LightOS Admin 发现并打开。安装后，用户可以从 LightOS 的 WebShell 入口进入目标实例，直接在网页中进行命令行操作，并使用标签、分屏、文件传输、服务转发和快捷键等能力。

项目目标

LightOS WebShell 的目标是为懒猫微服提供一个开箱即用的网页终端：

• 面向 LightOS 实例，而不是普通独立服务器。
• 与 LightOS Admin、实例列表、服务转发和 LPK 安装流程集成。
• 在浏览器刷新、网络短暂断开或切换页面后，尽可能保留已有终端会话。
• 同时兼顾桌面端和移动端操作，提供标签页、分屏、历史回放、文件管理和快捷键体验。

主要功能

终端和会话

• 自动发现 LightOS 实例，并在多个运行中的实例之间切换。
• 在浏览器中打开实例内 Shell，支持原始终端输入输出、窗口尺寸同步和 WebSocket 连接。
• 使用实例内的持久 agent 管理终端工作区，刷新页面、重新打开页面或短暂断网后可重新连接到已有 tab 和 pane。
• 服务升级后优先复用兼容的旧 agent，尽量保留正在运行的终端会话；协议不兼容时会明确提示。
• 支持终端输出历史回放，减少重连后的上下文丢失。
• LightOS 实例端使用 PTY 原始字节范围游标同步历史；网络重连只获取本地终端缺失的增量，页面刷新优先从按 pane 隔离的本地缓存恢复后再接续服务端输出。
• 支持终端活动检测、自动标签命名、忙闲状态和当前工作目录显示。

标签、分屏和搜索

• 支持多标签页、上下/左右分屏、窗格关闭、标签重命名和标签排序。
• 支持标签总览，可快速查看、切换、新建、关闭和拖拽排序标签。
• 支持终端内容搜索、结果跳转、全选缓冲区、复制选区、粘贴和链接识别/复制。
• 支持上下文菜单和键盘快捷键操作。

文件管理

• 支持上传文件到目标实例 /tmp，上传成功后自动复制文件路径。
• 支持从剪贴板读取文件并上传。
• 支持浏览实例内文件系统，从当前终端目录开始打开文件管理器。
• 支持下载单个文件；下载多个文件或目录时自动打包为 zip。
• 上传单批最多 32 个文件，单文件最大 2GB；下载一次最多选择 64 个条目。

设置和外观

• 支持主题切换，主题列表来自 runtime/static/themes.json。
• 支持内置字体、自定义字体上传、字体删除和系统默认字体恢复。
• 支持滚动历史行数设置，范围为 100 到 100000 行。
• 支持桌面端鼠标选区自动复制开关。
• 支持移动端像素级滚动开关。
• 支持手机快捷键和 PC 快捷键自定义、排序和恢复默认。

移动端体验

• 支持双行手机快捷键工具栏，可配置输入按键或动作。
• 支持移动端操作菜单、选择浮层、触摸选择、长按重复输入和触感反馈开关。
• 支持移动端标签总览和侧滑返回类交互。
• 服务更新提示在移动端使用底部确认面板，避免误触。

LightOS 集成

• 支持服务转发配置，可把实例内 HTTP/HTTPS 服务发布为 LightOS 应用入口。
• 支持服务转发的标题、子域名、路径、图标和跳过认证设置。
• 通过 LightOS Admin 信息识别当前部署，并按账号隔离可访问实例。
• 支持服务端版本变化检测，升级后提示用户刷新并重新连接。

构建和部署

前置条件：

• Go 工具链。
• lzc-cli。
• 可安装 LPK 的懒猫微服环境。

构建 LPK：

lzc-cli project release

安装到目标设备：

lzc-cli app install dist/cloud.lazycat.webshell.lcmd-*.lpk

开发环境也可以直接构建并安装：

lzc-cli project deploy

安装完成后，在 LightOS Admin 的 WebShell Provider 列表中应能看到 LCMD WebShell。

技术说明

• 后端使用 Go 实现，Web UI 通过 /=exec://8080 由 LPK 启动。
• 终端会话通过实例内 persistent agent 管理，并通过 WebSocket 转发到浏览器。
• 实例端终端历史由 persistent agent 作为可信数据源维护，浏览器使用 IndexedDB 按 selector、pane 和 history generation 隔离缓存；client: PC target 继续使用完整历史回放协议。
• 终端渲染使用项目内随包分发的 Ghostty Web 运行时资源。
• 本项目不使用 tmux，也不使用 xterm.js。

许可证

本项目代码使用 PolyForm Noncommercial License 1.0.0 授权，SPDX 标识为 PolyForm-Noncommercial-1.0.0。

这意味着本项目源码允许在非商业场景下使用、复制、修改和分发，但不能用于商业目的。禁止将本项目用于商业产品、商业服务、付费交付、商业集成或其他以商业收益为目的的场景。

完整许可证条款见 LICENSE。第三方文件保留其原始许可证声明，例如 runtime/static/ghostty-web.LICENSE 和 runtime/fonts/LICENSES/ 下的字体许可证。