[Bug/文档] 未配置 injection.externalGatewayUrl 时注入模板使用 fallback 网卡 IP，客户端 curl 超时；改配置后需清 hook cache

[vc1235-ui]

问题描述

单机部署 MemoryProxy（监听 0.0.0.0:8096），未配置 injection.externalGatewayUrl。LLM 系统提示中被注入的 <skill_tools> / <tdai_memory_tools> 模板，其中的 curl 地址为 fallback 出来的本机网卡 IP（http://10.100.1.4:8096），而该 IP 是部署机的旧网卡/容器网络地址，客户端实际不可达。

现象

1. agent 每次执行记忆检索 / skill 调用（curl <bridge>/memory-bridge/v3/...）全部超时（curl exit 28），记忆功能完全不可用；
2. 会话日志中可见模板地址与部署机实际 IP（192.168.204.160:8096）不一致，客户端无法访问 10.100.1.4:8096；
3. 排查过程确认：本机客户端（DSH/agent 运行端）与部署机均为内网环境，192.168.204.160:8096 可达，10.100.1.4:8096 不可达。

根因分析

MemoryProxy/src/injection/index.ts（约 255~288 行）：未配置 injection.externalGatewayUrl 时，proxyBaseUrl fallback 为 http://${hostIp}:${config.server.port}，其中 hostIp 取第一块非 internal 的 IPv4 网卡地址。

在以下场景会产出"客户端不可达"的模板地址：

• 部署机存在多网卡（如同时有 10.100.1.4 管理网和 192.168.204.160 业务网），取到的网卡 IP 不是客户端视角的访问地址；
• 部署机迁移/换 IP 后，旧 IP 被写入模板。

另外，模板渲染结果存在 hook cache（RedisHookCacheRepo / KvHookCacheRepo / ProxyStorage，多节点共享会互相覆盖）。修改 externalGatewayUrl 或网卡 IP 后，如果不清理缓存，LLM 仍会拿到旧模板，新配置不生效——排查时容易误判为"改了没生效"。

建议

1. 文档强化：在 config.example.yaml 的 injection.externalGatewayUrl 注释与部署文档中，把"生产必须显式配置"从"多节点必配"扩展到单节点也建议必配，并说明 fallback 行为（取哪块网卡、会产生什么问题）；
2. 缓存说明：在文档中明确"修改 externalGatewayUrl 后需清理 injection hook cache（Redis/COS）并重启，否则旧模板继续生效"；
3. 代码健壮性（可选）：fallback 时当前已有 warn 日志，但建议同时把 fallback 地址写入 health/诊断端点（如 GET /health 或新增 /injection/status），便于部署后快速核对模板中实际注入的地址；
4. 代码健壮性（可选）：fallback 取网卡 IP 时，若 config.server.host 为 0.0.0.0 且无法确定可达地址，可考虑优先输出警告并提示配置 externalGatewayUrl，避免静默产出错误模板。

环境信息

• 组件：MemoryProxy（单节点）
• 配置：server.host: 0.0.0.0、server.port: 8096；injection.injectors: ["skill", "knowledge", "tdai-memory"]；未设置 injection.externalGatewayUrl
• 触发链路：DSH 客户端 → proxy /dsh/default → 注入模板 → LLM 按模板 curl fallback 地址 → 超时

[vc1235-ui]

补充调查：injection.externalGatewayUrl 无远程修改通道，运维成本高

继续排查后确认，该配置只能本地 YAML + 重启进程生效，没有任何远程管理/热更新入口：

现状（代码事实）

1. 只从 YAML 启动时加载一次：src/config.ts 的 loadYamlConfig 用 readFileSync 一次性读入，无 watch/热重载；externalGatewayUrl（config.ts:388）不支持环境变量或 CLI 参数覆盖，改配置必须重启进程。
2. API 路由中没有配置管理端点（src/server.ts）：
   • GET/PUT/DELETE /v3/admin/rate-limits —— 仅限流配置，与 injection 无关；
   • POST /v3/session/refresh-cache —— 仅用进程内已加载的 config 对指定 session 重新 prewarm、刷新 hook 缓存，改不了地址本身（且多节点下若 hook cache 共享，其他节点旧模板仍需分别处理）；
   • 其余均为业务/代理端点。

建议

1. 支持环境变量覆盖：INJECTION_EXTERNAL_GATEWAY_URL（或统一 CONFIG_* 机制）优先级高于 YAML，便于容器化部署（K8s env / ConfigMap）与远程编排平台直接下发，无需 SSH 改文件；
2. 增加配置管理端点（可选，鉴权保护）：如 GET /v3/admin/config（脱敏展示当前生效配置，含 proxyBaseUrl 解析结果，便于核对模板实际地址）+ PUT /v3/admin/config（热更新 + 触发 hook cache 刷新），彻底解决"改了没生效"的排查困境；
3. 文档补充：明确"该配置无运行时修改入口，变更需改 YAML + 重启 + 清 hook cache"，避免其他部署者重复踩坑。