TencentDB Agent Memory 之 MemoryPanel 容器化部署指南:team-memory-control 单镜像构建与运行实战

原创2026-09-10 10:07:411,750 阅读
文章标签:人工智能AI AgentAgent 记忆本地部署MCP 服务知识图谱后端前端

TencentDB Agent Memory 之 MemoryPanel 容器化部署指南:team-memory-control 单镜像构建与运行实战

导读

本文以 MemoryPanel/docker/README.md 为核心,系统讲解 TencentDB Agent Memory 项目中 team-memory-control(Control 面板后端)的 Docker 容器化部署方案。你将掌握:Dockerfile.local 多阶段构建的内部结构、PANEL_UI/WEB_UI 两个关键构建参数的作用、完整的 docker build / docker run 命令、全部运行时环境变量语义,以及构建上下文忽略与密钥安全的最佳实践。读完即可在本地或离线环境一键构建并运行 :8123 的 Control 面板,并连通 Knowledge Service 与记忆 Gateway。


一、镜像定位:一个镜像装下「面板后端 + 前端静态资源」

docker/ 目录为 team-memory-control(Control 面板)提供容器化构建文件,产物是一个单体镜像:

  • 后端:Control HTTP 服务,默认监听 :8123,以 tsx 直跑 src/index.ts(stateless panel,业务入口在 src/panel/);
  • 前端:web/ 前端工程在独立 stage 编译,产物以静态资源形式由同一进程托管。
镜像名(示例) Dockerfile 构建上下文 说明
team-memory-control:local docker/local/Dockerfile.local 仓库根目录 . Control HTTP 服务,默认 :8123

目录结构如下:

docker/
├── README.md                          # 本文件
└── local/
    ├── Dockerfile.local               # Control 单镜像(多阶段构建)
    └── Dockerfile.local.dockerignore  # 构建上下文忽略规则

关键点:构建上下文必须是仓库根目录(整个仓库),因为 COPY . . 需要打包全部源码;这也是后面讨论 dockerignore 与密钥安全的基础。


二、Dockerfile.local 多阶段构建拆解

Dockerfile.local 共分三个阶段:

Stage 作用
base node:22-slim + 原生编译工具链(better-sqlite3 需要 python3/make/g++)
ui-builder 编译 web/:npm install + npm run build → dist/
runtime 拷贝全仓源码、npm install、嵌入 UI 产物,启动 Control

2.1 base:适配国内网络的原生依赖编译环境

base 阶段做了两件对国内开发者很实用的事:

  1. apt 源替换为腾讯云镜像:sed -i 's|deb.debian.org|mirrors.tencent.com|g' 替换 Debian 软件源,加速 apt-get update;
  2. 安装原生编译工具链:python3 make g++ git curl ca-certificates。其中 python3/make/g++ 是 better-sqlite3 原生模块编译的硬性依赖,curl 供 HEALTHCHECK 使用,git 可选。

apt 安装使用 BuildKit 缓存挂载(--mount=type=cache,target=/var/cache/apt,sharing=locked),多次构建时无需重复下载。

2.2 ui-builder:只构建被选中的面板

FROM base AS ui-builder
ARG PANEL_UI
ARG WEB_UI=1
COPY ${PANEL_UI}/ /ui/
  • PANEL_UI 决定拷贝哪个前端工程;
  • WEB_UI=1(默认)时执行 npm install --no-audit --no-fund && npm run build;
  • WEB_UI=0 时跳过 UI 构建,生成占位 index.html(详见第四节)。

2.3 runtime:整仓拷贝 + 镜像内重装依赖

FROM base AS runtime
COPY . .
RUN --mount=type=cache,id=npm-tmc,target=/root/.npm \
    npm install --no-audit --no-fund
COPY --from=ui-builder /ui/dist ./${PANEL_UI}/dist
ENV UI_DIST_DIR=./${PANEL_UI}/dist
ENV NODE_ENV=production HOST=0.0.0.0 PORT=8123

三个设计要点:

  • 全量依赖:COPY . . 后执行 npm install,不采用生产依赖裁剪,保证 stateless 后端在容器内完整运行;
  • 镜像内重编原生模块:宿主机平台编译的 better-sqlite3 二进制不能跨平台复用,因此在 runtime 阶段重新 npm install 编译(这正是 dockerignore 排除 node_modules 的原因);
  • 启动方式:CMD ["node", "--import", "tsx/esm", "src/index.ts"] 直接用 tsx 运行 TypeScript 源码,无需编译产物。

