Simmetric Chat
返回文档
指南 01

快速入门

Simmetric Chat 是一个本地优先、可离线运行（air-gap）的 AI 聊天平台：它可以在不连接外部云服务的情况下运行，使用本地 LLM（Ollama）、本地嵌入（Xenova）和本地向量数据库（LanceDB）。不过，在配置完成后，它也可以使用云提供商（OpenAI、Anthropic、OpenRouter）和远程向量数据库（Qdrant）。

2 分钟阅读

Simmetric Chat 是一个本地优先、可离线运行（air-gap）的 AI 聊天平台：它可以在不连接外部云服务的情况下运行，使用本地 LLM（Ollama）、本地嵌入（Xenova）和本地向量数据库（LanceDB）。不过，在配置完成后，它也可以使用云提供商（OpenAI、Anthropic、OpenRouter）和远程向量数据库（Qdrant）。

前置要求

  • Node.js ≥ 24 和 pnpm 11.24.0（monorepo 管理器；`corepack enable && corepack prepare [email protected] --activate`）
  • PostgreSQL 16（主数据库）
  • Ollama（可选，但建议用于本地 LLM）- https://ollama.com
  • Docker + Docker Compose（用于容器化部署，见 09 - Deployment）

验证：

bash
node -v && pnpm -v && psql --version

安装（本地开发）

bash
git clone <repo> simmetric-chat
cd simmetric-chat
pnpm install

monorepo 使用 pnpm workspaces + Turborepo。包位于 packages/：shared、server、frontend、collector、widget，以及桌面应用 src-tauri/。

环境变量

所有包都读取 仓库根目录下的 `.env`（唯一的运行时配置文件；旧的按包 .env 层级已移除：优先级为 process.env > 根 .env > 代码默认值）。创建最小文件：

bash
cp .env.example .env

必需的密钥（JWT_SECRET、COLLECTOR_SECRET）和 widget 密钥：

env
JWT_SECRET=$(openssl rand -hex 32)
COLLECTOR_SECRET=$(openssl rand -hex 32)
WIDGET_API_KEY=$(openssl rand -hex 32)
DATABASE_URL=postgresql://simmetricchat:simmetricchat@localhost:5432/simmetricchat
LLM_PROVIDER=ollama
LLM_MODEL=gemma4:latest
OLLAMA_BASE_URL=http://localhost:11434

WIDGET_API_KEY 是 widget 服务所必需的（它自己的 Zod schema 缺少该变量时会退出进程）；服务器启动时将其注册为 widget-service 账户的 API 密钥（幂等）。开发时可选的变量：API_KEY_HMAC_SECRET（在设置之前 sk- API 密钥不可用）和 ENCRYPTION_KEY（回退到 scryptSync(JWT_SECRET)；生产环境必需）。缺少 LICENSE_KEY 意味着 Community 构建。

完整的环境变量表：03 - Configuration。

数据库

创建 PostgreSQL 数据库（例如 docker compose -f docker/docker-compose.infra.yml up -d postgres），然后生成 Prisma 客户端、应用迁移和 seed：

bash
pnpm db:generate                  # 生成 Prisma 客户端（+ Prisma 7/pnpm 符号链接修复）
pnpm --filter server db:migrate   # 应用迁移（交互式）
pnpm --filter server db:seed      # 默认角色（Admin、Superuser、User）、权限、配置、模板

手动 seed 的替代方案：在空数据库上，前端显示 4 步设置向导（管理员、LLM 提供商、向量数据库）- 或者服务器自动 seed 引导管理员（默认 SEED_BOOTSTRAP_ADMIN=true，可通过 SEED_ADMIN_USERNAME / SEED_ADMIN_PASSWORD / SEED_ADMIN_EMAIL 配置，默认 admin / admin123 / [email protected]，并带有 mustChangePassword=true）。自助注册默认关闭（ALLOW_REGISTRATION=false）：管理员从 Settings 或通过 POST /api/auth/admin-register 创建用户。

启动开发环境

一条命令通过 Turborepo 启动所有服务：

bash
pnpm dev

默认端口：

Service端口说明
frontend5173Vite SPA（React 19），/api 代理 → server
server3000Express API + Swagger 位于 /api-docs
collector3210文档摄取微服务
widget3211可嵌入的 widget 服务（Preact）

打开 http://localhost:5173，使用 admin / admin123 登录，然后更改密码。

如果 Ollama 未运行，聊天会以连接错误失败。使用 ollama pull gemma4:latest && ollama serve 拉取模型，或在 Settings → Providers 中配置云提供商。

UI 快速导览

  • Sidebar - 按角色过滤的分组：Overview（仪表盘）、Chat（聊天、项目、工作区）、Knowledge（文档、知识库、上传）、Platform（widget、市场、分析 - 管理员）、System（事件日志、SSO - 管理员/enterprise）。条目遵循 13 个 RBAC 菜单部分。
  • Chat - 逐 token 流式输出、按聊天选择模型（Cmd+K 面板）、并排对比（Cmd+Shift+M）、RAG 引用、/model 斜杠命令。
  • Documents - 拖放上传（PDF、DOCX、XLSX、PPTX、TXT、MD、CSV、带 OCR 的图片），状态 pending → processing → completed → failed。
  • Settings - 5 个主标签页（个人资料、LLM 提供商、外观、安全、高级），嵌套子部分：Providers、LLM & Embedding、Vector DB、API Keys、Roles、Users、MCP Connections、Maintenance、Backups、DLP、Widget（专用页面）、OCR 等。
  • Maintenance - 嵌入模型更改后一键 RAG 重新索引。

推荐的第一步

  1. 配置提供商 - Settings → Providers：添加 Ollama（本地）或 OpenAI/Anthropic。
  2. 创建工作区和项目 - 文档和聊天都限定在工作区内。
  3. 上传文档 - Documents → 上传；等待 completed 状态。
  4. 聊天 - 在工作区中打开聊天并询问文档相关问题（混合 RAG）。
  5. （管理员）探索市场 - 安装 MCP 服务器以用工具扩展代理。

后续步骤