企业官网建设流程全解析

TencentDB-Agent-Memory Docker 部署实战：镜像构建、配置注入与 K8s 落地

【免费下载链接】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

导读

本文以 README.docker.md 为骨架，系统讲解 TencentDB-Agent-Memory（AI Agent 长期记忆服务）的容器化部署全流程：如何构建tencentdb-agent-memory镜像、如何通过 YAML 配置与环境变量注入 LLM/Redis/Shark 凭证、如何以 standalone / service 两种模式启动容器，以及如何在 K8s/TKE 中用 ConfigMap + Secret 完成生产级落地。读完本文，你将掌握从本地一键测试到云端多副本部署的完整链路，并理解镜像内部的分层构建原理与配置解析优先级。

1. 项目与镜像概览

TencentDB-Agent-Memory 是一个团队级的 AI Agent 长期记忆服务，为任意 Agent 框架提供四层渐进式记忆能力：

• L0 对话：原始会话记录；
• L1 原子记忆：从对话中抽取的最小记忆单元；
• L2 场景归纳：对记忆进行场景化聚合；
• L3 用户画像：基于长期记忆沉淀的用户画像。

官方提供 Docker 镜像tencentdb-agent-memory，关键镜像信息如下：

其中PID 1 为 tini这一点值得注意：tini 作为 init 进程，能够正确转发 SIGTERM/SIGKILL 信号给 Node 主进程及其 pipeline worker，并回收孤儿（zombie）进程，保证优雅退出与资源清理。这一点在 MemoryCore/Dockerfile 的ENTRYPOINT ["/usr/bin/tini", "--"]中直接体现。

1.1 镜像构建的源码级实现

镜像采用多阶段构建（Multi-stage Build，需DOCKER_BUILDKIT=1），这是镜像体积与构建速度的关键设计，见 MemoryCore/Dockerfile：

阶段一deps-builder（依赖安装）：

• 基础镜像node:22-slim，通过 apt 安装python3、make、g++、ca-certificates等原生编译工具链（用于编译sqlite-vec、@node-rs/jieba等含原生绑定的依赖）；
• 使用 BuildKit cache mount（--mount=type=cache,target=/var/cache/apt）缓存 apt 包，加速重复构建；
• 升级 npm 到 11（node:22-slim 自带 npm@10.9.8 存在 arboristedgesOutcrash，会稳定报Cannot read properties of null (reading 'edgesOut')）；
• 对package.json做补丁：删除peerDependencies（openclaw、node-llama-cpp会拉入带坏workspace:*引用的传递依赖），并添加overrides将@jimp/config-typescript指向npm:dotenv@latest短路规避；
• 执行npm install --omit=dev --omit=optional --ignore-scripts --legacy-peer-deps安装生产依赖；
• 单独安装esbuild（tsx 的 optionalDependency，--omit=optional后会丢失，但 esbuild 仅约 10MB，远小于被省略的 mongodb 等可选依赖）。

阶段二runtime（运行镜像）：

• 仅安装运行时必需品curl（供 HEALTHCHECK 使用）、tini、ca-certificates；
• 从 builder 阶段复制/build到/app；
• 创建数据目录/data/tdai-memory与配置目录/data/config（K8s 中可挂载 PVC）；
• 通过ENV预设运行参数：
  • NODE_ENV=production
  • TDAI_GATEWAY_CONFIG=/data/config/tdai-gateway.yaml
  • TDAI_GATEWAY_HOST=0.0.0.0
  • TDAI_DATA_DIR=/data/tdai-memory
  • NODE_OPTIONS="--max-old-space-size=1536"
• EXPOSE 8420，HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=15s使用 curl 探测/health；
• 启动命令node --import tsx src/gateway/server.ts（tsx 为运行时依赖，可直接运行 TypeScript）。

细节提示：Dockerfile 注释特别说明TDAI_GATEWAY_PORT没有写入 ENV，因为一旦成为镜像环境变量，就会盖掉挂载配置中的server.port（环境变量优先级高于 YAML），而 8420 与 gateway 的代码默认值一致。

1.2 .dockerignore 的安全设计

