Connapse

别再让 AI 会话之间丢失上下文。为你的 Agent 提供持久、可搜索的记忆。

你的 AI Agent 会在会话之间忘记一切。Connapse 可以解决这个问题。

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

📦 快速开始

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 [email protected]
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

首次运行将会：

1. 拉取 Docker 镜像（约需 2-5 分钟）
2. 使用 pgvector 扩展初始化 PostgreSQL，并运行 EF Core 迁移
3. 创建 MinIO 存储桶
4. 创建管理员账户（使用环境变量中的信息），并启动 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"

命令行客户端

connapse CLI 单独发布于 Destrayon/connapse-cli。

安装：

dotnet tool install -g Connapse.CLI
# or: download a binary from https://github.com/Destrayon/connapse-cli/releases/latest

开始使用：

connapse auth login --server https://localhost:5001
connapse --help

与 Claude（MCP）配合使用

Connapse 包含一个模型上下文协议（MCP）服务，可与 Claude 和任何 MCP 客户端集成。

设置：通过 Web UI 创建 Agent API 密钥（Settings → Agent API Keys），然后为你的客户端添加配置片段：

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

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

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

MCP 服务提供以下工具：

**完整参考：**请参阅 docs/mcp-tools.md，了解参数表、返回格式、错误情况和使用示例。

容器与来源：container_list 会为每个范围标记 managed 或 source。来源是 Connapse 以只读方式镜像的外部系统——可以搜索，但无法浏览，也无法写入。list_files 和所有写入工具只解析容器；传入来源 ID 时，它们会报告未找到。请参阅 docs/connectors.md。

🚀 功能

• 🗂️ 容器隔离的知识 — 每个项目都有自己的向量索引、存储连接器和搜索配置。不同项目、团队或客户端之间互不干扰。
• 🔍 混合搜索 — 向量相似度 + 关键词全文搜索，并支持可配置的融合方式（凸组合、DBSF、AutoCut）。获取纯向量搜索会遗漏的结果。
• 🧠 多提供商 AI — 可在 Ollama、OpenAI、Azure OpenAI 和 Anthropic 之间切换，用于嵌入和大模型；可在运行时按容器切换，无需重启。
• 🔌 为现有存储编制索引 — 连接 MinIO、本地文件系统（实时文件监控）或 Amazon S3（IAM 身份验证）。文件仍保留在原处。
• 🤖 4 种访问方式 — Web UI、REST API、CLI（原生二进制文件）和适用于 Claude 的 MCP 服务。为用户、脚本和 AI Agent 同样打造。
• 🔐 企业级身份验证 — 多层级 RBAC（Cookie + OAuth 2.1 + PAT + JWT），并支持 AWS 身份关联。配置身份关联后，将按 AWS 权限对每位用户的搜索结果进行过滤（可选；在此之前不受限制）。
• 🐳 一条命令即可部署 — 使用 Docker Compose，包含 PostgreSQL + pgvector、MinIO 和可选的 Ollama。内置结构化审计日志和速率限制。

🎯 Connapse 适合哪些人？

• AI Agent 开发者：需要一个 Agent 既能查询又能构建的知识后端 — 上传研究资料、整理语料库，并通过 MCP 或 REST API 搜索
• .NET / Azure 团队：希望 RAG 平台适配现有技术栈和云身份体系
• 企业团队：需要项目隔离的知识库，并具备完善的 RBAC 和审计跟踪
• 厌倦了反复上传文件的所有人：让 Connapse 连接现有的 Amazon S3/文件系统存储

🏗️ 架构

┌──────────────────────────────────────────────────────────────────────┐
│                         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  │                               │
└─────────────┬────────────────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────────────────┐
│                        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 Minimal APIs
• 前端：Blazor Server（交互模式）
• 嵌入：Ollama（默认）、OpenAI、Azure OpenAI（可配置）
• 大模型：Ollama、OpenAI、Azure OpenAI、Anthropic（可配置）
• 搜索：向量 + 关键词混合搜索，采用凸组合融合
• 连接器：托管存储（默认使用 MinIO）、文件系统、Amazon S3

📚 文档

• 架构指南 - 系统设计和组件概览
• API 参考 - REST API 端点和示例
• 连接器指南 - 连接器类型、配置和后台同步
• AWS 设置 - Roles Anywhere 访问、IAM Identity Center、S3 Access Grants、故障排除
• 部署指南 - Docker 和生产环境设置
• 安全策略 - 安全限制和路线图
• 贡献指南 - 如何参与贡献

🗺️ 路线图

Connapse 尚未达到 1.0 版本。重大设计工作在 Discussions 中跟踪。

v0.1.0 — 基础（已完成）

• ✅ 文档摄取管道（PDF、Office、Markdown、文本）
• ✅ 混合搜索（向量 + 关键词，采用凸组合融合）
• ✅ 带文件夹的容器文件浏览器
• ✅ Web UI、REST API、CLI、MCP 服务

v0.2.0 — 安全与身份验证（已完成）

