企业官网建设流程全解析

InvenTree Docker 生产环境部署指南：从零搭建、升级与健康检查

【免费下载链接】InvenTreeOpen Source Inventory Management System项目地址: https://gitcode.com/GitHub_Trending/in/InvenTree

本指南以 InvenTree 官方生产部署文档 docker_install.md 为核心骨架，结合仓库内 docker-compose.yml、Caddyfile、Dockerfile 等真实配置与 tasks.py 中的 invoke 任务实现，系统讲解如何用 Docker Compose 快速搭建一套生产级 InvenTree 库存管理系统。读完本文，你将掌握：三个必需文件的获取与.env变量配置、数据库初始化与管理员账号创建、容器的启动与升级流程、JSON 数据导出与日志查看、健康检查机制的原理与手工验证方法，以及自定义域名、HTTPS、端口调整和自定义 Docker 镜像等进阶配置。

部署前置条件

本文假设你已经安装好 Docker 与 Docker Compose。如果你使用的是stable稳定镜像标签，请务必对照 STABLE 版本文档阅读。本指南只提供一个"起点"，真实的生产需求可能比示例更复杂，需要你自行在此基础上调整。

在开始之前，请确认你具备基本的 docker 与 docker compose 概念认知。安装过程中若遇到问题，可优先查阅 FAQ 文档 中列出的常见问题与解决方案。

必需文件

生产部署不需要InvenTree 源码——只需从仓库的contrib/container/目录中下载以下三个文件，放到本机任意目录即可：

下载时如果系统给文件自动添加了.txt扩展名，务必重命名去掉后再继续。后续所有docker compose命令都必须在这三个文件所在的同一目录下执行。

从源码结构看，该 compose 文件定义了五个服务，文件头部注释明确说明：你不应该修改 docker-compose.yml 本身，所有定制都应通过.env文件完成。例如切换镜像版本只需修改INVENTREE_TAG变量：

# 默认是稳定版 # image: inventree/inventree:stable # # 使用开发版： # INVENTREE_TAG=latest # # 使用特定发布版本： # INVENTREE_TAG=0.7.5

编辑环境变量

.env文件是部署的核心配置入口。有两个变量是必须定义的：

• INVENTREE_EXT_VOLUME：指向你本机一个目录，所有持久化数据（数据库文件、上传的媒体文件、备份等）都存储在这里。compose 文件中对未设置该变量的服务直接使用了${INVENTREE_EXT_VOLUME:?You must specify...}语法强制校验，未设置会启动报错。
• INVENTREE_DB_USER与INVENTREE_DB_PASSWORD：数据库用户名与密码，务必修改默认值以增强安全性。compose 文件同样用:?语法强制要求这两个变量必须存在。

此外还有大量可选环境变量可定制安装，例如数据库名（INVENTREE_DB_NAME，compose 中同样为必填）、站点 URL、时区、调试开关等，完整清单见 配置文档。

生产镜像的持久化数据布局

Docker 容器本身是临时性的，所有持久化数据必须挂载到外部卷。从 docker-compose.yml 可以看到各容器统一把${INVENTREE_EXT_VOLUME}挂载到容器内，并通过 Dockerfile 中定义的环境变量指定各目录：

容器启动时 init.sh 会自动创建缺失的目录结构：若config.yaml不存在，会从config_template.yaml模板复制一份；若secret_key.txt不存在，会随机生成一个新密钥。注意：所有 InvenTree 容器实例必须使用同一个 secret key，否则会出现不可预期的行为。

初始数据库设置

完成.env配置后，执行以下命令进行初始数据库设置：

docker compose run --rm inventree-server invoke update

该命令依次完成以下步骤：

1. 确保所需 Python 包已安装
2. 创建新的（空的）数据库
3. 执行 schema 迁移，创建所需数据库表
4. 更新翻译文件
5. 更新所需静态文件

注意：invoke update默认会执行一次数据库备份；如需跳过可加--skip-backup参数。该参数在与更高版本 PostgreSQL 对接时尤其重要——详见 docker 理论文档。

创建管理员账户

如果是全新数据库，需要创建管理员（superuser）账户，执行并按提示操作：

docker compose run inventree-server invoke superuser

也可以改用环境变量或直接写在.env中，免去手工交互步骤，相关变量见 配置文档的管理员账户一节：

提供以上凭据后，InvenTree 启动时会自动创建具有 superuser 权限的账户。出于安全考虑，首次运行成功后务必把这些凭据从.env文件中移除。

启动容器

数据库初始化完成并创建管理员后，启动全部容器：

docker compose up -d

该命令会拉起以下 5 个容器：

各容器通过depends_on的service_healthy条件控制启动顺序：inventree-server依赖数据库与缓存先健康，inventree-worker依赖 Web 服务器先健康，inventree-proxy依赖 Web 服务器与工作进程都健康。

启动成功后，即可在浏览器访问 http://inventree.localhost 看到登录界面（或.env中配置的自定义域名）。注意该地址仅在运行 Docker 的本机可访问；要让网络内其他设备访问，需把INVENTREE_SITE_URL改为一个本网络可达的主机地址。

