故障排除

诊断常见主机、模块安装、控制台、服务、能力包和版本检查问题。

首先将主机状态与模块状态分开：

git status --short
lenso module doctor
curl -sS http://127.0.0.1:3000/api/admin/modules | jq .

如果主机正在运行但控制台没有显示预期的模块，请重新启动 API 和worker 安装后都会发生变化。

常见症状

症状	检查	修复
Console 地址不可用	`lenso console doctor` 与 Console Workload 健康状态	恢复 Console Service，或应用经过审查的升级。
Console 显示 `Operator required`	`GET /bootstrap/v1/status`	运行 `lenso console operator bootstrap`，然后重启 Console API 和 Worker。
Console 打开但缺少受管 Module	System Registry 与 enrollment 证据	校验 Module Release、Console UI artifact 和受管 Service enrollment。
Service Provider 已安装但不健康	`lenso service doctor <provider> --json`	启动 Service、修复声明的健康端点，或执行诊断返回的恢复动作。
应用程序生命周期下一步尚不清楚	`lenso app next`	运行 `lenso app explain` 来分别查看生成状态、模块和服务操作。
Launchpad 应用程序更改计划为空	`.lenso/app-change-plan.json`	运行 `lenso app plan --write-plan` 或 `lenso app plan --addon <name> --write-plan`。
能力包未显示在 Launchpad 中	`lenso capability check <pack-dir>`	修复包Manifest，然后重新运行 `lenso app compose --repo-root . --pack <pack-dir> --write-plan` 或 `--apply`。
Launchpad 应用更改计划被阻止	控制台Launchpad计划面板	审查被阻止的更改；不受支持的插件通常意味着选择受支持的蓝图或插件。
Launchpad 应用程序证明为空	`.lenso/app-proof.json`	在生成的应用程序根目录中运行 `lenso app verify --write-proof`。
Launchpad App Proof 已漂移	`lenso app diff`	使用 `lenso app repair --dry-run` 预览安全生成状态修复，如果计划正确，则运行 `lenso app repair`。
Service 安装变化后没有生效	`lenso service doctor <provider> --json`	Reconcile Host，并执行诊断返回的重启或恢复动作。
身份验证在本地工作，但会话速度很慢	`auth.session_cache` 和 `REDIS_URL`	安装`auth --profile redis-session-cache`并单独提供Redis。
Redis 身份验证配置文件在运行时失败	Redis 服务可用性	启动 Redis 并确认 `REDIS_URL` 指向正确的数据库。
CORS 阻止浏览器请求	`CORS_ALLOWED_ORIGINS`	添加前端源或使用生成的本地默认值。
本地冒烟中的 OTLP 导出器错误	`OTEL_EXPORTER_OTLP_ENDPOINT`	将其取消设置为正常的本地冒烟或启动可观测服务。
`just generated-check` 失败	git 差异	不要手动编辑生成的文件。运行 `just generate` 并提交生成的工件更改和源更改。
`just release-check` 基础设施失败	Docker、端口、Postgres	首先修复本地服务，然后重新运行gate。将代码失败视为发布阻碍。

Console 不可用或版本过旧

先检查独立安装状态：

lenso console doctor --help

若已安装版本过旧，规划不可变的 Release 升级：

lenso console upgrade --help

然后打开配置的 Console Service 地址。本地源码 checkout 默认为：

http://127.0.0.1:3030/

没有出现模块安装

检查本地回执：

cat .lenso/module-installs.json | jq .

检查install写的环境：

grep -E 'LENSO_MODULE_' .env

然后重新启动API和worker。链接模块安装可以更新 Cargo.toml 和 src/lib.rs，所以必要时重建主机。

服务尚未准备好

跑步：

lenso service workspace check
lenso module doctor

Doctor检查 .lenso/module-services.json 中声明的服务并报告：

服务未配置；
服务被禁用；
服务准备就绪；
手动服务尚未准备好；
陈旧的主机启动状态；
准备好的 URL 没有响应。

如果Provider是外部服务，请自行启动并确保 readyUrl 在启动主机之前响应。

Launchpad 应用程序更改计划

应用程序更改计划在生成之前为操作员和代理提供可审查的文件应用状态更改：

lenso app plan --write-plan
lenso app apply .lenso/app-change-plan.json --dry-run

对于插件更改，请包含插件名称：

lenso app plan --addon support-sla --write-plan

对于多个插件请求，请使用 App Composer：

lenso app compose --repo-root . --addon support-sla --addon customer-profile --write-plan
lenso app next
lenso app explain

对于能力包请求，请传递包目录：

lenso capability check ./capabilities/support-sla
lenso app compose --repo-root . --pack ./capabilities/support-sla --write-plan
lenso agent task --for-capability support-sla "continue the requested work"

如果该计划被阻止，请勿应用它。使用被阻止的项目消息和命令要选择受支持的插件或包，请先修复生成的状态，或继续手动。

Launchpad 应用程序证明漂移

App Proof 检查生成的产品蓝图的控制平面状态：

lenso app verify --write-proof
lenso app diff
lenso app repair --dry-run

使用试运行输出来决定修复是否合适。修复即可恢复生成的Launchpad、工作区和系统条目或丢失的脚手架目录。它不会覆盖现有的服务源文件，并且应该不删除未知服务。

Service Manifest URL 没有响应

直接打开Manifest：

curl -sS http://127.0.0.1:4100/lenso/service/v1/manifest | jq .

然后通过 CLI 获取 Provider 的精确诊断证据：

lenso service doctor billing --json

修复声明的 Manifest、健康 URL、凭据或部署目标，不要绕过 Service 安装记录。

生成的工件已更改

当 just generated-check 失败时，检查 diff：

git diff -- contracts generated

如果差异与您的 Rust/OpenAPI 更改匹配，请保留它。如果没有，请修复来源和再生：

just generate
just generated-check

端口被占用

更改一个 shell 的主机端口：

HTTP_PORT=3010 lenso serve

对于第一用户冒烟默认值，请使用：

FIRST_USER_SMOKE_HTTP_PORT=3011 \
FIRST_USER_SMOKE_PROVIDER_ADDR=127.0.0.1:4111 \
just first-user-smoke

发布门禁失败

运行较小的检查来查找失败层：

just fmt-check
just rust-check
just test
just generated-check
just arch-check

如果只有 Docker 或 Postgres 出现故障，请修复本地基础设施并重新运行。如果格式化、编译、测试、生成的合约或架构检查失败，将失败视为释放阻塞代码工作。