LLMStack 项目说明书

Doramagic 项目包 · 项目说明书

LLMStack 项目

一个零代码的多智能体框架，用于结合你的数据构建 LLM 智能体、工作流和应用

LLMStack 概览与系统架构

LLMStack 是一个开源的无代码（no-code）平台，用于构建生成式 AI Agent、工作流与聊天机器人，并将其与用户自有数据和业务流程对接。它由 Promptly 团队维护，既可以部署在云端，也可以本地化（on-premise）运行。资料来源：[README.md:1-30]()

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 3.1 Django 应用划分

继续阅读本节完整说明和来源证据。

章节 3.2 处理器与模型供应商（Providers）

继续阅读本节完整说明和来源证据。

章节 3.3 前端与构建链

继续阅读本节完整说明和来源证据。

一、项目定位与核心价值

LLMStack 是一个开源的无代码（no-code）平台，用于构建生成式 AI Agent、工作流与聊天机器人，并将其与用户自有数据和业务流程对接。它由 Promptly 团队维护，既可以部署在云端，也可以本地化（on-premise）运行。资料来源：README.md:1-30

平台核心定位可归纳为以下几点：

多模型链式调用（Chaining）：支持 OpenAI、Cohere、Stability AI、Hugging Face 等多家模型供应商，可在不写代码的情况下将多个 LLM 串联为复合应用。资料来源：web/src/components/HomepageFeatures/index.js:5-15
数据接入与向量化：支持 CSV、TXT、PDF、DOCX、PPTX 等多种数据格式以及 Google Drive、Notion、网站 URL、sitemap 等来源，平台会自动完成预处理与向量化并写入内置向量数据库。资料来源：README.md:60-70
多租户（Multi-tenant）：可创建多个组织并分配用户，资源按组织隔离。资料来源：README.md:25-30
协作与权限：提供 Viewer 与 Collaborator 两种角色，可对应用进行细粒度访问控制。资料来源：web/src/components/HomepageFeatures/index.js:21-30
多渠道触发：构建完成的 App 可通过 HTTP API 调用，也可由 Slack 或 Discord 触发。资料来源：README.md:17-22

二、系统架构总览

LLMStack 在运行时由本地 CLI 工具 + Docker Compose 后端服务 + 浏览器前端三部分组成。CLI 入口会拉起一组 Docker 容器（api、rqworker、redis、postgres、weaviate 等），随后自动打开浏览器指向 localhost:3000。资料来源：README.md:75-95

后端基于 Django 4.2 框架，同时通过 Django Channels 暴露 ASGI 接口以支持 WebSocket 实时通信。llmstack/server/wsgi.py 暴露传统 HTTP 入口，而 llmstack/server/asgi.py 则注册了多条 WebSocket 路由，覆盖 App 运行、Twilio 语音、资产流（Asset Streaming）、连接激活、Playground、Sheets 与应用商店等场景。资料来源：llmstack/server/wsgi.py:1-15、资料来源：llmstack/server/asgi.py:1-35

flowchart LR
    Browser[浏览器 / 前端 SPA] -->|HTTP| Django[Django API<br/>wsgi.py]
    Browser -->|WebSocket| Channels[Django Channels<br/>asgi.py]
    Django --> Apps[llmstack.apps]
    Django --> Processors[llmstack.processors]
    Django --> Sheets[llmstack.sheets]
    Django --> Assets[llmstack.assets]
    Channels --> Consumers[consumers.py<br/>App / Twilio / Playground]
    Django --> RQ[RQ Worker]
    RQ --> Redis[(Redis)]
    Django --> Postgres[(PostgreSQL)]
    Processors --> Weaviate[(Weaviate<br/>向量库)]
    CLI[llmstack CLI] --> Docker[Docker Compose<br/>api / rqworker / redis / postgres / weaviate]

三、关键模块组成

3.1 Django 应用划分

