TencentDB-Agent-Memory 团队记忆控制台前端:MemoryPanel Web 开发与部署实战指南
TencentDB-Agent-Memory 团队记忆控制台前端:MemoryPanel Web 开发与部署实战指南
本指南以仓库中 MemoryPanel/web/README.md 为骨架,完整讲解 Team Memory Control 管理界面的技术栈、本地开发启动流程、Vite 开发代理配置、生产构建产物托管方式,以及前端与 Control API 的对接边界与凭证安全规范。读完本文,你将能够在本地一键拉起 Control + 前端两套服务,理解 /api/v1 与 /v3 两条请求链路的代理规则,并掌握基于 X-Tdai-Service-Id / X-Tdai-User-Key 的无 Cookie 无状态登录与请求鉴权机制。
一、项目定位:无状态 Control 的 Web 管理界面
MemoryPanel/web 是 Team Memory Control(简称 Control)的 Web 管理界面,负责对接同仓库的无状态 Control 服务。Control 本身是一个"不保存服务端登录会话、不维护本地用户数据库"的团队记忆管理控制台,用于管理团队、用户、Agent、任务及其关联的 Skill、Wiki、Code Graph 和 Chat Memory 资产(参见 MemoryPanel/README.md)。
前端在整个体系中的职责可以概括为三层:
- 管理界面:通过浏览器提供团队、成员、Agent、API Key、Skill、Wiki、Code Graph、Chat Memory 与任务工作台的可视化管理入口;
- 凭证持有者:登录凭证由前端自行持有并缓存(无 Cookie、无服务端会话),每次业务请求通过自定义 Header 注入;
- 请求代理消费者:开发期依赖 Vite Dev Server 的代理能力,把不同前缀的请求分发到 Control(
/api/v1)与记忆网关(/v3)两套后端。
二、技术栈与目录结构
2.1 技术栈
按 package.json 实际依赖,前端技术栈如下:
| 类别 | 选型 |
|---|---|
| 框架 | React 18(react@^18.3.1) |
| 语言 | TypeScript 5 |
| 构建工具 | Vite 6(vite@^6.0.7)+ @vitejs/plugin-react |
| 路由 | React Router(react-router-dom@^7.18.1,采用 HashRouter) |
| 状态管理 | Zustand(zustand@^5.0.14) |
| 样式 | Tailwind CSS 3 + @tailwindcss/typography + TDesign(tea-component) |
| 国际化 | i18next + react-i18next |
| 图可视化 | sigma / graphology(用于 Code Graph 与 Wiki 知识图谱) |
| 其他 | lucide-react 图标、sonner 提示、react-markdown + remark-gfm 渲染 Markdown |
值得注意的是,前端使用 createHashRouter(见 routes/index.tsx),而非 BrowserRouter。源码注释说明这是为了"保持与旧版 hash 路由兼容,避免刷新 404(静态部署不需要服务端 fallback 配置)"——这意味着构建产物可以直接以纯静态方式托管,无需在 Web 服务器上配置 SPA fallback 规则。
2.2 源码目录脉络
从 src 目录结构看,前端代码按职责划分:
src/
├── components/ # 通用组件(登录门、Markdown 渲染、路由守卫、设置弹窗)
├── constants/ # 菜单等常量
├── i18n/ # zh-CN / en-US 双语资源
├── layouts/ # GlobalHeader、TabBar、ConsoleLayout 整体布局
├── lib/
│ └── api/ # 对 Control API 的分域封装(base / auth / teams / users / agents / assets / skills / tasks / chat-memory / meta-instances)
├── pages/ # Workbench、Wiki、Code、Skills、ChatMemory、Team 各业务页面
├── routes/ # 路由表(HashRouter)
├── services/ # 账号、资产范围、权限、当前角色等业务 store
├── stores/ # auth / backend 状态
└── utils/
路由表定义了 8 个核心页面:工作台(/)、Wiki(/wiki)、Code(/code)、Skills(/skills)、Chat Memory(/memory)、成员(/team/members)、Agent(/team/agents)、API Key(/team/api-keys),全部挂在 ConsoleLayout 父路由之下。
三、本地开发:完整启动流程
前端依赖 Control 后端才能正常工作,因此正确顺序是先启动 Control,再启动前端。
3.1 第一步:启动 Control(仓库根目录 / MemoryPanel)
在仓库根目录(即 MemoryPanel/)执行:
pnpm install
cp .env.example .env
cp config/metadata-instances.example.json config/metadata-instances.json
pnpm dev
三点实操提示:
config/metadata-instances.json是实例注册表,内含部署环境提供的实例 ID、Gateway 地址和 API Key,属于敏感文件,已被 Git 忽略,不得提交(字段说明见 metadata-instances.README.md 与 metadata-instances.example.json);- Control 默认监听
http://127.0.0.1:8123,健康检查端点为GET /health; - 使用 Wiki 或 Code Graph 功能时,还需要可访问的 Knowledge Service 与 Memory Gateway 作为外部依赖。
3.2 第二步:启动前端
cd web
npm install
cp .env.example .env
npm run dev
浏览器访问 http://127.0.0.1:5173 即可打开管理界面。.env.example 中给出了两个可选环境变量(详见 .env.example):
# Control 后端地址(vite proxy),默认 http://127.0.0.1:8123
# VITE_TMC_BACKEND_URL=http://127.0.0.1:8123
# 记忆 Gateway(可选,/v3 代理),默认 http://127.0.0.1:8420
# VITE_SKILL_GATEWAY_URL=http://127.0.0.1:8420
注意:Vite 不会热加载环境变量,修改 .env 后需要重启 dev server 才会生效。
3.3 前端包管理说明
后端使用 pnpm、前端使用 npm(见 MemoryPanel/README.md 与 package.json),两个目录的依赖互相独立,务必在对应目录下分别安装,不要混用包管理器。
四、开发代理:双链路请求转发
vite.config.ts 是前端开发期的"路由器"。对照源码 vite.config.ts,默认代理配置如下:
| 请求前缀 | 默认目标 | 环境变量 | 说明 |
|---|---|---|---|
/api/v1、/health |
http://127.0.0.1:8123 |
VITE_TMC_BACKEND_URL |
链路 A:Control 后端(Meta / Skill / Chat Memory / Knowledge / Agent 等公开 API) |
/v3 |
http://127.0.0.1:8420 |
VITE_SKILL_GATEWAY_URL |
记忆网关(/v3/skill/* 等数据面接口) |
从源码可以看到两个关键实现细节:
host: '0.0.0.0':开发服务器对所有网卡开放,方便容器或局域网内其他设备访问(而 Control 后端默认只监听 127.0.0.1);changeOrigin: true:代理时会改写请求头中的 Host 为后端目标,避免后端因 Host 校验而拒绝请求。
如需连接其他开发环境,请在未提交的 web/.env 中写入实际地址(通过 VITE_TMC_BACKEND_URL / VITE_SKILL_GATEWAY_URL 覆盖默认目标),不要把内部地址、账号或凭证写入 README、源码或已跟踪的环境文件。
五、生产构建与产物托管
npm run build
build 脚本实际执行 tsc && vite build(见 package.json),即先做 TypeScript 类型检查、再执行 Vite 构建,任何类型错误都会直接中断构建。产物输出到 web/dist/(源码中 outDir: 'dist' 且 emptyOutDir: true)。
Control 支持通过 UI_DIST_DIR=./web/dist 配置项同源托管这些静态文件——即由 Control 服务直接对外提供页面与 API,前端无需单独部署 Nginx 或静态服务器。结合前面提到的 HashRouter,这种静态托管不需要任何 SPA fallback 规则即可支持页面刷新与深链直达。
构建完成后可用 npm run preview 本地预览产物效果。
六、API 边界:前端对接的公开契约
6.1 前端使用的 Control API
前端仅对接以下 Control 公开 API 前缀(同时登记在 MemoryPanel/README.md 中):
/api/v1/meta/*:实例、身份与元数据管理/api/v1/skill/*:Skill 管理/api/v1/chat-memory/*:Chat Memory 管理/api/v1/knowledge/*:Wiki 与 Code Graph 管理/api/v1/agent-overview/*:Agent 资产聚合/api/v1/agent/*:Agent 生命周期操作
对接边界以仓库 docs/api 下的公开契约为准(如 meta-api.openapi.yaml);未列入公开契约的外部服务接口不属于前端对接范围,前端也不得直接调用。
6.2 无 Cookie 鉴权模型:Header 注入
README 强调"登录凭证保存在浏览器 localStorage,业务请求通过 X-Tdai-Service-Id 和 X-Tdai-User-Key Header 发送"。源码给出了完整的实现证据链:
- 会话缓存(panelSession.ts):登录凭证(
instanceId+userKey+ 可选的user)以 JSON 形式缓存在localStorage的tdai-panel.session键下。源码注释说明:早期版本曾用sessionStorage(tab 级,新开 tab 需重新登录),改为localStorage后多 tab 共享登录态,登出时通过 storage 事件同步; - 请求注入(base.ts):
metaPost每次请求自动从会话中读取凭证并注入两个 Header——X-Tdai-Service-Id(实例 ID,即注册表 id = 内核x-tdai-service-id)与X-Tdai-User-Key(用户 API Key);⚠️ Header 名以meta-api.openapi.yamlv1.1.0 为准,早期文档使用的X-Metadata-Instance-Id已改名,若仍按旧名发送,Control 会返回400 MISSING_INSTANCE_ID; - 登录验活(auth.ts):登录流程为 ①
GET /meta/instances选择实例 → ② 用户输入自持的user_key(sk-mem-…格式)→ ③POST /meta/auth/verify(此时 Header 仅带X-Tdai-Service-Id,user_key只放 body)→ ④ 返回valid === true后把凭证写入会话; - 401 全局处理:请求层在收到 401 时会派发
auth:unauthorized自定义事件,App 层监听后清空 auth 状态并展示登录页; - Meta 信封解析:所有 Meta 接口返回统一信封,
code !== 0或data为空时按错误处理,并优先从信封中提取message/request_id构造可读错误信息(error-message.ts 负责最终格式化)。
安全底线:前端不得记录、展示或上传完整凭证。user_key 是用户凭证,只能通过请求 Header 传递;实例注册表中的 api_key 仅供服务端调用外部服务,绝不返回浏览器。
七、常用命令速查
| 命令 | 说明 |
|---|---|
npm run dev |
启动 Vite 开发服务器(默认端口 5173) |
npm run mock |
以 mock 入口启动(VITE_ENTRY=mock vite) |
npm run build |
TypeScript 类型检查并构建到 web/dist/ |
npm run preview |
本地预览构建产物 |
npm run lint:check |
ESLint 检查 src/**/*.{ts,tsx}(lint 带 --fix 自动修复) |
npm run format:check |
Prettier 格式检查 src/**/*.{ts,tsx,css}(format 自动格式化) |
八、安全与提交规范
综合前端 README 与 MemoryPanel/README.md 的安全要求,前端开发与提交需遵守:
.env、真实实例注册表、日志和测试报告不得提交到版本库;- 文档与示例只能使用
example.com、回环地址及明显占位符,禁止出现内部地址、账号或凭证; - 提交前建议运行
bash scripts/secret-scan.sh --strict扫描敏感信息(脚本位于 MemoryPanel/scripts/secret-scan.sh); - 若凭证曾进入 Git 历史,应立即轮换凭证,并在发布前清理历史记录。
九、小结
MemoryPanel/web 是一个典型的"无状态后端 + 纯前端凭证持有"管理控制台实现:本地开发依赖 Vite 代理把 /api/v1 与 /v3 双链路分别转发给 Control 与记忆网关;生产构建产物可直接交给 Control 同源托管;鉴权完全基于 localStorage 会话与 X-Tdai-Service-Id / X-Tdai-User-Key Header 注入,无 Cookie、无服务端会话。理解这套启动流程、代理边界与凭证模型,是继续深入阅读前端各业务页面(pages)、API 分域封装(lib/api)以及 Meta OpenAPI 契约 的前提。