MemoryCore/.dockerignore 除排除node_modules、.git、docs、*.md等常规内容外，还主动排除所有根目录 yaml 配置（tdai-gateway.yaml、tdai-gateway.*.yaml）、.env等敏感文件，注释明确指出"生产走 env 注入或 volume 挂载"——这是防止 Langfuse / VDB / API_KEY 等真值混入镜像的关键安全实践。

2. 快速开始：从构建到启动

以下命令默认在MemoryCore/目录内执行；如果你位于仓库根目录，请先cd MemoryCore。

2.1 构建镜像

docker build -t tencentdb-agent-memory:latest .

若在内网构建需要加速 apt 源，可通过构建参数切换镜像源：docker build --build-arg APT_MIRROR=mirrors.tencent.com -t tencentdb-agent-memory:latest .Dockerfile 中ARG APT_MIRROR=deb.debian.org，默认走 Debian 官方源，公网可直接构建。

2.2 准备配置文件

项目提供两个配置模板（详见 README.docker.md）：

复制模板并修改：

# 单机模式 cp tdai-gateway.standalone.yaml tdai-gateway.yaml # 服务模式 cp tdai-gateway.service.yaml tdai-gateway.yaml

说明：当前开源仓库中实际提供的是 MemoryCore/tdai-gateway.standalone.yaml（standalone 零依赖模板）与 MemoryCore/tdai-gateway.yaml（standalone + Skill 模块的默认配置）。tdai-gateway.service.yaml为 README 文档描述的 service 模式模板，按文档说明使用即可。.dockerignore中tdai-gateway.*.yaml规则也印证了这类模板文件的存在与命名习惯。

模板间的核心差异：

• tdai-gateway.standalone.yaml：deployMode: standalone、stateBackend: "local"，进程内状态管理，不需要 Redis/Shark；
• tdai-gateway.yaml：同样 standalone 模式，但额外启用了 Skill 模块（skill.enabled: true），且llm.baseUrl指向腾讯云https://api.lkeap.cloud.tencent.com/v1，model 为deepseek-v3.2。Memory 引擎与 Skill 模块共享同一个baseDir，互不干扰：
  • Memory 数据：{baseDir}/conversations/、records/、scene_blocks/、persona.md…
  • Skill 数据：{baseDir}/skills/<name>/SKILL.md+files/
  • 共享 DB：{baseDir}/vectors.db

2.3 启动容器

Standalone 模式（最简）：

docker run -d --name agent-memory \ -v $(pwd)/tdai-gateway.yaml:/data/config/tdai-gateway.yaml:ro \ -e TDAI_LLM_API_KEY=sk-your-key \ -p 8420:8420 \ tencentdb-agent-memory:latest

• 配置以只读（:ro）方式挂载到/data/config/tdai-gateway.yaml；
• LLM API Key 通过环境变量TDAI_LLM_API_KEY注入，避免写入配置或镜像；
• 端口映射 8420 对外提供服务。

Service 模式（需要 Redis）：

# 启动 Redis（如果没有远端 Redis） docker run -d --name redis -p 6379:6379 redis:7-alpine # 启动 mock-shark（本地提供 VDB/COS 凭证） VDB_ENDPOINT=http://your-vdb:8100 \ VDB_API_KEY=xxx \ VDB_DATABASE=your-db \ COS_BUCKET=your-bucket \ COS_REGION=ap-guangzhou \ COS_SECRET_ID=xxx \ COS_SECRET_KEY=xxx \ npx tsx scripts/mock-shark-server.ts & # 启动 Memory Service docker run -d --name agent-memory \ -v $(pwd)/tdai-gateway.real.yaml:/data/config/tdai-gateway.yaml:ro \ -e TDAI_LLM_API_KEY=sk-your-key \ -p 8420:8420 \ tencentdb-agent-memory:latest

Docker Compose 一键启动（含 Redis）：

TDAI_LLM_API_KEY=sk-your-key docker compose -f docker-compose.local.yaml up --build

2.4 验证服务

curl http://localhost:8420/health

正常返回：

{ "status": "ok", "version": "0.1.0", "services": { "timerScanner": { "isLeader": true }, "pipelineWorker": { "workerId": "worker-xxx" }, "stateBackend": "connected" } }

