企业官网建设流程全解析

ai-memory 单二进制设计解析：MCP + HTTP + Web 挂载在一个 axum 服务上

【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory

ai-memory 是一个面向 AI 编码代理的长期记忆服务，用 Rust 编写、编译为单个二进制文件。它把 MCP 工具接口、Hook 事件入口和只读 Web 界面三种 HTTP 表面挂载在同一个 axum 服务上——一个进程、一个端口、一套认证，即可完成部署。

为什么坚持单二进制？

常见的 AI 记忆方案往往要同时跑一个 MCP 服务器、一个 Web API 和一个前端页面，运维上意味着三份配置、多组认证、多个端口。ai-memory 的做法完全不同：

• 一个进程，零外部依赖：记忆本体是磁盘上的 Markdown wiki + SQLite 派生索引，全部打包进同一个二进制。
• 一种认证姿态：机器 Bearer Token、人类 Cookie 会话、双因子校验全部作用在同一组中间件上，不存在"API 有权限、网页没权限"的分裂状态。
• 一套运维语义：单实例锁、优雅停机、Host 头防 DNS 重绑定，都只维护一份实现（见 serve.rs）。

对新手来说，最大的好处是：docker run一个容器，或者systemctl启一个服务，记忆系统就完整可用。

一个端口三张面孔：路由全景

启动 HTTP 传输（ai-memory serve --transport http）后，同一个 axumRouter上合并了如下表面：

组装逻辑集中在 serve.rs：先把 MCP 服务nest_service("/mcp", …)挂上机器侧路由，再 merge hook 路由、admin 路由、认证路由和 Web 路由，最后整体套上 Host 校验与 base-path 嵌套。

MCP 端点：默认无状态的 Streamable HTTP

MCP 部分基于 rmcp 的StreamableHttpService实现（serve.rs#L1105-L1113），有一个对新手很友好的细节：

• 默认无状态：每个POST /mcp独立处理、直接返回 JSON，不需要mcp-remote之类的 shim，curl都能直接测。
• 可选有状态：加--http-stateful恢复 Session-Id + SSE 行为，给需要服务端推送的客户端。
• stdio 也在同一个二进制里：--transport stdio给claude mcp add这类本地启动场景使用，两种传输共享同一套工具实现。

这意味着你既可以把 ai-memory 部署成团队共享的远程服务器，也可以在任何一台笔记本上以本地 stdio 方式运行——同一个二进制，两种形态。

Web 界面：只读、免维护、随手替换

Web 表面由独立 crate ai-memory-web 提供，设计上刻意保持只读：没有编辑、没有写接口，因为 Wiki 本身就是磁盘上的 Markdown，直接改文件即可。它解决的问题是"手机上、团队同事的机器上，能不能不docker exec cat就翻到记忆内容"。

项目列表页按卡片展示每个 workspace/project 的页面数量与最近活跃时间，点击进入单个项目后是页面树 + 最近活动时间线：

两个实用选项（参数定义见 cli.rs#L2260-L2306）：

• --enable-web：开启/web挂载（默认关闭）。
• --web-ui-dir <dir>：不用内置界面，改挂你自己的单页应用；服务器会自动往index.html注入<base href>，让你在反向代理子路径下也能直接跑，无需重新构建。

挂载在反向代理子路径下：base-path 与 web-slug

当你的 Nginx 把 ai-memory 放在https://example.com/wiki下时，只需要--base-path /wiki：/mcp、/api/v1、/hook、Web UI 全部自动落到前缀之下（/wiki/mcp、/wiki/api/v1…），前缀本身经过严格白名单校验，杜绝路径穿越（mount.rs#L49-L71）。

Web 挂载的拆分逻辑在 mount.rs：自定义 SPA 走公开路由（方便渲染登录页），内置浏览器与/api/v1走受保护路由，CORS 只作用于/api/v1，其余路由保持零跨域——这是明确的不变量，不是疏忽。

延伸阅读

想了解这套单二进制设计背后的完整数据流（捕获 → 整合 → 召回 → 交接）与安全不变量，推荐按顺序看：

• 架构总览：docs/ARCHITECTURE.md
• 安装与部署（systemd / Docker / 认证）：docs/install.md
• Web 前端 API 说明：docs/frontend-api.md
• MCP 客户端接入步骤：docs/mcp-install.md
• 多用户与安全模型：docs/security.md

一句话总结：ai-memory 用"一个 axum Router 合并所有表面"的设计，把 AI 代理记忆服务的部署从"三套系统"压缩成"一条命令"，这正是它敢自称基础设施级产品的底气。

【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory