ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

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

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-MemoryMemoryPanelControl Panel是 TencentDB Agent Memory 的治理面板采用无状态stateless架构通过一份本地 JSON 文件注册要纳管的记忆 Gateway 实例。本文以 MemoryPanel/config/metadata-instances.README.md 为骨架完整讲解metadata-instances.json的每个字段含义、本地与容器部署的配置步骤、底层加载与转发机制以及密钥保密要求。读完你既能独立完成多实例接入配置也能理解 Panel 后端如何依据该文件完成身份校验、请求转发与公开实例列表下发。一、为什么需要实例注册表stateless 面板与多实例纳管MemoryPanel 作为无状态控制面板自身不持有任何记忆数据所有元数据用户、团队、Agent、Skill、资产、ACL 等都保存在后端的记忆 GatewayKernel中。面板需要一种零数据库的方式声明我要管理哪些实例、每个实例的 Gateway 在哪里、用什么凭证转发——这份声明就是metadata-instances.json。从仓库结构看Panel 后端启动时panel-deps.ts会调用InstanceRegistry.load(config.metadataInstancesConfig)加载注册表随后所有针对某个实例的元数据请求都通过该注册表解析出目标gateway_endpoint与api_key再转发到内核。因此注册表是 Panel 与 Kernel 之间唯一的路由与凭证来源。二、字段总览与逐项精解原文档给出了核心字段表下面在完整继承的基础上结合 instance-registry.ts 的 zod 校验约束做逐项展开。字段必填说明id是instance_id 内核x-tdai-service-id本地常用default线上mem-{slug}name是登录页展示名仅通过GET /api/v1/meta/instances公开gateway_endpoint是记忆 Gateway 根 URL本地http://127.0.0.1:8420。Panel 后端 → Kernel 的转发地址不要用它来指 proxyproxy_endpoint否客户端接入 baseUrlCodeBuddy / ClaudeCode CLI 等。仅用于 Panel UI 客户端接入地址卡片的拼接展示。缺省时回落到gateway_endpoint等同老行为。线上部署 gateway 前置了 proxy 时两个值合一可以省略本地开源部署 core 和 proxy 分开时这里填 proxy 的对外地址如http://127.0.0.1:8096api_key是Gateway Bearer仅服务端转发用不出现在 instances API2.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_endpointPanel → 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 客户端接入地址 显示本地开源 coreproxy 分开跑时填 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-testE2E 自动化测试专用可随时清库。示例默认只演示了最小必填字段如需展示客户端接入地址可按需为实例补充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存在性检查文件不存在则抛出500 metadata instances config not found错误信息中直接给出cp config/metadata-instances.example.json config/metadata-instances.json的修复提示JSON 解析解析失败如语法错误抛出invalid metadata instances configzod 模式校验instances数组至少 1 项每项id、name、api_key非空gateway_endpoint必须是合法 URLproxy_endpoint可选但同样必须是合法 URL。校验失败时抛出metadata instances config validation failed。4.3 启动时序与依赖项参考 README.md 的本地开发流程完整步骤为pnpm installweb 目录另需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.tsKnowledge 回调的 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.jsonpanel-config.ts。相关环境变量汇总如下完整清单见 .env.example 与 docker/README.md变量默认值说明METADATA_INSTANCES_CONFIG./config/metadata-instances.json实例注册表路径METADATA_REMOTE_TIMEOUT_MS15000转发 Gateway 超时KNOWLEDGE_SERVICE_URLhttp://127.0.0.1:8421Knowledge Service 地址KNOWLEDGE_AUTH_TOKEN—调 KS 的 bearer tokenKNOWLEDGE_LLM_BINDING_SYNCtrue启动时是否同步 LLM binding6.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_URLhttp://host.docker.internal:8421 \ -e KNOWLEDGE_AUTH_TOKENks-token \ -e KNOWLEDGE_LLM_PROXY_BASE_URLhttp://host.docker.internal:8096 \ -v $(pwd)/config/metadata-instances.json:/app/config/metadata-instances.json:ro \ team-memory-control:local两条关键注意事项容器内地址若 Gateway 跑在宿主机挂载的metadata-instances.json里gateway_endpoint须用容器可访问的地址如http://host.docker.internal:8420不要用127.0.0.1镜像安全config/*.json含真实 kernel api_keybearer tokenDockerfile 的 dockerignore 已显式排除本地真值文件Dockerfile.local.dockerignore运行时通过-v挂载或 K8s Secret 注入。七、安全红线与更新注意事项凭证不入库config/metadata-instances.json已加入.gitignore仓库只保留 example 模板禁止把含真实api_key的文件提交到版本库api_key 永不公开它只存在于服务端转发链路instances API 不下发镜像内不留密钥生产镜像应运行时挂载真值文件或在 dockerignore 中排除并强制-v挂载docker/README.md更新提示首次 pull 到「该文件出库」的提交前请先备份本地metadata-instances.jsonpull 后若文件被删从备份恢复或按上文从 example 重新拷贝再填 key见原文档 metadata-instances.README.md。八、常见问题排查结合 docker/README.md 的故障排查表与注册表相关的高频问题如下现象可能原因启动报metadata instances config not found未执行cp config/metadata-instances.example.json config/metadata-instances.json启动报metadata instances config validation failed字段缺失、gateway_endpoint非法 URL、instances数组为空登录后 API 401 / 无 teammetadata-instances.json中gateway_endpoint不可达或api_key与 Gateway 不一致请求返回INVALID_INSTANCE请求头instance_id未在注册表中登记结语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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表