在 Render 上部署 agentmemory：Blueprint 持久化磁盘 + HMAC 密钥安全落地的完整方案

在 Render 上部署 agentmemoryBlueprint 持久化磁盘 HMAC 密钥安全落地的完整方案【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory本文以 agentmemory 官方 Render 部署模板为主线讲解如何通过 Render Blueprint 在一个 Web Service 上运行完整的 agentmemory REST API持久化磁盘挂载于/data、首次启动自动生成 HMAC 密钥并落盘、健康检查与 Bearer 鉴权全链路打通。读完本文你将掌握 render.yaml 蓝图配置、多阶段 Dockerfile 的版本锁定原理、entrypoint 的密钥生命周期管理以及轮换密钥、备份数据、SSH 访问 Viewer 等全套运维手法可直接照搬生产环境。部署方案总览单 Web Service 持久化磁盘Render 模板将 agentmemory 运行在单个 Render Web Service上核心形态如下详见 deploy/render/README.md公开 HTTPS 端点agentmemory REST API 运行在容器内端口3111。Render 会默认注入PORT默认值 10000模板通过envVars将PORT显式覆盖为3111保证发布端口与容器绑定端口一致1 GB 持久化磁盘挂载到/data用于存放 memories、BM25 索引与 stream 积压数据健康检查Render 对/agentmemory/livez进行存活探测HMAC Bearer 密钥容器首次启动时在内部生成持久化到/data/.hmac权限chmod 600运维人员只需从部署日志中捕获一次即可。该模板与其他平台模板fly.io、Railway、Coolify共享同一套设计保证见 deploy/README.md卷统一挂载/data、密钥只落盘不进平台环境变量、仅对外暴露 3111 端口、TLS 由平台边缘代理终结。这意味着在四个平台间迁移只是把/data打一个 tar 包再重新导入的问题。基础设施准备render.yaml Blueprint 逐项解读完整蓝图文件位于 deploy/render/render.yaml逐项拆解如下services: - type: web name: agentmemory runtime: docker plan: starter dockerfilePath: ./deploy/render/Dockerfile dockerContext: ./deploy/render healthCheckPath: /agentmemory/livez autoDeploy: false disk: name: data mountPath: /data sizeGB: 1 envVars: - key: PORT value: 3111 - key: AGENTMEMORY_VERSION value: 0.9.29 - key: III_VERSION value: 0.11.2 - key: III_SDK_VERSION value: 0.11.2要点说明plan: starterRender Free 套餐不支持持久化磁盘Starter$7/月是底线dockerfilePath/dockerContext指向仓库内deploy/render/目录。注意 Render 的一键部署按钮只会自动探测仓库根目录下的render.yaml而 agentmemory 仓库保持根目录整洁因此必须走 Blueprint 手动流程autoDeploy: false关闭自动部署后续更新通过 Deploy Hook 或手动触发避免仓库每次提交都触发重建disk挂载名data、路径/data、大小 1 GB。这是 agentmemory 全部状态memories、BM25 索引、stream 积压的唯一持久层envVars中的版本钉扎AGENTMEMORY_VERSION0.9.29对应 npm 包agentmemory/agentmemory的发行版本III_VERSION0.11.2对应引擎镜像iiidev/iiiIII_SDK_VERSION0.11.2用于锁死 SDK 版本原因见下文 Dockerfile 解读。镜像构建原理多阶段 Dockerfile 与版本锁定构建脚本 deploy/render/Dockerfile 采用多阶段构建无需预构建的 agentmemory 镜像所有依赖在构建期从上游拉取ARG III_VERSION0.11.2 FROM iiidev/iii:${III_VERSION} AS iii-image FROM node:22-slim ARG AGENTMEMORY_VERSION0.9.29 ARG III_VERSION0.11.2 ARG III_SDK_VERSION0.11.2 RUN apt-get update \ apt-get install -y --no-install-recommends openssl ca-certificates tini gosu curl \ rm -rf /var/lib/apt/lists/* COPY --fromiii-image /app/iii /usr/local/bin/iii关键点iii引擎二进制从官方iiidev/iii:${III_VERSION}镜像直接拷贝随构建参数锁定版本基础镜像为node:22-slim额外安装openssl生成 HMAC 密钥、tini作为 PID 1 的 init 进程负责回收僵尸进程、gosu降权运行、curl与ca-certificates接下来把 agentmemory 安装到独立前缀目录而不是全局安装并用overrides钉死iii-sdkWORKDIR /opt/agentmemory RUN printf {name:agentmemory-deploy,version:1.0.0,private:true,overrides:{iii-sdk:%s}}\n ${III_SDK_VERSION} package.json \ npm install agentmemory/agentmemory${AGENTMEMORY_VERSION} --omitoptional --no-fund --no-audit \ ln -s /opt/agentmemory/node_modules/.bin/agentmemory /usr/local/bin/agentmemory这一设计有明确的工程动机agentmemory 的 package.json 对iii-sdk使用 caret 范围^0.11.2若不锁定会解析到 0.11.6而 0.11.6 引入了 agentmemory CLI 尚未适配的 sandbox-everything 新 worker 模型。npm install -g会忽略overrides所以必须用本地前缀目录 overrides的方式强制对齐。最后EXPOSE 3111以tini作为入口点。首次启动入口entrypoint.sh 的三大职责模板的灵魂在首次启动脚本 deploy/render/entrypoint.sh。它以 root 运行完成三件事后降权启动 CLI职责一覆盖 npm 自带的 iii 配置。npm 包内置的iii-config.yaml默认绑定127.0.0.1且使用相对路径./data对比仓库根目录的 iii-config.yaml 即可看到差异这在托管平台不可用。entrypoint 写入部署调优版配置workers: - name: iii-http config: port: 3111 host: 0.0.0.0 default_timeout: 180000 cors: allowed_origins: - http://localhost:3111 - http://localhost:3113 - http://127.0.0.1:3111 - http://127.0.0.1:3113 allowed_methods: [GET, POST, PUT, DELETE, OPTIONS] - name: iii-state config: adapter: name: kv config: store_method: file_based file_path: /data/state_store.db - name: iii-queue config: adapter: name: builtin - name: iii-pubsub config: adapter: name: local - name: iii-cron config: adapter: name: kv - name: iii-stream config: port: 3112 host: 0.0.0.0 adapter: name: kv config: store_method: file_based file_path: /data/stream_store - name: iii-observability config: enabled: true service_name: agentmemory exporter: memory sampling_ratio: 1.0 metrics_enabled: true logs_enabled: true logs_console_output: true相比本地默认配置关键差异是HTTP/Stream 监听地址从127.0.0.1改为0.0.0.0容器内可被平台探活与边缘代理访问所有状态文件路径从相对./data/改为绝对/data/与磁盘挂载点对齐。CORS 白名单同时放行 3111API与 3113Viewer两个本地源。职责二chown 平台挂载卷。托管平台默认以 root、权限 755 挂载卷entrypoint 执行chown -R node:node $DATA_DIR后运行时用户才有写入权限。DATA_DIR与HMAC_FILE均可通过AGENTMEMORY_DATA_DIR、AGENTMEMORY_HMAC_FILE环境变量覆盖默认分别为/data与/data/.hmac。职责三首次启动生成并持久化 HMAC 密钥。核心逻辑如下if [ ! -s $HMAC_FILE ]; then SECRET$(openssl rand -hex 32) umask 077 printf %s\n $SECRET $HMAC_FILE chmod 600 $HMAC_FILE chown $RUN_AS $HMAC_FILE echo AGENTMEMORY_SECRET$SECRET echo Copy this value now. It will not be printed again. fi AGENTMEMORY_SECRET$(cat $HMAC_FILE) export AGENTMEMORY_SECRET exec gosu $RUN_AS agentmemory $openssl rand -hex 32生成 64 个十六进制字符的密钥umask 077chmod 600保证只有属主可读随后以AGENTMEMORY_SECRET环境变量注入进程最终用gosu降权到非特权node用户执行agentmemoryCLI。密钥从不写入任何配置文件也不设置为平台环境变量重启时直接从磁盘文件恢复。部署操作手册方式一手动 Blueprint 流程Render 的一键部署按钮只会自动检测仓库根目录的render.yamlagentmemory 仓库刻意保持根目录干净因此官方推荐 Dashboard 手动流程将deploy/render/目录推送到 Render 可达的 Git 平台例如rohitg00/agentmemory的一个 fork在 Render Dashboard 点击New →Blueprint指向仓库及路径deploy/render/render.yamlRender 读取 Blueprint自动创建磁盘、构建 Dockerfile 并启动服务。首次完整流程约需 3–5 分钟。方式二Deploy Hook 一键触发Blueprint 在账户中存在后可在服务设置中生成 Deploy Hook URL后续部署只需一次 curlcurl https://api.render.com/deploy/srv-XXYYZZ?keyAABBCC若要钉住特定agentmemory/agentmemory版本在下次部署前于服务的Environment标签页设置AGENTMEMORY_VERSION构建参数III_VERSION同理。这两个参数最终流入 Dockerfile 的ARG决定 npm 安装版本与引擎二进制来源。捕获 HMAC 密钥唯一一次打印首次部署成功后打开服务的Logs标签页搜索AGENTMEMORY_SECRET。你会看到且仅看到一行形如AGENTMEMORY_SECRET64 个十六进制字符的输出来自 entrypoint 的echo。将其复制到你的客户端环境后续启动不会再打印该密钥。这一生成一次、打印一次、落盘持久的设计与源码中的鉴权实现闭环agentmemory 服务端通过 src/triggers/api.ts 中注册的 HTTP 触发器校验Authorization: Bearer secret而 src/auth.ts 使用基于 HMAC-SHA256 的timingSafeCompare做常量时间比较杜绝时序侧信道校验失败返回401 unauthorized。验证部署健康检查与鉴权curl https://agentmemory.onrender.com/agentmemory/livez # {status:ok}/agentmemory/livez是 agentmemory 的存活探针端点在 src/triggers/api.ts 中api::liveness函数注册为GET /agentmemory/livez返回{status:ok, ...instanceInfo}其中instanceInfo还附带viewerPort、streamsPort等运行元数据。该端点也被 Render 用作healthCheckPath因此服务只要探活失败即被标记不健康并重启。需要注意的是/agentmemory/livez是免鉴权的健康检查而所有业务 API 调用则要求客户端携带Authorization: Bearer secret。另外若在客户端侧配置AGENTMEMORY_REQUIRE_HTTPS1集成插件会拒绝通过明文 HTTP 向非 loopback 主机发送 bearer 令牌——TLS 配置错误会响亮失败而非静默泄露密钥见 deploy/README.md。访问 ViewerSSH 端口转发3113 保持内部Render 每个服务只暴露一个公网端口已被 3111REST API占用。Viewer 端口在容器内绑定 localhost从源码看Viewer 端口为restPort 2见 src/index.ts 第 551 行即 3113外部无法直接访问需通过 Render SSH 隧道# Settings → SSH → 为服务启用 SSH复制连接命令 ssh srv-XXYYZZssh.region.render.com -L 3113:localhost:3113 # 现在浏览器访问 http://localhost:3113 即可命中容器内 Viewer这种API 公网、Viewer 内网的隔离刻意为之Viewer 是带交互界面的入口通过 SSH 隧道仅对运维人员开放减少了攻击面。运维实操轮换密钥与数据备份轮换 HMAC 密钥ssh srv-XXYYZZssh.region.render.com rm /data/.hmac exit # 从 Render Dashboard 或通过 Deploy Hook 触发一次重新部署重新部署后从日志中获取新密钥并更新所有客户端。旧令牌立即失效——这正是密钥只存于磁盘、启动时从文件加载模型带来的安全属性删除文件即完成轮换无需任何管理命令。备份/datassh srv-XXYYZZssh.region.render.com tar czf - /data agentmemory-$(date %Y%m%d).tar.gz此外Render 在付费套餐上会对持久化磁盘自动做每日快照SSH tar 包是双保险可将数据搬运到平台之外。成本明细与边界条件按模板默认配置Starter Web Service 1 GB 磁盘估算Starter 套餐 Web Service$7/月0.5 CPU、512 MB RAM1 GB 持久化磁盘$0.25/GB/月默认配置即 $0.25/月带宽每月含 100 GB 出站流量超出后 $0.10/GB。已知边界条件务必在选型前确认Render Free 套餐不支持持久化磁盘Starter$7/月是最低门槛每次部署都会重启服务。HMAC 密钥因存于磁盘而得以存活但滚动期间会有 10–30 秒的 502 窗口Render Web Service 仅运行 amd64 架构。Dockerfile 通过uname -m自动匹配对应的iii二进制无需人工干预但意味着无法利用 ARM 架构的算力或价格优势。进阶开启 LLM 与向量召回能力模板开箱即可运行无需任何 LLM 或 embedding 密钥搜索回退到 BM25-only 模式合成零 LLM压缩仍能保证记忆可索引。若要解锁 LLM 压缩与混合BM25 向量召回在 Render 的Environment标签页添加以下变量完整说明见 deploy/README.md变量作用ANTHROPIC_API_KEYLLM 压缩与摘要GEMINI_API_KEYLLM 备选提供商OPENROUTER_API_KEYLLM 备选提供商OPENAI_API_KEYEmbedding 提供商默认 text-embedding-3-smallVOYAGE_API_KEYEmbedding 备选提供商AGENTMEMORY_AUTO_COMPRESStrue每个观察批次都执行 LLM 压缩AGENTMEMORY_INJECT_CONTEXTtrue将召回的记忆重新注入 agent 提示词默认值刻意保守提供商密钥默认缺省不产生任何第三方调用、AGENTMEMORY_AUTO_COMPRESS与AGENTMEMORY_INJECT_CONTEXT默认关闭。建议在确认提供商配额能承受工作负载后再开启。小结Render 模板提供了一条设置后无需再管的托管路径Blueprint 自动挂载磁盘、entrypoint 首次启动生成并落盘 HMAC 密钥、tini gosu保证进程生命周期与最小权限、/agentmemory/livez与 Render 健康检查深度集成。它同时展示了 agentmemory 部署生态的通用工程模式——/data卷、密钥文件、3111 单端口暴露、TLS 由边缘代理终结——这套模式在 deploy/README.md 与其余平台模板fly.io、Railway、Coolify中一以贯之意味着你随时可以把/data打包迁移到其他平台而不改任何客户端代码。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考