你的 AI 智能体在每次会话之间都会遗忘一切。Connapse 解决了这个问题。

每当你开始一段新的对话，你的 AI 智能体都是从零开始的——没有过去研究的记忆，无法访问你的文档，也没有积累的知识。Connapse 是一个开源的知识后端，为智能体提供持久、可搜索的记忆。上传文档，或将其指向你现有的 Amazon S3 存储桶、Azure Blob 存储容器或本地文件系统。智能体可以通过 11 个 MCP 工具、REST API 或 CLI 查询并构建自己的研究语料库。容器隔离、混合搜索（向量+关键词）、自托管且私密。使用 Docker 60 秒即可部署。基于 .NET 10 构建。

AI 智能体通过 MCP 服务器查询你的知识库，并接收带有文档来源引用的结构化答案。

切换嵌入提供程序、调整分块参数并配置搜索——所有操作均在运行时完成，无需重启。

📦 快速开始

git clone https://github.com/Destrayon/Connapse.git && cd Connapse && docker-compose up -d
# Open http://localhost:5001

先决条件

Docker 和 Docker Compose
.NET 10 SDK (用于开发)
(可选) Ollama 用于本地嵌入

使用 Docker Compose 运行

# Clone the repository
git clone https://github.com/Destrayon/Connapse.git
cd Connapse

# Set required auth environment variables (or use a .env file)
export CONNAPSE_ADMIN_EMAIL=admin@example.com
export CONNAPSE_ADMIN_PASSWORD=YourSecurePassword123!
export Identity__Jwt__Secret=$(openssl rand -base64 64)

# Start all services (PostgreSQL, MinIO, Web App)
docker-compose up -d

# Open http://localhost:5001 — log in with the admin credentials above

首次运行将：

拉取 Docker 镜像（约 2-5 分钟）
初始化带有 pgvector 扩展的 PostgreSQL 并运行 EF Core 迁移
创建 MinIO 存储桶
播种管理员账户（来自环境变量）并启动 Web 应用程序

开发设置

# Start infrastructure only (database + object storage)
docker-compose up -d postgres minio

# Run the web app locally
dotnet run --project src/Connapse.Web

# Run all tests
dotnet test

# Run just unit tests
dotnet test --filter "Category=Unit"

使用 CLI

安装 CLI（选择一种方式）：

# Option A: .NET Global Tool (requires .NET 10)
dotnet tool install -g Connapse.CLI

# Option B: Download native binary from GitHub Releases (no .NET required)
# https://github.com/Destrayon/Connapse/releases

基本用法：

# Authenticate first
connapse auth login --url https://localhost:5001

# Create a container (project)
connapse container create my-project --description "My knowledge base"

# Upload files
connapse upload ./documents --container my-project

# Search
connapse search "your query" --container my-project

# Update to latest release (--pre to include alpha/pre-release builds)
connapse update
connapse update --pre

与 Claude (MCP) 一起使用

Connapse 包含一个模型上下文协议 (MCP) 服务器，用于与 Claude 和任何 MCP 客户端集成。

设置：通过 Web UI（设置 → 智能体 API 密钥）或 CLI (connapse auth agent-key create) 创建智能体 API 密钥，然后为你的客户端添加配置片段：

