Easy Memory

让 AI 跨会话、跨项目持久化记忆。 基于 Qdrant 向量数据库 + 官方向量模型（支持经 OpenAI-compatible relay 接入）/ Ollama 的 MCP 记忆服务。

Easy Memory 提供双 Shell 架构：

• MCP Shell — 通过 stdio 与 Claude Desktop / Cursor / VS Code 等 IDE 直接通信
• HTTP Shell — RESTful API，支持远程访问、多客户端共享记忆

---

目录

• 快速开始
• 客户端配置
• 30 秒排障（远端优先）
• HTTP API
• MCP Tools
• Docker 部署
• 环境变量
• Web UI 管理面板
• 架构文档

---

快速开始

推荐路径（远端 VPS 优先，约 30 秒）

如果你已有远端 Easy Memory 服务（例如 https://memory.zhiz.chat）和 API Key（em_...），建议优先使用 stdio 远程代理模式：

1. 在客户端 MCP 配置里使用 npx easy-memory@latest + EASY_MEMORY_URL + EASY_MEMORY_TOKEN
2. 执行 Reload Window / 重启客户端
3. 运行 MCP: List Servers（或客户端等效命令）确认 server 已连接

根键速记：VS Code 的 .vscode/mcp.json 用 servers；Claude Desktop / Cursor 常见 mcpServers。

只有在你没有远端服务时，再走下方“本地自托管（Qdrant + Ollama）”路径。

前置条件

依赖	版本	说明
Node.js	≥ 20	运行 MCP Server
Docker	≥ 24	运行 Qdrant + Ollama（或使用远程模式跳过）

💡 远程代理模式无需本地 Qdrant/Ollama
如果你有远端 Easy Memory 服务（如 memory.zhiz.chat），只需设置 EASY_MEMORY_TOKEN 和 EASY_MEMORY_URL 即可。参见 远程代理模式。

基础服务准备（Qdrant + Ollama）

Easy Memory 依赖两个基础服务：Qdrant（向量数据库）和 Ollama（本地 Embedding 模型）。

# 1. 启动 Qdrant 向量数据库
docker run -d --name qdrant \
  -p 6333:6333 \
  -v qdrant_data:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY=your-api-key \
  qdrant/qdrant:latest

# 验证 Qdrant 运行正常
curl http://localhost:6333/healthz
# 应返回: OK

# 2. 启动 Ollama（本地 AI 模型推理引擎）
docker run -d --name ollama \
  -p 11434:11434 \
  -v ollama_data:/root/.ollama \
  ollama/ollama:latest

# 3. 拉取 bge-m3 Embedding 模型（约 1.2GB，首次需等待）
docker exec ollama ollama pull bge-m3

# 验证 Ollama 运行正常
curl http://localhost:11434/api/tags
# 应返回包含 "bge-m3" 的模型列表

⚠️ 注意事项：

• QDRANT__SERVICE__API_KEY 是 Qdrant 的认证密钥，后续配置中需跟 QDRANT_API_KEY 保持一致
• bge-m3 模型首次加载约需 2GB 内存，低配机器可能较慢
• Ollama 默认监听 0.0.0.0:11434，生产环境建议限制到 127.0.0.1

默认远端方案：官方 OpenAI 向量模型（经第三方 relay 接入）

如果你需要更高质量的向量或本地资源不足，项目默认推荐启用 官方 OpenAI 向量模型，但通过兼容 relay 服务接入：

1. 准备支持 /v1/embeddings 的兼容服务与 API Key
2. 使用 .env.example 中的 OPENAI_EMBEDDING_* 配置项
3. 设置环境变量：

EMBEDDING_PROVIDER=openai-auto
OPENAI_EMBEDDING_API_KEY=sk-...
OPENAI_EMBEDDING_BASE_URL=https://api.vectorengine.ai/v1
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

openai-auto 模式下，远端官方 OpenAI 向量模型（经 relay 接入）优先，Ollama 自动兜底。

easy-memory 会自动发送 dimensions=1024，确保与当前 Qdrant dense vector collection 保持一致。

兼容：配置 Google 官方 Gemini 远端 Embedding

如果你更偏好 Google 官方 Vertex AI，也仍然可以继续使用 Gemini Embedding：

1. 前往 Google AI Studio 获取 API Key
2. 在 Google Cloud Console 创建项目并启用 aiplatform.googleapis.com
3. 设置环境变量：

