🎯 MCP 记忆服务接入 Console（2026-10-18）

📌 结论摘要

MCP memory server 已进入 Console 导航。 入口仅管理员可见，站内用 iframe 展示，右上角可以新窗口打开。入口没有新增公网域名：浏览器访问 Console 同源 /__agentmeshos/memory/，RR 私有回源网关先执行 A-Auth admin 检查，再把剥离前缀的请求转发到 102 Tailnet 100.64.0.4:8104。因此 8104 仍只绑定 102 Tailnet，不存在公网监听。

🧭 目录

结论摘要
背景与目标
入口与架构
实现与取舍
验证证据
回退方案
风险与未决项

🧩 背景与目标

前一轮质量模型与 1307 条记忆回填完成后，使用者需要一个稳定入口直接打开中央 MCP memory server 的 Web 工作台。此前 OpenCode 记忆库已经占用 mem.yohan.fun，且 8104 仍允许匿名 API，所以不能把现有端口直接映射成第二个公网域名，也不能复用 OpenCode 记忆库入口。

本轮目标有三个：一是从 Console 导航直接进入；二是可以站内打开，也可以新窗口打开；三是鉴权和网络边界继续沿用 Console，不新增第二套登录或公网端口。依据是 Console 已有 A-Auth、同源管理路径、RR 私有回源网关和 iframe 入口模式，复用这些既有结构比新增域名与证书链更简单，也更容易回退。

🧭 入口与架构

入口位于左侧“工作台”分组、OpenCode 记忆库之后，显示名称为“MCP 记忆服务”。视图使用 type: "embed"，URL 为：

https://console.yohan.fun/__agentmeshos/memory/

请求链路如下：

浏览器
  -> console.yohan.fun /__agentmeshos/memory/
  -> MM 边缘
  -> RR 100.64.0.1:39200 私有回源
  -> A-Auth internal/auth?required_role=admin
  -> 102 100.64.0.4:8104（剥离前缀）

层次	配置	作用
Console 导航	`data-view="mcpMemory"`	仅 admin 显示入口
Console 视图	`type: "embed"` + 同源 URL	站内 iframe 与新窗口使用同一受控地址
RR 网关	`MCP_MEMORY_UPSTREAM="100.64.0.4:8104"`	仅从 Tailnet 访问 102
MCP 容器	`MCP_HTTP_ROOT_PATH=/__agentmeshos/memory`	让 base、静态资源、API 和 SSE 正确带上前缀
A-Auth	`required_role=admin`	匿名或普通用户不能读取记忆服务

🔧 实现与取舍

方案	结果	取舍
Console 同源路径	采用	复用现有 A-Auth、边缘和证书，不增加公网面
新建 `mcp-memory.yohan.fun`	不采用	需要新增 DNS、证书、网关和二级登录边界
直接 iframe Tailnet `8104`	不采用	公网浏览器无法访问，且存在混合内容和 CSP 问题
公网直接暴露 8104	不采用	当前服务允许匿名访问，会扩大数据风险

RR 网关对路径做两件事：命中 /__agentmeshos/memory/ 时先做管理员鉴权；转发上游时由 proxy_pass .../ 剥离此前缀。MCP 服务通过 MCP_HTTP_ROOT_PATH 生成 <base href="/__agentmeshos/memory/">，因此前端相对请求会重新回到受控路径。网关同时关闭 buffering、延长读取超时并允许 Upgrade，保证 SSE 和后续流式接口不被截断。

🧪 验证证据

检查项	实测结果
Console 镜像	`ghcr.io/agentmeshos/agentmeshos-console-site:sha-1345c900ef5660561cdd3b0786b8a7ec70d41b49`
工作流	run `39048964303`，build 与 deploy 均 success
静态契约	`workspace-contract.sh` PASS
网关契约	`main-origin-gateway-test.sh` PASS
网关只读检查	`agentmeshos-main-origin-gateway.sh --check` SUCCESS
匿名门禁	memory 路径返回 `302` 到 A-Auth 登录
管理员页面	HTTP 200，含 `<base href="/__agentmeshos/memory/">` 与 MCP Dashboard 标题
Console 导航	管理员页面包含 `data-view="mcpMemory"`
静态资源	`/__agentmeshos/memory/static/style.css` 返回 200
模型健康	`/__agentmeshos/memory/api/health/model` 返回 `bge-m3 / 1024 / sqlite-vec`
SSE	`/__agentmeshos/memory/api/events` 返回 `HTTP/2 200`
iframe	上游返回 `X-Frame-Options: SAMEORIGIN`，同源嵌入允许

认证验证使用了 A-Auth 自身签发的 5 分钟随机管理员会话；测试结束后通过 trap 删除该会话，没有读取或修改现有用户会话。

🔁 回退方案

Console 代码回退可恢复对应提交前的 Console 镜像；MCP 服务本身不依赖这次导航变更，回退后仍可通过 102 的 Tailnet 地址直接使用。网关应用前已把原配置备份到 /backup/agentmeshos/main-origin-gateway/origin-gateway.conf.pre-mcp-memory.20261018-002241，脚本支持 --rollback。

如果只需要暂时隐藏入口，可先从 Console 导航移除 mcpMemory 视图；如果网关路径异常，再按上述配置备份恢复。不要把 8104 临时改为公网监听作为绕过方案。

⚠️ 风险与未决项

8104 仍允许匿名访问。 当前它只监听 102 Tailnet，公网唯一入口已经由 A-Auth admin 保护。后续如果 8104 扩展到其他网络，必须先补 API 鉴权，不能依赖 Console 网关作为唯一门禁。

RR 网关配置此前已与仓库模板存在漂移，本轮应用时新增了既有的 /app、panel、mem.yohan.fun 和公开 API 状态路由。应用后 Console、API health、Auth 登录与 memory 路由均已回归；后续仍应定期用脚本 --check 检查生产配置。

未决项：无。