llmstack/server/settings.py 的 INSTALLED_APPS 表明后端被划分为多个 Django 子应用，包括 apps、connections、jobs、organizations、assets、sheets 等，并通过 django_rq 接入异步任务队列。资料来源：llmstack/server/settings.py:120-145

URL 路由由 llmstack/server/urls.py 统一装配，所有业务路径都以根路径挂载，例如 /apps/、/processors/、/data/、/sheets/ 等，Django Admin 仅在显式启用时才暴露。资料来源：llmstack/server/urls.py:1-35

3.2 处理器与模型供应商（Providers）

平台通过 PROCESSOR_PROVIDERS 列表注册了 OpenAI、Anthropic、Cohere、Stability、Replicate、ElevenLabs、HeyGen、Mistral、Meta、Pinecone、Qdrant、Singlestore、Weaviate 等十余家供应商，每家通过 processor_packages 与可选的 config_schema 描述接入方式，Juniper 等可选供应商通过可选依赖 jnpr.junos 按需启用。资料来源：llmstack/server/settings.py:1-90

向量数据库默认使用内置的 Weaviate，连接参数通过环境变量 WEAVIATE_URL、WEAVIATE_HTTP_HOST、WEAVIATE_GRPC_PORT 等注入。资料来源：llmstack/server/settings.py:90-110

3.3 前端与构建链

前端代码位于 llmstack/client/，是基于 react-scripts 与 Craco 的 React 18 应用，使用了 Recoil 状态管理、react-router-dom、react-dropzone、react-papaparse、pdfjs-dist、lexical 等库。资料来源：llmstack/client/package.json:1-50

独立的产品/文档站点 web/ 则由 Docusaurus 3 构建，作为项目主页与文档门户，提供 Start 与 Deploy LLMStack 入口。资料来源：web/src/pages/index.js:1-70、资料来源：web/README.md:1-25

四、近期演进与社区关注点

依据 Release 记录，自 v0.2.2 起平台陆续引入了新的默认应用与文件转换能力，v0.2.4 增加了 Sheets 与消息反馈，v0.2.5 推出 AI Sheet Builder，v0.2.6 进一步加入基于 OpenAI Realtime API 的语音 Agent 与 Twilio 集成。资料来源：releases v0.2.2 - v0.2.6

社区中频繁被讨论的话题集中在安装与启动阶段的稳定性：

全新安装时可能因 Docker Desktop 未运行、Docker daemon 不可用或 Postgres 迁移脚本错误而启动失败。资料来源：issue #298、issue #288
Windows 上 NamedTemporaryFile 文件锁会导致 docker compose --env-file 失败，需要先释放临时文件句柄。资料来源：issue #299
默认 ALLOWED_HOSTS 不包含访问域名时会触发 DisallowedHost 异常。资料来源：issue #291
开发模式下 docker-compose.dev.yml 需要先登录私有镜像仓库，否则 pull access denied for llmstack-app。资料来源：issue #295
文件聊天类模板因 config 字段缺失曾出现 psycopg2.errors.UndefinedColumn，需要按 PR 修复 schema。资料来源：issue #304

对于追求企业级治理与合规的高级用户，社区也提出了在 No-code Agent 之上叠加自动审计与策略执行中间件（如 asqav）的诉求。资料来源：issue #308

核心功能：App、Agent、Sheets 与多通道接入

LLMStack 是一个面向生成式 AI 的无代码（no-code）平台，允许用户通过链式组合（chaining）多个大语言模型来构建 AI Agent、工作流和聊天机器人，并接入自有数据与业务流程。平台同时提供云端 SaaS（Promptly）与本地开源部署两种形态。核心能力可拆解为四大部分：App（应用）、Agent（智能体）、Sheets（AI 表格）与多通道接入。...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

LLMStack 是一个面向生成式 AI 的无代码（no-code）平台，允许用户通过链式组合（chaining）多个大语言模型来构建 AI Agent、工作流和聊天机器人，并接入自有数据与业务流程。平台同时提供云端 SaaS（Promptly）与本地开源部署两种形态。核心能力可拆解为四大部分：App（应用）、Agent（智能体）、Sheets（AI 表格） 与多通道接入。资料来源：README.md

平台支持的关键特性包括：

模型链式调用：支持 OpenAI、Cohere、Stability AI、Hugging Face 等多家模型提供商，开发者可在无代码构建器中把多个模型串联。资料来源：web/src/components/HomepageFeatures/index.js
自带数据（Bring your own Data）：支持 Web URL、Sitemap、PDF、音频、PPTX、Google Drive、Notion 等数据源，平台自动完成预处理与向量化。资料来源：web/src/components/HomepageFeatures/index.js
协作构建：通过细粒度权限模型，区分 Viewer 与 Collaborator 角色，允许多用户共同编辑应用。资料来源：web/src/components/HomepageFeatures/index.js

App（应用）与模板体系

LLMStack 的 App 是用户最终可发布与触发的最小可执行单元。模板（templates）层从文件系统加载，由环境变量 APP_TEMPATES_DIR（注意拼写沿用源码中的 APP_TEMPATES_DIR）控制，默认指向仓库内 contrib/apps/templates。已发布或上架的 App 由 STORE_APPS_DIR 控制，默认指向 contrib/apps。资料来源：llmstack/server/settings.py

flowchart LR
    T[App 模板目录<br/>contrib/apps/templates] --> R[注册到平台]
    S[App 商店目录<br/>contrib/apps] --> P[用户浏览/复制]
    R --> U[用户基于模板创建 App]
    P --> U
    U --> D[数据接入 + 模型链]
    D --> Pub[发布/触发]

模板在创建 App 时由前端（React + Craco）发起请求至后端 API。客户端基于 react-scripts 5.0.1 + [email protected] 构建，依赖 react-router-dom 与 recoil 进行路由与状态管理。资料来源：llmstack/client/package.json

常见失败模式：在 App Templates 中创建 File Chat 类应用时，若 config 列未正确迁移，可能触发 psycopg2.errors.UndefinedColumn: column "config ... 错误。资料来源：社区 issue #304

Agent（智能体）与多提供商接入

LLMStack 的 Agent 概念涵盖 AI SDR（销售代表）、Research Analyst（投研分析师）、RPA 自动化 等场景，由 LLM 调用外部工具（搜索、浏览器、第三方 API）协同完成复杂任务。资料来源：README.md

每个外部能力以 Provider 形式注入，平台在 settings.py 中以列表方式声明提供商及其配置 Schema。下表汇总了部分可见的 Provider：

Provider	用途	关键配置 Schema
LinkedIn	销售触达	`linkedin` 包
Apollo	销售情报	`ApolloProviderConfig`
HeyGen	AI 视频生成	`heygen` 包
Mistral	LLM 调用	`MistralProviderConfig`
Meta	LLM 调用	`MetaProviderConfig`
Pinecone / Qdrant / Singlestore	向量库后端	对应 `*ProviderConfig`
Weaviate	默认向量库	通过 `WEAVIATE_URL` 连接

资料来源：llmstack/server/settings.py

向量化数据由 llmstack/base/management/commands/dumpvectordata.py 中的 dumpvectordata 管理命令导出，该命令使用 weaviate.Client 连接 Weaviate 服务并按 Class 拉取对象与 Schema。资料来源：llmstack/base/management/commands/dumpvectordata.py

企业关注点：社区提出了对无代码 Agent 的治理与合规层（Governance & Compliance）的需求，建议在 Agent 链路上自动产出审计日志与策略执行中间件（如 asqav），以满足企业上线要求。资料来源：社区 issue #308

Sheets（AI 表格）

Sheets 是 LLMStack 在 v0.2.5 中引入的新型产物，本质上是一类由 AI 驱动的、面向结构化数据生成与编辑的 App。其模板与代码位置独立维护：

模板目录通过 SHEET_TEMPLATES_DIR 注入，默认值为 contrib/sheets。资料来源：llmstack/server/settings.py
配套功能包括 AI sheet builder（v0.2.5 推出）以及 v0.2.4 引入的「Token 使用量统计」与「消息反馈」机制。资料来源：Release v0.2.4、v0.2.5

Sheets 与传统 App 的差异在于：用户在一个表格化的画布上定义列与提示词，平台按行触发 LLM 生成结果并保留历史与可重跑能力。

多通道接入（Slack / Discord / Voice / Twilio）

平台允许将构建好的 AI 链作为后端响应外部触发，README 明确提到 Discord 与 Slack 机器人 集成。资料来源：README.md

在 v0.2.6 中进一步引入了：

Voice agents（语音智能体）：基于 OpenAI Realtime API 实现实时语音对话。资料来源：Release v0.2.6
Twilio 语音集成：通过 Twilio 桥接 PSTN/电话网络，使 Agent 可通过电话交互。资料来源：Release v0.2.6

触发链路可视为：外部渠道（Slack/Discord/Voice） → 平台 Webhook/Router → App/Agent 运行时 → LLM 链执行 → 渠道回写。

文档与网站

web/ 目录是基于 Docusaurus 2 的产品文档站，使用 Docusaurus 3.x 的模块类型别名，运行需要 node >= 18.0。本地预览命令为 yarn start，部署可通过 yarn deploy 推送到 gh-pages 分支。资料来源：web/package.json、web/README.md

文档站首页嵌入 YouTube 演示视频（P9VoR8WPy7E）与 GitHub Star 按钮，并对外引导到云端产品 trypromptly.com。资料来源：web/src/pages/index.js

数据管理、连接与 LLM 集成

LLMStack 是一个面向生成式 AI 的无代码（no-code）平台，其核心能力之一是让用户能够在不编写代码的前提下，把自有数据、第三方业务工具与多家大语言模型（LLM）连接起来，从而构建 AI 代理、工作流与聊天机器人。平台内置数据导入、预处理、向量化、检索与多模型串联等能力，支持云端与本地化部署，并以多租户（multi-tenant）方式组织数据与权限。资料来源：R...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

在数据流转方面，LLMStack 默认使用 Weaviate 作为向量数据库，PostgreSQL 作为业务数据库，Redis 作为缓存/队列，RQ Worker 执行后台任务。该运行时栈由 Django（WSGI 入口）驱动，对外暴露 Web 与 HTTP API 两种访问形式。资料来源：llmstack/server/wsgi.py、llmstack/base/management/commands/dumpvectordata.py

多 LLM 与第三方服务集成

LLMStack 通过统一的 Provider 机制接入各类模型与外部服务，便于在无代码编辑器里“按提供商”选择与切换。settings.py 中预置了多家主流 LLM 与业务数据提供商的注册信息，包括：

类别	代表性集成	配置 schema
通用 LLM	OpenAI、Cohere、Stability AI、Hugging Face	平台默认启用
商业 LLM	Mistral、Meta	`MistralProviderConfig`、`MetaProviderConfig`
向量数据库	Pinecone、Qdrant、Singlestore、Weaviate	各提供商独立 schema
业务工具	LinkedIn、Apollo、HeyGen	LinkedIn / Apollo / HeyGen

资料来源：llmstack/server/settings.py

每个 Provider 通过 processor_packages 字段声明其处理器（processor）所在的 Python 包路径，并通过可选的 config_schema 字段暴露基于 Pydantic 的配置类，从而在管理面板里以表单形式收集 API Key、模型参数等敏感信息。这种注册表机制使得新增一个 LLM 或数据源只需新增一个 Provider 条目和对应的 processor 包。资料来源：llmstack/server/settings.py

