Docker 部署 AI 应急响应代理：Hindsight 长期记忆集成实战

一位开发者在 Reddit 上为 RecallOps 项目求助——这是一个基于 Docker Compose 的 AI 应急响应代理，目标是在事故处理中调取长期记忆、结合 runbook 和 guardrails 引导响应。项目当前已经跑通：RecallOps 在 8000 端口启动，Hindsight 在 Docker 中运行且 8888 端口可从宿主机访问，记忆库也建好了。真正卡住的是集成细节：API token 没配、容器间 URL 不确定该用 localhost 还是服务名、以及如何验证记忆真的被存取而没有悄悄回退到 SQLite。

这个问题几乎是所有「本地 AI 应用 + 外部记忆层」组合都会踩的坑。下面按开发者提出的几个问题逐一拆解，结合 Docker 网络与记忆系统的通用实践给出可落地的建议。

容器间通信：别用 localhost，用服务名

这是整套架构里最容易出错、也最容易排查的一环。RecallOps 和 Hindsight 跑在各自的容器里，容器内的 localhost 指向容器自身，而不是宿主机，也不是兄弟容器。所以 RecallOps 容器里的 http://localhost:8888 一定连不上 Hindsight——尽管在宿主机浏览器里这个地址完全正常。

正确的做法是把两个服务放进同一个 Docker Compose 定义的网络（Compose 默认会创建一个共享网络），然后把 API base URL 配置为 Hindsight 的服务名加内部端口，形如 http://hindsight:8888。服务名由 Compose 文件里的 service key 决定。

一个常见的改良做法是把 base URL 做成环境变量而不是硬编码，这样本地开发、CI、以及未来可能的多环境部署都能复用同一份镜像。宿主机上用 localhost:8888 调试，容器内用服务名，两边互不干扰。

Docker Compose 默认会为同一个 compose 文件中的所有服务创建一个共享的 bridge 网络，每个服务在这个网络中拥有一个基于 service key 的 DNS 名称。容器内的 localhost 回环地址指向容器自身的网络栈，因此无法访问宿主机或其他容器暴露的端口；而服务名解析由 Docker 内置的嵌入式 DNS 完成，无需额外配置。需要注意的是，服务名只在同一网络内可解析，如果手动指定了多个网络，要确保 RecallOps 和 Hindsight 都接入同一个网络。另外，端口映射 ports: "8888:8888" 只影响宿主机到容器的访问，容器间通信应直接使用容器内部监听端口，而不是映射端口（除非映射关系不同）。

Hindsight 认证：本地部署也别裸奔

开发者提到已创建记忆库但还没配置 API token。即使只是本地演示，也建议从一开始就启用 token 认证，理由不是安全，而是避免后期切换时破坏适配器逻辑。带认证和不带认证的请求路径往往不同，早配早省事。

推荐的做法是通过环境变量注入 token，例如 HINDSIGHT_API_TOKEN，由 Compose 的 environment 段传入 RecallOps 容器。不要把 token 写进镜像或提交到仓库，用 .env 文件配合 .gitignore，演示前把示例值脱敏。

如果 Hindsight 支持在创建记忆库时绑定 token，那就让 token 与该记忆库一一对应，这样适配器层只需要关心「当前记忆库 + 对应 token」这一对配置，逻辑更干净。

在 Docker Compose 中，environment 段用于向容器注入环境变量，支持直接赋值或从 .env 文件读取。推荐使用 ${HINDSIGHT_API_TOKEN} 形式引用，这样 token 只存在于宿主机的 .env 文件中，不会进入镜像层或 Compose 文件。.env 文件应加入 .gitignore，而仓库中应提供 .env.example 作为模板，其中 token 字段留空或填入明显的占位符。对于本地演示，还可以考虑使用 Docker secrets 或外部密钥管理，但环境变量加 .env 已经能覆盖绝大多数场景。

验证记忆真的被存取：让回退可见

