41 lines
3.8 KiB
Markdown
41 lines
3.8 KiB
Markdown
# MemRelay 对话交接入口
|
||
|
||
> 定位：跨聊天窗口、跨 AI 客户端的**稳定入口文档**，只记录很少变化的事实、路径与硬约束。
|
||
>
|
||
> 维护规则：仅当部署拓扑、安全边界或上下文获取路径变化时更新本文。功能迭代、模型选型、任务状态、近期讨论等易变信息一律不写在这里——它们的正确归宿见"上下文获取路径"。
|
||
|
||
## 项目定位
|
||
|
||
MemRelay 是自托管的 AI 记忆、开发历史、密码库接入和文件仓储服务：让 Codex、Cursor、Claude Code 等客户端跨设备、跨项目、跨窗口恢复上下文，持续沉淀规则、偏好、事实、决定、经验、凭证与秒级检查点。AI 整理与记忆 Git 为可选增强、默认关闭；零配置基础模式是正式支持的完整运行方式。
|
||
|
||
## 部署拓扑（稳定事实）
|
||
|
||
- 正式实例：`https://mr.asio.asia`；ARM 板 `192.168.32.100`（Armbian，SSH root），Compose 位于 `/opt/1panel/docker/compose/memrelay`，数据 `/data/memrelay-stack`，宿主端口 `3003`。
|
||
- Sub2API 模型网关：同一块板，宿主端口 `3004`（板内/内网直连 `http://192.168.32.100:3004/v1`），公网 `https://sub2.asio.asia`。同板服务间调用走内网地址，不绕公网。
|
||
- 本机 Windows 不再部署 Docker 实例；开发目录 `E:\NIXProject\MemRelay`。
|
||
- 技术栈：后端 Python 3.12 + FastAPI + FastMCP + SQLAlchemy/SQLite + uv；前端 Vue 3 + Vite + Element Plus + pnpm；记忆引擎 Basic Memory v0.22.1（`third_party/` 子模块，独立容器经 MCP HTTP 调用）。
|
||
- OpenResty 只缓存带哈希的 `/assets/`；API、MCP、认证、签名地址不进代理缓存。
|
||
|
||
## 上下文获取路径（新窗口按序执行）
|
||
|
||
1. 读本文。
|
||
2. 读 `aidocs/project_context.md`——本机项目记忆时间线，最新条目在最上，是最完整的演进记录（gitignore，本机专属）。
|
||
3. 读 `docs/implementation-plan.md` 顶部数节——最近迭代的契约、诊断与验收结果。
|
||
4. 需要正式记忆、检查点、密码库或文件时，走 MemRelay 本体：Web `https://mr.asio.asia` 或 Streamable HTTP MCP（Token 在 Web「MCP Token」页创建，用完可撤销）。模型选型、生产经验等长期结论保存在 MemRelay 全局记忆中，以那里为准。
|
||
5. 不假设本地 git 与生产一致：核对 `git log` 与生产容器状态后再动手。
|
||
|
||
## 安全与工程边界（硬约束）
|
||
|
||
- 秘密值不进仓库、记忆正文、日志或交接文档；聊天中出现过的测试密钥用后立即撤销轮换。
|
||
- 发布纪律：完整门禁（后端 Ruff + pytest、前端 Vitest/ESLint/Prettier/构建）→ 停机备份（`MEMRELAY_DATA_PATH=/data/memrelay-stack sh scripts/backup.sh`）→ 只重建 `memrelay` 服务 → 保留回滚镜像标签 → 验证内外网 readiness。
|
||
- 含中文的文件禁止用 PowerShell `Get-Content`/`Set-Content` 修改——ANSI 误读会把 UTF-8 写成"合法编码的乱码"，常规校验发现不了；只用编辑工具或显式 UTF-8 编解码的 Python 脚本，改完做关键中文串的内容断言。
|
||
- 长 SSH 组合命令拆分执行；生产只读诊断用脚本管道 `docker exec -i memrelay-memrelay-1 python -`（脚本含中文时先 scp 再远端重定向，避免 PowerShell 管道污染）。
|
||
- Web、REST、MCP 共用服务层，改一处三端生效；提交信息格式 `<type>: <中文描述>`。
|
||
- 模型只通过"提案 + 服务端校验"影响记忆，永远不给模型直接增删改查记忆文件的能力。
|
||
|
||
## 常用验证（稳定）
|
||
|
||
- 就绪：`curl http://192.168.32.100:3003/api/v1/health/ready`、`curl https://mr.asio.asia/api/v1/health/ready`
|
||
- 容器：`docker ps --format '{{.Names}} {{.Status}}' | grep mem`（应两个 healthy）
|
||
- 数据库：容器内 `PRAGMA quick_check` 应为 ok；迁移版本查 `alembic_version` 表
|