故障排查 - Mirobody

先检查模型诊断结果和最近的容器日志：

docker compose exec mirobody mirobody doctor   # 每个用途选中了哪个模型
docker compose logs --tail 80 mirobody         # 服务端自身的日志

doctor 报告

mirobody doctor 先打印一行找到的密钥与本地模型服务，再为每个用途各打印一行：

输出	含义
`keys present : none`	没有模型厂商密钥，也没有本地模型服务。① 收集与 ② 标准化照常工作，文件抽取和 agent 不可用。打开 `./deploy.sh` 打印的首次设置页链接，或在 `.env` 中写入一个密钥或 `LOCAL_BASE_URL`，然后执行 `docker compose up -d`。
标记为 `OK` 的用途	该用途选中的条目与模型。
标记为 `--` 的用途	该用途没有可用模型，下一行写明缺少的密钥、服务或条目。
`retired keys`	早期版本的配置键，已不再读取。请把这项设置移到 `config.llm.yaml` 的 `MODELS` 条目或 `UTILS_*` 路由中。
`unread fields`	`MODELS` 条目里没有任何代码读取的字段，通常是拼写错误。

加上 --probe 可以发送真实请求，检查模型是否可用。如果已有模型配置但测试失败，请检查接口地址、网络连接和模型能力。

启动失败

现象	原因与处理
`deploy.sh` 中止：端口被其他容器占用	另一个项目占用了或。`deploy.sh` 不会停止不属于本项目的容器：请释放端口，或修改本项目的端口。
Compose 拒绝具名卷（`Host path binding is rejected`）	Docker 以 rootless 或加固模式运行。把复制为 `compose.override.yaml`，并创建其中列出的目录。
拉取镜像失败，或构建时无法访问 Docker Hub	Docker Hub 无响应时，`deploy.sh` 会依次尝试镜像源 `mirror.gcr.io` 和 `docker.1ms.run`；只有在完全拉取不到镜像时才会在本地构建。通过代理上网时，需要为 Docker 守护进程本身配置代理，只配置 shell 不够。
首次启动耗时很长	镜像没能拉取到，`deploy.sh` 于是从本地检出构建。请在运行 `./deploy.sh` 的 shell 里设置 `PIP_INDEX_URL`（它作为构建参数传入，不从 `.env` 读取），改用更近的包索引。
设置 `PRODUCTION: true` 后服务端拒绝启动	仍有预置登录码或 `REPLACE_THIS_VALUE_IN_PRODUCTION` 占位值，日志会写明是哪些，见在服务器上部署。
`mirobody dev` 退出并要求提供 Postgres	传入 `--pg-url`，或设置 `PG_URL` 或 `DATABASE_URL`。数据库需要 pgvector 扩展。

运行中的问题

现象	原因与处理
新克隆的仓库在查询 LOINC 时报错	术语包用 Git LFS 存储，克隆下来的只是指针文件。执行 `git lfs install && git lfs pull`。
设备同步从不执行，其余功能正常	检查 worker 日志与 Postgres 连接：设备拉取与任务状态都用 Postgres。
通过代理上网时模型调用报 `Cannot connect to host`	容器不会继承 shell 的代理设置。在 `.env` 中设置 `HTTP_PROXY` 与 `HTTPS_PROXY`，`compose.yaml` 会把它们传给服务端，并让本机的模型服务不走代理。
上传的文件已保存，但没有出现读数	没有选中视觉、OCR 或文本模型（见 doctor 报告），或者 `ENABLE_INDICATOR_EXTRACTION` 为 `0`。
演示账号无法登录	首次启动时 `SEED_DEMO_DATA` 为 `false`，或覆盖文件替换了 `EMAIL_PREDEFINE_CODES`（覆盖文件中的字典是替换，不是合并）。
某个设备 provider 没有出现	它的凭据缺失，启动时自行跳过了，启动日志会写明是哪一个。见设备 Provider。

本地模型

安装与启动见本地运行；下面是它可能出错的地方。

现象	原因与处理
首次设置页拒绝100% 在本机运行	`.env` 中的厂商密钥始终优先于本地条目。删掉密钥并执行 `docker compose up -d`，再选一次本地；或者保留密钥，按配置设置那三个覆盖变量。
在 Linux 主机上，页面找不到模型服务	在 Linux 上 `host.docker.internal` 指向 Docker 网桥，宿主机上的 `llama-server` 必须监听网桥地址（`--host 172.17.0.1`，由 `ip -4 addr show docker0` 查得），而不是 `127.0.0.1`。`local` 与 `local-cpu` 两个 Compose profile 不需要宿主机网络。
模型服务的日志里出现 `failed to initialize router models: ... Is a directory`	Docker 看不到这份检出，于是把一个空目录挂到了预设文件的位置。Colima 默认只共享你的主目录：把检出放在主目录下，或把路径加进它的挂载列表。
选好规模后的第一个问题很久没有回答	模型正在从 Hugging Face 下载；首次设置页显示每个模型的状态，用 Compose profile 运行模型时，`docker compose logs -f llama_cpu`（NVIDIA 显卡上为 `llama`）能看到下载进度。无法访问 huggingface.co 时，在 `.env` 中把 `HF_ENDPOINT` 设为镜像。
一个回答要好几分钟，而且没有流式输出	本地模型的正常表现：读取提示词期间没有任何输出，加载后的第一轮最慢。`local` 条目允许 600 秒的静默后才放弃。
`llama-server` 占用的内存远超模型权重	llama.cpp 的提示词缓存默认每个模型服务 8 GiB。随仓库提供的预设把每个回答模型的缓存限制为 1 GiB、文档阅读模型为零（中的 `cache-ram`）；自己写的预设需要同样的几行，否则机器会开始交换内存。
聊天里的照片只按其中的印刷文字回答	回答问题的模型看不见图片，收到的是照片的 OCR 文字：小规模只处理文本。请选择能看图的大规模，或改用厂商密钥。

以上没有覆盖的问题，欢迎在 GitHub 提交 issue：附上 doctor 报告和容器日志的最后几行，并去除其中的个人数据。