[Question]: Max retries exceeded with url: /run (Caused by NewConnectionError(“HTTPConnection(host=’sandbox-executor-manager’, port=9385): F

[Question]: Max retries exceeded with url: /run (Caused by NewConnectionError(“HTTPConnection(host=’sandbox-executor-manager’, port=9385): Failed to establish a new connection: [Errno 111] Connection refused”))

快速结论：这个报错最常见于使用 Helm 部署 RAGFlow 后，启用代码组件（code component）但未部署独立的 sandbox-executor-manager 服务。优先排查 Helm charts 是否包含 sandbox 服务，以及 SANDBOX_HOST 环境变量是否配置正确。

问题场景

用户通过 Helm 部署 RAGFlow 后，在使用代码组件时触发异常。设置 SANDBOX_ENABLED=1 环境变量后，RAGFlow 服务尝试连接自定义主机名 sandbox-executor-manager:9385，但因服务不存在导致连接被拒绝。

报错原文

Exception executing code: HTTPConnectionPool(host='sandbox-executor-manager', port=9385): Max retries exceeded with url: /run (Caused by NewConnectionError("HTTPConnection(host='sandbox-executor-manager', port=9385): Failed to establish a new connection: [Errno 111] Connection refused"))

原因分析

RAGFlow 的 Helm charts 当前不包含 sandbox-executor-manager 服务。 设置 SANDBOX_ENABLED=1 会使 RAGFlow 尝试使用沙箱服务，但该服务在 Helm 部署中默认不存在。此外，如果不设置 SANDBOX_ENABLED=1，代码组件可能无法正常运行，因为沙箱服务是代码执行的必要组件。

环境排查

确认 Helm 部署的 RAGFlow 版本。
检查是否已部署独立的 sandbox-executor-manager 服务。
确认 SANDBOX_HOST 和 SANDBOX_ENABLED 环境变量是否在 RAGFlow 的 Helm values 中正确配置。
确认 sandbox 服务所在主机的 Docker 版本（需 Docker 25.0+）。

解决步骤

部署独立的 sandbox-executor-manager 服务（可优先尝试）：使用 agent/sandbox 目录下的 docker-compose.yml 单独部署，或创建 Kubernetes Deployment。sandbox 服务需要：
- 特权模式（privileged mode）
- Docker 套接字挂载（/var/run/docker.sock）
- 暴露端口 9385
- 宿主机已安装 gVisor runtime
配置网络连通性：确保 RAGFlow 的 Pod 能够通过网络访问 sandbox 服务的 9385 端口。
设置 SANDBOX_HOST 环境变量：在 RAGFlow 的 Helm values 中，将 SANDBOX_HOST 设置为 sandbox 服务的实际地址（而非默认的 sandbox-executor-manager 主机名）。
设置 SANDBOX_ENABLED=1：必须启用此环境变量，否则代码组件无法调用沙箱服务。

验证方法

在 RAGFlow 前端界面中创建一个新的代码组件并运行。如果不再出现 Max retries exceeded 或 Connection refused 错误，且组件正常执行并返回结果，则表明问题已解决。也可通过 kubectl logs 查看 RAGFlow Pod 日志，确认无连接 sandbox 服务的报错。