Umami 项目中使用 Docker Compose 部署时脚本执行问题解析

问题背景

在使用 Docker Compose 部署 Umami 项目时，用户遇到了一个关于密码重置脚本无法正常运行的问题。具体表现为当尝试执行 yarn change-password 命令时，系统报错提示找不到 'prompts' 模块。

错误现象分析

当用户在 Docker 容器内执行密码修改命令时，系统抛出以下关键错误信息：

Error: Cannot find module 'prompts'
Require stack:
- /app/scripts/change-password.js

这表明系统在执行 change-password.js 脚本时，无法找到依赖的 prompts 模块。随后用户尝试通过 yarn add -D prompts 命令安装缺失的依赖，但安装过程也失败了，出现了权限被拒绝的错误。

根本原因

经过深入分析，这个问题主要由以下几个因素共同导致：

1. 容器权限问题：Docker 容器默认以非 root 用户运行，导致在容器内部安装新依赖时没有足够的文件系统权限。

2. 依赖管理冲突：Yarn 在尝试安装依赖时遇到了多个警告和错误，包括过时的依赖版本和权限问题。

3. 模块安装位置不正确：即使尝试安装依赖，由于容器文件系统的限制，模块可能没有被正确安装到预期的 node_modules 目录中。

解决方案

针对这个问题，我们推荐以下几种解决方案：

方案一：使用 PNPM 安装依赖

1. 首先进入容器：

   docker compose exec -it umami sh
   

2. 全局安装 PNPM：

   npm install -g pnpm
   

3. 使用 PNPM 安装 prompts 模块：

   pnpm add prompts
   

方案二：以 root 用户身份运行容器

1. 以 root 用户身份进入容器：

   docker compose exec --user root umami sh
   

2. 然后尝试安装依赖：

   yarn add prompts
   

方案三：重建 Docker 镜像

1. 修改项目的 package.json 文件，确保 prompts 被列为依赖项。

2. 重新构建 Docker 镜像：

   docker-compose build
   

3. 重新启动服务：

   docker-compose up -d
   

预防措施

为了避免类似问题再次发生，建议采取以下预防措施：

1. 完善项目依赖声明：确保所有脚本所需的依赖都明确列在 package.json 文件中。

2. 使用多阶段构建：在 Dockerfile 中使用多阶段构建，确保所有依赖在构建阶段就被正确安装。

3. 定期更新依赖：定期检查并更新项目依赖，避免使用已弃用或不再维护的包版本。

4. 容器权限管理：合理规划容器运行时的用户权限，平衡安全性和功能性需求。

技术原理深入

这个问题的本质在于 Node.js 模块系统的加载机制与 Docker 容器权限管理的交互。当脚本尝试 require('prompts') 时，Node.js 会按照以下顺序查找模块：

1. 当前目录的 node_modules
2. 父目录的 node_modules
3. 直到根目录的 node_modules
4. 全局安装的模块

在 Docker 环境中，由于容器文件系统的隔离和权限限制，这些查找路径可能无法正常工作，特别是当尝试安装新模块时。PNPM 之所以能解决这个问题，是因为它采用了不同的依赖管理策略，能够更好地处理容器环境中的权限问题。

总结

Umami 项目在使用 Docker Compose 部署时遇到的脚本执行问题，反映了容器化环境中依赖管理的复杂性。通过理解问题的根本原因并采用适当的解决方案，开发者可以有效地解决这类问题，同时通过实施预防措施，可以避免类似问题在未来发生。对于容器化部署的 Node.js 应用，合理的依赖管理和权限规划是确保应用稳定运行的关键因素。