Synaplan

---

如果 Synaplan 对你有用，请点个星，帮助更多人发现它。

_{聊天、每条回答的成本、你的文件、生成的媒体，以及可连接的应用。大约 30 秒。}

快速开始

git clone https://github.com/metadist/synaplan.git
cd synaplan
make up

打开 http://localhost:5173。使用 [email protected] / admin123 登录，然后点击 开始使用 Synaplan 演示版（每天 40 条消息，持续 14 天，无需 API 密钥 — 了解其工作原理），或连接你自己的 AI 密钥（免费选项：Groq），或本地 Ollama。

已发布的镜像、Docker 图形界面、封闭网络或 Linux 服务端：更多安装方式。

对比情况

人们通常会将 Synaplan 与聊天窗口或应用构建器进行比较。以下是各个项目的用途，并非排行榜。

	Synaplan	Open WebUI	LibreChat	Dify
项目定位	团队平台：聊天、作为知识库的文件、网站组件，以及可在 WhatsApp 和电子邮件上使用的同一助手	用于本地和云端模型的聊天界面	面向多个服务商的聊天应用	AI 应用和工作流构建器
首次运行	多个容器，约 4 GB	一个容器	一个 Compose 部署栈	一个 Compose 部署栈，并提供托管云服务
回答成本	显示在回答上	不显示在回答上	不显示在回答上	显示在构建器的使用日志中，不显示在聊天回答上
网站、WhatsApp 和电子邮件使用同一助手	是	否	否	支持网站组件；未内置 WhatsApp 和电子邮件

如果你只需要一个聊天窗口，Open WebUI 或 LibreChat 能让你更快实现目标。

---

为什么选择 Synaplan

• 自由，而非套餐等级。 整个平台——后端、前端、小组件、插件——均采用 Apache-2.0 许可，且只需一条命令即可启动。可自托管版本与云端使用的是同一套软件。
• 数百种模型，尽在一处。 OpenAI、Anthropic、Google Gemini、Groq、Mistral、xAI、HuggingFace、欧盟主权云服务提供商，以及通过 Ollama 使用的任何本地模型。可在界面中为每项任务切换服务提供商。
• 规划器只在关键环节使用昂贵模型。 一个请求会转化为一张小型任务图（提取 → 总结 → 生成 → 回复）。实时卡片会显示各个步骤。每个答案都会显示成本。
• 一切由你掌控，包括离线使用。 可部署在本地、欧盟云端，或完全隔离的环境中。不会使用你的数据进行训练，也不会强制收集遥测数据。
• 随时随地使用。 Web、iPhone、Android、桌面端、Outlook、聊天小组件、WhatsApp、电子邮件——还支持 Microsoft 365、Dropbox、Nextcloud / ownCloud、日历、Jira、Confluence 和 OpenCloud。
• 无需分叉即可扩展。 提供插件、OpenAPI REST API、MCP 服务和客户端，以及兼容 Anthropic 的端点，可供 Claude Code 等工具使用。可选的 sidecar 服务在你启用前会保持关闭。

---

开始体验

▶ 在 YouTube 上观看完整演示

点击任意截图即可查看大图。

聊天 每条回答都会显示费用	提供商设置 一个密钥，经过测试并加密	模型选择 每项任务都可使用不同模型	RAG 搜索 对文件进行语义搜索
媒体生成 在聊天中生成图像、视频和音频	聊天小组件 一段代码，适用于任何网站	AI 指令 使用自定义系统提示词	文件 上传文件即可构建知识库
插件 无需分叉即可扩展	管理 用户、用量和运行状况	品牌设置 为整个应用设置白标品牌

_{UI 更改后，使用 scripts/build-readme-tour.sh 重新生成这些资源。}

---

更多安装方式

快速入门采用本地检出。以下变体分别适用于已发布的镜像、无法访问公共互联网的机器，以及 Linux 服务。

在此机器上

快速入门就是这条路径。打开 http://localhost:5173。几秒钟内就会显示状态页面，列出每个启动步骤，并在应用就绪后切换到应用。首次启动：5–15 分钟。之后启动：几秒钟。

make up 会在其余镜像拉取完毕前先在 :5173 响应。docker compose up -d 会启动相同的服务栈；在这些镜像拉取完毕之前，:5173 不会响应。

1. 使用 [email protected] / admin123 登录。状态页面也会显示这些信息。
2. 点击 Start with Synaplan Demo（通过 web.synaplan.com，有效期 14 天，每天 40 条消息），或者粘贴一个服务提供商密钥（免费：Groq）。无需编辑配置文件。
3. 终端中也会显示相同的说明：docker compose logs -f startup-notes。

