docker compose exec mirobody python -m mirobody doctor # 每个用途选中了哪个模型
docker compose logs --tail 80 mirobody # 服务端自身的日志
doctor 报告
mirobody doctor 先打印一行找到的密钥，再为每个用途各打印一行：
| 输出 | 含义 |
|---|---|
keys present : none | 没有配置模型密钥。① 收集与 ② 转译照常工作，文件抽取和 agent 不可用。在 .env 中写入一个密钥，然后执行 docker compose restart。 |
标记为 OK 的用途 | 该用途选中的条目与模型。 |
标记为 -- 的用途 | 该用途没有可用模型，下一行写明缺少的密钥或条目。 |
retired keys | 早期版本的配置键，已不再读取。请把这项设置移到 config.llm.yaml 的 MODELS 条目或 UTILS_* 路由中。 |
unread fields | MODELS 条目里没有任何代码读取的字段，通常是拼写错误。 |
启动失败
| 现象 | 原因与处理 |
|---|---|
deploy.sh 中止：端口被其他容器占用 | 另一个项目占用了 、 或 。deploy.sh 不会停止不属于本项目的容器：请释放端口，或修改本项目的端口。 |
deploy.sh 中止：已有 Docker 网络占用了该子网 | compose.yaml 固定了一个子网，所以同一时间只能运行一份检出。删除提示中那个未使用的网络，或把本项目移到空闲子网，并在覆盖文件中把 PG_HOST 与 REDIS_HOST 改成新地址。 |
Compose 拒绝具名卷（Host path binding is rejected） | Docker 以 rootless 或加固模式运行。把 复制为 compose.override.yaml，并创建其中列出的目录。 |
| 拉取镜像失败，或构建时无法访问 Docker Hub | Docker Hub 无响应时，deploy.sh 会改用镜像源。通过代理上网时，需要为 Docker 守护进程本身配置代理，只配置 shell 不够。 |
| 首次启动耗时很长 | 首次启动时会先把 Python 依赖安装到一个卷中，然后服务端才开始监听端口。可以在 .env 中设置 PIP_INDEX_URL，改用更近的包索引。 |
设置 PRODUCTION: true 后服务端拒绝启动 | 仍有预置登录码或 REPLACE_THIS_VALUE_IN_PRODUCTION 占位值，日志会写明是哪些，见在服务器上部署。 |
mirobody serve 找不到配置 | config.yaml 不在 PyPI 包中。请在源码检出中运行，或使用不需要配置文件的 mirobody dev。 |
mirobody dev 退出并要求提供 Postgres | 传入 --pg-url，或设置 PG_URL 或 DATABASE_URL。数据库需要 pgvector 扩展。 |
运行中的问题
| 现象 | 原因与处理 |
|---|---|
| 新克隆的仓库在查询 LOINC 时报错 | 术语包用 Git LFS 存储，克隆下来的只是指针文件。执行 git lfs install && git lfs pull。 |
| 设备同步从不执行，其余功能正常 | Redis 无法连接。其他功能都能平稳降级，唯独厂商数据拉取不能。 |
通过代理上网时模型调用报 Cannot connect to host | 容器不会继承 shell 的代理设置。在 .env 中设置 HTTP_PROXY 与 HTTPS_PROXY，compose.yaml 会把它们传给服务端。 |
| 上传的文件已保存，但没有出现读数 | 没有选中视觉或文本模型（见 doctor 报告），或者 ENABLE_INDICATOR_EXTRACTION 为 0。 |
| 演示账号无法登录 | 首次启动时 SEED_DEMO_DATA 为 false，或覆盖文件替换了 EMAIL_PREDEFINE_CODES（覆盖文件中的字典是替换，不是合并）。 |
| 某个设备 provider 没有出现 | 它的凭据缺失，启动时自行跳过了，启动日志会写明是哪一个。见设备 Provider。 |