EMBEDDING_PROVIDER=auto
GEMINI_API_KEY=AIzaSy...
GEMINI_PROJECT_ID=my-gcp-project
GEMINI_REGION=us-central1

auto 模式下，Gemini 请求失败（限流/超时）会自动降级到 Ollama，确保服务不中断。

方式一：npx 直接运行（MCP 模式）

# 前提：Qdrant 和 Ollama 已按上方步骤启动

# 通过 npx 启动 MCP Server
npx easy-memory

方式二：Docker Compose 一键部署

git clone https://github.com/FlippySun/easy-memory.git && cd easy-memory
cp .env.example .env   # 默认即本地 Ollama；如需远端 relay，再改成 EMBEDDING_PROVIDER=openai-auto 并填写 OPENAI_EMBEDDING_API_KEY
docker compose up -d
docker exec ollama ollama pull bge-m3

方式三：从源码构建

git clone https://github.com/FlippySun/easy-memory.git && cd easy-memory
pnpm install
pnpm build

# MCP 模式
node dist/index.js

# HTTP 模式
EASY_MEMORY_MODE=http HTTP_AUTH_TOKEN=your-token node dist/index.js

---

客户端配置

mcp.json 根键速查（避免“工具列表为空”）

客户端	MCP 配置根键
VS Code (GitHub Copilot)	servers
Claude Desktop / Cursor	mcpServers

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "your-api-key",
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

Cursor

编辑 Cursor Settings → MCP → 添加：

{
  "mcpServers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "your-api-key",
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

VS Code (GitHub Copilot)

编辑 .vscode/mcp.json：

{
  "servers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "your-api-key",
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

远程代理模式（推荐 — 无需本地 Qdrant/Ollama）

当你有一台运行 Easy Memory HTTP 服务的远程服务器时，本地客户端可通过远程代理模式直接对接远端服务，无需本地安装 Qdrant 或 Ollama。

需要先在远端 Admin 面板创建 API Key（参见 VPS 生产部署 → 用户管理）。

Claude Desktop / Cursor / VS Code — stdio 代理模式：

{
  "mcpServers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory@latest"],
      "env": {
        "EASY_MEMORY_TOKEN": "em_your-api-key",
        "EASY_MEMORY_URL": "https://memory.zhiz.chat"
      }
    }
  }
}

仅需设置两个环境变量，npm 包会自动切换为远程代理模式：

• EASY_MEMORY_TOKEN — 远端 API Key（从 Admin 面板获取）
• EASY_MEMORY_URL — 远端服务地址

MCP Streamable HTTP 模式（直连远端，进阶）

⚠️ VS Code 告警说明（重点）

当配置 type: "http" 时，VS Code 可能先尝试 OAuth 流程，并提示： “不支持动态客户端注册（manual client registration）”。

Easy Memory 当前是 Bearer Token 鉴权（Authorization: Bearer ...），不支持 OAuth 动态客户端注册。 这通常不是 VPS 故障，而是客户端接入模式不匹配。

对 VS Code / Cursor，优先使用上面的**远程代理模式（stdio）**更稳妥。

支持 Streamable HTTP 的客户端可以直接连接远端 MCP 端点，无需 stdio 代理：

HTTP 直连（适合明确支持 Bearer Header 的客户端）：

{
  "servers": {
    "easy-memory": {
      "type": "http",
      "url": "https://memory.zhiz.chat/mcp",
      "headers": {
        "Authorization": "Bearer em_your-api-key"
      }
    }
  }
}

VS Code / Cursor 推荐配置（避免 OAuth 告警）

编辑 .vscode/mcp.json：

{
  "servers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory@latest"],
      "env": {
        "EASY_MEMORY_URL": "https://memory.zhiz.chat",
        "EASY_MEMORY_TOKEN": "em_your-api-key"
      }
    }
  }
}

这是 stdio 代理模式：VS Code 不会先走 OAuth 注册探测，工具握手更稳定。

配置变更后，请执行 Reload Window，再运行 MCP: List Servers 检查状态。 若工具列表为空，优先检查 EASY_MEMORY_URL / EASY_MEMORY_TOKEN； GET /health 返回 {"status":"ok","mode":"http"}，且用于连通性探针时故意不带 token 访问 /mcp 返回 401，都属于正常保护行为。

远程 HTTP 模式

如果部署了 HTTP Shell，客户端可通过 HTTP API 接入 — 无需本地 Qdrant/Ollama。详见 HTTP API 部分。

---

30 秒排障（远端优先）

