---
title: Lenso Console
description: 连接精确 System、加载 Module Surface，并检查直接运维状态。
---

Lenso Console 是独立安装、面向运维人员的 System Plane，负责一个 Lenso
System。其 Shell、API、Worker、Auth 域、Registry 与 Store 均独立于受观察的
业务 Service 运行。

Console 职责刻意保持狭窄：连接、报告状态、加载精确 Module Surface，以及调用
目标持有的强类型操作。它不会创建、部署、接管、删除、发布、升级、回滚或
协调生产 Workload。

## 连接本地目标

从已经组合的 Host 目录启动完整的已连接本地路径：

```sh
cd ./support-desk
lenso dev up --console-root ../lenso-console
```

该命令启动 Host、auto-start Provider Service 与 Console，创建仅限 loopback 的
已签名 Enrollment Material，协调 Module 自有 UI Artifact，并在报告 System
Ready 前连接精确拓扑。

对于单独准备的 Connection Bundle，使用同一个公开且幂等的入口：

```sh
LENSO_CONSOLE_TOKEN='<operator-session-token>' \
  lenso console connect \
  --console-url http://127.0.0.1:3030 \
  --bundle .lenso/console-connect.json
```

非交互操作请通过 `--token-file` 使用权限受限的普通文件。Bundle 绑定已签名的
Enrollment Receipt、可选的精确 Console Composition Artifact Effect，以及由
Digest 绑定的 System Connection Request。

## 底层 Enrollment Contract

Support Desk 本地验收把已签名的双边交换提交到：

```text
POST /api/console/v1/enrollment-receipts
```

Body 只包含 `{offer, receipt, baseUrl}`，Route 要求
`console.system.connect`。Console 使用仅服务端可见、按白名单配置的 Ed25519
信任项校验双方签名，然后保存精确 Enrollment Grant 与 Receipt。当前受支持切片
要求 `baseUrl` 是 loopback 目标。CLI 自有 `lenso-local-control-adapter` 以
`workload-control:<system>` 绑定，不使用业务 Enrollment；其余每个拓扑 Service
都必须具备 active signed Enrollment。

该 Endpoint 不是远程或生产自助 Enrollment。远程生产目标仍需要经过批准的
mTLS 与证书固定 Transport Seam。

## 底层 System Connection

公开连接边界是：

```text
POST /api/console/v1/system/connect
```

经过认证的请求包含一份精确 `lenso.system.v2` 拓扑、其 SHA-256 摘要，以及
同一 System 的 Management Binding。Console 会先校验 Service、Module、
Workload、Adapter、权限与 Policy 一致，再保存连接。

读取完整 System 需要 `console.system.read`；连接需要
`console.system.connect`。Service-scoped Grant 无法授权这两个路由。

未签名 Registry 写入绝不是连接捷径。Connect 会校验精确的活动 Enrollment、
Management Binding 与已发布 Core Contract。

## 读取状态

```text
GET /api/console/v1/system
```

响应与 **Services** 页面显示每个对象的直接状态：

| 状态 | 含义 |
| --- | --- |
| `connected` | 精确合约、摘要、Binding 与在线目标一致。 |
| `unavailable` | 当前无法观察声明的目标；原因会指出失败边界。 |
| `incompatible` | 协议、Schema、制品或能力不匹配。 |
| `unmanaged` | Observed 或 Enrolled 对象位于当前拓扑与 Management Binding 之外。 |

Console 不会合成第二套应用总分。Service 可以保持 connected，同时某个 Module
或 Adapter 显示自己的可操作状态。

## Module Surface

Module 自有 UI 是与 Manifest 位于同一个 Module Release 的不可变
`console_ui_esm` 制品。加载到 Shell 前，Console 会校验制品摘要、生成的
`lenso.console-module.v1` Manifest、协议范围、Entry、Style、Module 身份，
以及精确 System Receipt。

Surface 使用公开 `@lenso/console-module-api`、`@lenso/console-ui` 与注入的
强类型 Host API。读取或修改业务记录时，它通过同源 Surface Gateway 调用
生成客户端。服务端对每次请求重新
检查已认证 Console Actor、Module 身份、制品摘要、Module Release 摘要、
Contract 摘要，以及 Surface Grant 允许的 Operation ID。

Service Bearer Token 与 Adapter 凭据只保留在服务端。浏览器代码不会获得它们，
也不会直连业务 Service。

制品开发参见 [Module Console UI](/docs/zh/console-packages)；操作设计参见
[Business API 与 Console Surface](/docs/zh/admin-surfaces)。

## Workload Control

Workload 路由是以下路径下的同源 Console Service Endpoint：

```text
/api/console/v1/systems/{systemId}/workloads
```

已连接拓扑必须命名稳定 Workload Reference，并绑定强类型
`lenso.workload-control.v1` Adapter。Console 派生 Actor，只发送声明的操作，
持久化异步 Operation Record，再按 Operation 身份轮询到终态。

本地 Adapter 可以支持 Suspend/Resume 或 Stop/Start。Adapter 无法访问时，
观察结果为 `unknown` 且没有修订。变更会 fail closed，不排队、不改道，也不从
进程状态猜测结果。活动 Adapter 与 Console Workload 不能通过此路径控制自己。

## 访问控制

正式安装的 Console Service 没有默认凭据。通过外部安装权限创建第一个密码
用户和经过审计的 Operator Role：

```sh
lenso console operator bootstrap \
  --console-root ../lenso-console \
  --console-url http://127.0.0.1:3030 \
  --identifier admin@example.com
```

交互终端会隐藏密码输入。自动化必须使用 `--password-stdin` 或通过
`--password-file` 读取权限受限的普通文件。不要把 Service Bearer Token 放入
浏览器构建。

认证能力边界参见 [Auth Capabilities](/docs/zh/auth-capabilities)。

## 运维边界

- Console 报告已连接应用状态，不持有应用组合。
- 业务写入通过声明的 Business API 与 Surface Grant。
- 强类型管理操作在其所属 Service 或 Adapter 中执行。
- 生产发布与部署位于 Console 之外。
- Console 不可用不会停止 Autonomous Service 的业务执行。