InvokeAI Docker一键部署教程：镜像拉取端口映射与数据目录配置

部署前准备：先确认环境是否适合

InvokeAI 作为主流的 AI 绘画工具，非常适合在本地工作站、实验服务器或内网算力主机上运行。采用 Docker 部署 的优势在于环境隔离清晰，升级与回滚操作便捷，无需在宿主机反复处理 Python 版本冲突、依赖兼容以及系统库问题。对于希望快速搭建文生图、图生图、工作流生成环境的用户而言，容器化方案通常更为稳妥可靠。

开始部署前，建议提前准备三类条件。首先是硬件方面：NVIDIA 显卡用户应优先确认显存容量，入门使用建议 8GB 以上，若需生成大尺寸图片或加载更复杂的模型，显存要求会更高；没有独立显卡也可尝试 CPU 模式，但生成速度会明显下降。其次是系统环境：Linux 服务器最为常见，Windows 用户可通过 Docker Desktop 配合 WSL2 实现。最后是基础软件：需要安装 Docker Engine 与 Docker Compose；若需调用 NVIDIA 显卡，还需安装匹配版本的驱动和 NVIDIA Container Toolkit。

规划目录：把模型、配置和输出结果留在宿主机

部署 InvokeAI 时，不建议将数据只保存在容器内部。容器删除或重建后，内部文件可能一并丢失，因此需要提前规划好数据目录。常见做法是在宿主机创建一个独立目录，例如 /opt/invokeai，用于保存模型文件、配置文件、缓存以及生成结果。也可以选择容量更大的数据盘，例如 /data/ai/invokeai。

目录准备可参考以下思路：先创建目录，例如执行 mkdir -p /opt/invokeai；然后确认当前用户或 Docker 进程对该目录拥有读写权限。若后续出现无法保存图片、无法写入配置等问题，通常与目录权限有关。在团队共享环境中，建议由管理员统一创建目录并限制访问范围，避免模型文件和生成素材被无关账号读取。

镜像拉取：优先选择官方发布源

镜像配置的核心原则是可靠、可追踪、方便回滚。InvokeAI 官方镜像通常发布在 ghcr.io/invoke-ai/invokeai，生产或长期使用环境不建议随意采用来历不明的第三方镜像。拉取前可执行 docker pull ghcr.io/invoke-ai/invokeai:latest 获取最新版本。若追求稳定运行，建议改用明确版本号标签，避免 latest 在某次更新后带来兼容性变化。

拉取镜像失败时，请先检查 Docker 服务是否正常、DNS 能否解析、服务器是否能访问镜像仓库。企业内网环境可能需要配置镜像仓库访问策略，这类问题应由网络或运维侧处理。不要为了省事下载来源不明的离线包，因为镜像中可能隐藏不可见脚本或被篡改的依赖，后续排查成本非常高。

一条命令启动：端口映射与数据挂载

最简部署可以使用 docker run。示例命令为：docker run -d --name invokeai --gpus all -p 9090:9090 -v /opt/invokeai:/invokeai ghcr.io/invoke-ai/invokeai:latest。这里的 --name 用于设置容器名称，便于后续管理；--gpus all 表示允许容器调用可用的 NVIDIA 显卡；-p 9090:9090 是端口映射，前一个 9090 为宿主机端口，后一个 9090 为容器内服务端口；-v /opt/invokeai:/invokeai 则是数据目录挂载。

启动后可执行 docker ps 查看容器是否处于运行状态，再执行 docker logs -f invokeai 观察初始化日志。首次运行可能会进行配置生成、依赖检查或模型目录扫描，耗时稍长属正常现象。浏览器访问 http://服务器地址:9090 即可进入 Web 界面。若在本机部署，通常访问 http://127.0.0.1:9090。

使用 Compose 管理：更适合长期维护

如果需要长期运行，建议使用 Docker Compose 保存配置，便于迁移和重复部署。可以在 /opt/invokeai-deploy 下创建 compose 配置文件，服务名设置为 invokeai，镜像指定 ghcr.io/invoke-ai/invokeai:latest，端口设置为 "9090:9090"，数据卷设置为 "/opt/invokeai:/invokeai"，GPU 环境按 Docker 当前版本支持的写法配置。相比直接命令，Compose 的优势在于配置可读性强，升级时只需拉取新镜像并重新创建容器。

