Heimdall Bridge

海姆达尔记忆桥

版本： 1.1.0\ 更新： 2025年10月18日

1) 它是什么

一个作为（某种功能或服务）的微型FastAPI服务 认证的外观/立面 在您的MCP沙盒（或任何兼容的API）前面提供：

• /note， /batch 将备注附加到持久内存中
• /notes → 读取存储的内存
• /timeline (GET/POST) → 简单的时间戳事件日志
• /health 快速状态代理

它专为……设计 家庭实验室使用本地化、快速且易于部署。

2) 它不是什么

• 这不是数据库的替代品。它仅存储简单的JSON数据，并将其转发给您的MCP（管理控制面板/主控程序等，具体含义根据上下文确定）。
• 这不是一个面向互联网的产品。除非你增加了更强的身份验证，否则请仅在局域网内使用。
• 不依赖于单一后端。它会与您提供的任意MCP基础URL进行通信。

3) 你需要什么

• 在Linux上运行Python 3.10+（已在Fedora/RHEL系列上测试过）
• pip 和 venv
• 一个运行中的、兼容MCP的服务器（例如，您的FastAPI沙箱），其端点类似于：

- GET /health - GET /memory/read - POST /memory/write

• 如果MCP（可能是指某种服务或系统组件）通过带有私有CA（证书颁发机构）的TLS（传输层安全协议）进行通信，请将您的CA证书安装到系统证书包中，并进行设置 VERIFY 因此（建议： /etc/pki/tls/certs/ca-bundle.crt）。

4) 安装

sudo install -d -m 0755 /srv/heimdall-bridge/app /srv/heimdall-bridge/scripts
sudo cp -r app scripts systemd .env.sample .gitignore README.md /srv/heimdall-bridge/

cd /srv/heimdall-bridge
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install fastapi uvicorn[standard] requests
deactivate

sudo cp /srv/heimdall-bridge/.env.sample /etc/sysconfig/heimdall-bridge.env
sudo nano /etc/sysconfig/heimdall-bridge.env

sudo cp systemd/heimdall-bridge.service /etc/systemd/system/
sudo cp systemd/heimdall-bridge-heartbeat.service /etc/systemd/system/
sudo cp systemd/heimdall-bridge-heartbeat.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now heimdall-bridge.service
sudo systemctl enable --now heimdall-bridge-heartbeat.timer

5) 使用示例

健康

curl -sS -H "Authorization: Bearer $API_TOKEN" http://127.0.0.1:9091/health | jq .

添加一条备注

curl -sS -X POST http://127.0.0.1:9091/note   -H "Authorization: Bearer $API_TOKEN"   -H "Content-Type: application/json"   -d '{"text":"deploy: build 42 OK"}' | jq .

添加多个备注

curl -sS -X POST http://127.0.0.1:9091/batch   -H "Authorization: Bearer $API_TOKEN"   -H "Content-Type: application/json"   -d '{"notes":["forge: queued job 5","market: sold board"],"updated_by":"heimdall"}' | jq .

读取内存

curl -sS -H "Authorization: Bearer $API_TOKEN" http://127.0.0.1:9091/notes | jq .

时间线添加 + 阅读

TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -sS -X POST http://127.0.0.1:9091/timeline   -H "Authorization: Bearer $API_TOKEN"   -H "Content-Type: application/json"   -d "{"note":"manual heartbeat","by":"cli","ts":"$TS"}" | jq .

curl -sS -H "Authorization: Bearer $API_TOKEN" http://127.0.0.1:9091/timeline | jq .

6) 可选：通过Apache使用HTTPS发布

如果你的家用实验室已经安装了带有TLS的Apache，你可以将代理设置为反向代理桥接：

  ProxyPass        http://127.0.0.1:9091/
  ProxyPassReverse http://127.0.0.1:9091/
  RequestHeader set X-Forwarded-Proto "https"
  RequestHeader set X-Forwarded-Port  "443"

然后测试：

curl -ks -H "Authorization: Bearer $API_TOKEN" https://your-host/bridge/health | jq .

7) 安全提示

• 保持桥梁与（某物）的绑定 127.0.0.1 并且仅通过您的TLS反向代理进行发布。
• 旋转 API_TOKEN 定期地。
• 治疗；对待；款待 timeline.json 并且MCP内存非常敏感；请安全备份。

______________________________________________________________________

麻省理工学院许可证