# https://github.com/trypromptly/LLMStack 项目说明书

生成时间：2026-06-18 19:51:40 UTC

## 目录

- [LLMStack 概览与系统架构](#page-1)
- [核心功能：App、Agent、Sheets 与多通道接入](#page-2)
- [数据管理、连接与 LLM 集成](#page-3)
- [部署、安装、运维与常见故障](#page-4)

<a id='page-1'></a>

## LLMStack 概览与系统架构

### 相关页面

相关主题：[核心功能：App、Agent、Sheets 与多通道接入](#page-2), [部署、安装、运维与常见故障](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md)
- [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py)
- [llmstack/server/urls.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/urls.py)
- [llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py)
- [llmstack/server/asgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/asgi.py)
- [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json)
- [web/package.json](https://github.com/trypromptly/LLMStack/blob/main/web/package.json)
- [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js)
- [web/README.md](https://github.com/trypromptly/LLMStack/blob/main/web/README.md)
</details>

# LLMStack 概览与系统架构

## 一、项目定位与核心价值

LLMStack 是一个**开源的无代码（no-code）平台**，用于构建生成式 AI Agent、工作流与聊天机器人，并将其与用户自有数据和业务流程对接。它由 [Promptly](https://trypromptly.com) 团队维护，既可以部署在云端，也可以本地化（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]()

```mermaid
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]()

## See Also

- 官方文档：[docs.trypromptly.com/llmstack/introduction](https://docs.trypromptly.com/llmstack/introduction)
- 开发指南：[docs.trypromptly.com/llmstack/development](https://docs.trypromptly.com/llmstack/development)

---

<a id='page-2'></a>

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

### 相关页面

相关主题：[LLMStack 概览与系统架构](#page-1), [数据管理、连接与 LLM 集成](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md)
- [web/src/components/HomepageFeatures/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/components/HomepageFeatures/index.js)
- [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js)
- [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py)
- [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py)
- [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json)
- [web/package.json](https://github.com/trypromptly/LLMStack/blob/main/web/package.json)
</details>

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

## 概述

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

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

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

```mermaid
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` + `react@18.2.0` 构建，依赖 `react-router-dom` 与 `recoil` 进行路由与状态管理。资料来源：[llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/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](https://github.com/trypromptly/LLMStack/blob/main/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](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py)

向量化数据由 `llmstack/base/management/commands/dumpvectordata.py` 中的 `dumpvectordata` 管理命令导出，该命令使用 `weaviate.Client` 连接 Weaviate 服务并按 Class 拉取对象与 Schema。资料来源：[llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/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](https://github.com/trypromptly/LLMStack/blob/main/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](https://github.com/trypromptly/LLMStack/blob/main/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](https://github.com/trypromptly/LLMStack/blob/main/web/package.json)、[web/README.md](https://github.com/trypromptly/LLMStack/blob/main/web/README.md)

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

## See Also

- [架构总览：Server、Client 与 CLI](architecture-overview.md)
- [数据接入与向量化](data-ingestion-and-vectorization.md)
- [部署与运行：Docker / 本地 pip 安装](deployment-and-runtime.md)
- [Provider 接入指南](provider-integration.md)

---

<a id='page-3'></a>

## 数据管理、连接与 LLM 集成

### 相关页面

相关主题：[核心功能：App、Agent、Sheets 与多通道接入](#page-2), [部署、安装、运维与常见故障](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md)
- [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py)
- [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py)
- [llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py)
- [web/src/components/HomepageFeatures/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/components/HomepageFeatures/index.js)
- [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js)
- [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json)
- [llmstack/client/README.md](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/README.md)
</details>

# 数据管理、连接与 LLM 集成

## 概述

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

在数据流转方面，LLMStack 默认使用 Weaviate 作为向量数据库，PostgreSQL 作为业务数据库，Redis 作为缓存/队列，RQ Worker 执行后台任务。该运行时栈由 Django（WSGI 入口）驱动，对外暴露 Web 与 HTTP API 两种访问形式。资料来源：[llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py)、[llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/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](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py)

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

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

## 数据导入、向量化与存储

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

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

业务数据则由 Django ORM 写入 PostgreSQL，静态资源、生成文件、用户资产与公开资产分别落在不同目录，可通过 `STATIC_URL`、`GENERATEDFILES_ROOT`、`ASSETS_ROOT`、`PUBLIC_ASSETS_ROOT` 等环境变量自定义。该分层设计有助于在容器化部署时把易变数据（生成文件、资产）持久化到独立卷。资料来源：[llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/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](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.5)、[v0.2.4 Release](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.4)

## 数据流与运行时架构

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

```mermaid
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](https://github.com/trypromptly/LLMStack/blob/main/README.md)、[llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py)、[llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py)

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

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

## 常见部署与连接故障

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

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

## See Also

- [LLMStack 总览与快速开始](https://docs.trypromptly.com/llmstack/introduction)
- [开发与本地运行指南](https://docs.trypromptly.com/llmstack/development)
- [贡献指南](https://docs.trypromptly.com/llmstack/contributing)
- [v0.2.6 发布说明（Voice Agents / Twilio）](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.6)
- [v0.2.5 发布说明（Sheets / AI Sheet Builder）](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.5)

---

<a id='page-4'></a>

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

### 相关页面

相关主题：[LLMStack 概览与系统架构](#page-1), [数据管理、连接与 LLM 集成](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md)
- [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py)
- [llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py)
- [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py)
- [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json)
- [web/package.json](https://github.com/trypromptly/LLMStack/blob/main/web/package.json)
- [web/README.md](https://github.com/trypromptly/LLMStack/blob/main/web/README.md)
- [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js)
- [web/src/components/HomepageFeatures/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/components/HomepageFeatures/index.js)
</details>

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

## 项目概览与安装路径

LLMStack 是一个面向生成式 AI 的无代码平台，官方在 [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) 中明确提供了两条交付路径：自托管（本地或私有部署）与云端 SaaS（[Promptly](https://trypromptly.com)）。README 列出的核心能力包括：多模型链式调用（Chain multiple models）、自有数据接入（CSV / TXT / PDF / DOCX / PPTX 等）、Slack / Discord 触发、无代码构建器，以及云端或本地双部署形态。

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

## 后端运行时：WSGI 与 Django 配置

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

[llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/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` 等模型，便于备份或迁移向量库。

```mermaid
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](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json)）。`scripts.build` 调起 `craco build`，产物落到 `client/build/static` 并由 Django 通过 `STATICFILES_DIRS` 直接托管（见 [settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py)）。

文档站点 `web/` 使用 Docusaurus 3 构建（[web/package.json](https://github.com/trypromptly/LLMStack/blob/main/web/package.json) 与 [web/README.md](https://github.com/trypromptly/LLMStack/blob/main/web/README.md)）。本地开发：`yarn start`；生产构建：`yarn build`；部署到 GitHub Pages：`USE_SSH=true yarn deploy` 或 `GIT_USER=<user> yarn deploy`。首页 [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/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` |

补充运维注意事项：

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

## See Also

- [LLMStack 主仓库](https://github.com/trypromptly/LLMStack)
- [官方文档站](https://docs.trypromptly.com/llmstack/introduction)
- [开发环境指南](https://docs.trypromptly/LLMStack/blob/main/docs.trypromptly.com/llmstack/development)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: trypromptly/LLMStack; human_manual_source: deepwiki_human_wiki -->