1. 先看配置键名：VS Code 用 servers，Claude/Cursor 常见 mcpServers
2. 强制生效配置：执行 Reload Window / 重启客户端
3. 看 MCP 连接状态：运行 MCP: List Servers
4. 看服务健康：GET /health 返回 {"status":"ok","mode":"http"}
5. 看鉴权语义：

• 未带 token 访问 /mcp 返回 401 = 正常保护
• type: "http" 出现 OAuth 动态注册提示 = 模式不匹配，切回 stdio 远程代理

---

HTTP API

所有 /api/* 端点需要 Bearer Token 认证：

Authorization: Bearer <HTTP_AUTH_TOKEN>

GET /health

健康检查（无需认证）。

curl http://localhost:3080/health
# {"status":"ok","mode":"http"}

POST /api/save

保存一条记忆。

curl -X POST http://localhost:3080/api/save \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "项目使用 pnpm 作为包管理器",
    "source": "manual",
    "fact_type": "decision",
    "tags": ["tooling", "pnpm"]
  }'

请求字段：

字段	类型	必填	说明
content	string	✅	记忆内容
project	string	❌	项目标识（默认 default）
source	string	❌	来源：conversation / file_watch / manual
fact_type	string	❌	类型：verified_fact / decision / hypothesis / discussion / observation
tags	string[]	❌	标签列表
confidence	number	❌	置信度 0-1（默认 0.7）

POST /api/search

语义搜索记忆（混合检索：向量 + BM25）。

curl -X POST http://localhost:3080/api/search \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"query": "包管理器", "limit": 5}'

请求字段：

字段	类型	必填	说明
query	string	✅	搜索查询
project	string	❌	项目标识
limit	number	❌	返回数量 1-20（默认 5）
threshold	number	❌	相似度阈值 0-1（默认 0.55）
include_outdated	boolean	❌	是否包含已归档记忆
cross_model	boolean	❌	是否允许跨模型搜索（默认关闭，排查 fallback / 迁移时可显式开启）
tags	string[]	❌	按标签过滤

POST /api/forget

归档/删除记忆。

curl -X POST http://localhost:3080/api/forget \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uuid-of-memory",
    "action": "archive",
    "reason": "信息已过时"
  }'

action 说明：

• archive — 软删除（标记为归档，搜索时默认不返回）
• outdated — 标记为过时
• delete — 从向量库中彻底删除

GET /api/status

系统状态检查。

curl -H "Authorization: Bearer your-token" http://localhost:3080/api/status

---

MCP Tools

Easy Memory 暴露 8 个 MCP Tools。

其中：

• easy_memory_* 是 preferred discoverability alias，优先推荐给支持工具枚举的 AI / MCP 客户端使用
• memory_* 继续保留，作为向后兼容名称

Tool	说明
easy_memory_save	保存记忆到向量库（preferred）
easy_memory_search	语义检索相关记忆（preferred）
easy_memory_forget	归档/标记过时/删除记忆（preferred）
easy_memory_status	系统健康状态（preferred）
memory_save	保存记忆到向量库（兼容名）
memory_search	语义检索相关记忆（兼容名）
memory_forget	归档/标记过时/删除记忆（兼容名）
memory_status	系统健康状态（兼容名）

---

Docker 部署

开发环境

cp .env.example .env
docker compose up -d
docker exec ollama ollama pull bge-m3

生产环境

cp .env.example .env
# 编辑 .env: 设置强密码 QDRANT_API_KEY, HTTP_AUTH_TOKEN

docker compose -f docker-compose.prod.yml up -d
docker exec ollama ollama pull bge-m3

# 验证
curl http://your-server:3080/health

预构建镜像

docker pull thj8632/easy-memory:latest
# 或指定版本
docker pull thj8632/easy-memory:0.5.8

支持平台：linux/amd64, linux/arm64

---

VPS 生产部署

前置条件

需求	说明
VPS	2C/4G+ 内存（Ollama bge-m3 需 ~2G）
域名	A 记录解析到 VPS IP
Docker	Docker ≥ 24 + Docker Compose v2
端口	80/443 对外开放（反向代理用）

1. 部署服务

# 克隆代码
git clone https://github.com/FlippySun/easy-memory.git
cd easy-memory

# 配置环境变量
cp .env.example .env
vim .env
# 必须设置:
#   QDRANT_API_KEY=<强随机密钥>
#   HTTP_AUTH_TOKEN=<Master Token — 管理员自用>
#   ADMIN_TOKEN=<Admin Token — 管理后台>

# 启动
docker compose -f docker-compose.prod.yml up -d

# 验证
curl http://localhost:3080/health
# {"status":"ok","mode":"http"}

2. 反向代理 (HTTPS)

Caddy（推荐 — 自动 HTTPS）

cp deploy/Caddyfile.example /etc/caddy/Caddyfile
# 编辑: 替换 memory.example.com 为实际域名
sudo systemctl reload caddy

Nginx（手动证书）

cp deploy/nginx.conf.example /etc/nginx/conf.d/easy-memory.conf
# 编辑: 替换域名, 配置 SSL 证书
sudo certbot --nginx -d memory.example.com
sudo nginx -s reload

3. 三层认证架构

ADMIN_TOKEN（管理员）
  └─ 管理后台 /api/admin/*
  └─ 创建/吊销 Managed API Key
  └─ 查看 Analytics / Audit 数据

HTTP_AUTH_TOKEN（Master Token）
  └─ 访问 /api/* HTTP API（save/search/forget/status）
  └─ 无 per-key rate limit 限制
  └─ 不用于 /mcp 握手

Managed API Key（分发给普通用户）
  └─ Admin 通过 POST /api/admin/keys 创建
  └─ 可设置 rate limit、project 隔离
  └─ 可随时吊销/轮转

4. 用户管理

管理员为用户创建 Token

curl -X POST https://memory.example.com/api/admin/keys \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-alice",
    "scopes": ["memory_save", "memory_search", "memory_forget", "memory_status"],
    "rate_limit": 30,
    "project": "alice-project"
  }'
# 返回: { "id": "...", "key": "em_abc123...", "name": "user-alice" }
# ⚠️ key 仅此一次返回，请安全保存并发给用户

用户配置远程 MCP（推荐：stdio 代理模式）

VS Code / Cursor — 编辑 .vscode/mcp.json：

{
  "servers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory@latest"],
      "env": {
        "EASY_MEMORY_URL": "https://memory.example.com",
        "EASY_MEMORY_TOKEN": "em_abc123..."
      }
    }
  }
}

可选：Streamable HTTP 直连（进阶）

{
  "servers": {
    "easy-memory": {
      "type": "http",
      "url": "https://memory.example.com/mcp",
      "headers": {
        "Authorization": "Bearer em_abc123..."
      }
    }
  }
}

⚠️ 若 VS Code 弹出“动态客户端注册”相关 OAuth 提示，请切回上方 stdio 代理模式。

JetBrains IDE — 添加 MCP Server：

{
  "mcpServers": {
    "easy-memory": {
      "url": "https://memory.example.com/mcp",
      "headers": { "Authorization": "Bearer em_abc123..." }
    }
  }
}

Note: Claude Desktop 不原生支持 HTTP 远端连接，需使用远程代理模式（npx + EASY_MEMORY_TOKEN）。参见 远程代理模式。

5. Admin API

所有 Admin API 需要 ADMIN_TOKEN 认证：

Authorization: Bearer <ADMIN_TOKEN>

功能	方法	路径
创建 Key	POST	/api/admin/keys
列出全部 Key	GET	/api/admin/keys
查看 Key	GET	/api/admin/keys/:id
更新 Key	PATCH	/api/admin/keys/:id
吊销 Key	DELETE	/api/admin/keys/:id
轮换 Key	POST	/api/admin/keys/:id/rotate
封禁 IP	POST	/api/admin/bans
列出 IP 封禁	GET	/api/admin/bans
解封 IP	DELETE	/api/admin/bans/:ip
系统总览	GET	/api/admin/analytics/overview
用户用量	GET	/api/admin/analytics/users
搜索命中率	GET	/api/admin/analytics/hit-rate
审计日志	GET	/api/admin/audit/logs
导出日志	GET	/api/admin/audit/export
运行时配置	GET/PATCH	/api/admin/config

---

环境变量

.env.example 是当前仓库对外公开的权威配置模板。

新增配置项会优先落在 .env.example，再同步到本表和部署示例。

变量	默认值	说明
EASY_MEMORY_MODE	mcp	运行模式：mcp / http
QDRANT_URL	http://localhost:6333	Qdrant 连接地址
QDRANT_API_KEY	easy-memory-dev	Qdrant API Key
EMBEDDING_PROVIDER	ollama	Embedding 引擎：ollama / gemini / openai / auto / openai-auto；自托管默认走本地 Ollama，如需推荐远端方案请显式设置 openai-auto
OLLAMA_BASE_URL	http://localhost:11434	Ollama 地址
OLLAMA_MODEL	bge-m3	Ollama 模型名（1024 维）
OLLAMA_TIMEOUT_MS	120000	Ollama 请求超时（ms），首次加载模型需较长时间
OPENAI_EMBEDDING_API_KEY	—	官方 OpenAI 向量模型 relay 的 API Key（openai/openai-auto 模式必填）
OPENAI_EMBEDDING_BASE_URL	https://api.vectorengine.ai/v1	relay base URL 或完整 /embeddings 端点
OPENAI_EMBEDDING_MODEL	text-embedding-3-small	默认官方向量模型名（请求时自动带 dimensions=1024）
GEMINI_API_KEY	—	Google Cloud Vertex AI API Key（gemini/auto 模式必填）
GEMINI_PROJECT_ID	—	Google Cloud Project ID（gemini/auto 模式必填）
GEMINI_REGION	us-central1	Google Cloud Vertex AI 区域
GEMINI_MODEL	gemini-embedding-001	Gemini Embedding 模型
DEFAULT_PROJECT	default	默认项目标识
HTTP_PORT	3080	HTTP Shell 监听端口
HTTP_HOST	127.0.0.1	HTTP Shell 监听地址
HTTP_AUTH_TOKEN	—	HTTP API Bearer Token
TRUST_PROXY	false	信任反向代理 X-Forwarded-* 头
REQUIRE_TLS	false	拒绝非 HTTPS 请求（需 TRUST_PROXY=true）
ADMIN_TOKEN	—	Admin API Token（留空则禁用管理后台）
ADMIN_USERNAME	—	Admin 用户名 — 首次启动时自动创建管理员账户
ADMIN_PASSWORD	—	Admin 密码 — 与 ADMIN_USERNAME 配合使用
DATA_DIR	$HOME	数据文件存储目录（Docker 中设为 /data 并挂载 Volume）
RATE_LIMIT_PER_MINUTE	60	全局速率限制（次/分钟）
GEMINI_MAX_PER_HOUR	200	Gemini 每小时最大调用数
GEMINI_MAX_PER_DAY	2000	Gemini 每日最大调用数
EASY_MEMORY_TOKEN	—	远程代理模式：API Key（设置后启用远程代理，跳过本地服务）
EASY_MEMORY_URL	—	远程代理模式：远端 Easy Memory 服务 URL

---

⚠️ Breaking Changes (v0.2.0)

Vertex AI 迁移：GEMINI_PROJECT_ID 新增必填

从 v0.2.0 起，Gemini Embedding 已从 Generative Language API (generativelanguage.googleapis.com) 迁移至 Vertex AI (aiplatform.googleapis.com)。

影响范围： 使用 EMBEDDING_PROVIDER=gemini 或 EMBEDDING_PROVIDER=auto 的所有部署。

必须操作：

1. 新增环境变量 GEMINI_PROJECT_ID（Google Cloud 项目 ID）
2. 可选设置 GEMINI_REGION（默认 us-central1）
3. 确保 GEMINI_API_KEY 有 Vertex AI 权限

# .env 变更示例
EMBEDDING_PROVIDER=gemini          # 或 auto
GEMINI_API_KEY=your-api-key        # 无变化
GEMINI_PROJECT_ID=my-gcp-project   # ⬅️ 新增必填
GEMINI_REGION=us-central1          # 可选，默认 us-central1

纯 Ollama 用户仍可继续使用（显式设置 EMBEDDING_PROVIDER=ollama 即可）。

---

开发

pnpm install          # 安装依赖
pnpm build            # TypeScript 编译
pnpm typecheck        # 类型检查
pnpm test             # 单元测试 (940+ tests)
pnpm verify:local     # 本地提交前快速校验 (typecheck + test)
pnpm build:web        # 构建 Web UI 前端
pnpm build:all        # 构建后端 + 前端
pnpm dev:web          # 前端开发模式 (HMR)
pnpm test:e2e         # E2E 测试 (需要 Qdrant + Ollama)

项目结构

src/
├── index.ts              # 入口 — 双模式路由
├── container.ts          # 依赖注入容器
├── api/                  # HTTP Shell (Hono)
│   ├── server.ts         # HTTP 路由 + 审计中间件 + SPA 静态文件
│   ├── admin-routes.ts   # Admin API (Key/Ban/Analytics/Audit/Config)
│   ├── auth-routes.ts    # Auth API (Login/Register/Users)
│   ├── admin-auth.ts     # Admin Token 鉴权
│   ├── schemas.ts
│   └── middlewares.ts    # 双层鉴权 (Master + API Key)
├── mcp/                  # MCP Shell (stdio)
│   ├── server.ts         # 本地 MCP Server (stdio + Streamable HTTP)
│   └── remote-server.ts  # 远程代理 MCP Server (EASY_MEMORY_TOKEN)
├── services/             # 核心服务
│   ├── qdrant.ts         # Qdrant 向量数据库
│   ├── embedding.ts      # Embedding 编排 (多引擎 fallback)
│   ├── embedding-providers.ts  # Ollama/Gemini/OpenAI-compatible Provider
│   ├── bm25.ts           # BM25 稀疏向量 (混合检索)
│   ├── analytics.ts      # SQLite 用量分析聚合
│   ├── audit.ts          # JSONL 审计日志 (缓冲写入)
│   ├── api-key-manager.ts # API Key 管理 (SHA-256 哈希)
│   ├── ban-manager.ts    # IP/Key 封禁
│   ├── runtime-config.ts # 运行时配置管理
│   └── auth.ts           # 用户认证 (scrypt + JWT)
├── tools/                # MCP Tool 处理器
│   ├── save.ts
│   ├── search.ts
│   ├── forget.ts
│   └── status.ts
├── transport/            # 安全 stdio 传输
│   └── SafeStdioTransport.ts
├── types/                # Schema & 类型
│   ├── schema.ts         # MCP 数据契约
│   ├── admin-schema.ts   # Admin API Schema
│   ├── audit-schema.ts   # 审计日志 Schema
│   └── auth-schema.ts    # Auth/RBAC Schema
└── utils/                # 工具
    ├── hash.ts           # SHA-256 去重
    ├── logger.ts         # stderr JSON 日志
    ├── paths.ts          # 数据文件路径管理 (DATA_DIR)
    ├── sanitize.ts       # 内容脱敏
    ├── rate-limiter.ts   # 速率限制 (全局 + Per-Key)
    ├── ip.ts             # 代理感知 IP 提取
    └── shutdown.ts       # 优雅关闭

web/ # Web UI Admin Panel (React) ├── src/ │ ├── App.tsx # 路由 + 权限守卫 │ ├── api/client.ts # API 客户端 (JWT 自动注入) │ ├── contexts/auth.tsx # Auth 上下文 │ ├── components/ # UI 组件 (Button/Card/Modal/Table...) │ └── pages/ # 页面 (Login/Dashboard/ApiKeys/Bans/ │ # Analytics/AuditLogs/Users/Settings) └── vite.config.ts # Vite 构建配置

---

## Web UI 管理面板

访问 `http://your-server:3080/` 打开 Web UI 管理面板。

### 首次设置

1. 设置环境变量创建管理员账户：
   ```bash
   ADMIN_USERNAME=your-admin-name
   ADMIN_PASSWORD=your-secure-password
   ADMIN_TOKEN=your-admin-token

2. 启动服务后通过浏览器打开 Web UI 3 使用管理员账号密码登录

功能

• Dashboard: 实时概览（请求量/成功率/延迟/系统状态）
• API Keys: 密钥管理（创建/启用/禁用/删除）
• Bans: IP/Key 封禁管理
• Analytics: 用量分析（时间线/操作分布/错误追踪）
• Audit Logs: 审计日志（分页/筛选/导出）
• Users: 用户管理（创建/角色切换/启用禁用/删除）
• Settings: 运行时配置编辑

角色权限

权限	Admin	User
用户管理	✅	❌
API Key 管理	✅	❌
Ban 管理	✅	❌
配置修改	✅	❌
分析查看	✅	✅
审计日志	✅	✅
记忆操作	✅	✅

构建

pnpm build:web    # 构建前端到 dist/web/
pnpm build:all    # 构建后端 + 前端
pnpm dev:web      # 前端开发模式 (HMR + API 代理)

---

架构文档

• FEASIBILITY-ANALYSIS.md — 架构决策记录 (ADR)
• AUDIT-LOGGING-WHITEPAPER.md — 后处理架构白皮书（鉴权·审计·管控）
• CORE_SCHEMA.md — 数据契约与绝对红线
• INTEGRATION_GUIDE.md — 多端接入与 Prompt 调教

---

License

MIT © FlippySun