potluck (Double Gremlin181)

百乐餐

个人知识数据库MCP服务器 -使用Google Takeout、GDPR导出等对您的AI助手进行个性化设置。

\[！警告\] 该项目正在积极开发中。尚未准备好用于生产。

概述

Potluck是一个隐私优先的个人知识管理系统，它：

• 摄入 来自Google Takeout、Reddit GDPR导出、WhatsApp、YNAB等的数据
• 重复数据删除 对媒体使用感知哈希，对文本使用内容哈希
• 链接 通过时间、空间和语义关系跨源实体
• 暴露 通过模型上下文协议（MCP）将数据传输到LLM
• 保持 所有数据本地-没有用于嵌入或处理的外部API调用

特性

• 源不可知实体：聊天消息模型适用于WhatsApp、Telegram、SMS等。
• 混合搜索：将PostgreSQL全文搜索（关键字）与pgvector相似性（语义）相结合
• 人脸识别：通过自动聚类将照片链接到人（谷歌照片风格）
• 图像字幕：AI为图像生成alt文本描述
• 多个嵌入：支持每个实体的不同嵌入类型（文本、多模式）
• 网页用户界面：通过FastAPI+HTMX接口查看、搜索和管理您的数据

技术栈

• Python 3.12+ 使用FastAPI、SQLModel、Celery
• PostgreSQL 带有pgvector和pg_tde加密的（Percona风味）
• e5-small-v2 用于文本嵌入（通过句子转换）
• SigLIP 用于多模态嵌入（文本到图像搜索）
• EasyOCR 用于图像文本提取
• MTCNN+ArcFace 用于人脸检测和嵌入
• BLIP-2 用于AI图像字幕
• Docker Compose 便于部署

安装

快速安装（推荐）

只需一个命令即可安装并运行Potluck：

curl -fsSL https://raw.githubusercontent.com/DoubleGremlin181/potluck/main/scripts/install.sh | bash

这将：

• 创建 ~/.potluck/ 包含所有配置文件
• 生成安全的数据库凭据
• 拉取并启动所有Docker容器
• 运行数据库迁移
• 打印Claude Desktop的MCP配置

支持GPU （需要NVIDIA GPU+NVIDIA容器工具包）：

curl -fsSL https://raw.githubusercontent.com/DoubleGremlin181/potluck/main/scripts/install.sh | bash -s -- --gpu

安装后：

• 网页用户界面: http://localhost:8000
• 日志: cd ~/.potluck && docker compose logs -f
• 停止: cd ~/.potluck && docker compose down

开发设置

对于想要修改代码的贡献者：

git clone https://github.com/DoubleGremlin181/potluck.git
cd potluck
./scripts/setup.sh        # Start all services
# or
./scripts/setup.sh --db-only  # Start only DB, run app locally with: uv run potluck web

密钥管理

Potluck使用 pg_tde 用于透明数据加密。所有数据库表都是静态加密的。

开发（基于文件的密钥）

默认情况下，加密密钥存储在本地文件中。这是 仅适用于开发:

# Default setup uses file-based keys
./scripts/setup.sh

您将看到一个警告：

⚠️  SECURITY WARNING: Using file-based encryption keys

生产（HashiCorp保险库）

对于生产，配置 HashiCorp 保险库 作为密钥提供者：

1. 设置保险库 使用KV v2 secrets引擎：

   # Enable KV v2 secrets engine (if not already enabled)
   vault secrets enable -path=secret kv-v2

1. 配置Potluck 使用Vault凭据：

   # Option 1: Interactive setup
   ./scripts/setup.sh
   # When prompted, enter your Vault URL and token

   # Option 2: Manual configuration in .env
   VAULT_URL=https://vault.example.com:8200
   VAULT_TOKEN=your-vault-token
   VAULT_MOUNT=secret

1. 重新开始 （切换密钥提供者时需要）：

   docker compose down -v
   ./scripts/setup.sh

其他关键管理系统

pg_tde还支持KMIP兼容的KMS提供商（AWS KMS、Azure密钥库等）。请参阅 pg_tde文档 有关配置详细信息。

测试

所有测试都在Docker中运行，以确保本地开发和CI之间的一致性。

# Run all tests
docker compose --profile test run --rm test

# Run specific test file
docker compose --profile test run --rm test uv run pytest tests/unit/models/ -v

# Run with e2e tests (database integration)
docker compose --profile test run --rm test uv run pytest tests/ -v --run-e2e

GitHub Actions使用与 test 轮廓。

测试验证：

• Docker容器正确启动（使用pgvector+pg_tde的Percona PostgreSQL 17）
• PostgreSQL扩展已安装（vector、pg_tde、uuid ossp）
• 所有表都是在启用pg_tde加密的情况下创建的
• Alembic迁移成功运行
• 机器学习处理（OCR、人脸检测、字幕）工作正常

用法

MCP服务器（用于克劳德桌面）

添加到您的Claude桌面配置(claude_desktop_config.json):

{
  "mcpServers": {
    "potluck": {
      "command": "docker",
      "args": ["exec", "-i", "potluck-app", "potluck", "mcp"]
    }
  }
}

安装脚本会自动打印此配置。

网页用户界面

访问http://localhost:8000安装后。

项目结构

potluck/
├── src/potluck/
│   ├── core/          # Config, logging, Celery, exceptions
│   ├── models/        # SQLModel entities
│   ├── pipeline/      # Ingestion + processing pipeline
│   │   ├── ingestion/ # Source-specific data importers
│   │   ├── processing/# OCR, hashing, faces, captioning
│   │   ├── tasks/     # Celery background tasks
│   │   └── utils/     # Archive extraction, parsers
│   ├── embeddings/    # Embedding providers
│   ├── search/        # Hybrid search implementation
│   ├── linkers/       # Entity relationship detection
│   ├── mcp/           # MCP server and tools
│   ├── web/           # FastAPI + HTMX web UI
│   └── db/            # Database session management
├── alembic/           # Database migrations
├── tests/             # Unit and integration tests
├── scripts/           # Setup and utility scripts
└── docker/            # Dockerfiles for app and database

许可证

MIT许可证-请参阅 许可证 了解详情。