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/目录中下载以下三个文件放到本机任意目录即可文件名作用docker-compose.ymlDocker Compose 编排脚本定义全部容器.env环境变量文件集中存放全部可调参数CaddyfileCaddy 反向代理配置下载时如果系统给文件自动添加了.txt扩展名务必重命名去掉后再继续。后续所有docker compose命令都必须在这三个文件所在的同一目录下执行。从源码结构看该 compose 文件定义了五个服务文件头部注释明确说明你不应该修改 docker-compose.yml 本身所有定制都应通过.env文件完成。例如切换镜像版本只需修改INVENTREE_TAG变量# 默认是稳定版 # image: inventree/inventree:stable # # 使用开发版 # INVENTREE_TAGlatest # # 使用特定发布版本 # INVENTREE_TAG0.7.5编辑环境变量.env文件是部署的核心配置入口。有两个变量是必须定义的INVENTREE_EXT_VOLUME指向你本机一个目录所有持久化数据数据库文件、上传的媒体文件、备份等都存储在这里。compose 文件中对未设置该变量的服务直接使用了${INVENTREE_EXT_VOLUME:?You must specify...}语法强制校验未设置会启动报错。INVENTREE_DB_USER与INVENTREE_DB_PASSWORD数据库用户名与密码务必修改默认值以增强安全性。compose 文件同样用:?语法强制要求这两个变量必须存在。此外还有大量可选环境变量可定制安装例如数据库名INVENTREE_DB_NAMEcompose 中同样为必填、站点 URL、时区、调试开关等完整清单见 配置文档。生产镜像的持久化数据布局Docker 容器本身是临时性的所有持久化数据必须挂载到外部卷。从 docker-compose.yml 可以看到各容器统一把${INVENTREE_EXT_VOLUME}挂载到容器内并通过 Dockerfile 中定义的环境变量指定各目录目录用途Dockerfile 中的对应变量static/Web 服务器所需静态文件INVENTREE_STATIC_ROOTmedia/用户上传的媒体文件INVENTREE_MEDIA_ROOTbackup/数据库与媒体备份INVENTREE_BACKUP_DIRplugins/外部插件目录INVENTREE_PLUGIN_DIRconfig.yaml运行时配置文件INVENTREE_CONFIG_FILEsecret_key.txt应用加密签名密钥INVENTREE_SECRET_KEY_FILEoidc.pemOIDC 私钥INVENTREE_OIDC_PRIVATE_KEY_FILEcaddy/Caddy 生成的证书等持久文件—容器启动时 init.sh 会自动创建缺失的目录结构若config.yaml不存在会从config_template.yaml模板复制一份若secret_key.txt不存在会随机生成一个新密钥。注意所有 InvenTree 容器实例必须使用同一个 secret key否则会出现不可预期的行为。初始数据库设置完成.env配置后执行以下命令进行初始数据库设置docker compose run --rm inventree-server invoke update该命令依次完成以下步骤确保所需 Python 包已安装创建新的空的数据库执行 schema 迁移创建所需数据库表更新翻译文件更新所需静态文件注意invoke update默认会执行一次数据库备份如需跳过可加--skip-backup参数。该参数在与更高版本 PostgreSQL 对接时尤其重要——详见 docker 理论文档。创建管理员账户如果是全新数据库需要创建管理员superuser账户执行并按提示操作docker compose run inventree-server invoke superuser也可以改用环境变量或直接写在.env中免去手工交互步骤相关变量见 配置文档的管理员账户一节变量说明INVENTREE_ADMIN_USER管理员用户名INVENTREE_ADMIN_PASSWORD管理员密码INVENTREE_ADMIN_PASSWORD_FILE存放密码的文件路径适合 nix 用户INVENTREE_ADMIN_EMAIL管理员邮箱提供以上凭据后InvenTree 启动时会自动创建具有 superuser 权限的账户。出于安全考虑首次运行成功后务必把这些凭据从.env文件中移除。启动容器数据库初始化完成并创建管理员后启动全部容器docker compose up -d该命令会拉起以下 5 个容器容器名镜像作用inventree-dbpostgres:17PostgreSQL 数据库inventree-serverinventree/inventree:${INVENTREE_TAG:-stable}InvenTree Web 服务器gunicorninventree-workerinventree/inventree:${INVENTREE_TAG:-stable}django-q2 后台任务工作进程inventree-proxycaddy:alpineCaddy 反向代理与静态文件服务inventree-cacheredis:7-alpineRedis 缓存各容器通过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 down2. 拉取最新镜像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 后才启动。各服务的健康检查与依赖容器健康检查方式启动依赖inventree-dbPostgreSQLpg_isready无inventree-cacheredis-cli ping无inventree-serverinvoke server-health请求http://localhost:${INVENTREE_WEB_PORT:-8000}数据库与缓存必须健康inventree-workerinvoke worker-healthWeb 服务器必须健康inventree-proxywget --spider探测http://127.0.0.1:9090/api/system/health/Web 服务器与工作进程必须健康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-healthtasks.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 依赖 Lets Encrypt ACME 挑战要求服务器在标准端口 80 和/或 443 上可达。如果 InvenTree 发布在非标准端口见下文或主机无法从外部访问这两个端口自动 HTTPS 将失败。此时应在外部反向代理处终结 SSL参见 进程文档中的既有反向代理集成。Web 服务器绑定地址默认情况下容器化 InvenTree Web 服务器绑定所有网络接口在 8000 端口监听 IPv4 流量可通过以下变量调整环境变量默认值INVENTREE_WEB_ADDR0.0.0.0INVENTREE_WEB_PORT8000这两个变量在 Dockerfile 中被组合成 gunicorn 的启动绑定串-b ${INVENTREE_WEB_ADDR}:${INVENTREE_WEB_PORT}。警告INVENTREE_WEB_PORT控制的是inventree-servergunicorn与inventree-proxyCaddy之间的内部端口不是网络内其他机器连接的端口多数情况下应保持默认值 8000。代理外部端口真正发布到宿主机、供网络内其他设备访问的端口由inventree-proxy服务独立控制环境变量默认值INVENTREE_HTTP_PORT80INVENTREE_HTTPS_PORT443如果 80/443 已被同主机其他服务占用可修改INVENTREE_HTTP_PORT与/或INVENTREE_HTTPS_PORT并同步更新INVENTREE_SITE_URL带上匹配端口例如INVENTREE_SITE_URLhttp://192.168.1.10:5143IPv6 支持若需启用 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同时在工作目录创建一个DockerfileARG 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 --fromprebuild /root/.local /root/.local多阶段构建的思路是prebuild阶段安装所有编译依赖并构建 wheelproduction阶段只安装运行时共享库再把 wheel 从构建阶段拷贝过来从而让最终镜像保持精简。注意pull_policy: never确保 Compose 使用本地构建的镜像而不是从仓库拉取官方镜像。常见问题排查从 docker 理论文档 可以整理出以下高频坑点卷映射异常如果安装看似正常、但上传的文件和插件每次重启都不见了说明挂载卷没有真正映射到宿主机目录。若之前用多种方式配置过安装先清理旧卷绑定再开始避免遗留问题docker volume rm -f inventree-production_inventree_dataPostgreSQL 版本上限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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考