---
title: 故障排除
description: 诊断当前 Compose、Run locally、Connect 与 Status 生命周期。
---

请分开检查每个生命周期边界。有效组合不代表进程正在运行；进程正在运行也不
代表 Console 已连接对象。

## 首轮检查

```sh
test -f ./support-desk/lenso.app.json
cd ./support-desk
lenso system dev --system-file ./lenso.app.json --dry-run --json
curl -sS http://127.0.0.1:3030/api/console/v1/system
```

Console 请求还需要具备 `console.system.read` 的已认证 Actor。

## 常见症状

| 症状 | 检查 | 处理 |
| --- | --- | --- |
| 缺少 `lenso.app.json` | Compose 输出目录与 Source Pack 路径 | 从持有该 Pack 的目录重新运行 Compose 命令。 |
| 已连接本地启动失败 | `lenso dev up --console-root ...` 报告的第一个失败阶段 | 修复对应的 Host、Provider、Store、Console、Artifact 或 Connection 阶段后再重试。 |
| 业务 Service 无法 Enrollment | `.lenso/console-connect.json` 中的 Signed Receipt、Allowlist Key 与 loopback `baseUrl` | 修正 Service 身份或合约；不得绕过 Signed Enrollment。 |
| Connect 拒绝业务 Service | Active Signed Enrollment 与发布的 Core Contract | 使用 `lenso console connect` 重新应用精确 Bundle；不要手工编辑 Receipt。 |
| Connect 拒绝拓扑 | Bundle 中的 Topology SHA-256 Digest 与 Management Binding | 从已组合应用重新生成 Bundle；不要在旧 Digest 下提交另一份拓扑。 |
| Local Control Adapter 看似未 Enrollment | Adapter ID 与 Binding | 使用 `lenso-local-control-adapter` 和 `workload-control:<system>`；该 CLI 自有 Adapter 不使用业务 Enrollment。 |
| 缺少 Module Surface | Module Release、UI Artifact、Contract 与 Surface Grant 摘要 | 重新连接回执已绑定所有身份的精确应用。 |
| Adapter Connection 为 `unavailable` | Local Control Adapter 进程与 Target-owned Status Endpoint | 重启本地运行；Workload Observation 保持 `unknown`，变更不会排队。 |
| 对象为 `incompatible` | Reason 中的 Protocol、Schema、Capability 与 Artifact 细节 | 对齐声明的合约，并以相同身份重新连接。 |
| 对象为 `unmanaged` | Observed 或 Enrolled 对象是否属于当前拓扑与 Management Binding | 将其放入有意的新组合，或保持在当前已连接 System 之外。 |
| 产品验收找不到仓库 | 同级 Checkout 名称或 Root Override 变量 | 提供 `LENSO_FRAMEWORK_ROOT`、`LENSO_CLI_ROOT` 与 `LENSO_CONSOLE_ROOT`。 |
| 产品验收无法启动 PostgreSQL | `PATH` 中的 `initdb`、`postgres` 与 `pg_isready` | 安装本地 PostgreSQL Binary，或提供数据库名包含 `acceptance` 的 disposable `LENSO_ACCEPTANCE_DATABASE_URL`。 |
| 浏览器验收无法启动 | Headless Chrome 兼容浏览器与已安装依赖 | 运行 `pnpm install --frozen-lockfile`，再重试显式验收命令。 |

## Compose（组合）

Bare Support Desk Blueprint 包含 `auth`、`notification-worker` 与
`support-api`：

```sh
lenso app compose ./support-desk --blueprint support-desk --apply
```

Support Ticket 与 Story Module 来自验收 Capability Pack，而非 Bare
Blueprint。完整产品命令必须从 `lenso-examples` 仓库根目录运行，参见
[产品蓝图](/docs/zh/product-blueprints)。

Source Pack 使用相对路径时，当前目录会影响 CLI 解析结果。`--apply` 原子写入
生成组合。请检查 `support-desk/lenso.app.json`，不要手工编辑。

## Run locally（本地运行）

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

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

该命令保持在前台，并报告失败的精确 Host、Provider、Store、Console、Artifact
或 Connection 阶段。Ctrl-C 只停止本次调用启动的进程。

只有需要把 Composition 与 Adapter 校验和已连接 Host、Provider、Console 路径
隔离时，才使用 System Sandbox Dry Run：

```sh
lenso system dev --system-file ./lenso.app.json --dry-run --json
```

若上一次 Sandbox Run 仍持有 Adapter Socket 或进程，使用其限定范围的 Cleanup
入口：

```sh
lenso system dev --system-file ./lenso.app.json --cleanup
```

Cleanup 只针对该次本地运行记录的资源。

## Connect（连接）

`lenso dev up --console-root` 会在报告 System Ready 前写入并应用精确的本地
Bundle。重新应用单独准备的 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；
Identity、Release、Artifact、Topology 或 Binding 变化时，应从已组合应用重新生成。

CLI 先把每份 Signed Receipt 提交到底层 Enrollment Boundary，再应用由 Digest
绑定的 System Connection：

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

Console 使用 Server-only Allowlist 校验双方签名。本地 `baseUrl` 必须是
loopback HTTP。System Request 必须包含精确 `lenso.system.v2` 拓扑、其 SHA-256
摘要，以及同一 System 的 Management Binding；不存在可以替代该路径的无签名
Registry Write。

## Status（状态）

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

Connection State 与 Workload Operational State 是不同维度：

| 维度 | 对象 | 值 |
| --- | --- | --- |
| Connection Projection | System、Service、Module、Surface、Adapter | `connected`、`unavailable`、`incompatible`、`unmanaged` |
| Workload Operation | Workload Observation | Target-owned State，例如 `running`、`suspended`、`stopped`、`unknown` |

`unmanaged` 描述当前拓扑与 Management Binding 之外的 Observed 或 Enrolled
对象。拓扑已声明的业务 Service 若没有 Active Enrollment，就无法连接。

Local Control Adapter 不可用时，Workload Operational State 为 `unknown`。
Console 会立即拒绝 Control Request，不排队、不改道，也不根据进程状态推断结果。

## Surface 可打开但业务数据失败

浏览器必须通过 Surface Gateway 调用生成客户端。确认已连接回执绑定了精确
Module Identity、Module Release Digest、`console_ui_esm` Artifact Digest、
Business API Contract Digest 与允许的 Operation ID。

Service Credential 留在 Console Service。不要把凭据放入浏览器，也不要让
Surface 直接调用业务 Service。

## 产品级验收

显式运行完整黑盒入口：

```sh
pnpm acceptance:support-desk
```

Runner 默认把 `lenso`、`lenso-cli` 与 `lenso-console` 解析为同级 Checkout；
未提供 Acceptance Database URL 时会启动 disposable PostgreSQL，并清理临时
目录。全部前置条件与 Override 参见[示例](/docs/zh/examples)。