agentmemory远程部署安全加固指南：HMAC密钥、Bearer令牌与HTTPS强制三件套

agentmemory远程部署安全加固指南：HMAC密钥、Bearer令牌与HTTPS强制三件套

【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory

agentmemory是专为 AI 编程代理打造的持久记忆服务（基于真实世界基准测试排名第一），能让 Claude Code、Cursor、Devin 等代理跨会话记住你的项目上下文。默认情况下它绑定本机回环地址、不设密码——但一旦把 agentmemory 部署到远程服务器供多人或云端代理访问，就必须在三步内完成安全加固：配置AGENTMEMORY_SECRET启用 Bearer 令牌认证、理解内置的 HMAC 恒定时间比较机制、用AGENTMEMORY_REQUIRE_HTTPS强制 HTTPS。本文带你用不到 10 分钟把远程部署的 agentmemory 变成"带门禁"的服务。

为什么本地默认"不设防"，远程必须加固

agentmemory 的 REST API 默认绑定127.0.0.1，本机访问无需任何凭证，这是刻意的轻量设计。但远程部署后有两个真实风险：

• 未认证访问：任何能到达 3111 端口的人都能读写你的全部记忆数据；
• 凭据被窃听：Bearer 令牌和记忆内容在明文 HTTP 传输中可被网络中间人抓包。

好消息是：三条防线全部内置在 agentmemory 中，你只需要设置环境变量，无需改一行源码。

第一步：配置 AGENTMEMORY_SECRET，一键启用 Bearer 令牌认证

在服务端启动前设置环境变量即可：

export AGENTMEMORY_SECRET="一串足够长的随机字符串"

服务启动时会在 src/index.ts 读取该密钥。一旦设置：

• 所有受保护的 REST 端点（记忆读写、搜索、治理、导出等）都要求请求头携带Authorization: Bearer <secret>，否则返回 401；
• 所有官方 hook 脚本（会话开始、工具调用前后、停止钩子等）会自动读取同一个变量并附带令牌，例如 src/hooks/post-tool-use.ts，无需逐条配置；
• 独立 MCP 服务@agentmemory/mcp会自动把令牌附加到对远端的每一次 REST 调用上（见 src/mcp/rest-proxy.ts）。

MCP 端点的鉴权逻辑非常直观，见 src/mcp/server.ts：

if (!sec) return null; // 未设置密钥则不鉴权（仅适合本机） const auth = req.headers?.["authorization"] ?? req.headers?.["Authorization"]; if (typeof auth !== "string" || !timingSafeCompare(auth, `Bearer ${sec}`)) { return { status_code: 401, body: { error: "unauthorized" } }; }

多实例同步（Mesh）同样受保护：早期的 mesh push/pull 端点曾允许无认证请求（项目标记为 HIGH 级修复，见 CHANGELOG.md），现在 mesh 同步在两端都强制要求AGENTMEMORY_SECRET，见 src/functions/mesh.ts。

第二步：看懂内置 HMAC 比较——为什么它防得住时序攻击

很多项目直接写received === secret，攻击者可通过观察响应耗时逐字符猜出密钥。agentmemory 在 src/auth.ts 中用了更稳妥的组合拳：

1. 随机 32 字节 HMAC 密钥（randomBytes(32)）在进程启动时生成；
2. 待比较的两个字符串分别经HMAC-SHA256摘要，输出长度恒定为 32 字节——比较时间不再泄露原始字符串长度信息；
3. 用 Node 内置的timingSafeEqual做恒定时间字节比较，杜绝逐字符计时侧信道。

const hmacA = createHmac("sha256", hmacKey).update(a).digest(); const hmacB = createHmac("sha256", hmacKey).update(b).digest(); return timingSafeEqual(hmacA, hmacB);

你不需要做任何事，这套机制已内置于所有 Bearer 校验路径，属于"免费获得的加固"。

第三步：AGENTMEMORY_REQUIRE_HTTPS 强制 HTTPS，拒绝明文发送令牌

即使令牌校验很严密，如果走明文 HTTP 传输，令牌照样能被抓包。agentmemory 的官方集成（Hermes、OpenClaw、pi 等）内置了明文 Bearer 守卫：

• 目标地址是https://，或指向本机回环（localhost/127.0.0.1/::1）——放行；
• 目标是明文 HTTP 的远程地址——默认先打印警告"Bearer tokens and memory payloads can be observed on the network; use HTTPS or an SSH tunnel"，见 integrations/openclaw/plugin.mjs；
• 再设置AGENTMEMORY_REQUIRE_HTTPS=1，同一场景将直接抛错拒绝启动，从机制上杜绝明文传输。

export AGENTMEMORY_REQUIRE_HTTPS=1

Hermes 集成中同样的守卫位于 integrations/hermes/init.py。配套的回归测试 test/integration-plaintext-http.test.ts 覆盖了 localhost 放行、LAN IP 警告、https放行等全部分支。

部署建议：在 Cloudflare、Nginx 或平台托管层（项目提供了 deploy/ 下 Coolify、Fly.io、Railway、Render 的官方 Dockerfile 与一键模板）终止 TLS，把 3111 端口藏在反向代理之后，只对外暴露 443。

锦上添花：两条内置的额外防线

🔒Viewer 只绑定本机 + 每响应 CSP 随机 nonce：可视化面板服务默认监听127.0.0.1，且每个响应的 Content-Security-Policy 都使用一次性脚本 nonce 并禁用内联事件属性（script-src-attr 'none'），构造见 src/auth.ts。通过 REST 访问的/agentmemory/viewer同样遵循 Bearer 令牌规则。

🛡️自动打码入库的密钥：记忆写入前会经过隐私函数，自动把Bearer xxx、各类 API key、GitHub token、JWT 等模式替换为[REDACTED_SECRET]，见 src/functions/privacy.ts——即使对话内容误粘了令牌，也不会存入长期记忆。

远程部署安全核对清单

一句话总结：设好AGENTMEMORY_SECRET、打开AGENTMEMORY_REQUIRE_HTTPS=1、把服务藏进 HTTPS 反代——三步之后，你的远程 agentmemory 就同时拥有了 Bearer 令牌门禁、HMAC 恒定时间校验与传输层加密三重防护，可以放心让云端代理长期连接。

【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory