如何在Neo4j Docker容器启动时执行Cypher脚本？

阿华AIGC实验室

2026-5-15

在Neo4j Docker容器启动后自动执行Cypher迁移脚本的解决方案

你遇到的问题其实是Docker化Neo4j时很常见的场景——需要在数据库完全就绪后自动运行迁移脚本，之前尝试的几种方式要么时机不对（比如EXTENSION_SCRIPT过早执行），要么破坏了Neo4j的默认启动流程。下面给你几个可行的方案，按推荐程度排序：

方案1：自定义启动脚本，先启动Neo4j再执行迁移

这个方案的核心是：先调用Neo4j官方容器的默认启动流程，等待数据库完全就绪后，再遍历执行你的Cypher脚本。

步骤1：编写自定义启动脚本

创建docker-neo4j-entrypoint.sh脚本（放在你的./data/import/migrations/scripts目录下）：

#!/bin/bash
set -e

# 1. 启动Neo4j后台进程，不阻塞脚本执行
/docker-entrypoint.sh neo4j &
NEO4J_PID=$!

# 2. 等待Neo4j服务就绪（用cypher-shell验证Bolt连通性，比curl更可靠）
echo "Waiting for Neo4j to become available..."
until cypher-shell -u neo4j -p "" "RETURN 1" > /dev/null 2>&1; do
    sleep 3
done
echo "Neo4j is ready! Starting migration..."

# 3. 遍历/scripts目录下的Cypher脚本并执行（按文件名顺序）
for script in /scripts/*.cypher; do
    if [ -f "$script" ]; then
        echo "Executing migration script: $script"
        cypher-shell -u neo4j -p "" -f "$script"
        if [ $? -ne 0 ]; then
            echo "Failed to execute $script"
            exit 1
        fi
    fi
done

# 4. 等待Neo4j主进程，保证容器不会在迁移完成后退出
wait $NEO4J_PID

给脚本添加执行权限：

chmod +x ./data/import/migrations/scripts/docker-neo4j-entrypoint.sh

步骤2：调整Dockerfile

修改你的Dockerfile，确保脚本被正确复制并设置为ENTRYPOINT：

FROM neo4j:3.3.1
COPY ./data/import/migrations/scripts /scripts
# 给自定义脚本添加执行权限
RUN chmod +x /scripts/docker-neo4j-entrypoint.sh
ENV NEO4J_AUTH=none
ENTRYPOINT ["/scripts/docker-neo4j-entrypoint.sh"]

方案说明

我们先以后台方式启动Neo4j，避免阻塞迁移脚本的执行
使用cypher-shell检测服务就绪，能准确判断数据库是否可接受查询
如果需要严格的迁移顺序，可以给脚本命名加数字前缀，比如01_init_schema.cypher、02_import_data.cypher
最后通过wait命令绑定Neo4j主进程，确保容器持续运行

方案2：使用Docker Compose的`command`结合临时脚本（适合快速测试）

如果你不想修改ENTRYPOINT，可以在docker-compose.yml中追加启动命令，让Neo4j启动后自动触发迁移：

neo4j:
  container_name: 'app-db'
  build:
    context: .
    dockerfile: DOCKERFILE_DB
  volumes:
    - ./data/CSVs:/import
    - ./data/import/migrations:/import/migrations
    - ./data/import/migrations/scripts/migrate.sh:/migrate.sh
  ports:
    - "7687:7687"
    - "7474:7474"
    - "7473:7473"
  networks:
    - app-network
  command: bash -c "/docker-entrypoint.sh neo4j & sleep 30 && /migrate.sh && wait"

其中migrate.sh只需要包含方案1中执行Cypher脚本的部分（不需要启动Neo4j的代码）。

注意事项

sleep 30是简单的等待方式，不如cypher-shell检测可靠，适合测试环境快速验证
这种方式不会阻塞容器启动，迁移脚本会在后台执行

对你疑问的解答

是否推荐自动执行迁移？
完全推荐！这是环境自动化的最佳实践，特别是跨平台协作时，能保证所有人的数据库初始状态一致，避免手动操作的误差，也能无缝融入CI/CD流程。
Neo4j/Docker有没有原生机制？
Neo4j官方容器没有直接提供“启动后执行脚本”的原生机制，但通过自定义启动脚本的方式，是社区公认的标准解决方案。你之前尝试的EXTENSION_SCRIPT是用于Neo4j扩展初始化的，时机确实过早，不适合执行数据迁移。
是否需要手动进入容器执行？
不需要，除非是临时调试或紧急修复。自动执行迁移更适合团队协作和标准化环境部署场景。