Docker部署Neo4j容器出现退出码4故障，寻求排查解决方法

问题 #

在Windows 11系统下使用Docker部署Neo4j，采用如下docker-compose.yml配置：

version: '3.3'
services:
  neo4j:
    image: neo4j:latest
    container_name: "cmkg-neo4j-db"
    restart: always
    volumes:
      - $HOME/neo4j/data:/data
      - $HOME/neo4j/import:/var/lib/neo4j/import
      - ./db/neo4j-cyphers:/import
      - $HOME/neo4j/plugins:/plugins
      - $HOME/neo4j/logs:/logs
    ports:
      - 7474:7474
      - 7687:7687
    environment:
      - NEO4J_ACCEPT_LICENCE_AGREEMENT=yes
      - NEO4J_AUTH=neo4j/root
      - NEO4J_dbms_default__listen__address=0.0.0.0
      - NEO4J_dbms_default__advertised__address=localhost
      - NEO4J_dbms_connector_bolt_enabled=true
      - NEO4J_dbms_routing_enabled=true
      - NEO4J_dbms_connector_bolt_listen__address=:7687
      - NEO4J_dbms_connector_bolt_advertised__address=:7687
      - NEO4J_dbms_logs_debug_level=DEBUG
      - NEO4J_apoc_import_file_use__neo4j__config=true
      - NEO4J_apoc_initializer_cypher=CALL apoc.cypher.runSchemaFile('file:///init_db_setup.cypher')
      - NEO4J_apoc_import_file_enabled=true
      - NEO4J_dbms_security_procedures_unrestricted=apoc.\\*
      - NEO4JLABS_PLUGINS=["apoc", "n10s"]
    networks:
      - cmkg_net

  api:
    container_name: "cmkg-container"
    restart: always
    build:
      context: .
    ports:
      - 5000:5000
    environment:
      - NEO4J_URI=bolt://neo4j:7687
      - NEO4J_USER=neo4j
      - NEO4J_PW=root
    volumes:
      - .:/app
    links:
      - 'neo4j'
    depends_on:
      - 'neo4j'
    networks:
      - cmkg_net

networks:
  cmkg_net:
    driver: bridge

该部署曾正常运行，拉取新分支后出现故障，容器退出码为4，日志信息如下：

cmkg-neo4j-db exited with code 4
cmkg-neo4j-db   | NEO4JLABS_PLUGINS has been renamed to NEO4J_PLUGINS since Neo4j 5.0.0.
cmkg-neo4j-db   | The old name will still work, but is likely to be deprecated in future releases.
cmkg-neo4j-db   | Installing Plugin 'apoc' from /var/lib/neo4j/labs/apoc-*-core.jar to /plugicmkg-neo4j-db   | Applying default values for plugin apoc to neo4j.conf
cmkg-neo4j-db   | Skipping dbms.security.procedures.unrestricted for plugin apoc because it is already set.cmkg-neo4j-db   | You may need to add apoc.* to the dbms.security.procedures.unrestricted setting in your configuration file.cmkg-neo4j-db   | Fetching versions.json for Plugin 'n10s' from https://neo4j-labs.github.io/neosemantics/versions.jsoncmkg-neo4j-db   | Installing Plugin 'n10s' from null to /plugins/n10s.jar
cmkg-neo4j-db exited with code 4

切换回旧分支后问题依旧，尝试卸载重装Docker和Neo4j仍无法解决。请问该故障的原因是什么，如何修复？

故障原因 #

1. n10s插件自动安装失败：日志显示Neo4j尝试安装n10s时，获取到的安装包路径为null，说明无法正确拉取该插件的版本信息或安装文件，导致插件安装失败触发容器退出码4。
2. 环境变量兼容性与镜像版本冲突：使用的neo4j:latest镜像已自动升级到Neo4j 5+版本，虽然旧环境变量NEO4JLABS_PLUGINS仍兼容，但新版本的插件安装逻辑变化，导致n10s无法自动适配安装。
3. 本地挂载目录残留干扰：之前部署残留的plugins、data目录存在文件损坏或权限问题，新容器启动时无法正常加载插件或数据。

修复方案 #

方案一：适配Neo4j 5+环境变量并指定插件版本 #

修改docker-compose.yml中Neo4j服务的环境变量：

• 将NEO4JLABS_PLUGINS替换为NEO4J_PLUGINS（Neo4j 5+官方推荐变量名）
• 明确指定n10s版本（需与Neo4j版本匹配，例如Neo4j 5对应n10s 5.x版本，Neo4j 4.4对应n10s 4.4.x版本）

environment:
  # 保留原有其他变量
  - NEO4J_PLUGINS=["apoc", "n10s:4.4.0.12"] # 示例版本，需根据实际Neo4j镜像版本调整
  - NEO4J_dbms_security_procedures_unrestricted=apoc.*,n10s.* # 新增n10s的权限放开

方案二：手动下载插件到本地挂载目录 #

1. 下载与当前Neo4j版本匹配的apoc核心版和n10s插件jar包。
2. 找到Windows系统中$HOME/neo4j/plugins对应的实际路径（通常为C:\Users\<你的用户名>\neo4j\plugins），将下载的jar包放入该目录。
3. 删除docker-compose.yml中的NEO4JLABS_PLUGINS或NEO4J_PLUGINS环境变量，让Neo4j直接加载本地plugins目录中的插件。

方案三：清理本地挂载目录并重新部署 #

1. 停止并删除所有相关容器及卷：

docker-compose down -v

2. 备份$HOME/neo4j/data目录（若有重要数据），然后删除$HOME/neo4j下的data、plugins、logs文件夹。
3. 重新启动容器：

docker-compose up -d

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