没有云端密钥？COMPOSE_PROFILES=local-ai ENABLE_LOCAL_GPT_OSS=true make up 会拉取本地聊天模型（gpt-oss:20b，约 14 GB）。下载完成后即可开始聊天。

已发布镜像，无需检出 Git 仓库

只需一个文件。同目录下的 .env 文件可选。

mkdir synaplan && cd synaplan
curl -fsSL -o compose.yaml https://raw.githubusercontent.com/metadist/synaplan/main/deploy/quickstart/compose.yaml
docker compose up -d

打开 http://127.0.0.1:8000。首次访问时会打开设置页面：创建管理员，然后点击 Start with Synaplan Demo，或者粘贴一个服务提供商密钥（免费：Groq），即可完成。首次启动会拉取镜像，需要几分钟。

需要占用更少空间（约 3.2 GB，而非约 5.3 GB）？deploy/quickstart/compose.lite.yaml 会省略 tts、qdrant（文档搜索仍使用 MariaDB VECTOR；记忆功能会暂停）和 centrifugo，同时保留完全相同的卷名称——因此之后可以切换到 compose.yaml，不会丢失任何聊天记录或文件。

Docker 图形界面（Portainer、Dockge、Synology Container Manager，……）：创建一个服务栈，将 deploy/quickstart/compose.yaml 粘贴为其 Compose 文件，然后部署。来自 deploy/quickstart/.env.example 的任何设置都可以填入服务栈的环境变量中——无需设置任何变量。如果图形界面运行在另一台机器上（NAS 或服务器），请添加 SYNAPLAN_HTTP_BIND=0.0.0.0 和 SYNAPLAN_URL=http://<that machine's IP>:8000；否则 Synaplan 只能在该机器本身打开。Dockge 会在一次性 secrets-init 步骤完成后将服务栈标记为“exited”；这是预期行为，Synaplan 会继续运行。

设置写入 .env 后，再次运行 docker compose up -d（使用图形界面时：修改服务栈的变量，然后重新部署）：

• SYNAPLAN_VERSION 用于从发布页面选择一个发行标签。留空表示使用发布此文件时对应的发行版。切勿使用 latest。
• SYNAPLAN_HTTP_BIND=0.0.0.0 和 SYNAPLAN_URL=http://<this machine's IP>:8000 可让网络中的其他设备访问。SYNAPLAN_URL 必须是用户输入的地址，否则实时聊天会保持断开状态。在网络地址上使用纯 http:// 时，浏览器会屏蔽麦克风和剪贴板复制；聊天和文件功能仍可用。若要使用这两项功能，请使用 封闭网络 HTTPS。
• 示例文件中列出了服务提供商密钥、引导管理员和邮件设置，每项各占一行。

数据存放在命名 Docker 卷中，包括数据库、上传文件、向量数据和生成的密钥。请将它们保存在一起：没有对应的 secrets 卷，数据库就无法启动。docker compose down 会保留所有数据；docker compose down -v 会将其全部删除。

**更改发行版：**备份这些卷，设置 SYNAPLAN_VERSION，然后运行 docker compose up -d（或在图形界面中重新部署服务栈）。如果较新的标签已经迁移数据库，之后要回退到较旧的标签，就必须恢复该备份。具体步骤见更新自托管部署。

办公文档、本地 AI、文件处理、封闭网络 TLS 和脚本化备份，请改用完整的 deploy/compose.yaml 和 deploy/selfhost.env.example。

封闭网络

可选启用。默认情况下，本机仍使用 http://127.0.0.1:8000。

当网络无法连接到公共互联网，且用户通过本机地址访问 Synaplan 时，启用此功能。聊天需要 https://<address>/。证书由本机创建。浏览器会显示一次警告。

该网络中的任何 IPv4 地址都可用，包括 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、100.64.0.0/10 和 169.254.0.0/16，以及你分配且不对外通告的地址段。

cp deploy/selfhost.env.example deploy/.env
# Set SYNAPLAN_VERSION. Leave SYNAPLAN_HTTP_BIND at 127.0.0.1.
deploy/scripts/local-tls.sh 10.0.0.15
deploy/scripts/prepare.sh
docker compose --env-file deploy/.env -f deploy/compose.yaml pull
deploy/scripts/validate-release.sh
docker compose --env-file deploy/.env -f deploy/compose.yaml up -d