该健康检查在容器内由 Dockerfile 的HEALTHCHECK指令以curl -fsS http://127.0.0.1:${TDAI_GATEWAY_PORT:-8420}/health自动执行，也可手动 curl 验证。timerScanner（定时扫描器）、pipelineWorker（流水线 worker）、stateBackend（状态后端连接状态）三个字段分别对应 MemoryCore/src/services/timer-scanner.ts 与 MemoryCore/src/services/pipeline-worker.ts 两类后台任务。

3. 配置方式：YAML + 环境变量双层体系

3.1 配置文件 + 环境变量（推荐）

所有配置项同时支持YAML 配置文件和环境变量，环境变量优先级更高：

┌─────────────────────────────┐ │ 环境变量 (最高优先级) │ ← Secret 敏感凭证 ├─────────────────────────────┤ │ tdai-gateway.yaml 配置文件 │ ← ConfigMap 挂载 ├─────────────────────────────┤ │ 代码默认值 │ ← 兜底 └─────────────────────────────┘

容器内配置文件路径由TDAI_GATEWAY_CONFIG环境变量指定，默认/data/config/tdai-gateway.yaml。

源码级佐证：配置解析逻辑位于 MemoryCore/src/gateway/config.ts 的resolveConfigPath()函数，其解析顺序为：

1. TDAI_GATEWAY_CONFIG环境变量显式指定的路径；
2. 当前工作目录（CWD）下的./tdai-gateway.yaml或./tdai-gateway.json；
3. <dataDir>/tdai-gateway.yaml或<dataDir>/tdai-gateway.json；
4. 纯环境变量配置（无文件）。

这意味着即使不挂载任何配置文件，服务也能仅凭环境变量启动（代码默认值兜底）。

3.2 配置文件结构详解

以 standalone 模式为例（结合 tdai-gateway.standalone.yaml 与 tdai-gateway.yaml 两个真实模板）：

deployMode: standalone # standalone | service server: port: 8420 host: "0.0.0.0" llm: # LLM API (OpenAI 兼容) baseUrl: "https://api.lkeap.cloud.tencent.com/v1" apiKey: "${TDAI_LLM_API_KEY}" # 通过环境变量注入 model: "deepseek-v3.2" maxTokens: 32000 # 最大 token 数 timeoutMs: 300000 # 请求超时（毫秒） memory: promptMode: code # prompt 模式 capture: enabled: true # 对话捕获开关 extraction: enabled: true # L1 抽取开关 enableDedup: true # 去重 maxMemoriesPerSession: 20 # 每会话最大记忆数 persona: # L3 用户画像 triggerEveryN: 50 # 每 N 轮触发 maxScenes: 15 # 最大场景数 pipeline: # 记忆流水线 everyNConversations: 5 # 每 N 轮对话触发一次 enableWarmup: true # 预热 l1IdleTimeoutSeconds: 600 # L1 空闲超时 l2DelayAfterL1Seconds: 90 # L2 在 L1 后的延迟 l2MinIntervalSeconds: 900 # L2 最小间隔 l2MaxIntervalSeconds: 3600 # L2 最大间隔 recall: # 记忆召回 enabled: true maxResults: 5 # 最大召回条数 scoreThreshold: 0.3 # 分数阈值 strategy: "hybrid" # bm25 | embedding | hybrid timeoutMs: 5000 storeBackend: "sqlite" # sqlite（零配置）| tcvdb（腾讯云向量数据库） embedding: # 向量搜索 provider: "none" # 默认关闭，仅用 BM25 # provider: "openai" # model: "text-embedding-3-small" # dimensions: 1536 bm25: enabled: true language: "zh" skill: # Skill 模块（standalone.yaml 中默认关闭） enabled: true routing: mode: "bm25" # bm25 | embedding | hybrid searchTopK: 20 extraction: enabled: true maxIterations: 16 # Review Agent 最大迭代轮数 resources: maxResourceSizeBytes: 5000000 # 单个资源文件上限 5MB redis: # Redis (service 模式必需) host: "redis:6379" keyPrefix: "tdai_memory" shark: # Shark 配置中心 (下发 VDB/COS 凭证) baseUrl: "http://shark:8000" scanner: # Timer Scanner intervalMs: 500 worker: # Pipeline Worker pollMs: 200