2.4 端口、健康检查与静态托管

  • 端口:EXPOSE 8123,运行时以 HOST=0.0.0.0 监听;
  • 健康检查:HEALTHCHECK 每 15s 探测一次,超时 10s、重试 20 次、启动宽限 60s,检查命令为 curl -fsS http://127.0.0.1:8123/health;
  • 静态托管:ENV UI_DIST_DIR=./web/dist 指向 UI 产物目录。在 src/panel/http/app.ts 中,serveStatic 以该目录为根托管前端;/api/ 与 /health 路径优先命中后端路由,其余路径回退到 index.html(SPA 路由兜底)。

三、构建参数说明

参数 默认值 说明
PANEL_UI web 前端工程目录(当前活跃面板为 web/;frontend/ 为历史目录,已不维护)
WEB_UI 1 1 正常构建面板 UI;0 跳过 UI 构建、生成占位 index.html(见下文「禁用面板 UI 构建」)

运行时通过 METADATA_INSTANCES_CONFIG 指定实例表,UI_DIST_DIR=./web/dist 托管前端(Dockerfile 已通过 ENV 预置,可在 docker run 时覆盖)。


四、构建与运行

4.1 前置条件

  • Docker(建议启用 BuildKit,以使用 --mount=type=cache 缓存挂载与 <dockerfile>.dockerignore 优先规则);
  • Node 引擎要求与仓库一致:>=22(见仓库根 package.json)——仅影响源码开发,容器内已由 node:22-slim 固定;
  • 构建必须在仓库根目录执行(上下文为整个仓库)。

4.2 标准构建与启动命令

# 在仓库根目录
docker build \
  --build-arg PANEL_UI=web \
  -t team-memory-control:local \
  -f docker/local/Dockerfile.local .

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

登录方式:浏览器打开 http://localhost:8123/,选择实例 ID,填入 Gateway 的 user_key。实例表字段说明见 config/metadata-instances.README.md。

