TencentDB Agent Memory MemoryPanel 多实例注册表配置完全指南：metadata-instances.json 字段解析与安全实践

TencentDB Agent Memory MemoryPanel 多实例注册表配置完全指南：metadata-instances.json 字段解析与安全实践

【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory

MemoryPanel（Control Panel）是 TencentDB Agent Memory 的治理面板，采用无状态（stateless）架构，通过一份本地 JSON 文件注册要纳管的记忆 Gateway 实例。本文以 MemoryPanel/config/metadata-instances.README.md 为骨架，完整讲解metadata-instances.json的每个字段含义、本地与容器部署的配置步骤、底层加载与转发机制，以及密钥保密要求。读完你既能独立完成多实例接入配置，也能理解 Panel 后端如何依据该文件完成身份校验、请求转发与公开实例列表下发。

一、为什么需要实例注册表：stateless 面板与多实例纳管

MemoryPanel 作为无状态控制面板，自身不持有任何记忆数据，所有元数据（用户、团队、Agent、Skill、资产、ACL 等）都保存在后端的记忆 Gateway（Kernel）中。面板需要一种"零数据库"的方式声明"我要管理哪些实例、每个实例的 Gateway 在哪里、用什么凭证转发"——这份声明就是metadata-instances.json。

从仓库结构看，Panel 后端启动时（panel-deps.ts）会调用InstanceRegistry.load(config.metadataInstancesConfig)加载注册表，随后所有针对某个实例的元数据请求，都通过该注册表解析出目标gateway_endpoint与api_key再转发到内核。因此，注册表是 Panel 与 Kernel 之间唯一的路由与凭证来源。

二、字段总览与逐项精解

原文档给出了核心字段表，下面在完整继承的基础上，结合 instance-registry.ts 的 zod 校验约束做逐项展开。

2.1id：实例身份即内核服务标识

id不只是面板内部索引，它在整个链路中等价于内核的x-tdai-service-id请求头。从 validate-panel-headers.ts 可以看到，面板收到元数据请求后，会从请求头取出instance_id，调用deps.instanceRegistry.resolve(instanceId)解析注册表条目；如果不存在，直接返回400 INVALID_INSTANCE。也就是说，前端每个请求必须携带的实例 ID，必须在注册表中预先登记，二者一一对应。

命名约定上，本地开发常用default；线上按环境/租户使用mem-{slug}形态，便于区分 dev、staging、prod 等不同实例。

2.2name：唯一公开的展示字段

name只用于登录页/实例选择页的展示，且是唯一通过公开接口下发的注册表字段（连同id）。原因见 instance-registry.ts 的listPublic()：公开视图仅输出instance_id、name、gateway_endpoint与可选的proxy_endpoint，绝不包含api_key。

2.3gateway_endpoint：Panel → Kernel 的转发地址

这是最容易混淆的字段。它的语义是Panel 后端向内核转发请求时使用的根 URL，而非客户端（CodeBuddy / ClaudeCode CLI）的接入地址。本地开源部署时 MemoryCore Gateway 默认监听8420端口（见 tdai-gateway.yaml 与 tdai-gateway.standalone.yaml），因此本地示例填http://127.0.0.1:8420。

源码注释（instance-registry.ts）特别强调：gateway_endpoint控制的是面板转发链路，绝对不能挪作 proxy 使用；即便客户端实际直连 proxy，面板转发也必须指向 gateway。

2.4proxy_endpoint：可选的客户端展示地址

proxy_endpoint不影响任何转发行为，仅用于前端"客户端接入地址"卡片的拼接展示。它遵循以下回退逻辑：

• 缺省（不填）：前端回落gateway_endpoint，等同老行为；
• 线上/内网部署：Gateway 前置了 Proxy，两个值合一，直接省略该字段；
• 本地开源部署：Core 与 Proxy 分开运行，客户端要接的是 Proxy 的对外地址，此时显式填写，如http://127.0.0.1:8096。

在listPublic()中，proxy_endpoint仅在显式配置时才随响应下发，避免前端拿到undefined字段（instance-registry.ts）。

2.5api_key：服务端专用 Bearer 凭证

api_key是调用 Gateway 时使用的 Bearer Token（从 kernel 侧获取，即 tdai kernel gateway 的 bearer token）。它只在 Panel 后端 → Kernel 的服务端转发中使用：中间件解析出实例条目后，把gatewayApiKey写入请求上下文（validate-panel-headers.ts）。任何公开接口、登录页响应都不会下发该值，它是注册表中最敏感的数据，等同于内核的访问凭证。

三、完整配置示例（可复制）

仓库提供可直接复制改写的模板 config/metadata-instances.example.json，结构如下：

{ "_comment": "复制本文件为 metadata-instances.json 后按注释替换真值。真值文件已被 .gitignore 排除，禁止提交。api_key 是 tdai kernel gateway 的 bearer token，从 kernel 侧获取。proxy_endpoint 可选，仅影响 UI '客户端接入地址' 显示；本地开源 core+proxy 分开跑时填 proxy 对外地址（如 http://127.0.0.1:8096），线上/内网 gateway 前置 proxy 时省略。", "instances": [ { "id": "default", "name": "本地默认实例", "gateway_endpoint": "http://127.0.0.1:8420", "api_key": "REPLACE_WITH_KERNEL_BEARER_TOKEN" }, { "id": "e2e-test", "name": "E2E 自动化测试专用（可随时清库）", "gateway_endpoint": "http://127.0.0.1:8420", "api_key": "REPLACE_WITH_KERNEL_BEARER_TOKEN" } ] }

模板中预设了两个实例：default（本地默认实例）与e2e-test（E2E 自动化测试专用，可随时清库）。示例默认只演示了最小必填字段；如需展示客户端接入地址，可按需为实例补充proxy_endpoint。