• ✅ 三级身份验证：Cookie + 个人访问令牌 + JWT（HS256）
• ✅ 基于角色的访问控制（Admin / Editor / Viewer / Agent）
• ✅ 仅限邀请的用户注册（由管理员控制）
• ✅ 一流的 Agent 实体，具备 API 密钥生命周期管理
• ✅ Agent 管理 UI + PAT 管理 UI
• ✅ 审计日志（上传、删除、容器操作）
• ✅ CLI 身份验证命令（auth login、auth whoami、auth pat）
• ✅ GitHub Actions 发布管道（原生二进制文件 + NuGet 工具）
• ✅ 256 项测试通过（单元测试 + 集成测试）

v0.3.0 — 连接器架构（已完成）

• ✅ 3 种连接器类型：托管存储（默认使用 MinIO，提供商抽象）、文件系统（FileSystemWatcher）、Amazon S3（仅限 IAM）
• ↩️ Azure Blob Storage 连接器（托管身份）— 于 v0.3.0 发布，之后已移除（#476）：未经验证，为了干净地重建而拆除
• ✅ 按容器覆盖设置（分块、嵌入、搜索、上传）
• ↩️ 云身份关联：Azure AD（OAuth2+PKCE）— 于 v0.3.0 发布，之后与 Azure Blob 连接器一同移除（#476）
• ↩️ AWS IAM Identity Center（设备身份验证流程）— 于 v0.3.0 发布，之后已移除（#435）：设备流程无法将每个用户的身份传递到令牌中
• ⚠️ 基于 IAM 的范围强制执行 — v0.3.0 中的 CloudScopeService 已构建，但从未接入搜索（#422），之后已移除；每用户 AWS 搜索过滤已基于 ISearchScopeResolver + AWS S3 Access Grants 重建（史诗任务 #436）— 选择启用；配置 AWS 身份关联后将采用失败关闭策略
• ✅ 多提供商嵌入：Ollama、OpenAI、Azure OpenAI
• ✅ 多提供商大模型：Ollama、OpenAI、Azure OpenAI、Anthropic
• ✅ 支持多种向量维度，并为每个模型提供部分 IVFFlat 索引
• ✅ 跨模型搜索：针对旧版向量自动从语义搜索回退到混合搜索
• ✅ 后台同步：本地使用 FileSystemWatcher，云容器每 5 分钟轮询一次
• ✅ 所有提供商均支持连接测试（Amazon S3、MinIO、大模型、嵌入）
• ✅ 457 项测试通过（单元测试 + 集成测试）

v0.3.2 — 加固与完善（已完成）

• ✅ 强化输入验证：文件名长度、路径深度、控制字符、搜索参数、Agent 字段
• ✅ 安全修复：空 API 密钥导致的身份验证绕过、路径遍历、安全标头中间件
• ✅ 统一上传管道（IUploadService），供 API 和 MCP 共用
• ✅ 上传文件类型允许列表
• ✅ 速率限制中间件（按用户和按 IP）
• ✅ 批量 MCP 工具：bulk_upload 和 bulk_delete
• ✅ CLI 改进：files 命令、container stats、--pre 更新、--help 标志
• ✅ 使用自托管字体（不依赖 CDN）
• ✅ 在 ghcr.io 发布 Docker 软件包

未来计划

• v0.4.0：通信连接器（Slack、Discord）。（按用户划分的 AWS 搜索权限——史诗任务 #436，通过 IAM Identity Center SAML 身份关联实现，而非 Cognito——已发布。）
• v0.5.0：知识平台连接器（Notion、Confluence、GitHub）
• v1.0.0：可用于生产环境的稳定版本

❓ 常见问题

Connapse 需要访问互联网吗？ — 不需要。使用 Ollama 即可完全离线地生成嵌入并进行搜索。

它能处理多少文档？ — 每个容器可处理数千份文档。基于 PostgreSQL + pgvector 构建。

哪些 MCP 客户端可与 Connapse 配合使用？ — 任何支持 Streamable HTTP 传输的客户端都可以，例如 Claude Desktop、Claude Code、VS Code、Cursor 等。

我的数据是私密的吗？ — 完全可自托管。使用 Ollama 时，任何数据都不会离开你的设备。云服务提供商（OpenAI、Azure）为可选项。

支持哪些嵌入提供商？ — Ollama（本地）、OpenAI 和 Azure OpenAI。无需重新部署即可在运行时切换。

🤝 参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

快速贡献清单：

• Fork 此仓库并创建功能分支
• 遵循 CONTRIBUTING.md 中的代码规范
• 为新功能编写测试（xUnit + FluentAssertions）
• 确保所有测试通过：dotnet test
• 如有需要，更新文档
• 提交拉取请求

适合新手的首批问题：查看标记为 good-first-issue 的问题

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE。

你可以自由：

• ✅ 用于商业用途
• ✅ 修改
• ✅ 分发
• ✅ 再许可
• ✅ 私下使用

唯一的要求是在软件的任何重要部分中包含版权声明和许可证。

💬 支持与社区

• 📖 文档：docs/
• 🐛 错误报告：GitHub Issues
• 💡 功能请求：GitHub Discussions
• 🔒 安全问题：请参阅 SECURITY.md

🙏 致谢

本项目基于以下技术构建：

• .NET - 应用框架
• Blazor - Web UI
• PostgreSQL + pgvector - 向量数据库
• MinIO - 兼容 S3 的对象存储
• Ollama - 本地大模型推理

⭐ 如果你觉得这个项目有用，请为仓库点星以表达支持！