网络注意事项:若 Gateway 跑在宿主机,挂载的 metadata-instances.json 里 gateway_endpoint 须用容器可访问的地址(如 http://host.docker.internal:8420),不要用 127.0.0.1(容器内回环地址指向容器自身)。同理,KNOWLEDGE_SERVICE_URL、KNOWLEDGE_LLM_PROXY_BASE_URL 也需指向容器可达的 KS 与 proxy。

4.3 禁用面板 UI 构建(WEB_UI=0)

面板 UI 依赖 @tencent/* 等内部包,公共 npm 镜像不提供。若构建环境无法访问内部 npm 源(如离线机、外部 CI),npm install 会失败。此时用 WEB_UI=0 跳过 UI 构建:

docker build \
  --build-arg PANEL_UI=web \
  --build-arg WEB_UI=0 \
  -t team-memory-control:local-no-ui \
  -f docker/local/Dockerfile.local .

该模式的行为在 Dockerfile 中由条件分支实现:WEB_UI=0 时不再执行 npm install/npm run build,而是直接写入占位 dist/index.html(内容为 “Control panel UI is disabled in this image”)。

能力边界:镜像会生成占位 dist/index.html,Control 后端与 /health、/api/* 完全可用(app.ts 中 /api/ 与 /health 优先返回后端路由,不依赖前端产物),仅静态面板页面不可访问(前端路由返回占位提示)。需要面板 UI 时请用默认 WEB_UI=1 并确保能拉到内部依赖。


五、常用环境变量全解

下表完整继承自 docker/README.md,并对照 panel-config.ts 源码验证了默认值、类型与解析方式(envInt 对非法数字回退默认值,envBool 仅接受 true/1 为真):

变量 默认 说明
UI_DIST_DIR ./web/dist 静态前端目录(Dockerfile 通过 ENV 设为 ./${PANEL_UI}/dist)
METADATA_INSTANCES_CONFIG ./config/metadata-instances.json 实例注册表路径
METADATA_REMOTE_TIMEOUT_MS 15000 转发 Gateway 超时(毫秒)
KNOWLEDGE_SERVICE_URL http://127.0.0.1:8421 Knowledge Service(KS)地址,容器内须指向容器可访问的 KS
KNOWLEDGE_AUTH_TOKEN — 调 KS 的 bearer token,按部署填充
KNOWLEDGE_TIMEOUT_MS 15000 调 KS 超时(毫秒)
KNOWLEDGE_LLM_BINDING_SYNC true 启动时为每个实例确保 KS 的 LLM 绑定(走 proxy 记账);false 跳过
KNOWLEDGE_LLM_PROXY_BASE_URL http://127.0.0.1:8096 LLM 记账 proxy 地址(容器内须可达)
LOG_LEVEL / LOG_FORMAT info / json 日志级别与格式;本地可设 LOG_FORMAT=pretty

此外,从 panel-config.ts 源码还可确认两个由 Dockerfile 预置、通常无需手动覆盖的服务端变量:HOST(默认 0.0.0.0)与 PORT(默认 8123)。

注:LLM_MODEL(wiki ingest 模型)不在 Panel 配置,统一由 KS 侧 LLM_MODEL 决定(默认 Memory-Model)。

5.1 关于 KNOWLEDGE_LLM_BINDING_SYNC 的底层行为

启动时若 KNOWLEDGE_LLM_BINDING_SYNC=true,src/panel/index.ts 会以 best-effort 非阻塞方式调用 ensureKnowledgeLlmBindings。其流程见 ensure-knowledge-llm-binding.ts:

  1. 先一次性调 KS /v3/internal/llm-binding/list 拿到所有 binding 状态缓存;
  2. 对每个 TMC 实例:
    • KS 已有可用 key(has_api_key=true)→ 不碰 Gateway,仅调 /set 更新 proxy_base_url(不传 api_key,KS 保留原值);
    • KS 无可用 key → 走 Gateway user/list + user/create(或 user-key/create)流程,mint 新 key 后 push 到 KS /set;
  3. 任何单实例失败仅记日志跳过,绝不阻塞启动。

该设计避免每次 Panel 重启都去 Gateway 重新 mint key(受 active key 上限 20 约束),对应文档中「启动卡在 ensure LLM binding」的故障排查建议(见第八节)。


六、实例注册表 metadata-instances.json

容器内的实例表通过 METADATA_INSTANCES_CONFIG 指定,并以只读卷挂载覆盖镜像内文件。字段语义(详见 metadata-instances.README.md):

字段 必填 说明
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 的转发地址
proxy_endpoint 否 客户端接入 baseUrl;仅用于 UI「客户端接入地址」卡片展示,缺省回落 gateway_endpoint
api_key 是 Gateway Bearer;仅服务端转发用,不出现在 instances API

参照 config/metadata-instances.example.json 的完整样例,本地初始化方式为:

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

config/metadata-instances.json 已加入 .gitignore;仓库只保留 metadata-instances.example.json。


七、Dockerfile.local.dockerignore 与安全提示

BuildKit 会优先使用 <dockerfile>.dockerignore(而非仓库根 .dockerignore)。当前忽略清单(见 Dockerfile.local.dockerignore)主要排除:

  • **/node_modules、.pnpm-store/ — 避免宿主机平台编译的 better-sqlite3 或旧依赖进入镜像(镜像内会重新 npm install 重编);
  • **/dist、**/build、*.map、*.tsbuildinfo — 旧产物不入镜像(UI 在 ui-builder stage 重新构建);
  • .env、.env.*、config/*.json、config/*.yaml、data/、**/*.db 等 — 禁止把密钥与本地数据打进镜像;
  • docs/、tests/、e2e 脚本、.git 等 — 缩小构建上下文(tests 目录中的 shell 脚本硬编码内部路径,排除还可避免泄漏内部 GitLab 域名与部署习惯)。

安全提示(务必重视):注意 dockerignore 中 config/*.json 会排除 metadata-instances.json,但 Dockerfile 的 COPY . . 在构建上下文层面仍可能把该文件带进镜像除非被 dockerignore 命中。文档明确警告:若 metadata-instances.json 含真实 api_key,生产镜像应改为运行时挂载(-v /path/to/metadata-instances.json:/app/config/metadata-instances.json:ro),或在 dockerignore 中排除该文件并强制 -v 挂载,严禁把密钥打进镜像层。


八、本地开发对照与故障排查

方式 命令
源码开发 pnpm dev
Docker 单镜像 见上文 docker build / docker run

常见故障速查表(现象 → 可能原因):

现象 可能原因
GET / 404 UI_DIST_DIR 未设为 ./web/dist,或前端 stage npm run build 失败
登录后 API 401 / 无 team metadata-instances.json 中 gateway_endpoint 不可达,或 api_key 与 Gateway 不一致
知识资产加载失败 / 500 KNOWLEDGE_SERVICE_URL 容器内不可达,或 KNOWLEDGE_AUTH_TOKEN 不匹配
启动卡在「ensure LLM binding」 KNOWLEDGE_LLM_PROXY_BASE_URL 容器内不可达;可设 KNOWLEDGE_LLM_BINDING_SYNC=false 临时跳过

结合前文源码可进一步定位:GET / 404 对应 app.ts 中 serveStatic({ root: distDir }) 的根目录配置;「ensure LLM binding」卡住则源于 ensure-knowledge-llm-binding.ts 中 mint key / /set 调用对 proxy 与 KS 的依赖——虽然该逻辑整体 best-effort 不阻塞启动,但若 proxy 不可达,日志会持续告警并最终导致 wiki 侧 LLM 记账不可用,此时临时关闭同步可先恢复面板其他功能。


九、可继续深入的仓库路径索引

登录后查看全文
TencentDB-Agent-Memory