同事访问 **https://10.0.0.15/**。80 和 443 端口必须空闲。应用本身仍运行在 127.0.0.1:8000。如果有第二个网络接口，可再添加一个参数：deploy/scripts/local-tls.sh 10.0.0.15 192.168.1.20。如果使用公共域名，请保留你自己的 HTTPS 代理，并关闭此功能。

详情：docs.synaplan.com/local-network · deploy/README.md。

在服务器上运行

以上命令用于开发栈（从源码构建、Vite、MailHog、phpMyAdmin）或已发布的镜像。对于 Linux 服务器，安装程序会写入 deploy/.env，固定使用最新版本，并按 prepare → pull → validate → start → smoke-test 的顺序运行。密钥会存放在 deploy/data/secrets.env。

curl -fsSL https://raw.githubusercontent.com/metadist/synaplan/main/install.sh | \
  bash -s -- --mode server --domain https://ai.example.com

手动执行相同步骤的方法见安装和 deploy/README.md。参数：bash install.sh --help。

如果不想手动克隆，可使用以下一行命令启动开发栈：

curl -fsSL https://raw.githubusercontent.com/metadist/synaplan/main/install.sh | bash

---

一个 AI，随处可用

同一个助手、同一个知识库、同一套模型策略，可用于团队已经在使用的所有渠道。在 Channels 下连接一次系统；之后，规划器便可从中读取信息并将结果发送到该系统。

对话界面

界面	功能	获取方式
Web 应用	完整的聊天和管理 UI，支持浅色／深色模式及五种语言	本仓库 — make up
移动应用	在 iPhone 和 Android 上聊天、处理文档和语音；连接到 web.synaplan.com 或你自己的服务器	App Store · Google Play
Synaplan Desktop	配对电脑并在其上运行技能。在 Web 应用中选择 Channels → Synaplan Desktop。暂时没有安装程序 — 从仓库构建。	metadist/synaplan-desktop
Outlook 加载项	将 Synaplan 集成到 Outlook（Web、新版和经典版、Mac）中 — 查找和处理邮件，无需将邮件发送到其他地方	metadist/Synamail
聊天小组件	只需一段代码，即可将助手嵌入任何网站 — 支持跨源访问，并包含人工接管功能	小组件指南
WhatsApp 和电子邮件	AI 会通过问题所来自的渠道作答	WhatsApp · 电子邮件
MCP 和 Claude Code	将你的 RAG 和记忆作为 MCP 工具使用；提供兼容 Anthropic 的 POST /v1/messages 端点	MCP 指南 · 指南

已连接的系统

在 Manage → Connections（或 Manage → Connections → MCP Servers / Manage → Channels → Email）下进行设置。在聊天中，使用 Connections 页面上以胶囊标签显示的频道名称，例如 nextcloud、dropbox、outlook。

频道	可用功能	设置方式
Microsoft 365	实时搜索 Outlook 邮件、查看日历事件（outlook）、通过你自己的邮箱发送邮件	Manage → Connections — OAuth，不会存储密码
Dropbox	将生成的文件保存到 Dropbox 文件夹（dropbox）	Manage → Connections — OAuth
Nextcloud / ownCloud / WebDAV	将文件保存到你拥有的文件夹（nextcloud / folder）	Manage → Connections — 应用密码，绝不会使用你的账户密码
CalDAV calendar	将生成的会议添加到你拥有的日历（calendar）	同一个 Nextcloud 预设可一步创建文件夹和日历
IMAP mailbox	实时搜索任何 IMAP 收件箱，并与 Microsoft 365 搜索结果合并	Manage → Channels → Email
Jira & Confluence	搜索和总结；获准写入时，可创建工单或页面。粘贴的 Confluence 页面会通过已登录账户读取	Manage → Connections → MCP Servers — 选择 Jira & Confluence 卡片，然后使用 Atlassian 登录（无需 API 令牌）
Saved Tasks	固定计划，并按需或按计划运行（每小时 / 每天 / 工作日）	Manage → Automations → Saved Tasks
Nextcloud / OpenCloud apps	将这些云盘中的文件用作 AI 知识，文件存储仍由云盘掌控	synaplan-nextcloud · synaplan-opencloud

详情和频道名称：docs/CONNECTIONS.md。

---

Synaplan 生态系统

以下所有项目都基于同一平台，只是针对不同场景打包。选择适合你的即可——无需其他组件。

