Synaplan Multimodal Gateway

Synaplan

基于人工智能的知识管理，支持 RAG、聊天小部件和多渠道集成。

在线实例：web.synaplan.com  |  文档：docs.synaplan.com  |  API：Swagger UI

---

前提条件

• Docker + Docker Compose v2（macOS/Windows 上的 Docker Desktop，或 Linux 上的 Docker Engine + Compose 插件）
• Git
• 至少 8 GB 内存（本地 AI 标准安装建议 16 GB）
• 标准安装约需 9 GB 可用磁盘空间（最小安装约需 5 GB）
• 空闲 TCP 端口 5173、8000、8082、8025、3307、6333、11435

Apple Silicon（M1–M4）Mac： Synaplan 的容器镜像针对 linux/amd64 发布，因此在 Apple Silicon 上通过模拟运行。在 Docker Desktop → 设置 → 通用 中，启用 “在 Apple Silicon 上使用 Rosetta 进行 x86/amd64 模拟”（macOS 13+），可获得比默认 QEMU 更快、更稳定的容器体验。不启用也能正常运行——只是速度较慢，且首次构建耗时更长。

快速开始

git clone https://github.com/metadist/synaplan.git
cd synaplan
docker compose up -d

打开 http://localhost:5173 —— 用户界面约 2 分钟就绪。使用标准安装时，本地 Ollama 模型（gpt-oss:20b、bge-m3，总计约 14 GB）会在后台继续下载——使用本地 AI 的聊天功能将在下载完成后可用（docker compose logs -f backend 显示进度）。如需最快的首次体验，请使用下方的最小安装。

---

安装选项

模式	命令	大小	适用场景
标准	docker compose up -d	~9 GB	完整功能，本地 AI
最小	docker compose -f docker-compose-minimal.yml up -d	~5 GB	仅云端 AI（Groq/OpenAI）

对于最小安装，请在启动服务栈之前设置您的 API 密钥，以便首次启动即可识别（避免重启）。在 console.groq.com 获取免费密钥：

echo "GROQ_API_KEY=your_key" >> backend/.env
docker compose -f docker-compose-minimal.yml up -d

已启动但未设置密钥？添加密钥并重启后端：

echo "GROQ_API_KEY=your_key" >> backend/.env && docker compose restart backend

---

访问入口

服务	URL
应用	http://localhost:5173
API	http://localhost:8000
API 文档	http://localhost:8000/api/doc
phpMyAdmin	http://localhost:8082
MailHog	http://localhost:8025

默认登录凭据：

邮箱	密码	级别
[email protected]	admin123	管理员
[email protected]	demo123	专业版
[email protected]	test123	新用户（未验证）

---

功能特性

• AI 聊天 — Ollama、OpenAI、Anthropic、Groq、Gemini
• 多任务路由 — AI 规划器将复杂请求分解为任务图（提取 → 摘要 → 生成 → 回复），并在步骤执行时实时流式传输任务卡片
• RAG 搜索 — 使用 MariaDB VECTOR 或 Qdrant 进行语义文档搜索
• 聊天小部件 — 嵌入任何网站（小部件指南）
• 实时支持 — 实时 WebSocket 层（Centrifugo + Redis）：人工接管小部件聊天、输入状态提示、操作员通知（实时指南）
• WhatsApp — Meta Business API 集成
• 邮件 — AI 驱动的邮件回复
• 音频 — Whisper 转录（输入）+ 可选的 synaplan-tts（输出）
• 文档 — PDF、Word、Excel、带 OCR 的图像
• AI 记忆 — 基于 Qdrant 向量搜索的用户画像
• 反馈系统 — 由 Qdrant 驱动的反馈采集与分析
• 插件 — 非侵入式插件系统（插件指南）
• MCP 服务器 （早期访问） — 通过模型上下文协议连接 AI 客户端（Claude、Cursor 等）；您的 RAG 和记忆将成为 POST /mcp 上的工具（MCP 指南）
• MCP 客户端 （早期访问） — 在 频道 → MCP 服务器 下连接您的 MCP 服务器（CRM、wiki、n8n 等）；多任务规划器通过 mcp_fetch DAG 节点从中拉取实时数据——只读、SSRF 防护、按主题选择加入。由预设的 BCONFIG 标志启用（MCP.CLIENT_ENABLED、MULTITASK.MCP_FETCH_ENABLED — app:seed 在部署时将其设置为开启；显式的 0 行是操作员的终止开关）。详见 docs/MULTITASK_DATA_NODES.md

---

Qdrant 向量数据库

Qdrant 作为内部 Docker 服务运行——无需配置。它为 AI 记忆、RAG 文档搜索和反馈系统提供支持。

随 docker compose up -d 自动启动。没有它 Synaplan 也能完全正常工作（记忆和向量搜索将被禁用）。

---

实时与后台处理

两个 compose 文件也会启动三个内部服务（无主机端口，无需设置）：

服务	角色
redis	必需的共享基础设施：缓存、会话、锁、速率限制、消息队列（Redis Streams）、Centrifugo 引擎
centrifugo	用于实时功能的 WebSocket 网关（实时聊天接管、输入状态提示、操作员通知）——浏览器通过 /connection/websocket 同源连接
worker	Symfony Messenger 消费者，执行异步作业（AI 处理、文档索引、小部件爬取）

在多节点集群中，所有节点共享一个 Redis，因此在一个节点上发布的 WebSocket 事件可以到达连接到任何其他节点的浏览器。详情：docs/REALTIME.md。

---

文本转语音（可选）

如需语音输出，请在 Synaplan 旁边运行 synaplan-tts：

git clone https://github.com/metadist/synaplan-tts.git && cd synaplan-tts && docker compose up -d

---

常用命令

# Logs
docker compose logs -f backend

# Restart
docker compose restart backend

# Reset database
docker compose down -v && docker compose up -d

# Run tests
make test

# Code quality
make lint

---

文档

面向用户和 API 的文档位于 docs.synaplan.com。源码：metadist/synaplan-docs。

仓库内指南（面向在此代码库上工作的开发者）：

指南	描述
安装	详细设置说明
配置	环境变量、API 密钥
开发	命令、测试、架构
实时 / WebSocket	Centrifugo + Redis 实时层，多节点部署
RAG 系统	文档搜索与处理
聊天小部件	在网站上嵌入聊天
WhatsApp	Meta Business API 设置
邮件	邮件渠道集成

相关仓库

仓库	用途
synaplan	主应用（本仓库）
synaplan-docs	公共文档站点（docs.synaplan.com）
synaplan-tts	可选的 Piper TTS 服务
synaplan-sortx	文档排序插件 + 本地工具
synaplan-charts	用于 Kubernetes 的 Helm charts
synaplan-platform	生产部署配置

---

项目结构

synaplan/
├── backend/        # Symfony PHP API
├── frontend/       # Vue.js SPA
├── docs/           # Documentation
├── _docker/        # Docker configs
└── plugins/        # Plugin system

---

贡献

有关开发指南和代码标准，请参阅 AGENTS.md。

---

许可证

Apache-2.0