四、本地配置与启动步骤

4.1 生成本地配置文件

cp config/metadata-instances.example.json config/metadata-instances.json # 再按本机 Gateway 填写 gateway_endpoint / api_key

复制完成后，编辑config/metadata-instances.json，将每个实例的gateway_endpoint指向本机可达的 Gateway（本地为http://127.0.0.1:8420），并用从内核侧获取的真实 Bearer Token 替换api_key占位值。文件包含凭证，已被.gitignore排除，不得提交入库；仓库只保留metadata-instances.example.json作为模板。

4.2 面板启动链路

配置好后启动面板，InstanceRegistry.load()会在启动阶段完成三项工作（instance-registry.ts）：

1. 存在性检查：文件不存在则抛出500 metadata instances config not found，错误信息中直接给出cp config/metadata-instances.example.json config/metadata-instances.json的修复提示；
2. JSON 解析：解析失败（如语法错误）抛出invalid metadata instances config；
3. zod 模式校验：instances数组至少 1 项；每项id、name、api_key非空，gateway_endpoint必须是合法 URL，proxy_endpoint可选但同样必须是合法 URL。校验失败时抛出metadata instances config validation failed。

4.3 启动时序与依赖项

参考 README.md 的本地开发流程，完整步骤为：pnpm install（web 目录另需npm install）→ 复制.env.example为.env→ 复制并编辑实例注册表 →pnpm dev启动后端（默认http://127.0.0.1:8123，健康检查GET /health）→cd web && npm run dev启动前端（http://127.0.0.1:5173，开发服务器将/api/v1与/health转发到本地 Control）。前置条件包括 Node.js 22+、可访问的 Memory Gateway，以及使用 Wiki / Code Graph 时需可访问的 Knowledge Service。

五、注册表的运行时消费链路

配置不是静态摆设，注册表在面板的多个环节被实时消费：

• 实例列表下发：GET /api/v1/meta/instances直接返回deps.instanceRegistry.listPublic()（routes/meta/instances.ts），即仅公开instance_id、name（及可选proxy_endpoint），无分页；
• 请求身份校验与转发：元数据中间件按请求头instance_id解析条目，将gateway_endpoint与api_key注入上下文，供后续 Meta / Skill / Chat-Memory 等路由转发到内核（validate-panel-headers.ts）；
• Knowledge 回调的 S2S 资产登记：Knowledge Service 抽取完成回调时，面板用注册表解析出的gateway_endpoint与api_key以任务发起者身份把知识资产登记为 meta 资产（callback-routes.ts）；
• 启动时 LLM binding 同步：面板启动会遍历注册表中每个实例，向 Knowledge Service 确保该实例的 LLM binding 存在（best-effort，失败只记日志不阻塞启动），详见 ensure-knowledge-llm-binding.ts 与 .env.example 中的KNOWLEDGE_LLM_BINDING_SYNC开关。

六、环境变量与容器化部署要点

6.1 注册表路径由环境变量控制

注册表文件路径通过METADATA_INSTANCES_CONFIG环境变量指定，默认./config/metadata-instances.json（panel-config.ts）。相关环境变量汇总如下（完整清单见 .env.example 与 docker/README.md）：

6.2 Docker 部署必须只读挂载

容器化部署时，必须通过只读挂载提供metadata-instances.json，禁止把真实 API Key 写入镜像、示例文件或版本库（README.md）。参考命令：

docker run -d --name tmc-control \ -p 8123:8123 \ -e UI_DIST_DIR=./web/dist \ -e METADATA_INSTANCES_CONFIG=/app/config/metadata-instances.json \ -e KNOWLEDGE_SERVICE_URL=http://host.docker.internal:8421 \ -e KNOWLEDGE_AUTH_TOKEN=<ks-token> \ -e KNOWLEDGE_LLM_PROXY_BASE_URL=http://host.docker.internal:8096 \ -v "$(pwd)/config/metadata-instances.json:/app/config/metadata-instances.json:ro" \ team-memory-control:local

两条关键注意事项：

1. 容器内地址：若 Gateway 跑在宿主机，挂载的metadata-instances.json里gateway_endpoint须用容器可访问的地址（如http://host.docker.internal:8420），不要用127.0.0.1；
2. 镜像安全：config/*.json含真实 kernel api_key（bearer token），Dockerfile 的 dockerignore 已显式排除本地真值文件（Dockerfile.local.dockerignore），运行时通过-v挂载或 K8s Secret 注入。

七、安全红线与更新注意事项

1. 凭证不入库：config/metadata-instances.json已加入.gitignore，仓库只保留 example 模板；禁止把含真实api_key的文件提交到版本库；
2. api_key 永不公开：它只存在于服务端转发链路，instances API 不下发；
3. 镜像内不留密钥：生产镜像应运行时挂载真值文件，或在 dockerignore 中排除并强制-v挂载（docker/README.md）；
4. 更新提示：首次 pull 到「该文件出库」的提交前，请先备份本地metadata-instances.json；pull 后若文件被删，从备份恢复，或按上文从 example 重新拷贝再填 key（见原文档 metadata-instances.README.md）。

八、常见问题排查

结合 docker/README.md 的故障排查表，与注册表相关的高频问题如下：

结语

metadata-instances.json是 MemoryPanel stateless 架构的核心路由表：id绑定内核服务标识、gateway_endpoint决定面板转发去向、api_key保障服务端凭证安全、proxy_endpoint优化客户端接入展示。正确理解这四个字段的分工与回退关系，区分"面板转发地址"与"客户端接入地址"，并坚持"凭证不入库、容器只读挂载"的安全基线，即可在多实例、多环境（本地 / dev / staging / prod）下稳定纳管你的记忆资产。

【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory