TencentDB Agent Memory 之 MemoryPanel 容器化部署指南:team-memory-control 单镜像构建与运行实战
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 阶段做了两件对国内开发者很实用的事:
- apt 源替换为腾讯云镜像:
sed -i 's|deb.debian.org|mirrors.tencent.com|g'替换 Debian 软件源,加速apt-get update; - 安装原生编译工具链:
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:
- 先一次性调 KS
/v3/internal/llm-binding/list拿到所有 binding 状态缓存; - 对每个 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;
- KS 已有可用 key(
- 任何单实例失败仅记日志跳过,绝不阻塞启动。
该设计避免每次 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 记账不可用,此时临时关闭同步可先恢复面板其他功能。
九、可继续深入的仓库路径索引
- MemoryPanel/docker/local/Dockerfile.local — 多阶段构建完整实现(base / ui-builder / runtime、WEB_UI 条件分支、HEALTHCHECK、CMD);
- MemoryPanel/docker/local/Dockerfile.local.dockerignore — 构建上下文忽略清单与密钥安全注释;
- MemoryPanel/src/panel/config/panel-config.ts — 全部环境变量的解析与默认值;
- MemoryPanel/src/panel/http/app.ts — 后端路由、静态托管与 SPA 回退逻辑;
- MemoryPanel/src/panel/startup/ensure-knowledge-llm-binding.ts — 启动时 LLM binding 同步的实现细节;
- MemoryPanel/config/metadata-instances.example.json 与 MemoryPanel/config/metadata-instances.README.md — 实例注册表配置样例与字段说明。