常用管理命令包括 docker compose up -d 启动，docker compose logs -f 查看日志，docker compose down 停止并移除容器。注意，down 只要不删除宿主机挂载目录，就不会清空 /opt/invokeai 中的数据。升级前建议先备份 compose 文件和数据目录中的关键配置，尤其是自定义模型索引、工作流模板以及常用参数。

端口映射：不要随意暴露管理入口

InvokeAI 的 Web 服务默认端口常用 9090。若宿主机 9090 已被占用，可改为其他外部端口，例如 -p 19090:9090，访问时使用 http://服务器地址:19090。排查端口问题时，可用 ss -lntp 查看监听状态，也可检查云主机安全规则或本机防火墙是否放行对应端口。

从安全角度考虑，不建议直接将 Web 界面开放给所有外部访问。AI 绘画工具通常会处理本地图片、提示词、模型文件和生成结果，这些内容可能包含个人素材或项目资料。更稳妥的做法是在内网使用，或在前置网关中增加访问控制。若必须远程访问，应限制来源地址、开启身份校验，并定期查看访问日志。

模型目录配置：让 InvokeAI 找到资源

模型文件通常体积较大，应统一放在挂载目录下的模型相关子目录中。不同版本的 InvokeAI 对目录结构和模型导入方式可能有差异，建议以当前版本界面中的 Model Manager 或官方文档为准。一般流程是先将模型文件复制到宿主机挂载目录，再在 Web 界面中导入或扫描，确认模型名称、类型和基础模型版本正确。

模型配置容易出错的点有三个：一是模型格式不匹配，导致加载失败；二是文件权限不足，容器能看到目录但无法读取文件；三是显存不足，模型能导入但生成时失败。遇到问题不要反复重装容器，应先查看日志中的报错关键词，再分别检查文件路径、权限和硬件资源。

升级与回滚：不要盲目追新

升级流程建议分四步：先备份 /opt/invokeai 中的重要配置和工作流；再记录当前镜像标签，可用 docker inspect 查看；然后拉取新版本镜像；最后重建容器并验证常用功能。若使用 latest 标签，升级虽然简单，但不可控因素更多。对稳定性要求高的环境，建议使用明确版本号，并在测试目录先行验证。

回滚时，只需将镜像标签改回旧版本并重新启动容器。如果新版本改动了配置结构，回滚前还应恢复备份的配置文件。生成结果目录也要单独确认，避免误删。任何升级动作都不应在重要任务进行中执行，最好安排在低使用时段，并提前告知使用者。

常见问题与处理办法

问题一：容器启动后浏览器打不开。先确认 docker ps 中端口映射是否存在，再检查访问地址是否写成了宿主机地址和外部端口。若部署在云主机，还需确认安全规则允许该端口访问。

问题二：提示无法使用 GPU。检查宿主机 nvidia-smi 是否正常，再执行 docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi 测试容器是否能识别显卡。若失败，多数原因是驱动、容器工具包或 Docker 运行时配置问题。

问题三：生成图片很慢或直接报错。可能是 CPU 模式运行、显存不足、分辨率设置过高或模型过大。可先降低图片尺寸、批量数量和采样步数，再观察资源占用情况。

问题四：模型导入后不可用。检查模型文件是否完整、格式是否符合当前版本要求、路径是否在挂载目录内。必要时重新扫描模型，或查看 Web 界面的模型管理提示。

实用建议：把部署当成长期服务维护

InvokeAI Docker 部署不只是把容器跑起来，还需要关注数据、权限、访问和版本管理。个人用户可以用单目录挂载简化管理；团队环境则应区分模型目录、输出目录和配置目录，并定期清理缓存与无用生成文件。重要模型和模板建议保留备份，避免磁盘故障或误操作带来损失。

使用 AI 绘画工具 时，还应注意素材来源和生成内容的合规边界。不要上传敏感证件、商业机密或未获授权的私人素材；发布生成图前，应确认模型许可、素材授权以及使用场景。只要镜像来源可信、端口控制得当、数据目录规划清晰，Docker 方式部署 InvokeAI 就能在可维护性和使用效率之间取得较好的平衡。