故障排除
本页以问答形式解答常见的安装和运行问题。如果你的问题不在列表中， 请收集相关日志行并在 GitHub 仓库 上提交 issue。
为什么应用提示端口已被占用？
本地后端默认监听 127.0.0.1:8000。如果另一个程序占用了该端口，
sidecar 就无法启动。请关闭冲突的程序，或者通过在环境中设置 NEOTA_PORT
以不同的端口启动服务器。应用中的错误消息会包含端口号以及解决冲突所需的细节。
后端 sidecar 无法启动
桌面应用将后端作为内嵌的 Node.js sidecar 运行。如果它启动失败， 应用窗口会显示连接错误。请检查以下各项：
- 可能已有另一个 NeoTavern 实例在运行并占用了端口。
- 数据目录在当前位置上可能不可写。
- 杀毒软件或防火墙可能阻止了内嵌的 Node 运行时。
解决原因后重启应用。如果应用进入崩溃循环，它会提供一个安全模式启动选项， 在第三方插件和主题加载之前将其禁用 —— 用它来恢复。
数据库被锁定
NeoTavern 使用带 WAL 模式和 busy 超时的 SQLite，因此短暂并发访问是 预期内并被妥善处理的。持续的"database is locked"错误通常意味着第二个 应用实例打开了同一个数据目录，或者某个备份或导入操作仍在运行。 关闭重复的实例，等待长操作完成后再重试。
如何清除缓存？
缓存位于 data/cache/ 下，并且完全可以重新生成：缩略图、分词器数据和
插件依赖下载。清除缓存绝不会删除你的原始文件，原始文件单独存放在
data/files/ 下。使用设置 → 数据中的维护控件来清除缓存并重建全文搜索
索引。这两个操作在真正执行前都会确认将被删除内容的数量和大小。
日志在哪里？
日志写入 data/logs/server.log，达到 10 MB 时轮转。日志文件经过脱敏处理：
密钥、API 密钥和用户消息内容绝不会被记录。控制台输出与文件同时保留。
报告错误时，请附上相关的日志行和错误详情中显示的 trace ID。
如何回到一个可用的界面？
使用安全模式：它可以在第三方主题和插件加载之前进入，并将其禁用。 在主题或插件损坏之后，安全模式无需手工编辑文件即可恢复内置界面。 详情请参阅主题和扩展。
为什么发送按钮被禁用？
按钮只会在有具体原因时被禁用，原因会显示在按钮旁边 —— 最常见的是没有 激活的提供商或没有选择角色。在 AI 设置中连接提供商或选择一个角色， 按钮即可使用。请参阅快速开始。