# lzc-webshell-plugins

**Repository Path**: lazycatcloud/lzc-webshell-plugins

## Basic Information

- **Project Name**: lzc-webshell-plugins
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LightOS WebShell Provider Examples

本仓库是外部 WebShell provider 开发者的参考源，包含 WebShell Provider 开发说明和可运行示例。

## 目录结构

```text
.
├── README.md
├── webshell_provider.md
└── examples/
    ├── demo-webshell/
    └── zellij-webshell/
```

根目录文档说明 provider 对接规范；`examples/` 目录提供不同实现方式的参考代码。

## 开发入口

先阅读 [WebShell Provider 开发说明](./webshell_provider.md)，了解 provider 如何通过 LPK Resource Export 声明能力、如何接收实例 selector、如何访问 LightOS 实例，以及如何使用 Catlink 和 Publish API。

再从 `examples/demo-webshell` 开始。它是最小 PTY 桥接示例，用来学习 provider 声明、实例 selector、`lightosctl exec`、Catlink 和 Publish API：

- `resources/lightos.webshell/default/webshell-provider.json`：provider 声明文件。
- `lzc-build.yml`：通过 `resource_exports` 导出 `lightos.webshell` 资源。
- `package.yml`：声明 LPK 基本信息、`lightos.manage` 权限和 i18n 名称。
- `main.go`：示例后端，包含实例列表、`lightosctl exec`、PTY WebSocket、lightos-admin 信息查询。
- `runtime/static/lightos-catlink-provider.js`：Catlink iframe attach 和状态查询 bridge。
- `runtime/static/main.js`：示例前端，包含实例切换、终端连接、Catlink 状态、Publish 服务列表和创建。

`examples/demo-webshell` 不维护持久会话。页面重连只会重新连接示例后端，不保证用户命令和 shell 状态保留。

`examples/zellij-webshell` 展示如何接入已有 Web terminal/session manager。它包含 zellij Web UI 的专属代理、自动登录和路径适配，不是最小模板。稳定的 WebShell provider 契约以 [WebShell Provider 开发说明](./webshell_provider.md) 为准。

`examples/*/dist/` 是构建产物，可以删除后通过 `lzc-cli project release` 重新生成。

## 前置条件

- Go 工具链。
- `lzc-cli`，用于构建 LPK。
- 可安装 LPK 的 Lazycat Microserver 环境。
- 目标环境中至少有一个 running 状态的 LightOS 实例。
- 当前示例构建目标为 Linux amd64。
- 构建 `examples/zellij-webshell` 时，需要本机可用的 Linux amd64 `zellij` 二进制。

## 构建示例

构建 demo provider：

```sh
cd examples/demo-webshell
lzc-cli project release
```

构建 zellij provider：

```sh
cd examples/zellij-webshell
ZELLIJ_BIN="$(command -v zellij)" lzc-cli project release
```

安装到目标环境：

```sh
cd examples/demo-webshell
<install-lpk-command> dist/cloud.lazycat.webshell.demo-v0.1.0.lpk

cd ../zellij-webshell
<install-lpk-command> dist/cloud.lazycat.webshell.zellij-v0.1.0.lpk
```

`<install-lpk-command>` 替换为当前开发环境支持的 LPK 安装命令。

## 验证示例

安装后，在 lightos-admin 的 WebShell provider 列表中确认 provider 已出现。打开某个 LightOS 实例的 WebShell 时，provider 页面 URL 应包含完整实例 selector：

```text
?name=<name>@<owner_deploy_id>
```

阅读源码时可以忽略 `dist/`，它只保存 release 后的产物。

常见问题：

- provider 没出现在列表：检查 `resource_exports` 是否导出 `lightos.webshell`，以及 `webshell-provider.json` 是否位于 `resources/lightos.webshell/default/`。
- 无法列出或进入实例：检查 `package.yml` 是否声明 `lightos.manage` 权限。
- 页面找不到实例：确认目标环境中存在 running 状态的 LightOS 实例。
- Catlink 或 Publish API 请求失败：跨域请求需要当前用户登录态，并设置 `credentials: "include"`。

Go 编译验证：

```sh
cd examples/demo-webshell
go test ./...

cd ../zellij-webshell
go test ./...
```

## Provider 设计建议

WebShell provider 是普通 LPK 应用。provider 自己负责页面、终端 UI、WebSocket、PTY、tab、pane、tmux、zellij 等实现细节；lightos-admin 负责发现 provider、按实例选择 provider，并打开对应 provider 页面。

建议把终端会话状态维护在目标 LightOS 实例内，例如实例内的 tmux、zellij 或自定义会话进程。provider LPK 后端尽量只负责页面服务、会话发现和 attach 转发，这样 provider 升级或重启时，浏览器可以重新 attach 到实例内已有会话。