自 v0.2.6 起，平台还引入了基于 OpenAI Realtime API 的语音代理（Voice agents）以及 Twilio 语音集成，使电话/语音通道可以作为 LLM 应用的输入与输出。资料来源：v0.2.6 Release

数据导入、向量化与存储

平台对外支持多种数据形态与来源，常见类型包括 CSV、TXT、PDF、DOCX、PPTX 等；常见来源涵盖 Google Drive、Notion、网站 URL、Sitemap、音频以及直接上传。资料来源：README.md

数据在进入平台后会自动执行预处理与向量化，并向量化结果写入所选的向量数据库。默认情况下，Weaviate 作为内置向量库；dumpvectordata 管理命令通过 Weaviate HTTP API（/v1/schema）导出 schema，并使用 weaviate.Client 操作 class/object，展示了 LLMStack 与 Weaviate 之间的交互契约。资料来源：llmstack/base/management/commands/dumpvectordata.py

业务数据则由 Django ORM 写入 PostgreSQL，静态资源、生成文件、用户资产与公开资产分别落在不同目录，可通过 STATIC_URL、GENERATEDFILES_ROOT、ASSETS_ROOT、PUBLIC_ASSETS_ROOT 等环境变量自定义。该分层设计有助于在容器化部署时把易变数据（生成文件、资产）持久化到独立卷。资料来源：llmstack/server/settings.py

社区提示：v0.2.5/v0.2.4 引入的 Sheets 模块与 AI Sheet Builder 让结构化数据可以在界面中以“表”的方式维护，并参与检索增强生成（RAG）。如果遇到类似 issue #304 中“column config”未定义的报错，多与数据库迁移未完成有关，建议先执行 makemigrations 与 migrate 再重启 API 容器。资料来源：v0.2.5 Release、v0.2.4 Release

数据流与运行时架构

下图概括了一次典型的“用户请求 → 数据检索 → 多模型串联 → 响应返回”的端到端流程：

flowchart LR
    U[用户/前端 React 18] -->|HTTP/API| A[Django API (WSGI)]
    A -->|鉴权 & 编排| O[Apps / Agents 编排层]
    O -->|读取/写入| DB[(PostgreSQL)]
    O -->|任务入队| RQ[Redis + RQ Worker]
    O -->|语义检索| VDB[(Weaviate / Pinecone / Qdrant / Singlestore)]
    O -->|调用模型| P[Provider 注册表]
    P --> M1[OpenAI / Mistral / Meta]
    P --> M2[Hugging Face / Cohere / Stability AI]
    P --> M3[LinkedIn / Apollo / HeyGen / Twilio]
    M1 & M2 & M3 --> O
    O -->|流式响应| U

资料来源：README.md、llmstack/server/settings.py、llmstack/server/wsgi.py

编排层是无代码编辑器的核心：用户在 Web UI 中拖拽节点即可把“输入 → 检索 → Prompt → 模型 A → 模型 B → 输出”拼装成一条 AI Chain；该 Chain 在运行时由 RQ Worker 异步执行，长任务可水平扩展。资料来源：README.md

前端方面，客户端使用 React 18 + Recoil + styled-components，并集成 Lexical 富文本、PDF.js、react-papaparse 等库用于文档解析、表格展示与富输入，使终端用户在上传 PDF/PPTX/CSV 时即可获得与 LLM 链配套的解析体验。资料来源：llmstack/client/package.json

常见部署与连接故障

社区中频繁出现的故障多集中在“安装与连接”阶段，了解这些模式有助于快速定位问题：