其中deployMode、server、llm、redis、shark、scanner、worker、memory等为 README 文档给出的 service 模式骨架；maxTokens、timeoutMs、capture/extraction/persona/pipeline/recall调参项、storeBackend、embedding、bm25、skill等则来自仓库实际提供的两个配置模板，可直接复制使用。

Skill 模块提示：在 tdai-gateway.yaml 中，skill.enabled: true且skill.extraction.enabled: true需要顶层llm配置有效；skill.routing.mode若为embedding/hybrid需要启用memory.embedding，否则自动降级为bm25。

3.3 环境变量与配置文件对照表

使用原则：敏感凭证（API Key、Redis 密码等）一律走环境变量注入；非敏感配置（端口、扫描间隔、调参项等）写入 YAML 并通过 ConfigMap 挂载。环境变量优先级更高，因此也常用于"在不动配置文件的前提下临时覆盖"。

4. K8s / TKE 部署

README 文档给出 K8s/TKE 部署的核心做法（参考清单MemoryCore/deploy/k8s/tdai-memory.yaml，该文件位于文档描述的部署目录中）：

1. ConfigMap挂载tdai-gateway.yaml到/app/config/；
2. Secret通过环境变量注入TDAI_LLM_API_KEY+REDIS_PASSWORD；
3. Deployment设置TDAI_GATEWAY_CONFIG=/data/config/tdai-gateway.yaml。

Deployment 中的关键配置片段：

env: - name: TDAI_GATEWAY_CONFIG value: /data/config/tdai-gateway.yaml - name: TDAI_LLM_API_KEY valueFrom: secretKeyRef: name: tdai-memory-secrets key: TDAI_LLM_API_KEY volumeMounts: - name: config-volume mountPath: /app/config readOnly: true volumes: - name: config-volume configMap: name: tdai-memory-config

与镜像设计的呼应：

• 镜像内TDAI_GATEWAY_CONFIG默认值为/data/config/tdai-gateway.yaml，而示例中 ConfigMap 挂载到/app/config、环境变量又显式指定/data/config/tdai-gateway.yaml——这正是 3.1 节"环境变量优先级最高"的实际应用：显式指定挂载路径，避免默认值路径下找不到配置；
• 配置文件只读挂载（readOnly: true），Secret 走secretKeyRef引用，符合.dockerignore中"生产走 K8s Secret + env template"的注释约定；
• 镜像中已预设HEALTHCHECK（curl 探测/health），K8s 的 liveness/readiness probe 可在 Deployment 清单中单独定义；
• 数据目录/data/tdai-memory可作为 PVC 挂载，保证多副本/重启后记忆数据持久化；
• Dockerfile 注释明确TDAI_GATEWAY_PORT不写入 ENV，因此 service 模式下挂载配置中的server.port不会被镜像级环境变量覆盖。

5. API 概览

容器启动后暴露以下核心接口（详见 README.docker.md）：