适配器模式的初衷是外部记忆不可用时回退 SQLite，保证服务不中断。但这也带来一个隐蔽风险：你永远不知道自己用的是哪种存储。演示时如果记忆层其实没生效，页面照样能跑，问题被悄悄掩盖。

解决办法是让回退这件事「喊出来」。几个可操作的手段：

• 在适配器里加结构化日志，每次读写都打印当前走的是 Hindsight 还是 SQLite，以及触发回退的原因（超时、连接拒绝、认证失败等）。
• 在 Ops Console 上加一个状态徽标，实时显示记忆后端健康状态。这既是调试工具，也是演示亮点。
• 写一个最小验证脚本：通过 Hindsight API 直接写入一条带唯一标记的记忆，再从 RecallOps 侧触发检索，确认这条标记能被取回。如果取不到，检查日志里是否发生了回退。

有一点值得强调：回退到 SQLite 不应该被当作正常状态静默处理。它应该是显式的、可观测的降级行为。很多自建 AI 应用的记忆问题，最后都是靠日志里一行被忽略的回退记录定位的。

适配器模式（Adapter Pattern）是一种结构型设计模式，它将一个类的接口转换成客户端期望的另一个接口，使得原本不兼容的类可以协同工作。在 RecallOps 的语境下，适配器层定义了一组记忆操作接口，Hindsight 和 SQLite 分别提供实现，上层业务代码只依赖接口而不关心具体后端。这种模式天然支持降级：当 Hindsight 不可用时，适配器可以切换到 SQLite 实现。但降级的触发条件、切换时机和恢复策略都需要显式定义，否则就会出现文中提到的“静默回退”问题。建议在适配器初始化时明确配置回退策略（如超时时间、重试次数、是否自动恢复），并将这些配置也纳入环境变量管理。

测试回退行为：主动制造故障

要验证「Hindsight 不可用时事故数据仍然完整」，最直接的方式是主动把 Hindsight 停掉。用 docker compose stop hindsight 或者从网络中断开该容器，然后走一遍完整的事故流程：创建事故、写入、读取、更新。关注三点——RecallOps 是否仍然响应、SQLite 里的数据是否完整、日志是否正确标记了回退。

恢复 Hindsight 后，再验证一遍系统能否回到使用外部记忆的状态。理想情况下适配器应能自动重连，或者至少给出明确提示，而不是永久卡在 SQLite 模式。

另外建议给「故障注入」留个开关，比如通过环境变量强制禁用 Hindsight，这样每次代码改动后都能快速回归测试回退路径，而不必真的去停容器。

录 Demo 前的检查清单

开发者提到需要确认 Ops Console 的导航和交互控件是否正常，这一点常被低估——演示翻车往往不是因为后端，而是前端某个按钮不响应。综合整理一份检查清单：

• 网络：确认容器内使用的是服务名而非 localhost，且两个服务在同一网络。
• 认证：token 通过环境变量注入，非明文硬编码，示例配置已脱敏。
• 记忆链路：写入一条测试记忆并成功取回，日志中无回退记录。
• 回退路径：停掉 Hindsight 后应用仍可用，数据不乱。
• 前端：Ops Console 所有导航项和交互控件逐一点过。
• 日志级别：演示时把记忆相关日志调到可见级别，方便展示系统在「思考」。

架构层面的一个建议

RecallOps 的适配器模式设计是对的，但可以再往前走一步：把「记忆操作」抽象成一组明确的接口（写入、按语义检索、按时间范围检索、删除），让 Hindsight 和 SQLite 都实现这套接口。这样回退时行为可预期，测试也更容易写——针对接口写一套测试用例，两个后端各跑一遍就能证明适配器一致。

对于 Groq/OpenAI 的推理层，同样建议保留可切换的配置。应急响应场景对延迟敏感，不同模型在工具调用和长上下文上的表现差异明显，留好切换口子在演示和实际使用中都更灵活。

整套集成并不复杂，难的是把每个环节的「隐式假设」显式化：网络怎么通、认证怎么带、回退怎么看得见。想清楚这三点，RecallOps 的记忆层就能稳稳跑起来。