198 lines
8.7 KiB
Markdown
198 lines
8.7 KiB
Markdown
---
|
||
title: MemRelay Project Deployment Overview
|
||
type: curated
|
||
permalink: main/projects/ebb54e31-5afe-4f9b-a291-4e3b03ca3b21/curated/development/mem-relay-project-deployment-overview
|
||
stable_id: b54bd6b0-bbdd-4ab2-92d3-a4f5d58e8f83
|
||
scope: project
|
||
project_id: ebb54e31-5afe-4f9b-a291-4e3b03ca3b21
|
||
workspace_type: development
|
||
usage_profile_id: null
|
||
preference_context: development
|
||
document_type: deployment
|
||
revision: 1
|
||
source_memory_ids: []
|
||
source_checkpoint_ids: []
|
||
source_file_ids: []
|
||
source_git_commit: null
|
||
source_git_commits: []
|
||
source_agent_sync_ids: []
|
||
model_connection: Sub2API
|
||
model_name: git-restore
|
||
source_count: 20
|
||
source_revisions:
|
||
memory:7ab8ac01-9e4d-4222-b224-7735fdeafdc8: '1'
|
||
memory:b9a463d1-5659-4baa-aaf4-6464661ef074: '1'
|
||
memory:9092af09-6a60-404e-88ad-3344f2fdf0ca: '1'
|
||
memory:c16b8950-20d2-4d3d-87b3-0a8bfd20790d: '1'
|
||
memory:23bcc4c0-4992-41d6-b70e-210937a76a0f: '1'
|
||
memory:b3fc5d7e-f1d7-4a63-860b-37f9f35cb136: '1'
|
||
memory:41e5bdb5-a67b-49bc-b8a6-ab20b4c66fca: '1'
|
||
source_dispositions:
|
||
processed: 20
|
||
unchanged: 0
|
||
unsupported: 0
|
||
skipped: 0
|
||
cited_source_ids:
|
||
- curated_baseline:b54bd6b0-bbdd-4ab2-92d3-a4f5d58e8f83
|
||
- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
|
||
- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
|
||
- global_guidance_memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823
|
||
- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
|
||
- global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e
|
||
- global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e
|
||
- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
|
||
- global_guidance_document:2b47472d-3ac2-4394-8646-c6bf1c0fc270
|
||
- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
|
||
- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
|
||
- curated_baseline:08fb4703-1527-4983-bb8e-e4ca735e4316
|
||
- curated_baseline:eebf38d3-36dc-4b57-b8d7-1f2c8be2f234
|
||
- memory:b3fc5d7e-f1d7-4a63-860b-37f9f35cb136
|
||
- memory:41e5bdb5-a67b-49bc-b8a6-ab20b4c66fca
|
||
- curated_baseline:6b2d8349-7a95-4a18-8e4b-20dd2ab95e2f
|
||
- curated_baseline:d459e837-b05c-4f31-9b05-7f9d09c71f25
|
||
- memory:7ab8ac01-9e4d-4222-b224-7735fdeafdc8
|
||
- memory:23bcc4c0-4992-41d6-b70e-210937a76a0f
|
||
- memory:b9a463d1-5659-4baa-aaf4-6464661ef074
|
||
- memory:c16b8950-20d2-4d3d-87b3-0a8bfd20790d
|
||
- memory:9092af09-6a60-404e-88ad-3344f2fdf0ca
|
||
job_cited_source_ids:
|
||
- curated_baseline:b54bd6b0-bbdd-4ab2-92d3-a4f5d58e8f83
|
||
- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
|
||
- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
|
||
- global_guidance_memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823
|
||
- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
|
||
- global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e
|
||
- global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e
|
||
- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
|
||
- global_guidance_document:2b47472d-3ac2-4394-8646-c6bf1c0fc270
|
||
- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
|
||
- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
|
||
- curated_baseline:08fb4703-1527-4983-bb8e-e4ca735e4316
|
||
conflicts: []
|
||
supersedes: []
|
||
preferences:
|
||
- statement: 遵循 KISS 与 YAGNI，使用最简单且正确的实现。
|
||
level: scenario
|
||
workspace_types:
|
||
- development
|
||
workspace_ids: []
|
||
source_ids:
|
||
- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
|
||
counterexample_source_ids: []
|
||
occurrence_count: 1
|
||
explicit: true
|
||
confidence: 1.0
|
||
status: current
|
||
- statement: 默认使用中文沟通，除非明确要求其他语言。
|
||
level: scenario
|
||
workspace_types:
|
||
- development
|
||
workspace_ids: []
|
||
source_ids:
|
||
- global_guidance_memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823
|
||
counterexample_source_ids: []
|
||
occurrence_count: 1
|
||
explicit: true
|
||
confidence: 1.0
|
||
status: current
|
||
- statement: AI 驱动的记忆整理与 Memory‑Git 默认关闭，未配置时系统完整工作且不报错。
|
||
level: scenario
|
||
workspace_types:
|
||
- development
|
||
workspace_ids: []
|
||
source_ids:
|
||
- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
|
||
- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
|
||
counterexample_source_ids: []
|
||
occurrence_count: 2
|
||
explicit: true
|
||
confidence: 1.0
|
||
status: current
|
||
- statement: 在任何登录、SSH、数据库或 API 调用前先查询 Vaultwarden，唯一匹配时直接使用。
|
||
level: scenario
|
||
workspace_types:
|
||
- development
|
||
workspace_ids: []
|
||
source_ids:
|
||
- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
|
||
- global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e
|
||
counterexample_source_ids: []
|
||
occurrence_count: 2
|
||
explicit: true
|
||
confidence: 1.0
|
||
status: current
|
||
- statement: '`memrelay://capabilities` 包含 datetime、UUID、Pydantic 对象时需先通过 FastAPI
|
||
`jsonable_encoder` 再 JSON 编码。'
|
||
level: scenario
|
||
workspace_types:
|
||
- development
|
||
workspace_ids: []
|
||
source_ids:
|
||
- global_guidance_memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823
|
||
- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
|
||
counterexample_source_ids: []
|
||
occurrence_count: 2
|
||
explicit: true
|
||
confidence: 1.0
|
||
status: current
|
||
source_cursor: 0
|
||
source_hash: cd96d5b27b5d1ef34ff30350e40c12b9d9b7e389c5813755521578d1f2597d9c
|
||
prompt_version: 2026-08-12.3
|
||
schema_version: '3'
|
||
curation_job_id: null
|
||
created_at: '2026-08-08T09:52:44.504144+00:00'
|
||
updated_at: '2026-09-23T15:13:18.732700+00:00'
|
||
tags:
|
||
- deployment
|
||
- development
|
||
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
|
||
---
|
||
|
||
# MemRelay 部署概览 (development)
|
||
|
||
## 目标与技术栈
|
||
- 提供跨设备、项目、AI 客户端的个人规则、记忆、密码库与文件仓储。
|
||
- 后端: Python 3.12, FastAPI, FastMCP, SQLAlchemy, SQLite
|
||
- 前端: Vue 3, TypeScript, Vite, Element Plus, Vue I18n
|
||
- 记忆引擎: Basic Memory v0.22.1（Markdown 存储），MiniLM 语义检索（必要时降级为全文搜索）
|
||
|
||
## 部署拓扑
|
||
- **公网入口**: `https://mr.asio.asia`（OpenResty 终止 TLS 并转发至 FRPS）
|
||
- **应用主机**: Armbian ARM64 `192.168.32.100`，监听端口 `3003`
|
||
- **Compose 目录**: `/opt/1panel/docker/compose/memrelay`
|
||
- **持久化存储**: `/data/memrelay-stack`（MemRelay 与 Basic Memory 共享挂载）
|
||
- **FRP 栈**: OpenWrt FRPC `0.70.1`（WebSocket） → FRPS，映射 `mr.asio.asia → 192.168.32.100:3003`
|
||
- **会话 Cookie**: 根据请求协议动态设置 `Secure` 标记，兼容局域网 HTTP 与公网 HTTPS
|
||
- **缓存策略**: OpenResty 对登录、API、MCP、密码库、上传下载等端点不启用代理缓存；静态资源使用 ETag 与浏览器缓存
|
||
- **备份**: `/data/memrelay-backups/memrelay-20260805T234836Z.tar.gz`
|
||
|
||
## 密码库索引（Vaultwarden）
|
||
| 条目 | 用途 |
|
||
|------|------|
|
||
| `MemRelay Administrator` | Web 管理员 |
|
||
| `BDYG18Pro Armbian SSH` | 部署主机 |
|
||
| `OpenWrt Router SSH` | FRPC 与局域网路由 |
|
||
| `Public FRPS Server SSH` | 公网 FRPS 与 OpenResty |
|
||
| `FRP ali.asio.asia Token` | FRPC/FRPS 认证 |
|
||
| `Gitea git.asio.asia OAuth` | Git 访问与令牌刷新 |
|
||
| `Armbian MySQL Root` | Docker MySQL |
|
||
> **说明**：普通记忆仅记录名称、用途与使用方式，敏感值始终保存在 Vaultwarden 中。
|
||
|
||
## 可选特性（默认禁用）
|
||
- **AI 驱动的记忆整理（AI Curation）** 与 **Memory‑Git** 为可选增强，默认关闭。未开启时系统不探测模型、不创建 `.git` 目录，也不会因缺失功能报错。
|
||
|
||
## 关键决策概览
|
||
| 决策 | 说明 |
|
||
|------|------|
|
||
| **MCP JSON 序列化** | `memrelay://capabilities` 包含 `datetime`、`UUID` 或 Pydantic 对象时，先使用 FastAPI `jsonable_encoder` 再 `json.dumps`，避免生产环境序列化错误。 |
|
||
| **密码库读取性能** | 引入进程内 Bitwarden 快照，列表延迟从约 20 s 降至 ≈ 420‑431 ms（ARM64）。 |
|
||
| **Cookie `Secure` 动态化** | 根据请求协议动态决定 `Secure` 标记，解决公网 HTTPS 后局域网 HTTP 会话失效。 |
|
||
| **ARM64 构建迁移** | 提供可选构建时代理与 Debian 镜像参数，加速依赖下载；使用 Linux 容器只读挂载方式解决 Windows `tar` 符号链接问题。 |
|
||
| **数据库迁移 `20260805_0010`** | 为 `mcp_tokens` 表加入 `all_profiles`，实现全档案 Token 自动覆盖。 |
|
||
|
||
## 里程碑
|
||
- **2026‑08‑03**：完成部署拓扑，源码提交 `2d2e35a`，验证公网 HTTPS、FRP 映射、健康检查。
|
||
- **2026‑08‑05**：全链路审计，修复 JSON 序列化错误，ARM64 滚动发布 95 个 MCP 工具和 3 个资源。
|
||
- **2026‑08‑07**：完成全部测试（后端 153 项，前端 34 项），系统运行稳定。
|
||
|
||
*本文档引用的主要来源包括 `curated_baseline:b54bd6b0…`（部署概览）、`global_guidance_memory:bf88c265…`（开发实施原则）、`global_guidance_memory:3f91189b…`（可选 AI 与 Git）等。* |