这些接口对应 MemoryCore/src/gateway/server.ts 服务入口：/health返回进程与依赖状态（供 K8s probe 与curl验证）；/capture与/recall对应 L0→L1 的记忆写入与召回；/search/memories、/search/conversations分别检索 L1 原子记忆与 L0 对话；/v2/*为多租户 API，需 Bearer Token 鉴权。

6. 架构总览

README 文档给出容器内架构图：

┌─────────────────────────────────────────────────────┐ │ TencentDB Agent Memory │ │ │ │ ┌──────────┐ ┌──────────────┐ ┌───────────────┐ │ │ │ Gateway │ │ TimerScanner │ │ PipelineWorker│ │ │ │ HTTP API │ │ 500ms 扫描 │ │ 竞争消费 │ │ │ └────┬─────┘ └──────┬───────┘ └──────┬────────┘ │ │ │ │ │ │ │ ┌────▼─────────────────────────────────▼────────┐ │ │ │ IStateBackend (Redis / Local) │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ ┌────▼───────────┐ ┌────────────┐ ┌───────────┐ │ │ │ TdaiCore │ │ StorePool │ │ COS │ │ │ │ L0→L1→L2→L3 │ │ VDB 连接池 │ │ 对象存储 │ │ │ └────────────────┘ └────────────┘ └───────────┘ │ └─────────────────────────────────────────────────────┘ │ │ │ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ │ LLM │ │ TCVDB │ │ COS │ │ API │ │ 向量库 │ │ 对象存储│ └─────────┘ └─────────┘ └─────────┘

关键组件解析：

• Gateway（HTTP API）：对外提供第 5 节所列接口，是请求入口；
• TimerScanner：以scanner.intervalMs（默认 500ms）间隔扫描，负责定时触发流水线任务；
• PipelineWorker：以worker.pollMs（默认 200ms）轮询消费任务，多实例时"竞争消费"，配合 Redis 实现任务互斥；
• IStateBackend（Redis / Local）：状态后端抽象，standalone 用 local（进程内），service 用 Redis（多副本共享状态）；
• TdaiCore（L0→L1→L2→L3）：核心记忆引擎，完成对话→原子记忆→场景归纳→用户画像的渐进式加工；
• StorePool（VDB 连接池）：管理腾讯云向量数据库（TCVDB）连接，对应配置中的storeBackend: "tcvdb"与memory.tcvdb段；
• COS（对象存储）：存放对话原文、记忆内容等大对象，对应cos.domain、COS_BUCKET等配置；
• 外部依赖 LLM API、TCVDB、COS 通过配置注入，standalone 模式下仅 LLM 为必需外部依赖。

7. 文件结构速览

与容器化部署直接相关的文件（以 README.docker.md 文件结构说明为准）：

. ├── MemoryCore/ │ ├── Dockerfile # 镜像构建 │ ├── docker-compose.local.yaml # 本地一键测试 (含 Redis) │ ├── tdai-gateway.standalone.yaml # Standalone 配置模板 │ ├── tdai-gateway.service.yaml # Service 配置模板 │ ├── tdai-gateway.real.yaml # 本地测试配置 (连真实服务) │ ├── deploy/k8s/tdai-memory.yaml # K8s/TKE 部署清单 │ ├── scripts/mock-shark-server.ts # Mock Shark (本地开发) │ └── src/gateway/server.ts # 服务入口

部署提示：docker-compose.local.yaml、tdai-gateway.real.yaml、deploy/k8s/与scripts/mock-shark-server.ts按文档描述属于部署配套资源；注意 MemoryCore/.dockerignore 将deploy目录与scripts/mock-shark-*脚本排除在镜像构建之外，即 mock-shark 等仅用于宿主机本地开发调试，不会进入生产镜像。镜像内的核心代码包括 MemoryCore/src/gateway/server.ts（服务入口）与 MemoryCore/src/gateway/config.ts（配置解析）。

8. 部署模式选型建议

生产落地的推荐路径：

1. 本地先用 standalone + SQLite 验证记忆链路（capture → recall）；
2. 需要团队共享、多副本时切换到 service 模式：部署 Redis，通过 Shark 下发 TCVDB/COS 凭证，启用storeBackend: "tcvdb"与向量搜索；
3. K8s/TKE 上以 ConfigMap 管理非敏感配置、Secret 管理凭证，PVC 持久化/data/tdai-memory，用 liveness/readiness probe 保障健康巡检。

结语

从 README.docker.md 出发，结合 MemoryCore/Dockerfile、MemoryCore/.dockerignore、MemoryCore/tdai-gateway.standalone.yaml、MemoryCore/tdai-gateway.yaml 与 MemoryCore/src/gateway/config.ts 的实现细节，你可以看到这套容器化体系的设计逻辑：多阶段构建控制体积与安全、双层配置体系分离敏感与非敏感信息、tini + HEALTHCHECK 保证容器级健康、standalone/service 双模式适配从本地到云端的不同形态。按本文步骤操作，即可在几分钟内跑通一条"构建镜像 → 本地验证 → K8s 落地"的完整部署链路。

【免费下载链接】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