Docker 未运行：在 macOS 上执行 llmstack 启动命令时若报 Cannot connect to the Docker daemon at unix:///var/run/docker.sock，需先启动 Docker Desktop。资料来源：issue #298
PostgreSQL 密码认证失败：常见于 docker/.env.dev 中默认密码与容器期望值不一致，需确保 .env 中 POSTGRES_PASSWORD 与应用配置一致。资料来源：issue #286
ALLOWED_HOSTS 不匹配：通过 pipx 安装后，访问 http://localhost 可能因 Host 头校验失败，需在 Django settings 中将对应域名加入 ALLOWED_HOSTS。资料来源：issue #291
Windows 下 NamedTemporaryFile 锁：CLI 启动时未及时关闭临时文件，导致 docker compose --env-file 失败。资料来源：issue #299
新装迁移失败：v0.2.6 等版本在干净数据库上执行迁移时可能因 Pydantic v2 兼容性问题报错，建议对照迁移日志逐项修复。资料来源：issue #288

部署、安装、运维与常见故障

LLMStack 是一个面向生成式 AI 的无代码平台，官方在 README.md 中明确提供了两条交付路径：自托管（本地或私有部署）与云端 SaaS（Promptly）。README 列出的核心项目括：多模型链式调用（Chain multiple models）、自有数据接入（CSV / TXT / PDF / DOCX / PPTX 等）、Slack / Discor...

章节 相关页面

继续阅读本节完整说明和来源证据。

项目概览与安装路径

对于自托管场景，README 推荐通过 pip install llmstack 后调用 llmstack 命令启动，CLI 会拉起一组 Docker 容器作为运行时依赖。这一交付形态是社区反馈最集中的部分——多数 bug 报告均出现在 pip install + llmstack 命令链路中。

后端运行时：WSGI 与 Django 配置

后端基于 Django 4.2，llmstack/server/wsgi.py 通过 DJANGO_SETTINGS_MODULE=llmstack.server.settings 暴露标准的 WSGI 应用，可被 Gunicorn / uWSGI 等 ASGI/WSGI 服务器直接包装。容器化运行时由 Docker Compose 编排，API 服务在启动时会执行迁移、收集静态资源并启动 RQ Worker。

llmstack/server/settings.py 中与环境强相关的几类配置包括：

存储目录：通过 GENERATEDFILES_ROOT、ASSETS_ROOT、PUBLIC_ASSETS_ROOT 环境变量切换生成文件、资产和公共资产的位置，对应 FileSystemStorage 后端。
模板目录：APP_TEMPLATES_DIR、SHEET_TEMPLATES_DIR、DATA_PIPELINES_DIR、STORE_APPS_DIR 默认指向仓库内 contrib/apps、contrib/sheets、contrib/data/pipelines，可通过同名环境变量覆盖为自定义路径。
第三方 Provider：内置 OpenAI、Anthropic、Google、Cohere、Stability、HuggingFace、Mistral、Meta、Pinecone、Qdrant、Singlestore、Weaviate、LinkedIn、Apollo、HeyGen 等，通过 config_schema 指向各自的 Pydantic 配置模型。

向量化数据可通过 llmstack/base/management/commands/dumpvectordata.py 中定义的 dumpvectordata 管理命令导出，它封装了 weaviate.Client(WEAVIATE_URL) 并提供 WeaviateSchema / WeaviateClassObject 等模型，便于备份或迁移向量库。

flowchart LR
  User[用户浏览器] --> Frontend[React 前端<br/>craco build]
  Frontend -->|REST/WS| Django[Django API<br/>WSGI]
  Django --> Redis[(Redis<br/>缓存/队列)]
  Django --> Postgres[(Postgres 16)]
  Django --> Weaviate[(Weaviate<br/>向量库)]
  Django --> RQ[RQ Worker]
  RQ --> Providers[第三方模型 Provider]

前端与文档站点的构建

主前端位于 llmstack/client，使用 Create React App + Craco 构建（llmstack/client/package.json）。scripts.build 调起 craco build，产物落到 client/build/static 并由 Django 通过 STATICFILES_DIRS 直接托管（见 settings.py）。

文档站点 web/ 使用 Docusaurus 3 构建（web/package.json 与 web/README.md）。本地开发：yarn start；生产构建：yarn build；部署到 GitHub Pages：USE_SSH=true yarn deploy 或 GIT_USER=<user> yarn deploy。首页 web/src/pages/index.js 通过 ReactPlayer 内嵌 YouTube 演示，并链接到云端和自托管文档。

