本地运行自定义Open edX项目的目录替换方法及报错排查

自定义项目目录正确替换流程 #

直接替换devstack自动生成的默认目录会触发git状态校验失败、挂载权限冲突，属于不被支持的操作，正确方案是通过挂载映射指向本地自定义目录，步骤如下：

• 先清理异常环境：在devstack根目录执行make dev.down关停所有容器，将之前直接覆盖替换的默认源码目录全部恢复或移除，避免挂载冲突。
• 配置挂载映射：在devstack根目录新建或编辑docker-compose.override.yml文件，修改对应服务的volumes配置，将默认源码路径替换为本地自定义目录的绝对路径，参考配置如下：

  version: "3.7"
  services:
    lms:
      volumes:
        - /替换为本地自定义edx-platform的绝对路径:/edx/app/edxapp/edx-platform
        - /替换为本地自定义edx-theme的绝对路径:/edx/app/edxapp/edx-platform/themes/custom-theme
    cms:
      volumes:
        - /替换为本地自定义edx-platform的绝对路径:/edx/app/edxapp/edx-platform
        - /替换为本地自定义edx-theme的绝对路径:/edx/app/edxapp/edx-platform/themes/custom-theme
    ecommerce:
      volumes:
        - /替换为本地自定义ecommerce的绝对路径:/edx/app/ecommerce/ecommerce
        - /替换为本地自定义ecommerce-themes的绝对路径:/edx/app/ecommerce/ecommerce/themes/custom-theme
    credentials:
      volumes:
        - /替换为本地自定义credentials的绝对路径:/edx/app/credentials/credentials
  

• 跳过默认源码拉取：在devstack根目录新建options.local.mk文件，写入DEVSTACK_SKIP_GIT_PULL=1，避免devstack启动时自动拉取官方源码覆盖自定义挂载配置。

npm install Error 2 报错修复 #

该报错是直接替换目录后的典型连锁问题，按以下顺序排查修复：

• 修复目录权限：devstack容器内服务运行用户的UID/GID均为1000，直接替换本地目录后容器无写入权限会导致npm安装失败。在本地每个自定义项目根目录执行sudo chown -R 1000:1000 ./，给容器运行用户分配目录读写权限。
• 清理不兼容依赖残留：本地自定义目录如果之前在宿主机环境执行过npm install，会生成和容器内Node/NPM版本不匹配的node_modules、package-lock.json文件，进入edx-platform目录执行rm -rf node_modules package-lock.json test_root/log/*删除残留文件，ecommerce、credentials目录下如果有同类残留文件也一并删除。
• 清理npm缓存：执行make dev.up lms启动lms容器，再执行make lms-shell进入容器命令行，执行npm cache clean --force清理容器内损坏的npm缓存。
• 验证依赖安装：在lms容器内的/edx/app/edxapp/edx-platform目录下手动执行npm install，确认无报错后退出容器，再执行make dev.provision完成全量环境初始化即可。

提示：所有依赖安装操作必须在对应容器内执行，不要在宿主机直接给Open edX项目装Node、Python依赖，否则会出现版本兼容问题。

内容的提问来源于stack exchange，提问作者pabloposada19