更新 InvenTree

危险：如果当前安装版本低于1.0.0，不能直接升级到最新版，必须先执行 从 Pre 1.0.0 升级 的中间步骤。

更新过程分为四步：

1. 停止容器

docker compose down

2. 拉取最新镜像

docker compose pull

确保容器运行的是最新版 InvenTree 源码。若目标是某个特定 "tagged" 版本，可先修改.env中的INVENTREE_TAG变量再执行拉取。

3. 更新数据库

docker compose run --rm inventree-server invoke update

该命令默认执行数据库备份，可用--skip-backup跳过。

4. 重启容器

docker compose up -d

所有docker compose命令都必须在 docker-compose.yml 所在目录 下执行。

数据备份

数据库与媒体文件都存放在外部卷（INVENTREE_EXT_VOLUME指定的目录）中，强烈建议定期备份该卷中的文件。详细方案见 数据备份文档。

InvenTree 基于 django-dbbackup 库提供原生备份能力：invoke backup导出原生数据库文件与媒体归档，invoke restore恢复，invoke listbackups查看已有备份；更新过程中也会自动执行备份。

以 JSON 导出数据库

若想导出为与数据库无关的 JSON 文件，执行：

docker compose run --rm inventree-server invoke export-records -f /home/inventree/data/data.json

数据库记录将被导出到挂载卷目录下的data.json文件（即宿主机INVENTREE_EXT_VOLUME目录中）。

查看日志

查看所有容器的日志：

docker compose logs

查看指定容器日志：

docker compose logs <container-name>

例如：

docker compose logs inventree-server

实时跟随日志流使用-f参数：

docker compose logs -f

容器健康检查

生产版 docker-compose.yml 为每个服务都定义了健康检查。这些检查能让 Docker 及外部监控工具发现"容器在运行但实际已失效"的情况（典型场景：后台工作进程卡死而容器仍在运行）。健康检查同时控制服务启动顺序——依赖方会等待上游容器报告 healthy 后才启动。

各服务的健康检查与依赖