常见故障与排查

下表汇总了社区 issue 中高频出现、与部署/安装直接相关的故障，结合源码给出定位方向。

故障现象	触发条件	源码定位	处理建议
`llmstack doesn't start on a fresh install`（#297）	Python 3.12 + Conda，CLI 启动失败	CLI 通过 Docker Compose 拉起运行时	确认 Docker Desktop/daemon 运行；降低 Python 版本至 3.11
`Cannot connect to the Docker daemon at unix:///var/run/docker.sock`（#298）	Docker 未启动	CLI 调用 Docker SDK 拉取镜像	`brew services start docker` 或启用 Docker Desktop
Windows 下 `NamedTemporaryFile` 文件锁导致 Docker 拒绝 `--env-file`（#299）	Windows 平台	CLI 写临时 env 文件给 `docker compose`	升级到修复版本，或在 Windows 上改用 WSL2
新装迁移失败 `psycopg2.errors.UndefinedColumn` 与 Pydantic V2 错误（#288、#304）	Postgres 16 全新安装	Django migration / File Chat App 配置列	重新执行 `manage.py migrate`；检查 `app.config` 列是否存在
`pull access denied for llmstack-app`（#295）	开发 compose 引用本地镜像	`docker-compose.dev.yml` 引用未构建的镜像	先执行 `docker build` 或切换到发布版标签
`password authentication failed for user "llmstack"`（#286）	0.2.5 容器启动后 Postgres 鉴权失败	数据库用户密码不匹配	同步 `POSTGRES_PASSWORD` 环境变量后重启 `postgres` 容器
`Disallowed Host - invalid host header`（#291）	自定义域名访问	Django `ALLOWED_HOSTS` 未配置	在 `.env` 中设置 `ALLOWED_HOSTS=your.domain.com`

补充运维注意事项：

版本选择：参考 v0.2.6 起引入 Voice Agents（OpenAI Realtime + Twilio），早期版本可能缺少对应配置字段；如不需语音能力，可停留在 0.2.5（Sheets 首发版本）。
资产持久化：ASSETS_ROOT 与 PUBLIC_ASSETS_ROOT 默认指向 /home/appuser/data/，容器重建前务必挂载卷，否则生成的图片/视频/PPT 会丢失。
向量库迁移：dumpvectordata 管理命令会读取 WEAVIATE_URL 并以 Pydantic 模型反序列化 schema，迁移到新集群时建议先导出对象、再在新集群上恢复。
环境变量模板：自托管首次运行前，应将 POSTGRES_PASSWORD、DJANGO_SECRET_KEY、ALLOWED_HOSTS、OAuth Provider 凭据（如 CONNECTION_GOOGLE_CLIENT_ID）写入 .env，避免容器重启后鉴权或回调失效。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Bug in file chat app

可能增加新用户试用和生产接入成本。

high 来源证据：Disallowed Host - invalid host header - you may need to add ... to ALLOWED_HOSTS

可能增加新用户试用和生产接入成本。

high 来源证据：https://docs.trypromptly.com/llmstack/development Getting error when running docker compose for running in dev environm…

可能增加新用户试用和生产接入成本。

high 来源证据：LLMStack fails to start when performing migration on fresh install

可能影响升级、迁移或版本选择。

Pitfall Log / 踩坑日志

项目：trypromptly/LLMStack

摘要：发现 15 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug in file chat app。

1. 安装坑 · 来源证据：Bug in file chat app

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug in file chat app
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/trypromptly/LLMStack/issues/304 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Disallowed Host - invalid host header - you may need to add ... to ALLOWED_HOSTS

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Disallowed Host - invalid host header - you may need to add ... to ALLOWED_HOSTS
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/trypromptly/LLMStack/issues/291 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：https://docs.trypromptly.com/llmstack/development Getting error when running docker compose for running in dev environm…

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：https://docs.trypromptly.com/llmstack/development Getting error when running docker compose for running in dev environment
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/trypromptly/LLMStack/issues/295 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

