commune-dev/commune

# Commune 后端 面向 AI 智能体的开源邮件基础设施。以编程方式接收、发送和处理邮件，内置安全性、加密和送达管理功能。 **[架构](./ARCHITECTURE.md)** · **[API 参考](./docs/PUBLIC_API.md)** · **[安全性](./docs/security/)** ## 功能介绍 Commune 为 AI 智能体系统处理完整的邮件生命周期： - **入站处理** — 通过 Resend webhooks 接收邮件，具备垃圾邮件检测、提示词注入分析、附件扫描和结构化数据提取功能 - **出站发送** — 发送邮件时自动处理线程、收件人验证、抑制列表管理以及符合 RFC 标准的邮件头 - **送达追踪** — 处理退信、投诉和送达事件，并自动管理抑制列表 - **Webhook 转发** — 将处理后的邮件投递到您的端点，支持 HMAC-SHA256 签名、指数退避重试和熔断器 - **静态加密** — 对所有邮件内容、主题、参与者和附件使用 AES-256-GCM 字段级加密 - **实时通知** — 向已连接的仪表盘客户端推送 WebSocket 消息 ## 前置条件 - **Node.js** 18+ - **MongoDB** (本地或托管 — 例如 MongoDB Atlas) - **Resend 账户**，包含 API 密钥和至少一个已验证的域名 - **Redis** (可选 — 回退到内存模式用于速率限制和缓存) ## 快速开始 ### 1. 克隆并安装 ``` cd backend npm install ``` ### 2. 配置环境 ``` cp .env.example .env ``` 编辑 `.env` 文件并填入您的值。最少需要配置的变量： ``` # Database MONGO_URL=mongodb://localhost:27017/commune # Email provider RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # Authentication (generate a strong random string, ≥32 chars) JWT_SECRET=your-secure-random-string-at-least-32-characters # Encryption at rest (generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))") EMAIL_ENCRYPTION_KEY=64-hex-character-key-here # Public URL for webhook callbacks PUBLIC_WEBHOOK_BASE_URL=https://your-backend-url.com # Frontend URL (for email verification links) FRONTEND_BASE_URL=http://localhost:3000 ``` ### 3. 运行 ``` # Development (with hot reload via ts-node) npm run dev # Production npm run build npm start ``` 服务器将在端口 8000 上启动 (可通过 `PORT` 配置)。 ### 4. 验证 ``` curl http://localhost:8000/health # {"status":"ok"} ``` ## API 结构 后端提供两组 API 接口： ### 仪表盘 API (`/api/*`) 由前端仪表盘使用。通过 JWT 认证 (来自 `/auth/signin` 的 Bearer token)。 | Endpoint | Purpose | |----------|---------| | `POST /auth/signup` | 创建组织 + 用户，发送验证邮件 | | `POST /auth/verify` | 使用 token 验证邮箱 | | `POST /auth/signin` | 登录，返回 JWT | | `POST /api/domains` | 创建域名 | | `POST /api/domains/:id/verify` | 验证域名 DNS 记录 | | `POST /api/domains/:id/inboxes` | 在域名上创建收件箱 | | `POST /api/email/send` | 发送邮件 | | `GET /api/messages` | 查询消息 | ### 公共 API (`/v1/*`) 由 SDK 和外部集成使用。通过 API 密钥认证 (创建密钥时获取的 Bearer token)。 | Endpoint | Purpose | |----------|---------| | `POST /v1/messages/send` | 发送邮件 | | `GET /v1/threads` | 列出会话线程 | | `GET /v1/threads/:id/messages` | 获取线程中的消息 | | `GET /v1/domains` | 列出域名 | | `POST /v1/domains/:id/inboxes` | 创建收件箱 | | `GET /v1/delivery/metrics` | 投递统计 | | `GET /v1/delivery/events` | 投递事件历史 | | `GET /v1/search` | 跨消息的语义搜索 | 完整 API 参考请参阅 [docs/PUBLIC_API.md](./docs/PUBLIC_API.md)。 ## 域名设置 1. 创建域名：使用 `{ "name": "mail.yourdomain.com" }` 调用 `POST /api/domains` 2. 响应中包含需要在 DNS 提供商处添加的 DNS 记录 (MX, SPF, DKIM) 3. 验证：调用 `POST /api/domains/:id/verify` — 检查 DNS 传播情况 4. 创建收件箱：使用 `{ "localPart": "support", "displayName": "Support Agent" }` 调用 `POST /api/domains/:id/inboxes` 现在，发送至 `support@mail.yourdomain.com` 的入站邮件将被处理并转发至您的 webhook 端点。 ## Webhook 集成 为您的收件箱配置 webhook 以接收处理后的邮件： ``` POST /api/domains/:domainId/inboxes/:inboxId/webhook { "endpoint": "https://your-app.com/webhooks/email" } ``` 每封入站邮件都会作为带签名的 POST 请求投递到您的端点，包含以下标头： | Header | Value | |--------|-------| | `x-commune-signature` | `v1={HMAC-SHA256(secret, "{timestamp}.{body}")}` | | `x-commune-timestamp` | Unix 毫秒时间戳 | | `x-commune-delivery-id` | 唯一投递 ID | | `x-commune-attempt` | 尝试次数 (1-8) | 请求载荷包含完整的消息、附件元数据、垃圾邮件分析和提示词注入分析。验证示例请参阅 [docs/security/webhook-signatures.md](./docs/security/webhook-signatures.md)。 ## 结构化数据提取 使用 AI 从邮件中提取结构化 JSON 数据。在您的收件箱上配置 JSON Schema： ``` PUT /api/domains/:domainId/inboxes/:inboxId/extraction-schema { "name": "invoice_extraction", "description": "Extract invoice details from emails", "enabled": true, "schema": { "type": "object", "properties": { "invoiceNumber": { "type": "string" }, "amount": { "type": "number" }, "dueDate": { "type": "string" } }, "required": ["invoiceNumber", "amount"] } } ``` 提取的数据会出现在 webhook 载荷的 `extractedData` 字段中，以及存储消息的 `metadata.extracted_data` 字段下。提取功能具备会话感知能力 —— 它使用完整的线程上下文来处理多轮邮件链。需要在环境中配置 `AZURE_OPENAI_ENDPOINT`、`AZURE_OPENAI_API_KEY` 和 `AZURE_OPENAI_DEPLOYMENT`。 ## 安全性 安全性架构在 [ARCHITECTURE.md](./ARCHITECTURE.md) 中有详细记录。主要亮点包括： - **静态加密** — AES-256-GCM 字段级加密，支持密钥轮换和三层密钥保护 (指纹锁、解密金丝雀、启动熔断) - **入站威胁检测** — 5 层垃圾邮件检测、提示词注入分析 (5 个信号类别)、ClamAV + 启发式附件扫描 - **送达保护** — 每个组织的发送健康熔断器 (退信/投诉率监控)、14 天域名预热计划、自动抑制列表管理 - **API 安全** — Bcrypt 哈希 API 密钥、JWT 认证、滑动窗口速率限制 (Redis + Lua)、带自动过期的审计日志 - **传输安全** — HSTS、通过 Helmet 的安全标头、Svix webhook 签名验证、带时间安全比较的 HMAC 签名出站 webhooks 有关每个安全子系统的详细文档，请参阅 [docs/security/](./docs/security/) 目录。 ## 环境变量 | Variable | Required | Description | |----------|----------|-------------| | `MONGO_URL` | 是 | MongoDB 连接字符串 | | `RESEND_API_KEY` | 是 | Resend API 密钥 | | `JWT_SECRET` | 是 (生产环境) | JWT 签名密钥 (≥32 字符) | | `EMAIL_ENCRYPTION_KEY` | 是 (生产环境) | 用于 AES-256-GCM 的 64 个十六进制字符 | | `PUBLIC_WEBHOOK_BASE_URL` | 是 | 用于 Resend webhook 回调的公开 URL | | `FRONTEND_BASE_URL` | 是 | 用于验证邮件的前端 URL | | `REDIS_URL` | 否 | 用于速率限制的 Redis (回退到内存模式) | | `AZURE_OPENAI_ENDPOINT` | 否 | 用于结构化提取的 Azure OpenAI | | `AZURE_OPENAI_API_KEY` | 否 | Azure OpenAI 密钥 | | `AZURE_OPENAI_DEPLOYMENT` | 否 | Azure OpenAI 部署名称 | | `CLOUDINARY_CLOUD_NAME` | 否 | 用于附件存储的 Cloudinary | | `CLOUDINARY_API_KEY` | 否 | Cloudinary API 密钥 | | `CLOUDINARY_API_SECRET` | 否 | Cloudinary 密钥 | | `CLAMAV_HOST` | 否 | 用于附件扫描的 ClamAV 守护进程 | | `QDRANT_URL` | 否 | 用于向量搜索的 Qdrant | 完整列表及说明请参阅 `.env.example`。 ## 构建 ``` npm run build # Compiles TypeScript to dist/ npm start # Runs the compiled server ``` ## 生态系统 | Package | Description | |---------|-------------| | **[commune](https://github.com/shanjai-raj/commune)** | **邮件 & SMS 基础设施 — 可自托管后端** | | [commune-ai](https://github.com/shanjai-raj/commune-ai) | TypeScript/Node.js SDK | | [commune-python](https://github.com/shanjai-raj/commune-python) | Python SDK | | [commune-mcp](https://github.com/shanjai-raj/commune-mcp) | 用于 Claude Desktop, Cursor, Windsurf 的 MCP 服务器 | | [commune-cli](https://github.com/shanjai-raj/commune-cli) | 命令行界面 | ## 许可证 Apache License 2.0 — 详见 [LICENSE.md](./LICENSE.md)。

标签：AES-256, AI 基础设施, BullMQ, GNU通用公共许可证, MITM代理, MongoDB, Node.js, Redis, SMS 网关, Webhook 分发, 向量搜索, 垃圾邮件检测, 开源, 提示词注入检测, 搜索引擎查询, 漏洞评估, 电子邮件 API, 程序化收件箱, 自动化攻击, 自托管, 通信平台, 邮件基础设施, 邮件安全, 静态加密