Web 服务器对外暴露了一个轻量、免认证的健康端点/api/system/health/；反向代理的健康检查通过 Caddy 在 9090 端口探测该路径，外部监控系统也可直接复用同一路径。从 Caddyfile 可以看到:9090站点仅将/api/system/health/*反向代理到内部 Web 服务器，其余请求一律返回 404——这是专供内部健康检查使用的私有端口。

查看容器健康状态

docker compose ps

健康的容器会在状态列显示(healthy)。想查看详细的健康检查历史，直接检查容器：

docker inspect inventree-server

在输出中找到Health段即可。

手工健康检查

InvenTree 的 invoke 工具提供了与 Docker 健康检查完全一致的手工检查命令：

检查 Web 服务器：

docker compose exec inventree-server invoke server-health --address "http://localhost:8000"

检查后台工作进程：

docker compose exec inventree-worker invoke worker-health

两个命令健康时退出码为0，不健康时为1。从 tasks.py 的实现可以看到，worker-health通过读取一个由后台进程每分钟写入一次的心跳时间戳文件（inventree_worker_heartbeat）来判断：若文件距今超过timeout（默认 3 分钟）分钟即判定过期。这就是"工作进程卡死但容器仍存活"能被检测出来的底层原理——无需启动 Django、无需访问数据库。server-health（tasks.py）则直接请求/api/system/health/端点，收到 HTTP 200 即视为健康。其他参数（如自定义超时）见 invoke 工具文档。

进一步配置

检查安全态势

部署完成后建议阅读 威胁建模资料，确保你的安装方式符合软件设计时的安全假设。

自定义域名

默认访问地址是http://inventree.localhost。要使用自定义域名，编辑.env文件中的INVENTREE_SITE_URL变量为期望的域名即可。INVENTREE_SITE_URL在 配置文档 中被定义为关键设置——它是用户访问 InvenTree 的入口 URL，还会被自动用作受信任的 CSRF 与 CORS 主机，务必设置正确。

SSL 配置

提供的 Caddyfile 已内置 Automatic HTTPS 支持，开箱即用——只需把INVENTREE_SITE_URL设为https://开头的 URL。Caddy 容器会自动为你的域名生成 SSL 证书，证书等持久文件存放在外部卷的caddy目录中。

警告：Automatic HTTPS 依赖 Let's Encrypt ACME 挑战，要求服务器在标准端口 80 和/或 443 上可达。如果 InvenTree 发布在非标准端口（见下文），或主机无法从外部访问这两个端口，自动 HTTPS 将失败。此时应在外部反向代理处终结 SSL，参见 进程文档中的既有反向代理集成。

Web 服务器绑定地址

默认情况下，容器化 InvenTree Web 服务器绑定所有网络接口，在 8000 端口监听 IPv4 流量，可通过以下变量调整：

这两个变量在 Dockerfile 中被组合成 gunicorn 的启动绑定串（-b ${INVENTREE_WEB_ADDR}:${INVENTREE_WEB_PORT}）。

警告：INVENTREE_WEB_PORT控制的是inventree-server（gunicorn）与inventree-proxy（Caddy）之间的内部端口，不是网络内其他机器连接的端口，多数情况下应保持默认值 8000。

代理（外部）端口

真正发布到宿主机、供网络内其他设备访问的端口由inventree-proxy服务独立控制：

如果 80/443 已被同主机其他服务占用，可修改INVENTREE_HTTP_PORT与/或INVENTREE_HTTPS_PORT，并同步更新INVENTREE_SITE_URL带上匹配端口，例如：

INVENTREE_SITE_URL="http://192.168.1.10:5143"

IPv6 支持：若需启用 IPv6 / 双栈，创建/启动容器时将INVENTREE_WEB_ADDR设为[::]。

演示数据集

想快速体验，可安装 InvenTree 演示数据集：

docker compose run --rm inventree-server invoke dev.setup-test -i

要推倒重来（完全删除现有数据库），执行：

docker compose run --rm inventree-server invoke dev.delete-data

安装自定义软件包

如果需要向镜像安装自定义软件包（例如某些系统级依赖），可以构建自定义镜像并让每次更新自动使用它。需要修改 docker-compose.yml：

@@ services: # Uses gunicorn as the web server inventree-server: # If you wish to specify a particular InvenTree version, do so here - image: inventree/inventree:${INVENTREE_TAG:-stable} + image: inventree/inventree:${INVENTREE_TAG:-stable}-custom + pull_policy: never + build: + context: . + dockerfile: Dockerfile + target: production + args: + INVENTREE_TAG: ${INVENTREE_TAG:-stable} # Only change this port if you understand the stack. # If you change this you have to change: # - the proxy settings (on two lines) @@ services: # Background worker process handles long-running or periodic tasks inventree-worker: # If you wish to specify a particular InvenTree version, do so here - image: inventree/inventree:${INVENTREE_TAG:-stable} + image: inventree/inventree:${INVENTREE_TAG:-stable}-custom + pull_policy: never command: invoke worker depends_on: - inventree-server

同时在工作目录创建一个Dockerfile：

ARG INVENTREE_TAG FROM inventree/inventree:${INVENTREE_TAG} as production # Install whatever dependency is needed here (e.g. git) RUN apk add --no-cache git

如果需要额外的开发期依赖（例如仅为构建某个 pip wheel），可用多阶段构建：

ARG INVENTREE_TAG # prebuild stage - needs a lot of build dependencies # make sure, the alpine and python version matches the version used in the inventree base image FROM python:3.12-alpine3.18 as prebuild # Install whatever development dependency is needed (e.g. cups-dev, gcc, the musl-dev build tools and the pip pycups package) RUN apk add --no-cache cups-dev gcc musl-dev && \ pip install --user --no-cache-dir pycups # production image - only install the cups shared library FROM inventree/inventree:${INVENTREE_TAG} as production # Install e.g. shared library later available in the final image RUN apk add --no-cache cups-libs # Copy the pip wheels from the build stage in the production stage COPY --from=prebuild /root/.local /root/.local

多阶段构建的思路是：prebuild阶段安装所有编译依赖并构建 wheel，production阶段只安装运行时共享库，再把 wheel 从构建阶段拷贝过来，从而让最终镜像保持精简。注意pull_policy: never确保 Compose 使用本地构建的镜像而不是从仓库拉取官方镜像。

常见问题排查

从 docker 理论文档 可以整理出以下高频坑点：

• 卷映射异常：如果安装看似正常、但上传的文件和插件"每次重启都不见了"，说明挂载卷没有真正映射到宿主机目录。若之前用多种方式配置过安装，先清理旧卷绑定再开始，避免遗留问题：

docker volume rm -f inventree-production_inventree_data

• PostgreSQL 版本上限：inventree-server与inventree-worker容器支持连接到指定版本以内的 PostgreSQL；连接更新的版本不保证可用，且新版数据库上invoke update的备份/恢复命令会因版本不匹配而失败，此时需加--skip-backup跳过备份步骤。
• invoke 命令找不到：确保invoke已正确安装（pip install -U invoke）且已满足最低版本要求；invoke update等管理命令必须从包含tasks.py的源码顶层目录、或在 docker 容器上下文中执行（见 invoke 工具文档）。

总结

InvenTree 的生产 Docker 部署是一条高度"约定优于配置"的路径：三个文件 + 一个.env即可拉起完整的多容器栈，数据库、缓存、Web 服务器、后台工作进程与反向代理各司其职，健康检查机制让编排顺序与故障感知自动化。掌握本文的部署、升级、备份与定制流程后，你可以在 配置文档 基础上按需扩展环境变量，并结合 进程文档 深入理解每个容器的运行细节。

【免费下载链接】InvenTreeOpen Source Inventory Management System项目地址: https://gitcode.com/GitHub_Trending/in/InvenTree