4. 安全/权限坑 · 来源证据：LLMStack fails to start when performing migration on fresh install

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LLMStack fails to start when performing migration on fresh install
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/trypromptly/LLMStack/issues/288 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安全/权限坑 · 来源证据：connection to server at "postgres" (172.18.0.3), port 5432 failed: FATAL: password authentication failed for user "llms…

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：connection to server at "postgres" (172.18.0.3), port 5432 failed: FATAL: password authentication failed for user "llmstack"
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/trypromptly/LLMStack/issues/286 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 安全/权限坑 · 来源证据：llmstack doesn't start on a fresh install.

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：llmstack doesn't start on a fresh install.
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/trypromptly/LLMStack/issues/297 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：Docker CLI fails on Windows due to NamedTemporaryFile lock — unable to start containers

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docker CLI fails on Windows due to NamedTemporaryFile lock — unable to start containers
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/trypromptly/LLMStack/issues/299 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

8. 安装坑 · 来源证据：Feature: Governance and compliance layer for no-code agents

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature: Governance and compliance layer for no-code agents
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/trypromptly/LLMStack/issues/308 | 来源类型 github_issue 暴露的待验证使用条件。

9. 安装坑 · 来源证据：very buggy

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：very buggy
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/trypromptly/LLMStack/issues/298 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

10. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/trypromptly/LLMStack | README/documentation is current enough for a first validation pass.

11. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/trypromptly/LLMStack | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/trypromptly/LLMStack | no_demo; severity=medium

13. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/trypromptly/LLMStack | no_demo; severity=medium

14. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/trypromptly/LLMStack | issue_or_pr_quality=unknown

15. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/trypromptly/LLMStack | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

LLMStack 项目

LLMStack 概览与系统架构

一、项目定位与核心价值

二、系统架构总览

三、关键模块组成

3.1 Django 应用划分

3.2 处理器与模型供应商（Providers）

3.3 前端与构建链

四、近期演进与社区关注点

See Also

核心功能：App、Agent、Sheets 与多通道接入

概述

App（应用）与模板体系

Agent（智能体）与多提供商接入

Sheets（AI 表格）

多通道接入（Slack / Discord / Voice / Twilio）

文档与网站

See Also

数据管理、连接与 LLM 集成

概述

多 LLM 与第三方服务集成

数据导入、向量化与存储

数据流与运行时架构

常见部署与连接故障

See Also

部署、安装、运维与常见故障

项目概览与安装路径

后端运行时：WSGI 与 Django 配置

前端与文档站点的构建

常见故障与排查

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安装坑 · 来源证据：Bug in file chat app

2. 安装坑 · 来源证据：Disallowed Host - invalid host header - you may need to add ... to ALLOWED_HOSTS

3. 安装坑 · 来源证据：https://docs.trypromptly.com/llmstack/development Getting error when running docker compose for running in dev environm…

4. 安全/权限坑 · 来源证据：LLMStack fails to start when performing migration on fresh install

5. 安全/权限坑 · 来源证据：connection to server at "postgres" (172.18.0.3), port 5432 failed: FATAL: password authentication failed for user "llms…

6. 安全/权限坑 · 来源证据：llmstack doesn't start on a fresh install.

7. 安装坑 · 来源证据：Docker CLI fails on Windows due to NamedTemporaryFile lock — unable to start containers

8. 安装坑 · 来源证据：Feature: Governance and compliance layer for no-code agents

9. 安装坑 · 来源证据：very buggy

10. 能力坑 · 能力判断依赖假设

11. 维护坑 · 维护活跃度未知

13. 安全/权限坑 · 存在评分风险

14. 维护坑 · issue/PR 响应质量未知

15. 维护坑 · 发布节奏不明确