项目	简介
synaplan	平台本身（本仓库）：后端、前端、组件、插件、开发栈，以及用于 Elestio、AWS Marketplace 和 Umbrel 适配器的 deploy/ 生产环境契约
synaplan-charts	Kubernetes Helm 图表，适用于运行 K8s 集群的合作伙伴和企业
Mobile apps	原生 iOS 和 Android 应用 — App Store · Google Play
synaplan-desktop	Synaplan Desktop — 配对一台电脑并在其上运行技能。暂时没有安装程序；请从源代码构建。
Synamail	Outlook 加载项（Web、新版和经典版、Mac）— 在你的邮箱中使用 Synaplan
synaplan-nextcloud / synaplan-opencloud	Nextcloud / OpenCloud 应用 — 将其中的文件用作 AI 知识，文件存储仍由云盘掌控（ownCloud 可通过内置 WebDAV 连接使用）
synaplan-tts	可选的可自托管文本转语音服务，用于语音输出
synaplan-base-php	平台构建所基于的 Docker 基础镜像（FrankenPHP + gRPC + whisper.cpp）

---

前提条件

• Docker + Docker Compose v2（macOS/Windows 上的 Docker Desktop，或 Linux 上的 Docker Engine + Compose 插件）
• Git（缺少 git 时，也可以使用 curl + tar 运行单行安装程序）
• 至少 8 GB RAM（启用 local-ai 配置后，建议使用 16 GB）
• 标准安装需要约 4 GB 可用磁盘空间（包括文件处理 + 语音回答；启用 local-ai 还需约 1 GB，如果还启用本地聊天模型，则还需约 14 GB）
• 主机上必须有几个可用端口。端口列表以及无需编辑 Compose 文件即可更改端口的方法，请参阅安装 — 端口冲突。

Apple Silicon（M1–M4）Mac — 构建后端镜像，不要拉取镜像。 上述三步启动流程已经包含此操作：make up 会从多架构基础镜像在本地构建后端和 worker，因此 PHP/FrankenPHP 可在 arm64 上原生运行，无需承担仿真开销。这是速度最快的方式，也是默认方式——无需进行任何特殊操作。（已发布的 ghcr.io/metadist/synaplan 镜像同样支持多架构，因此拉取后也能原生运行。）首次本地构建需要几分钟；之后每次启动都会命中缓存。两个可选开发工具（phpMyAdmin、MailHog）的上游镜像仍仅支持 amd64——如果要保留它们，请启用 Docker Desktop → Settings → General → "Use Rosetta for x86/amd64 emulation on Apple Silicon"（macOS 13+），以便快速仿真这两个工具。

---

安装选项

模式	命令	大小	适用场景
单行命令	curl -fsSL https://raw.githubusercontent.com/metadist/synaplan/main/install.sh | bash	约 4 GB	最简单的启动方式——检查前提条件、获取并启动标准服务栈（生产环境可使用 --mode server）
标准安装	make up	约 4 GB	本地试用：单击一次即可开始聊天（使用 Synaplan Demo 或你自己的密钥）、处理文件、获取语音回答——先显示状态页面，再启动其余服务
快速入门（精简版）	deploy/quickstart/compose.lite.yaml	约 3.2 GB	已发布的镜像，6 个运行时容器（无需克隆 git 仓库、无需 .env；与 compose.yaml 共用卷）
+ 本地 AI	COMPOSE_PROFILES=local-ai make up	约 5 GB	在自己的硬件上添加 Ollama 和 bge-m3 嵌入模型（本地聊天模型可选，另需约 14 GB）
生产环境	install.sh --mode server 或 deploy/ 下的 compose + 脚本	已发布的镜像	在 Linux 服务上自托管——请参阅安装
Kubernetes	synaplan-charts	已发布的镜像	面向合作伙伴和企业的 Helm 集群部署

直接运行 docker compose up -d 也会启动相同的服务栈，但在所有镜像拉取完毕之前，:5173 不会有响应——提供 make up 正是为了让状态页面在几秒内即可响应。

默认不会下载任何 AI 权重，因此首次启动主要耗时在 Docker 镜像和 npm ci 上。COMPOSE_PROFILES=local-ai 与自托管安装在 deploy/.env 中使用的是同一个开关，它会在后台拉取本地嵌入模型（bge-m3，约 1 GB），用于 RAG 和语义搜索；进度会显示在应用中。

想通过 shell 而不是 UI 设置提供商密钥？backend/.env 中的密钥仍然有效——容器启动时，后端会读取该文件，并在首次使用时将密钥导入加密存储。请在启动前写入密钥，或在之后重启容器：