claude mcp add connapse --transport streamable-http http://localhost:5001/mcp --header "X-Agent-Api-Key: YOUR_API_KEY"

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "connapse": {
      "transport": "streamable-http",
      "url": "http://localhost:5001/mcp",
      "headers": {
        "X-Agent-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

添加到你的 .vscode/settings.json (VS Code) 或 Cursor MCP 配置中：

{
  "mcp": {
    "servers": {
      "connapse": {
        "transport": "streamable-http",
        "url": "http://localhost:5001/mcp",
        "headers": {
          "X-Agent-Api-Key": "${input:connapseApiKey}"
        }
      }
    }
  }
}

VS Code 将在首次使用时提示输入 API 密钥。

MCP 服务器公开了 11 个工具：

工具	描述
`container_create`	创建一个用于组织文件的新容器
`container_list`	列出所有带有文档计数的容器
`container_delete`	删除一个容器
`container_stats`	获取容器统计信息（文档、分块、存储、嵌入）
`upload_file`	将单个文件上传到容器
`bulk_upload`	在一次操作中上传最多 100 个文件
`list_files`	列出路径下的文件和文件夹
`get_document`	检索文档的完整解析文本内容
`delete_file`	从容器中删除单个文件
`bulk_delete`	在一次操作中删除最多 100 个文件
`search_knowledge`	在容器内进行语义、关键词或混合搜索

完整参考：请参阅 docs/mcp-tools.md 获取参数表、返回格式、错误案例和使用示例。

写入保护：Amazon S3 和 Azure Blob 存储容器是只读的（从源同步）。文件系统容器遵循每个容器的权限标志。如果容器阻止写入，上传和删除工具将返回错误。

“创建一个名为 'project-research' 的容器，用于存放我的架构笔记”
“将我下载文件夹中的所有 PDF 上传到 project-research 容器”
“在我的 project-research 容器中搜索关于限流策略的信息”
“列出我 project-research 容器中 /notes/ 文件夹下的所有文件”
“获取 project-research 中 distributed-systems-notes.md 的全文”
“从 project-research 中删除 meeting-2026-03-14.md 并上传此更新版本”
“删除 project-research 中 /drafts/ 文件夹下的所有文件”
“我的 project-research 容器中有多少文档和分块？”

Connection refused on localhost:5001 — Docker 未运行或端口冲突。检查 docker compose ps 和 docker compose logs web。

401 Unauthorized / API 密钥无效 — 在“设置 > 智能体 API 密钥”中验证密钥。密钥仅在创建时显示一次。

工具未在 Claude 中显示 — 配置更改后重启你的 MCP 客户端。使用 curl http://localhost:5001/mcp 验证端点。

上传失败或超时 — 检查文件类型是否在允许列表中。最大文件大小取决于服务器配置。

搜索无结果 — 文档上传后需要时间进行嵌入。检查容器统计信息以查看嵌入进度。

🚀 功能

🗂️ 容器隔离知识 — 每个项目都有自己的向量索引、存储连接器和搜索配置。项目、团队或客户之间不会交叉污染。
🔍 混合搜索 — 向量相似度 + 关键词全文搜索，支持可配置的融合（凸组合、DBSF、AutoCut）。获取纯向量搜索无法找到的结果。
🧠 多提供程序 AI — 在运行时，按容器切换 Ollama、OpenAI、Azure OpenAI 和 Anthropic，用于嵌入和 LLM，无需重启。
🔌 索引现有存储 — 连接 MinIO、本地文件系统（实时文件监控）、Amazon S3 (IAM 认证) 或 Azure Blob 存储（托管身份）。你的文件保持原位。
🤖 4 种访问界面 — Web UI、REST API、CLI（原生二进制文件）和 MCP 服务器（为 Claude 提供 11 个工具）。专为人类、脚本和 AI 智能体打造。
🔐 企业级认证 — 多层 RBAC（Cookie + OAuth 2.1 + PAT + JWT），支持 AWS IAM Identity Center 和 Azure AD 身份链接。云权限是事实来源。
🐳 一键部署 — Docker Compose 包含 PostgreSQL + pgvector、MinIO 和可选的 Ollama。内置结构化审计日志和限流功能。

📄 多格式摄入：PDF、Office 文档、Markdown、纯文本 — 自动解析、分块和嵌入
⚡ 实时处理：通过 SignalR 进行后台摄入并实时更新进度
🎛️ 运行时配置：无需重启即可更改每个容器的分块策略、嵌入模型和搜索设置
☁️ 云身份链接：AWS IAM Identity Center (设备认证流程) + Azure AD (OAuth2+PKCE)，并强制执行 IAM 派生范围
👥 仅限邀请访问：管理员控制的用户注册，具有四种角色（管理员/编辑者/查看者/智能体）
🤖 智能体管理：专用的智能体实体，具有 API 密钥生命周期、范围权限和审计追踪
📋 审计日志：针对上传、删除、容器操作和认证事件的结构化审计追踪
📦 CLI 分发：原生自包含二进制文件（Windows/Linux/macOS）以及通过 NuGet 提供的 .NET 全局工具
🔄 跨模型搜索：项目进行中切换嵌入模型 — 自动为旧向量提供语义→混合回退

🎯 Connapse 适合谁？

AI 智能体开发者：需要一个智能体既能查询又能构建的知识后端 — 上传研究资料、策划语料库，并通过 MCP 或 REST API 进行搜索
.NET / Azure 团队：需要一个符合现有技术栈和云身份的 RAG 平台
企业团队：需要具有适当 RBAC 和审计追踪的项目隔离知识库
厌倦了重复上传文件的人 — 将 Connapse 指向你现有的 Amazon S3/Azure Blob 存储/文件系统存储

本项目处于积极开发阶段 (v0.3.2)，即将达到生产就绪状态。

v0.3.x 增加了基于 IAM 访问控制的云连接器架构、多提供程序嵌入和 LLM 支持、云身份链接 (AWS SSO + Azure AD) 以及限流功能。

✅ 认证和授权 (v0.2.0)
✅ 基于角色的访问控制 (管理员/编辑者/查看者/智能体)
✅ 审计日志
✅ 云身份链接 — AWS IAM Identity Center + Azure AD OAuth2+PKCE (v0.3.0)
✅ IAM 派生范围强制执行 — 云权限是事实来源 (v0.3.0)
✅ 限流 — 内置 ASP.NET Core 中间件，具有针对用户和 IP 的策略 (v0.3.2)
⚠️ 在生产环境中设置强 Identity__Jwt__Secret — 请参阅部署指南

请参阅 SECURITY.md 获取完整的安全策略。

🏗️ 架构

┌──────────────────────────────────────────────────────────────────────┐
│                         Access Surfaces                              │
│  Web UI (Blazor)  │  REST API  │  CLI  │  MCP Server                │
└─────────────┬────────────────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────────────────┐
│                       Core Services Layer                            │
│  Document Store  │  Vector Store  │  Search  │  Ingestion           │
└─────────────┬────────────────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────────────────┐
│                        Connectors Layer                              │
│  MinIO  │  Filesystem  │  Amazon S3  │  Azure Blob Storage          │
└─────────────┬────────────────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────────────────┐
│                        Infrastructure                                │
│  PostgreSQL+pgvector  │  MinIO (S3)  │  Ollama (optional)           │
└──────────────────────────────────────────────────────────────────────┘

数据流：上传 → 搜索

[Upload] → [Parse] → [Chunk] → [Embed] → [Store] → [Searchable]
              ↓
         [Metadata]
              ↓
        [Document Store]

目标：从上传到可搜索 < 30 秒。

关键技术：

数据库：PostgreSQL 17 + pgvector 用于向量嵌入
对象存储：托管存储抽象 — 默认为 MinIO (S3 兼容)，可按部署覆盖
后端：ASP.NET Core 10 最小 API
前端：Blazor Server (交互模式)
嵌入：Ollama (默认)、OpenAI、Azure OpenAI (可配置)
LLM：Ollama、OpenAI、Azure OpenAI、Anthropic (可配置)
搜索：混合向量 + 关键词，带有凸组合融合
连接器：托管存储 (默认 MinIO)、文件系统、Amazon S3、Azure Blob 存储

📚 文档

架构指南 - 系统设计和组件概述
API 参考 - REST API 端点和示例
连接器指南 - 连接器类型、配置和后台同步
AWS SSO 设置 - AWS IAM Identity Center 集成
Azure 身份设置 - Azure AD OAuth2+PKCE 集成
部署指南 - Docker 和生产环境设置
安全策略 - 安全限制和路线图
贡献指南 - 如何贡献

🗺️ 路线图

Connapse 处于 1.0 版本之前。主要设计工作在 Discussions 中跟踪。

v0.1.0 — 基础 (已完成)

✅ 文档摄入管道 (PDF, Office, Markdown, 文本)
✅ 混合搜索 (向量 + 关键词，带有凸组合融合)
✅ 带有文件夹的基于容器的文件浏览器
✅ Web UI, REST API, CLI, MCP 服务器

v0.2.0 — 安全与认证 (已完成)

✅ 三层认证：Cookie + 个人访问

Connapse