# https://github.com/invoke-ai/InvokeAI 项目说明书

生成时间：2026-07-24 23:01:05 UTC

## 目录

- [项目概览](#page-overview)
- [Lib 模块](#page-invokeai-frontend-web-src-features-cropper-lib)
- [Api 模块](#page-invokeai-app-api)
- [App 模块](#page-invokeai-frontend-web-src-app)

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

## 项目概览

### 相关页面

相关主题：[Lib 模块](#page-invokeai-frontend-web-src-features-cropper-lib)

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

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

- [README.md](https://github.com/invoke-ai/InvokeAI/blob/main/README.md)
- [docker/Dockerfile](https://github.com/invoke-ai/InvokeAI/blob/main/docker/Dockerfile)
- [docker/README.md](https://github.com/invoke-ai/InvokeAI/blob/main/docker/README.md)
- [invokeai/app/invocations/custom_nodes/README.md](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/invocations/custom_nodes/README.md)
- [invokeai/app/services/shared/README.md](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/services/shared/README.md)
- [invokeai/app/services/workflow_records/default_workflows/README.md](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/services/workflow_records/default_workflows/README.md)
</details>

# 项目概览

InvokeAI 是一个面向 Stable Diffusion 及同类扩散模型创作者的开源生成引擎，提供从文字到图像（Text2Image）、图像到图像（Image2Image）、局部重绘（Inpainting）到节点化工作流的完整工具链。本页基于仓库根目录与子模块的官方文档，勾勒项目的定位、核心能力、体系结构与部署形态。

## 一、项目定位与目标

InvokeAI 的核心目标是构建一套可本地化部署、可扩展、跨硬件的生成式 AI 创作平台。项目同时面向终端创作者（通过 Web UI、Canvas、Launcher）与开发者（通过 Python 包、节点系统、API）。

- 提供官方桌面启动器（Launcher）与基于浏览器的统一界面，避免手工环境配置。
- 通过节点编辑器（Node Editor）支持将多次生成、ControlNet、放大、合成等步骤串联为可复用工作流。
- 通过 `invokeai.yaml`、`api_keys.yaml` 等配置文件集中管理模型、密钥与运行参数。

资料来源：[README.md](https://github.com/invoke-ai/InvokeAI/blob/main/README.md)

## 二、核心能力概览

下表汇总社区与版本说明中提到的关键能力，便于快速建立认知。

| 能力类别 | 主要内容 |
| --- | --- |
| 基础生成 | Txt2Img、Img2Img、Inpainting（含 SDXL 模型） |
| 高级控制 | ControlNet、PatchMatch 修复、节点化工作流 |
| 模型支持 | SDXL、FLUX.1、FLUX.2、Z-Image Turbo、Qwen Image 等 |
| 硬件适配 | NVIDIA CUDA、AMD ROCm（含 gfx1151）、CPU 回退 |
| 协作与扩展 | 多账户实验模式、自定义节点、默认工作流模板 |
| 安全维护 | 6.13.7 起针对 `invokeai.yaml`、`api_keys.yaml` 的安全补丁 |

社区中关于 FLUX.1、Z-Image Turbo、Flux.2、ControlNet、AnimatedDiff 的增强请求长期居高不下，反映出“模型兼容性”与“控制能力”是用户最关注的方向。资料来源：[invokeai/app/services/workflow_records/default_workflows/README.md](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/services/workflow_records/default_workflows/README.md)

## 三、系统架构与组件

InvokeAI 后端采用 Python 包形式组织，主要由以下逻辑层构成：

1. **应用层（App / Invocations）**：定义节点调用（Invocation），是节点编辑器与外部 API 的统一抽象。`custom_nodes` 子目录为第三方扩展提供注册入口。
2. **服务层（Services）**：包括会话、模型管理、图像处理、工作流记录、共享服务（`shared`）等。共享服务用于在多个上下文间复用配置与状态。
3. **工作流层（Workflows）**：`default_workflows` 目录存放官方提供的模板工作流，用户可在此基础上二次开发。
4. **前端层**：基于浏览器的 Web UI 与 Canvas，与后端通过 REST/WS 协议通信。

```mermaid
graph TD
  UI[Web UI / Canvas] --> API[InvokeAI API]
  API --> INV[Invocations / 节点]
  INV --> SVC[Services]
  SVC --> MOD[Models / Images]
  WF[默认工作流] --> INV
  CN[自定义节点] --> INV
```

社区曾报告“移动节点选中文本导致 UI 卡顿”（#9285）等前端稳定性问题，提示 UI 与节点层之间的交互需要进一步打磨。资料来源：[invokeai/app/invocations/custom_nodes/README.md](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/invocations/custom_nodes/README.md)、[invokeai/app/services/shared/README.md](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/services/shared/README.md)

## 四、部署形态与扩展性

InvokeAI 提供三种主流部署路径：

- **Launcher 桌面安装器**：面向普通用户，自动管理 Python 环境、模型下载与更新；近期在 RTX 50 系列上报告过启动崩溃（#9164），需关注驱动与 CUDA 兼容性。
- **Docker 镜像**：通过 `docker/Dockerfile` 构建，文档说明见 `docker/README.md`，适合服务器与 CI 场景。
- **手动/源码安装**：面向高级用户与开发者，便于自定义依赖与接入新模型（如 ROCm gfx1151 等较新硬件，见 #8655）。

扩展性方面，开发者可通过自定义节点（Custom Nodes）注册新的 Invocation，将其与默认工作流组合形成新能力；企业或团队也可在多账户模式下共用同一后端（自 v6.12.0 起为实验特性）。资料来源：[docker/Dockerfile](https://github.com/invoke-ai/InvokeAI/blob/main/docker/Dockerfile)、[docker/README.md](https://github.com/invoke-ai/InvokeAI/blob/main/docker/README.md)

## 五、社区关注点速览

结合 Issue 与 Release 信息，当前社区的焦点集中在：

- **新模型支持**：FLUX.2、Z-Image Turbo、Qwen Image 等持续被请求。
- **离线与无网络环境**：Z-Image Turbo 在断网时无法生成的报告（#9031）凸显本地模型缓存的必要性。
- **跨平台兼容**：NVIDIA Blackwell、AMD gfx1151、CPU 模式（PatchMatch ABI 问题 #9287）等环境差异仍是主要摩擦点。
- **安全与配置**：v6.13.7 修复了可读取 `invokeai.yaml` / `api_keys.yaml` 的安全缺陷，提示敏感配置文件需要妥善保护。

资料来源：[README.md](https://github.com/invoke-ai/InvokeAI/blob/main/README.md)、[docker/README.md](https://github.com/invoke-ai/InvokeAI/blob/main/docker/README.md)

---

<a id='page-invokeai-frontend-web-src-features-cropper-lib'></a>

## Lib 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Api 模块](#page-invokeai-app-api)

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

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

- [invokeai/frontend/web/src/features/cropper/lib/editor.ts](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/cropper/lib/editor.ts)
- [invokeai/frontend/web/src/features/canvas/lib/canvas.ts](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/canvas/lib/canvas.ts)
- [invokeai/frontend/web/src/features/nodes/util/graphUtils.ts](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/features/nodes/util/graphUtils.ts)
- [invokeai/backend/util/torch_utils.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/backend/util/torch_utils.py)
- [invokeai/backend/lora/lora.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/backend/lora/lora.py)
- [invokeai/backend/patches/lora_patches.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/backend/patches/lora_patches.py)
- [invokeai/backend/image_util/invokeai_patchmatch.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/backend/image_util/invokeai_patchmatch.py)
</details>

# Lib 模块

## 概述与定位

Lib 模块是 InvokeAI 项目中用于封装可复用业务逻辑、工具函数与算法实现的代码层，贯穿前后端架构。在设计原则上遵循"功能内聚、依赖最小"，主要承担三类职责：

- **抽象业务能力**：将重复使用的能力（图像裁剪、画布几何、张量处理、模型权重加载等）从 UI 组件或服务入口中剥离，提升复用性并降低耦合。
- **隔离副作用**：将涉及原生扩展（CUDA/ROCm、PatchMatch C++ 绑定）的代码集中管理，便于版本对齐与问题定位。
- **桥接上层与底层**：作为 React 组件、FastAPI 路由与底层模型之间的纯函数层，方便单元测试与跨平台打包。

资料来源：[invokeai/frontend/web/src/features/cropper/lib/editor.ts:1-60]()
资料来源：[invokeai/backend/util/torch_utils.py:1-50]()

## 前端 Lib 子模块

InvokeAI 前端采用 feature-based 目录结构，几乎每个功能目录下都存在 `lib/` 或 `util/` 子目录，集中放置与该功能强绑定的 TypeScript 工具函数。

| 子目录 | 典型职责 |
|--------|----------|
| `features/cropper/lib/` | 图像裁剪编辑器，处理拖拽、缩放、区域坐标换算 |
| `features/canvas/lib/`  | 画布几何变换、撤销/重做栈、序列化与反序列化 |
| `features/nodes/util/`  | 节点图的事件流、参数校验、连接合法性判定 |

这些 lib 文件通常被上层 React 组件直接 `import`，避免在渲染函数内嵌入复杂计算，以减少不必要的重渲染开销。`features/cropper/lib/editor.ts` 中就封装了裁剪框的初始化、约束更新与结果导出逻辑，被 `ImageCropper` 组件复用。

资料来源：[invokeai/frontend/web/src/features/cropper/lib/editor.ts:30-80]()
资料来源：[invokeai/frontend/web/src/features/canvas/lib/canvas.ts:20-90]()
资料来源：[invokeai/frontend/web/src/features/nodes/util/graphUtils.ts:15-60]()

## 后端 Lib 子模块

后端 lib 主要位于 `invokeai/backend/util/`、`invokeai/backend/lora/`、`invokeai/backend/patches/` 与 `invokeai/backend/image_util/` 目录，承担与 PyTorch、模型 I/O 及原生扩展相关的底层能力。

### 关键组件

- **torch_utils**：封装设备检测、精度管理、显存统计与张量移动，被多个生成流程复用。
- **lora 模块**：实现 LoRA / LoHA / LoCon 等适配器权重的加载、合并与卸载，直接影响显存占用与推理速度。
- **patches**：集中放置对 diffusers、transformers 等第三方库的 monkey-patch，避免补丁逻辑散落在业务代码中。
- **invokeai_patchmatch**：封装 C++ PatchMatch 扩展，提供图像修复与无缝克隆能力。

资料来源：[invokeai/backend/util/torch_utils.py:40-120]()
资料来源：[invokeai/backend/lora/lora.py:60-150]()
资料来源：[invokeai/backend/patches/lora_patches.py:10-50]()
资料来源：[invokeai/backend/image_util/invokeai_patchmatch.py:20-70]()

## 社区反馈与典型问题

社区中与 lib 模块相关的高频问题集中在原生依赖兼容性与设备适配：

- **PatchMatch 加载失败（#9287）**：由于系统 libtiff/libjpeg 与 InvokeAI 自带版本的 ABI 不一致，导致 `jpeg12_*` 符号在运行时无法解析，发生在 `invokeai_patchmatch` 初始化阶段。建议通过统一容器镜像或预编译 wheel 解决。
- **AMD ROCm gfx1151 支持（#8655）**：与 PyTorch 原生扩展兼容性相关，需要在 `torch_utils` 的设备识别逻辑中扩展对 gfx1151 的分支处理。
- **RTX 50 系列启动崩溃（#9164）**：涉及 CUDA 扩展加载路径，可能需要更新 `torch_utils` 中的 CUDA capability 检测与 SM 版本映射。
- **Z-Image Turbo 离线生成失败（#9031）**：与 `lora` 模块及模型元数据加载链路相关，需保证本地缓存与远端探测逻辑一致。

资料来源：[invokeai/backend/image_util/invokeai_patchmatch.py:25-45]()

## 小结

Lib 模块是 InvokeAI 中连接业务功能与底层依赖的关键层。前端 lib 通过 feature-scoped 工具函数支撑 UI 交互与状态计算，后端 lib 则承担设备适配、模型权重管理与原生扩展绑定。理解 lib 的边界有助于在新功能开发中正确选择代码放置位置，并在依赖冲突时快速定位根因——这也是社区中多数兼容性问题的共同入口。

---

<a id='page-invokeai-app-api'></a>

## Api 模块

### 相关页面

相关主题：[Lib 模块](#page-invokeai-frontend-web-src-features-cropper-lib), [App 模块](#page-invokeai-frontend-web-src-app)

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

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

- [invokeai/app/api/auth_dependencies.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/api/auth_dependencies.py)
- [invokeai/app/api/dependencies.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/api/dependencies.py)
- [invokeai/app/api/extract_metadata_from_image.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/api/extract_metadata_from_image.py)
- [invokeai/app/api/no_cache_staticfiles.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/api/no_cache_staticfiles.py)
- [invokeai/app/api/routers/_access.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/api/routers/_access.py)
- [invokeai/app/api/routers/app_info.py](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/app/api/routers/app_info.py)
</details>

# Api 模块

## 概述与职责

`Api 模块` 位于 `invokeai/app/api/` 目录下，是 InvokeAI 后端对外提供 HTTP 服务的核心层，基于 FastAPI / Starlette 框架构建。它向上层的 Web UI、CLI、第三方集成以及远程托管模型（例如 v6.13.0 引入的 GPT Image 等外部 provider）暴露 RESTful 端点，向下则与 `invokeai/app/services/` 中的领域服务（模型管理、图生图、调度、事件总线等）通过 FastAPI 的依赖注入（`Depends`）机制解耦。

模块的职责可以概括为四点：
1. 注册路由（`APIRouter`），将各功能子模块统一挂载到同一个 `FastAPI` 应用上；
2. 提供统一的鉴权与多用户访问控制原语；
3. 暴露应用自身元信息，便于客户端做能力探测；
4. 提供静态资源与图像元数据相关的辅助工具函数。

资料来源：[invokeai/app/api/dependencies.py:1-40]()

## 依赖注入与鉴权

`dependencies.py` 定义了跨路由复用的 `Depends` 工厂，例如对 `ApiDependencies`、当前用户、会话、图形会话上下文等的解析；这些工厂在每个请求被调用时被 FastAPI 自动注入，从而让路由函数保持纯净，不必自行处理服务查找。`auth_dependencies.py` 则在此之上叠加鉴权能力：v6.12.0 起引入的多用户模式（Multi-User Mode）要求对受保护端点验证 Bearer Token / Session Cookie，未通过校验时统一抛出 `HTTPException`，并由 `_access.py` 中定义的访问控制路由器集中处理拒绝响应。资料来源：[invokeai/app/api/auth_dependencies.py:1-60]() 资料来源：[invokeai/app/api/routers/_access.py:1-50]()

## 路由结构

`invokeai/app/api/routers/` 目录下按业务领域拆分路由，常量命名以下划线开头的文件（如 `_access.py`）表示基础设施类路由，其余则按功能命名（如 `app_info.py`、`images.py`、`session.py`、`model_manager.py` 等）。`app_info.py` 负责返回应用版本、是否启用多用户模式、可用的 provider 后端等元数据，供前端在登录后做能力协商；其它子路由按领域划分，使 Api 模块保持“高内聚、低耦合”的分层结构。资料来源：[invokeai/app/api/routers/app_info.py:1-80]()

下表列出与本页面直接相关的若干文件及其承担的职责：

| 文件 | 主要职责 |
| --- | --- |
| `auth_dependencies.py` | Bearer / Session 鉴权依赖工厂 |
| `dependencies.py` | 通用 `Depends` 工厂，注入领域服务 |
| `routers/_access.py` | 访问控制与拒绝响应处理 |
| `routers/app_info.py` | 应用元信息与能力探测端点 |
| `no_cache_staticfiles.py` | 不缓存的静态资源挂载 |
| `extract_metadata_from_image.py` | 从上传图片中提取 PNG / EXIF 元数据 |

## 静态资源与图像元数据辅助

`no_cache_staticfiles.py` 继承自 Starlette 的 `StaticFiles`，但覆写响应头以禁止浏览器与中间代理缓存，从而保证前端打包产物在版本升级后立即生效——这对 InvokeAI 这种频繁发布的桌面 / 服务端应用尤为重要（参见 v6.13.0、v6.13.7 等多次发布）。`extract_metadata_from_image.py` 提供从 PNG / JPEG 中读取 InvokeAI 自定义块（prompt、seed、模型哈希、ControlNet 配置等）的能力，是图像回灌到工作流、复现生成结果的关键工具。资料来源：[invokeai/app/api/no_cache_staticfiles.py:1-40]() 资料来源：[invokeai/app/api/extract_metadata_from_image.py:1-60]()

## 社区关注点

社区中讨论度较高的话题（如 FLUX.1 / Flux.2 / Z-Image Turbo / ControlNet 等增强请求，以及 #9031 提到的离线场景下生成失败、#9268 中 SDXL 蒙版被忽略等 bug）大多最终落在具体业务路由中——例如 `images.py`、`session.py`、`model_manager.py`——但其依赖注入、鉴权与元信息端点均由本 Api 模块统一承接。理解这一层有助于在排查“无网络时 Z-Image Turbo 加载失败”或“模型切换后元信息错乱”等问题时，从请求生命周期角度定位是鉴权、依赖装配还是路由处理环节出错。

---

<a id='page-invokeai-frontend-web-src-app'></a>

## App 模块

### 相关页面

相关主题：[Api 模块](#page-invokeai-app-api)

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

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

- [invokeai/frontend/web/src/app/components/App.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/app/components/App.tsx)
- [invokeai/frontend/web/src/app/components/AppErrorBoundaryFallback.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/app/components/AppErrorBoundaryFallback.tsx)
- [invokeai/frontend/web/src/app/components/GlobalHookIsolator.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/app/components/GlobalHookIsolator.tsx)
- [invokeai/frontend/web/src/app/components/GlobalImageHotkeys.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/app/components/GlobalImageHotkeys.tsx)
- [invokeai/frontend/web/src/app/components/GlobalModalIsolator.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/app/components/GlobalModalIsolator.tsx)
- [invokeai/frontend/web/src/app/components/InvokeAIUI.tsx](https://github.com/invoke-ai/InvokeAI/blob/main/invokeai/frontend/web/src/app/components/InvokeAIUI.tsx)
</details>

# App 模块

App 模块是 InvokeAI 前端 Web 应用（基于 React + TypeScript）的顶层容器模块，承担应用入口、全局副作用隔离、错误兜底、快捷键路由以及模态层管理职责。该模块位于 `invokeai/frontend/web/src/app/components/` 目录下，由若干互相关联的 React 组件构成，是用户登录后看到的工作台 UI（文本到图像、图像到图像、画布、节点图等）的真正渲染起点。

## 模块职责与组成

App 模块并不直接承担图像生成或模型管理业务，其核心职责是搭建一个**稳定、可恢复、可扩展**的 UI 容器层。其主要组件包括：

- `InvokeAIUI.tsx`：应用最高层壳组件，负责挂载主题提供者、路由以及后续的 App 组件。
- `App.tsx`：核心容器，负责按需启用功能特性、组装主要功能面板与画廊区域，并承载全局副作用。
- `GlobalHookIsolator.tsx`：用于隔离 React 副作用（hooks），保证组件树局部更新不会污染全局状态。
- `GlobalImageHotkeys.tsx`：注册全局图像相关快捷键。
- `GlobalModalIsolator.tsx`：管理全局模态对话框的挂载和层级隔离。
- `AppErrorBoundaryFallback.tsx`：错误边界兜底 UI，在任意子组件抛出未捕获异常时呈现给用户。

## 组件层级与渲染流程

App 模块以 `InvokeAIUI` 为根，向下依次包裹主题、路由与 `App` 组件，再由 `App` 注入全局副作用容器与功能面板。整体层级可概括为：

```mermaid
graph TD
    A[InvokeAIUI] --> B[ThemeProvider / Router]
    B --> C[App]
    C --> D[GlobalHookIsolator]
    C --> E[GlobalImageHotkeys]
    C --> F[GlobalModalIsolator]
    C --> G[AppErrorBoundaryFallback]
    C --> H[主功能面板 / 画廊]
```

资料来源：[invokeai/frontend/web/src/app/components/InvokeAIUI.tsx:1-40]()

`InvokeAIUI` 在最外层只承担「壳」职责，自身并不渲染业务 UI；真正的应用入口落在 `App` 组件中。这样设计的好处是：当未来需要替换主题、添加新的全局 Provider 或嵌入 Electron 外壳时，不必改动业务层。资料来源：[invokeai/frontend/web/src/app/components/InvokeAIUI.tsx:1-60]()

## 全局副作用与隔离

为了在大型 React 应用中避免全局状态被意外覆盖，App 模块引入了三类隔离容器：

| 组件 | 主要职责 | 关键作用 |
|------|---------|----------|
| GlobalHookIsolator | 包裹 hooks 触发的副作用 | 限制 React Portal、事件监听等溢出范围 |
| GlobalModalIsolator | 提供全局模态挂载点 | 统一 z-index 与焦点管理 |
| GlobalImageHotkeys | 注册图像快捷键 | 监听复制/粘贴/保存等图像操作 |

资料来源：[invokeai/frontend/web/src/app/components/GlobalHookIsolator.tsx:1-50]()、[invokeai/frontend/web/src/app/components/GlobalModalIsolator.tsx:1-50]()、[invokeai/frontend/web/src/app/components/GlobalImageHotkeys.tsx:1-50]()

例如，`GlobalImageHotkeys` 会监听浏览器级别的键盘事件，将图像复制、粘贴、下载等行为桥接到 Redux 或 Zustand 等全局 store，从而让 Canvas、Img2Img 等多个功能面板共享同一套快捷键约定。资料来源：[invokeai/frontend/web/src/app/components/GlobalImageHotkeys.tsx:20-80]()

## 错误边界与社区反馈

App 模块使用 `AppErrorBoundaryFallback` 作为兜底组件，包裹在 `App` 树内部。当任意子组件（如 Canvas 渲染、节点编辑器）抛出异常时，React 会卸载出错子树并渲染该兜底 UI，避免白屏。资料来源：[invokeai/frontend/web/src/app/components/AppErrorBoundaryFallback.tsx:1-60]()

社区中曾出现「节点编辑器拖拽文本导致 UI 卡死」的反馈（issue #9285），此类问题往往首先由 App 模块的错误边界捕获，再以可恢复的提示界面呈现给用户，从而降低整页崩溃的概率。资料来源：[invokeai/frontend/web/src/app/components/AppErrorBoundaryFallback.tsx:30-90]()

此外，App 模块也是版本兼容性问题的第一现场：在 v6.13.0 中报告的 SDXL 蒙版丢失（issue #9268）、RTX 50 系列启动崩溃（issue #9164）等 bug，最终都会以 UI 提示或回退界面的形式体现在 App 模块中，便于用户自助排查。

## 小结

App 模块以「壳 + 隔离 + 兜底」三层结构，为 InvokeAI 提供了稳健的前端渲染入口。`InvokeAIUI` 与 `App` 协同搭建容器，`GlobalHookIsolator`、`GlobalModalIsolator`、`GlobalImageHotkeys` 提供横向能力，`AppErrorBoundaryFallback` 则为整页提供安全网。理解该模块是后续阅读 Gallery、Canvas、Node Editor 等功能模块的前提。

---

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

---

## Doramagic 踩坑日志

项目：invoke-ai/InvokeAI

摘要：发现 30 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：[bug]: Add support for ROCm version for gfx1151 (Rocm >= 6.4)。

## 1. 安装坑 · 来源证据：[bug]: Add support for ROCm version for gfx1151 (Rocm >= 6.4)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug]: Add support for ROCm version for gfx1151 (Rocm >= 6.4)
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/8655 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：[bug]: Launcher crashes on startup with breakpoint exception (0x80000003) on systems with NVIDIA RTX 50-series (Blackwe…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug]: Launcher crashes on startup with breakpoint exception (0x80000003) on systems with NVIDIA RTX 50-series (Blackwell) GPUs
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9164 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：[bug]: Move node's selected text hangs/crash the web interface UI

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug]: Move node's selected text hangs/crash the web interface UI
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9285 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：[bug]: PatchMatch fails to load due to libtiff/libjpeg ABI mismatch (jpeg12_* unresolved at runtime)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug]: PatchMatch fails to load due to libtiff/libjpeg ABI mismatch (jpeg12_* unresolved at runtime)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9287 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 来源证据：[bug]: Z-Image Turbo Generation Does Not Work Without Internet Access

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug]: Z-Image Turbo Generation Does Not Work Without Internet Access
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9031 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 6. 安全/权限坑 · 失败模式：security_permissions: [bug]: PatchMatch fails to load due to libtiff/libjpeg ABI mismatch (jpeg12_* unresolved at r...

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [bug]: PatchMatch fails to load due to libtiff/libjpeg ABI mismatch (jpeg12_* unresolved at runtime)
- 对用户的影响：Developers may expose sensitive permissions or credentials: [bug]: PatchMatch fails to load due to libtiff/libjpeg ABI mismatch (jpeg12_* unresolved at runtime)
- 证据：failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/9287 | [bug]: PatchMatch fails to load due to libtiff/libjpeg ABI mismatch (jpeg12_* unresolved at runtime)

## 7. 安全/权限坑 · 来源证据：[bug]: Inpainting mask ignored with SDXL model

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug]: Inpainting mask ignored with SDXL model
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9268 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 8. 安装坑 · 失败模式：installation: InvokeAI 6.13.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: InvokeAI 6.13.0
- 对用户的影响：Upgrade or migration may change expected behavior: InvokeAI 6.13.0
- 证据：failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.13.0 | InvokeAI 6.13.0

## 9. 安装坑 · 失败模式：installation: Version 6.13.0.rc2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Version 6.13.0.rc2
- 对用户的影响：Upgrade or migration may change expected behavior: Version 6.13.0.rc2
- 证据：failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.13.0.rc2 | Version 6.13.0.rc2

## 10. 安装坑 · 失败模式：installation: Version 6.13.0.rc3

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Version 6.13.0.rc3
- 对用户的影响：Upgrade or migration may change expected behavior: Version 6.13.0.rc3
- 证据：failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.13.0.rc3 | Version 6.13.0.rc3

## 11. 安装坑 · 失败模式：installation: [bug]: Add support for ROCm version for gfx1151 (Rocm >= 6.4)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [bug]: Add support for ROCm version for gfx1151 (Rocm >= 6.4)
- 对用户的影响：Developers may fail before the first successful local run: [bug]: Add support for ROCm version for gfx1151 (Rocm >= 6.4)
- 证据：failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/8655 | [bug]: Add support for ROCm version for gfx1151 (Rocm >= 6.4)

## 12. 安装坑 · 失败模式：installation: [bug]: Inpainting mask ignored with SDXL model

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [bug]: Inpainting mask ignored with SDXL model
- 对用户的影响：Developers may fail before the first successful local run: [bug]: Inpainting mask ignored with SDXL model
- 证据：failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/9268 | [bug]: Inpainting mask ignored with SDXL model

## 13. 安装坑 · 失败模式：installation: [bug]: Launcher crashes on startup with breakpoint exception (0x80000003) on systems with NVI...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [bug]: Launcher crashes on startup with breakpoint exception (0x80000003) on systems with NVIDIA RTX 50-series (Blackwell) GPUs
- 对用户的影响：Developers may fail before the first successful local run: [bug]: Launcher crashes on startup with breakpoint exception (0x80000003) on systems with NVIDIA RTX 50-series (Blackwell) GPUs
- 证据：failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/9164 | [bug]: Launcher crashes on startup with breakpoint exception (0x80000003) on systems with NVIDIA RTX 50-series (Blackwell) GPUs

## 14. 安装坑 · 失败模式：installation: [bug]: Move node's selected text hangs/crash the web interface UI

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [bug]: Move node's selected text hangs/crash the web interface UI
- 对用户的影响：Developers may fail before the first successful local run: [bug]: Move node's selected text hangs/crash the web interface UI
- 证据：failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/9285 | [bug]: Move node's selected text hangs/crash the web interface UI

## 15. 安装坑 · 失败模式：installation: [bug]: Z-Image Turbo Generation Does Not Work Without Internet Access

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [bug]: Z-Image Turbo Generation Does Not Work Without Internet Access
- 对用户的影响：Developers may fail before the first successful local run: [bug]: Z-Image Turbo Generation Does Not Work Without Internet Access
- 证据：failure_mode_cluster:github_issue | https://github.com/invoke-ai/InvokeAI/issues/9031 | [bug]: Z-Image Turbo Generation Does Not Work Without Internet Access

## 16. 安装坑 · 失败模式：installation: v6.10.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v6.10.0
- 对用户的影响：Upgrade or migration may change expected behavior: v6.10.0
- 证据：failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.10.0 | v6.10.0

## 17. 安装坑 · 失败模式：installation: v6.10.0rc2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v6.10.0rc2
- 对用户的影响：Upgrade or migration may change expected behavior: v6.10.0rc2
- 证据：failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.10.0rc2 | v6.10.0rc2

## 18. 安装坑 · 失败模式：installation: v6.11.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v6.11.0
- 对用户的影响：Upgrade or migration may change expected behavior: v6.11.0
- 证据：failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.11.0 | v6.11.0

## 19. 安装坑 · 失败模式：installation: v6.12.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v6.12.0
- 对用户的影响：Upgrade or migration may change expected behavior: v6.12.0
- 证据：failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.12.0 | v6.12.0

## 20. 安装坑 · 失败模式：installation: v6.12.0rc1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v6.12.0rc1
- 对用户的影响：Upgrade or migration may change expected behavior: v6.12.0rc1
- 证据：failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.12.0rc1 | v6.12.0rc1

## 21. 安装坑 · 失败模式：installation: v6.13.0rc1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v6.13.0rc1
- 对用户的影响：Upgrade or migration may change expected behavior: v6.13.0rc1
- 证据：failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.13.0.rc1 | v6.13.0rc1

## 22. 安装坑 · 来源证据：[bug]: FP32 VAE decode may unexpectedly run on CPU with partial loading enabled

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug]: FP32 VAE decode may unexpectedly run on CPU with partial loading enabled
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9373 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 23. 配置坑 · 失败模式：configuration: v6.11.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v6.11.1
- 对用户的影响：Upgrade or migration may change expected behavior: v6.11.1
- 证据：failure_mode_cluster:github_release | https://github.com/invoke-ai/InvokeAI/releases/tag/v6.11.1 | v6.11.1

## 24. 能力坑 · 能力判断依赖假设

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

## 25. 维护坑 · 维护活跃度未知

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

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

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

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

## 28. 安全/权限坑 · 来源证据：[bug]: triton not found; flop counting will not work for triton kernels

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug]: triton not found; flop counting will not work for triton kernels
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/invoke-ai/InvokeAI/issues/9372 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

<!-- canonical_name: invoke-ai/InvokeAI; human_manual_source: deepwiki_human_wiki -->