echo "GROQ_API_KEY=your_key" >> backend/.env
make up
# already running? pick up the new key with:
# docker compose restart backend worker

---

访问

打开 http://localhost:5173。API 位于 http://localhost:8000，API 文档位于 http://localhost:8000/api/doc。phpMyAdmin、MailHog、Qdrant、Tika、Ollama 和 TTS 的地址请参阅：安装 — 开发服务 URL。

默认登录凭据：

邮箱	密码	级别
[email protected]	admin123	ADMIN
[email protected]	demo123	PRO
[email protected]	test123	NEW（未验证）

---

功能

• AI 聊天 — Ollama、OpenAI、Anthropic、Gemini、Groq、Mistral、xAI、TrustedTokens (DE)、A2Agent (CN)、HuggingFace（提供商列表）
• 自我感知助手 — 询问“你在这里能做什么？”或输入 /help；AI 助手会根据此安装实例的实时能力作答，而不是给出泛泛的介绍
• 多任务 DAG 路由 — AI 规划器会将复杂请求拆解为有向任务图（提取 → 总结 → 生成 → 回复），将每个步骤分配给最合适的模型，并在执行过程中实时显示任务卡片；简单步骤使用成本更低的模型，减少不必要的令牌消耗
• RAG 搜索 — 使用 MariaDB VECTOR 或 Qdrant 进行语义文档搜索
• 聊天小组件 — 可嵌入任何网站（小组件指南）
• 移动应用 — 在 iPhone 和 Android 上使用聊天、文档和语音功能，可连接至 web.synaplan.com 或你自己的服务（App Store · Google Play）
• Synaplan Desktop — 配对一台计算机，并在其上运行技能。打开 Channels → Synaplan Desktop。目前还没有安装程序（synaplan-desktop）
• AI 助手 — 保存可发布为不同版本的配方（指令、知识文件夹、工具、触发器）（助手）
• 工具与审批 — 统一的工具注册表；写入类操作会在 Approvals 下暂停等待审批（工具）
• 用户与群组 — 共享文件夹、聊天、助手和任务；进入 Operate → Users（人员）
• 文件处理 — 在隔离的边车环境中，对你选择的文件副本运行简短的 Python 或 Node 程序（指南）
• 实时支持 — 实时 WebSocket 层（Centrifugo + Redis）：接管小组件聊天、显示输入状态、通知客服人员（实时功能指南）
• WhatsApp — Meta Business API 集成
• 电子邮件 — AI 驱动的电子邮件回复，以及实时邮箱搜索（IMAP 和 Microsoft 365）
• 连接 — Microsoft 365、Dropbox、Nextcloud / ownCloud / WebDAV、CalDAV——读取邮件、保存文件结果、写入日历事件（连接指南）
• 保存的任务 — 固定多步骤计划，按需或按计划运行；提供 Steps 编辑器和 webhook 触发器（Manage → Automations → Saved Tasks）
• 监控的页面 — 保存 URL，按计划进行比较，并在页面变更时通过电子邮件发送差异
• 音频 — Whisper 转录（输入）+ 可选的 synaplan-tts（输出；内置五种语音，界面语言决定所选语音）
• 文档 — 支持 PDF、Word、Excel 和带 OCR 的图像；助手也可创建和修改 Office 文件；可选 Collabora CODE 边车，用于生成缩略图、导出 PDF、预览和合并（Office 文档）
• AI 记忆 — 使用 Qdrant 向量搜索进行用户画像分析
• 反馈系统 — 由 Qdrant 驱动的反馈收集与分析
• 插件 — 非侵入式插件系统（插件指南）
• MCP 服务（提前体验）— 通过 Model Context Protocol 连接 AI 客户端（Claude、Cursor 等）；你的 RAG 和记忆会成为 POST /mcp 上的工具（MCP 指南）
• MCP 客户端（提前体验）— 在 Manage → Connections → MCP Servers 下连接你自己的 MCP 服务（Jira、Confluence、CRM、wiki、n8n 等）。规划器通过 mcp_fetch 获取实时数据；在该服务上启用 allow write actions 后，还可以通过 mcp_action 创建工单或页面——破坏性工具仍会被拒绝。提供 SSRF 防护，并按主题选择性启用。预置的 BCONFIG 标志（MCP.CLIENT_ENABLED、MULTITASK.MCP_FETCH_ENABLED、MULTITASK.MCP_ACTION_ENABLED）可启用此功能；值为 0 的显式配置项是运维人员的紧急关闭开关。请参阅 docs/MULTITASK_DATA_NODES.md
• Claude Code 与兼容 Anthropic 的 API — 将 Claude Code 或任何使用 Anthropic 协议的客户端指向你的实例（POST /v1/messages）；在 Manage → Developer & devices → Coding clients 下配置（指南）

---

AI 提供商与模型

Synaplan 不绑定特定提供商：在 Operate → AI infrastructure → Providers & keys 中连接所需的提供商（密钥会即时验证、加密后存储在数据库中，无需重启即可生效），或者在 backend/.env 中设置以下环境变量——这些变量会在容器启动时读取，并在首次使用时导入加密存储。每位用户可为每项任务（聊天、视觉、图像、视频、音频、嵌入）选择不同的模型——没有任何模型被硬编码。

提供商	backend/.env 中的变量	模型
OpenAI	OPENAI_API_KEY	GPT-5.6 Sol / Terra / Luna、GPT-5.5（+ Pro）、GPT-5.4（+ mini）、GPT Image、Whisper、text-embedding-3
Anthropic	ANTHROPIC_API_KEY	Claude Opus 5、Sonnet 5、Fable 5、Opus 4.8、Haiku 4.5（聊天 + 视觉）
Google Gemini	GOOGLE_GEMINI_API_KEY	Gemini 3.x / 2.5 聊天 + 视觉、Nano Banana（含 Pro / Lite）、Veo 3.1、Gemini TTS
Groq	GROQ_API_KEY	Qwen 3.6 27B（聊天 + 视觉）、GPT-OSS 20B/120B、Whisper Large v3
Mistral 🇫🇷	MISTRAL_API_KEY	Mistral Medium 3.5（+ 视觉）、Mistral Large 3、Mistral Large 4（+ 视觉）、Voxtral 转录 + TTS
xAI	XAI_API_KEY	Grok 4.7 / 4.6 / 4.5（+ 视觉、500K 上下文）、Grok Imagine 图像 + 视频（含 Pro / 1.5 等级）
Meta	META_API_KEY	Muse Spark 1.3、Muse Wonder（+ 视觉）、Muse Image、Muse Voice Transcribe — Meta Model API
Cerebras	CEREBRAS_API_KEY	Qwen 3.8 27B（+ 视觉）、GPT OSS 120B — 推理速度极快（约 2,000–3,000 tokens/s）
TrustedTokens 🇩🇪	TRUSTEDTOKENS_API_KEY	GLM 5.2 / 5.3（+ Flash 视觉）、Chimera、Qwen3.6 35B（+ 视觉）、GPT OSS 120B — 在德国 GPU（TNG）上进行主权推理，零数据留存
A2Agent 🇨🇳	A2AGENT_API_KEY	Qwen3.8 MAX / Flash（+ 视觉）、DeepSeek V4 Pro / Flash、MiniMax M3 — 通过 A2Agent 网关使用中国前沿模型
HuggingFace	HUGGINGFACE_API_KEY	Kimi K3 / K2.5 / K2.6 / K2.7 Code（聊天 + 视觉）
TheHive	THEHIVE_API_KEY	Flux Schnell、SDXL
Higgsfield	HIGGSFIELD_API_KEY + HIGGSFIELD_API_SECRET	Soul、Reve、DoP、Kling 2.1
Cloudflare Workers AI	CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN	bge-m3 嵌入（也可用作嵌入备用方案）
Ollama 🇩🇪 可自托管	OLLAMA_BASE_URL（无需密钥）	任意本地模型——聊天、视觉、bge-m3 嵌入

价格透明。 每个模型均采用其提供商自己的费率（每 1M 个输入/输出 tokens 的美元价格，或按媒体的每张图像 / 每秒 / 每字符计价）——中间没有专有积分单位。选择器会在每个模型旁以及每条回答上显示免费 / 低 / 中 / 高费用徽标，GET /api/v1/config/models 会返回 priceIn / priceOut，统计页面会记录每次调用的实际费用。在 web.synaplan.com 托管实例上，同一目录也用于计算套餐用量；使用 Ollama 自托管时，每个 token 的费用为零。详情：模型定价与费用透明度。

模型目录的变更（新增模型、退役版本、价格更新）通过 seeder 发布，因此现有安装会切换到受支持的后继模型，而不会悄悄保留已失效的模型——退役记录会注明后继模型，并在下次部署时切换所有安装。参见 docs/PRICING_MAINTENANCE.md。

---

精简设计：核心与可选组件

