项目与排障
常见问题与排障
处理启动、模型连接、项目打开、后台任务、图片与导出中的常见问题。
排障时先保留当前页面上的错误码和完整提示，再一次只改变一个条件。不要通过删除项目数据库、.lumi/ 或资产文件来“试试看”，这可能把可恢复问题变成数据丢失。
Lumi 没有打开工作台
- 检查菜单栏或系统托盘是否仍有 Lumi 图标。
- 从托盘菜单选择重新打开，而不是反复启动多个实例。
- 如果桌面程序已经退出，重新启动 Lumi。旧浏览器页面的会话会失效，需要由新的启动器重新打开。
- 仍失败时，从托盘菜单打开日志目录，记录最近错误，但在反馈前删除访问 URL、令牌、密钥和本机路径等敏感信息。
macOS 或 Windows 阻止启动
只使用 GitHub Releases 的官方文件，并先核对 SHA-256。macOS 未公证和 Windows 未 Authenticode 签名会触发系统警告；在不能确认来源时不要绕过。具体步骤见安装 Lumi。
模型服务连接失败
- 确认服务商、区域、业务空间 ID 或 Account ID 对应同一个账户环境。
- 检查 API Key / Token 是否过期、撤销或缺少调用权限。
- 确认当前网络能访问服务商接口，没有被代理、防火墙或公司网络拦截。
- 保存后重新执行连接检查；不要把密钥粘贴到日志或反馈截图中。
项目无法打开
| 提示 | 处理方式 |
|---|---|
| 路径已失效 | 使用“重新定位”选择移动后的完整项目根目录 |
| 没有写权限 | 把项目移到当前账户可以读写的位置，或修复文件夹权限 |
| 路径属于其他项目 | 选择原项目对应的文件夹，不要用另一个项目替代 |
| 项目已锁定 | 关闭正在使用该项目的其他 Lumi 实例，再重试 |
| 需要升级 Lumi | 安装更新版本后再打开，保留当前项目完整备份 |
项目升级前 Lumi 会在内部备份目录创建数据库一致性备份。如果迁移失败，不要继续手动改数据库；保留项目目录和日志以便定位。
保存显示冲突
章节或 STORY.md 可能被外部工具修改。先停止在另一编辑器中的保存，然后根据界面选择重新加载当前版本、把外部内容导入为新版本，或以数据库版本重新生成 STORY.md。复制自己尚未保存的文字到临时文档，再处理冲突。
后台任务失败或停住
- 打开任务状态或对应工作区，查看错误摘要与当前进度。
- 确认模型连接仍然有效，并检查服务商控制台是否有限额或请求错误。
- 对可重试任务使用界面的“重试”，它会保留任务创建时冻结的输入和模型配置。
- 如果要求不同输入，取消旧任务，修改正文、提示词或参考后创建新任务。
刷新不是重试。任务在刷新后仍会恢复原状态，不会因此创建新的模型调用。
图片显示缺失或损坏
不要直接从 assets/ 或 .lumi/ 删除文件。先打开“设定 → 资产”的完整性维护，运行扫描并查看 missing、corrupt、pending、quarantined 或 orphan 结果。未知文件不会被自动删除；使用界面提供的安全 reconcile 或恢复操作。
导出按钮不可用
- 没有可用图：至少为一个活动画面段落设置就绪的当前图片。
- 部分缺图：返回补图，或在导出对话框明确允许部分导出。
- 有图片生成任务运行：等待任务结束后重新检查就绪度。
- 历史导出已完成：从导出历史直接下载，不需要创建重复任务。
请求帮助前准备什么
在 GitHub Issues 提交问题时说明 Lumi 版本、操作系统、重现步骤、预期结果和错误码。可以附上脱敏截图或相关日志片段，但必须移除 API Key、Token、完整访问 URL、个人目录、项目 UUID 和故事私密内容。