命令行诊断
字数
1527 字
阅读时间
6 分钟
TIP
控制台打不开、实例起不来或会话数据可疑时，终端中的几条命令往往比界面更有用。
两个入口
- 全局启动器
chatluna：管理~/.chatluna下的所有实例，负责创建、启动、停止、升级和修复，面向「实例」。 - 实例内命令：在项目目录中通过包管理器执行，负责诊断和导出，面向「数据」。它不能启动实例，启动始终用全局启动器。
分不清时，看两者的帮助信息即可。
实例管理
| 命令 | 作用 |
|---|---|
create <名字> | 创建实例（可选模板、包管理器、目录） |
start [名字] | 启动，可后台运行 |
list | 列出实例与运行状态 |
stop [名字] | 停止 |
restart [名字] | 重启 |
dev [目录] | 开发模式启动（热更新，不做恢复与安全模式） |
不指定名称时使用默认实例，它在首次创建实例时写入全局配置。服务器上通常用后台模式启动，日志写入日志目录。开发模式关闭了快照恢复和安全模式，出错时能直接看到完整的调用栈。
依赖管理
| 命令 | 作用 |
|---|---|
add <包...> | 安装插件 |
remove <包...> | 卸载插件 |
link <目录> | 链接本地插件目录 |
unlink <名字> | 取消链接 |
安装与控制台共用同一个包管理队列，和界面同时操作也不会冲突。link 用于本地开发，调试结束后 unlink。
维护
update：更新启动器和实例插件。流程是快照 → 更新 → 健康检查，失败自动回滚。repair：实例严重异常或起不来时，收集现场诊断信息，调用本地 Agent 尝试修复，并生成报告。report：查看最近一次修复的报告，包含启动失败时的日志尾部。new：在实例、项目或仓库中生成插件脚手架。
WARNING
repair 能处理配置格式错误、依赖版本异常这类环境问题，修不了业务逻辑错误。自动修复失败时，报告中的原始日志才是人工排查的关键。
诊断
| 检查 | 检查什么 | 失败时先看 |
|---|---|---|
| 配置检查 | 插件清单是否合法、依赖是否满足、受保护路径是否正确、控制台资源是否完整 | 插件名拼写、缺失的 npm 包、控制台路径是否在受保护前缀中 |
| 会话检查 | 会话日志的不变量：消息是否断档、索引与内容是否一致、状态标记是否成对闭合 | 最近几条消息的写入记录，是否有意外中断留下的未闭合标记或索引错位 |
| 缓存检查 | 会话的上下文缓存周期、前缀命中情况、缓存失效的原因 | 每轮都未命中时，看报告中的切换点，找出是哪次提示词改动或动态注入破坏了公共前缀 |
| 提供商检查 | 各提供商端点的连通性、延迟和凭据有效性（需要实例运行） | 网络代理、DNS、各提供商的 API Key 与 Base URL |
| 导出 | 把会话的完整历史导出为 JSONL | 会话 ID 是否正确，数据文件是否有权限问题或损坏 |
TIP
导出内容包括工具调用和系统消息在内的完整日志，分享前确认其中没有敏感配置或隐私信息。
诊断命令在终端中输出易读的报告。在脚本或自动化中使用时看退出码：成功为 0，发现问题为非零。修复报告是统一的结构化格式，可以直接附在 Issue 中。
部署中的用法
- 服务器：后台模式启动，交给 systemd 等服务管理器托管；升级用
update，失败时根据报告回滚。 - 容器：入口脚本直接启动实例进程，健康检查探测 WebUI 端口；起不来时看容器的标准输出。
- CI：用实例内命令做冒烟检查，校验配置清单、依赖完整性和会话日志能否正常读取。
与 supervisor 的关系
通过命令行启动的实例全程由 supervisor 监管：进程崩溃时自动拉起，健康检查失败时进入恢复流程，连续恢复失败后进入安全模式。命令行只是发起操作的一端。
常见问题
找不到实例：检查名称拼写，以及 ~/.chatluna/instances 下是否有对应目录。
start 后立刻退出：看日志尾部，常见原因是端口被占用、配置格式错误或核心依赖缺失。
list 显示运行中，但打不开：可能刚启动、健康检查还没通过，也可能端口被防火墙或反向代理拦截。
update 后起不来：用 repair 尝试修复，或回滚到更新前的快照，报告中有具体的失败原因。
doctor 报路径保护错误：控制台路径不在受保护前缀中，这是危险配置，必须立即修正。
导出失败：通常是会话 ID 错误或数据文件损坏，先跑一次会话检查。