make up 会启动完整平台，但核心刻意保持精简：应用、数据库和 Redis。其他所有部分都是增加一项功能并占用 RAM 的组件。需要时开启，不需要时关闭——无论如何，Synaplan 都会继续运行，只是隐藏相应功能。http://localhost:5173 上的启动状态页面会列出每个组件当前的开启／关闭状态；登录后，操作 → 系统状态（/admin/features）也会显示相同信息。

组件	提供的功能	默认状态	开关
核心 — frontend、backend、worker、scheduler、db（MariaDB）、redis	应用、API、异步任务、计划任务、存储、缓存和队列	始终开启	—
Ollama（ollama）	在你的硬件上运行本地 AI：用于文档搜索的 bge-m3 嵌入，可选的本地聊天（ENABLE_LOCAL_GPT_OSS=true）	关闭	COMPOSE_PROFILES=local-ai make up — 与生产环境中的 deploy/.env 使用相同的开关
Qdrant（qdrant）	用于 AI 记忆、反馈分析和大规模 RAG 的向量数据库	开启	docker compose stop qdrant — 文档搜索本身使用 MariaDB VECTOR（默认的 VECTOR_STORAGE_PROVIDER），因此 RAG 仍可正常运行；记忆功能会暂停
Centrifugo（centrifugo）	实时支持：人工接管小组件聊天、输入指示器、客服人员通知（实时功能指南）	开启	REALTIME_ENABLED=false make up（然后运行 docker compose stop centrifugo）— 仪表板将回退为普通 REST 刷新
Apache Tika（tika）	从 PDF、Word、Excel 和 1000 多种格式中提取文本，用于 RAG	开启	docker compose stop tika — 上传的文件之后只能索引纯文本／OCR 内容
Collabora CODE（collabora）	Office 文件功能：缩略图、“下载为 PDF”、内嵌预览、“合并为 PDF”（约占用 2 GB RAM）— 详情	关闭	docker compose --profile office up -d
Docling（docling）	在 Tika 之前进行感知布局的内容提取（表格、标题）— 模块	关闭	docker compose --profile docling up -d
SearXNG（searxng）	可自托管的网络搜索，让查询留在你的网络中 — 模块	关闭	docker compose --profile searxng up -d
文件处理（compute）	对你选择的文件副本运行简短的 Python / Node 任务 — 详情	开启	COMPUTE_URL=disabled make up
文本转语音（tts）	语音回答，内置五种语音 — 详情	开启	docker compose stop tts
Keycloak（keycloak）	用于 OIDC 开发的 SSO 测试领域（配置）	关闭	docker compose --profile oidc up -d

让默认开启的组件在重启后仍保持关闭。 下次运行 up -d 时，docker compose stop 的效果会被撤销。若要永久将某个组件设为按需启用，请在 docker-compose.override.yml 中为它指定一个 profile（该文件不会纳入 git 跟踪）——这样普通的 up -d 会跳过它，使用 --profile optional 则会重新启用它：

services:
  qdrant:
    profiles: [optional]

生产环境遵循相同规则：deploy/compose.yaml 始终启动 web/worker/scheduler，以及 db/redis/centrifugo/tika/qdrant 和语音回答；office、local-ai 和 compute 则作为 profiles（在 deploy/.env 中设置 COMPOSE_PROFILES=office,local-ai,compute）。Kubernetes 安装通过 synaplan-charts 接入相同服务。其他仅供开发使用的容器（phpmyadmin、mailhog、frontend-widgets、startup-notes）不会部署到生产环境。

---

实时处理与后台处理

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

服务	作用
redis	必需的共享基础设施：缓存、会话、锁、速率限制、消息队列（Redis Streams）、Centrifugo 引擎
centrifugo	实时功能的 WebSocket 网关（实时聊天接管、正在输入提示、操作员通知）——浏览器通过 /connection/websocket 以同源方式连接
worker	Symfony Messenger 消费者，用于执行异步任务（AI 处理、文档索引、小组件抓取）
scheduler	每 60 秒触发一次：已保存的任务、媒体任务回收、临时文件清理、更新检查

在多节点集群中，所有节点共用一个 Redis，因此在某个节点上发布的 WebSocket 事件也会发送到连接在其他节点上的浏览器。详情请见：docs/REALTIME.md。

---

文本转语音

运行 make up 即可启动语音输出——synaplan-tts，镜像为 ghcr.io/metadist/synaplan-tts。镜像中已包含 五种 Piper 语音（英语、德语、西班牙语、法语、土耳其语）。停止 tts 容器即可隐藏扬声器控件。

