issues
Docker / Nix / SSH / 远程后端问题LCP
一句话结论：这页只处理“为什么容器里起不来、为什么 SSH backend 连不上、为什么远端文件和本地不一致、为什么我以为在一台机器上运行，实际跑在另一台”这类排障问题；…
一句话结论：这页只处理“为什么容器里起不来、为什么 SSH backend 连不上、为什么远端文件和本地不一致、为什么我以为在一台机器上运行，实际跑在另一台”这类排障问题；先分清到底是谁在执行、谁在读文件、谁持有依赖和配置。
如果你现在只想先记住一句：
大多数远程 backend 问题，不是 Hermes 核心逻辑坏了，而是“执行环境边界没搞清：命令从哪发出、在哪执行、读哪份文件、用哪套依赖”。
⚡ 先按症状跳转
你现在最像哪一种：
A. Docker / Nix 环境起不来
B. SSH backend 连不上 / 连上后还是不对
C. 文件、路径、依赖和本地理解不一致
D. 你怀疑其实不是 backend，而是 CLI / 模型 / 配置问题
🩺 先做什么：最小排查动作
先不要急着重新部署或重建容器。 先把这 4 个问题答出来：
- 我现在到底是在本地执行，还是在 Docker / SSH / 远端 backend 执行
- 当前真正读文件、跑命令的是哪台机器 / 哪个环境
- 我看到的问题是“连不上”，还是“连上了但环境不对”
- 我改的文件，和它实际读的文件，是不是同一份
这 4 个问题没分开，后面几乎一定越改越乱。
🚫 先别急着做的事
- 不要把“我本地有这个文件 / 依赖”自动等同于“远端也有”
- 不要把“SSH 通了”自动等同于“远端环境已准备好”
- 不要在没确认执行地前就判断是模型、工具或 Hermes bug
- 不要一边改 backend、一边改 profile、一边改部署路径
📌 先记住这 4 个官方基线
1）先分清“发命令的地方”和“执行命令的地方”
远程 backend 排障里最容易错的，不是语法，而是边界：
- 你在哪发命令
- 命令最终在哪执行
- 读的是本地文件，还是容器 / 远端文件
如果这三件事没拆开，后面所有现象都会显得像随机错误。
2）Backend 问题先查执行环境，不先查模型
这页最重要的判断线不是“它回没回”，而是：
- 当前到底是不是 docker / ssh / 远端 backend
- 当前 backend 读的是哪套配置
- 当前环境里到底有没有这份代码、依赖、文件
所以 backend 页优先回答“谁在执行”，不是先回答“模型为什么慢”。
3）本地文件和远端文件默认不是同一份
请先把这个当成默认前提：
- 本地有，不代表远端有
- 本地改了，不代表远端马上变
- 本地装过，不代表容器 / 远端也装过
这不是异常，是远程 backend 的正常边界。
4）SSH 通了，不等于远端环境就对了
SSH / Docker 最容易出现的误判是：
- 通道建立成功
- 但远端工作目录不对
- 远端依赖不全
- 远端项目路径和本地理解不一致
所以“能连上”最多只证明第一段，不证明全链路可用。
❓FAQ
01｜为什么 Docker backend 起不来？
先说结论：最常见不是 Hermes agent 坏了，而是 Docker backend 所需的运行条件、镜像环境或 backend 配置根本没对齐。
先做什么：
- 先确认当前 backend 到底是不是 docker
- 先确认你测试的入口真的在走 docker backend
- 先确认问题是“容器根本起不来”，还是“起得来但环境不对”
重点检查：
- Docker backend 没正确配到当前环境
- 容器运行条件不满足
- 当前入口其实没切到 docker backend
- 问题其实属于 Docker 环境本身，不在 Hermes 推理链路
什么时候该跳转：
- 如果根因更像 backend 选择 / 当前生效配置不对，跳到 07-配置 / Profiles / 环境隔离问题
- 如果你已经确认就是 Docker backend 行为问题，留在本页
02｜为什么我以为进了容器，但行为还是像本地？
先说结论：最常见不是容器半坏，而是你把“配置成 docker backend”与“当前所有动作都已经在容器里执行”当成了一回事。
先做什么：
- 先区分命令发出地和命令执行地
- 先确认当前读文件的是本地还是容器
- 先确认你看到的是哪一边的状态
高频混淆：
- backend 配好了，但当前入口没真正切过去
- 你在看本地文件，却以为容器也会自动看到
- 你把“CLI 在本地”误当成“执行也一定在本地”或相反
什么时候该跳转：
- 如果核心问题是“哪套配置在生效”，跳到 07-配置 / Profiles / 环境隔离问题
- 如果核心问题是“容器环境边界没分清”，留在本页
03｜为什么 SSH backend 连不上？
先说结论：最常见不是 Hermes 不支持 SSH，而是 SSH 目标、认证、网络可达性、远端可执行环境，或 backend 配置没有真正对齐。
先做什么：
- 先确认这台远端主机本来就能 SSH 到
- 先确认当前 backend 的目标确实是这台机器
- 先区分“完全连不上”和“能连上但环境不对”
重点检查：
- 主机不可达
- SSH 认证失败
- 远端 backend 配置填错
- 远端虽然能连，但不具备 Hermes 预期环境
什么时候该跳转：
- 如果问题就是 SSH 通道本身，留在本页
- 如果 SSH 已通，但远端环境配置错位，跳到 07-配置 / Profiles / 环境隔离问题
04｜为什么 SSH 看起来连上了，但执行环境还是不对？
先说结论：SSH 连上，只证明通道建立了；不代表远端路径、依赖、工作目录、配置文件、profile 都和本地预期一致。
先做什么：
- 先把“连接成功”和“环境正确”拆开
- 先确认远端机器上到底有什么
- 先确认远端当前读的是哪套配置和目录
常见误判：
- 以为 SSH 通了，一切就都对
- 以为远端自动拥有本地同样的依赖
- 以为本地改的配置会自动同步到远端
什么时候该跳转：
- 如果问题已经变成远端机器准备不足，跳到 03-国内落地 / 01-总览 或 04-自己造东西
- 如果你仍在判断 backend 边界，留在本页
05｜为什么远端文件 / 路径 / 依赖和本地不一样？
先说结论：因为远端 backend 本来就不是你的本地文件系统和依赖环境。默认把两边当成一样，是最常见误判。
先做什么：
- 先放弃“本地当然等于远端”的默认假设
- 先确认远端当前工作目录是什么
- 先确认项目是否真的在远端那个位置
最常见原因：
- 远端读的是远端文件系统
- 本地路径在远端根本不存在
- 本地装过的依赖，远端没装
- 你把“我的项目目录”错误地套给远端
什么时候该跳转：
- 如果你本质在查远端环境怎么部署 / 准备，跳到 03-国内落地 / 01-总览
- 如果你主要在厘清 backend 边界，留在本页
06｜为什么改了本地文件，远端执行没变化？
先说结论：最常见不是 Hermes 缓存了旧结果，而是你改的是本地文件，远端执行根本不读这份本地文件。
先做什么：
- 先确认当前执行地到底在哪
- 先确认当前读取的是哪份文件
- 先确认本地改动有没有进入远端运行环境
典型场景：
- 本地改动没有同步到远端
- 远端实际跑的是另一份代码
- 你把编辑器里看到的文件误当成远端正在执行的文件
什么时候该跳转：
- 如果根因更像部署 / 同步链路没建立，跳到 03-国内落地 / 01-总览
- 如果只是远端文件边界没分清，留在本页
07｜为什么容器 / 远端里找不到我以为已有的依赖？
先说结论：因为“我本地装过”不等于“容器里装过”，更不等于“远端主机也装过”。
先做什么：
- 先按执行环境来判断依赖，不要按记忆判断
- 先确认依赖到底装在哪一台机器 / 哪个环境里
- 先确认当前命令究竟在哪个环境执行
你要先拆开的 3 件事：
- 依赖装在哪
- 命令在哪执行
- 你是不是把“本机已安装”误当成“所有 backend 都已安装”
什么时候该跳转：
- 如果已经确认是环境准备不足，跳到 02-安装 / 更新 / 环境问题 或 03-国内落地 / 01-总览
- 如果你现在还分不清执行环境是谁，留在本页
08｜什么时候这更像 backend 问题？
先说结论：如果问题主要体现在“跑在哪、读哪份文件、用哪套依赖、连哪台机器”，更像 backend；如果主要体现在“会不会回、模型认不认、provider 报什么错”，更像 CLI / 模型层。
先做什么：
- 先问自己：问题是发生在执行环境选择上，还是执行结果上
- 先问自己：是“谁在执行”不清，还是“执行后返回什么”不对
简单分界线：
- backend 层：执行环境边界
- CLI 层：交互方式和本地会话
- 模型层：推理链路与 provider
什么时候该跳转：
- 如果是 provider / model 报错，跳到 03-模型 / Provider / 自定义 endpoint 问题
- 如果是交互体验异常，跳到 04-CLI / TUI / 会话问题
- 如果是执行环境边界问题，留在本页
09｜什么时候该回配置 / 部署页？
先说结论：只要你现在的问题已经不是“backend 哪里行为怪”，而是“环境到底怎么准备、怎么部署、怎么选路线”，就不该继续把它当单点 backend 问题硬调。
先做什么：
- 先回配置 / 安装 / 部署总览，把边界整理清楚
- 再回来查单点 backend 问题
这些情况更适合跳转：
- 你还没分清本地、容器、远端主机三条路线
- 你现在其实在补基础设施
- 你现在更像在搭运行环境，而不是排 Hermes backend 单点问题
什么时候该跳转：
🔹 官方依据
✅ 看完这页，你应该能立刻判断
- 问题到底是 Docker / SSH / 远端 backend 边界，还是其实是 CLI / 模型层
- 当前到底是哪台机器、哪套环境在执行
- 你改的文件和它实际读的文件是不是同一份
- 该继续排 backend，还是回配置 / 部署页重新拆问题
➡️ 下一步
完成后进入：
如果你想先回到上一阶段入口重新确认位置：
🔗 相关排查入口
如果当前页没有命中症状，先回到遇到问题总入口重新按问题类型分流。