# Already running after `make up`. Standalone on another machine:
docker run -d --name synaplan-tts -p 127.0.0.1:10200:10200 ghcr.io/metadist/synaplan-tts:latest

后端会读取 SYNAPLAN_TTS_URL（compose 默认值为 http://tts:10200）。

语音由界面语言决定。 聊天会发送当前前端区域设置（en / de / es / fr / tr）；如果后端检测到回复使用了其他语言，则以检测结果为准。随后 Piper 会将短代码映射到对应的内置语音（德语界面 → kerstin，西班牙语 → davefx，……）。没有单独的语音选择器。要添加更多 Piper 模型，请将 .onnx + .onnx.json 放入额外语音卷中——请参阅 synaplan-tts README 和 docs.synaplan.com/tts。

---

Office 文档

缩略图、PDF 导出、内嵌预览和“合并为 PDF”需要一个可选的 Collabora CODE 旁路服务。默认情况下该服务处于关闭状态，因此 make up 不会拉取它。聊天以及 DOCX / XLSX / PPTX 生成无需此服务。设置说明（包括为何 OFFICE_CONVERT_URL 不应放在 backend/.env 中）：安装 — 可选的 Office 转换。

---

文件处理

助手可以在你已选择文件的副本上运行简短的 Python 或 Node 程序。运行 make up 即可启动。开发令牌以及如何关闭旁路服务，请参阅安装 — 文件处理。

---

常用命令

# Startup progress ("please wait..." notes + READY message)
docker compose logs -f startup-notes

# Logs
docker compose logs -f backend

# Restart
docker compose restart backend

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

# Run tests
make test

# Code quality
make lint

---

文档

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

仓库内指南（供参与此代码库开发的开发者使用）：

指南	说明
安装	本地开发环境和生产环境可自托管（deploy/）
配置	环境变量、API 密钥
功能开关	各阶段功能（人员与共享、助手、工具、已保存任务步骤、桌面端、文件处理等）：管理员开关、FEATURE_* 环境变量固定值、默认值
文件处理 / 计算	可选的 sidecar：开关、compose 配置文件、配额、工作区
连接	Microsoft 365、Dropbox、Nextcloud / WebDAV、CalDAV、Jira / Confluence
AI 模型定价	模型目录、提供商价格、停用模型
开发	命令、测试、架构
实时通信 / WebSockets	Centrifugo + Redis 实时层、多节点部署
可观测性	请求关联 ID、脱敏事件环形缓冲区、管理员日志 API
Office 文档	可选的 Collabora CODE sidecar（PDF 导出、预览、格式转换）
RAG 系统	文档搜索和处理
聊天小组件	在网站中嵌入聊天
WhatsApp	Meta Business API 设置
电子邮件	电子邮件渠道集成
兼容 Anthropic 的 API	Claude Code / Messages API 网关（POST /v1/messages）
安全计算（用户文档）	用户可见的内容：文件处理卡片、工作区、配额

相关仓库

仓库	用途
synaplan	主应用（当前仓库）
synaplan-docs	公共文档网站（docs.synaplan.com）
Synamail	Outlook 加载项
synaplan-desktop	Synaplan Desktop（Windows、macOS、Linux）。尚无安装程序；请从源代码构建。
synaplan-apps	iOS 和 Android 应用 — App Store · Google Play
synaplan-nextcloud	Nextcloud 集成
synaplan-opencloud	OpenCloud 集成
synaplan-tts	可选的 Piper TTS — 包含 4 种预置语音的 镜像
synaplan-sortx	文档分类插件 + 本地工具
synaplan-charts	Kubernetes Helm charts
synaplan-platform	生产环境部署配置

---

项目结构

synaplan/
├── backend/        # Symfony PHP API
├── frontend/       # Vue.js SPA
├── docs/           # Developer documentation
├── deploy/         # Production self-host compose + lifecycle scripts
├── sidecars/       # Optional sidecars (secure compute)
├── _docker/        # Docker configs
└── plugins/        # Plugin system

---

Star 历史

## 社区与支持

• Discord — 与团队和社区交流；自托管和配置问题可在这里最快得到解答
• GitHub Issues — 报告 Bug 和提交功能请求
• 安全政策 — 了解如何私下报告漏洞，以及后续处理流程
• www.synaplan.com — 产品、托管和企业联系信息

贡献

请参阅 CONTRIBUTING.md。AGENTS.md 是在此代码库中工作的编码 Agent 指南。

---

许可证

Apache-2.0