Neo4j是目前使用最广泛的图数据库之一，它用节点、关系、属性三种核心元素来建模，能在人际关系链路、知识图谱、推荐系统等场景下提供远优于关系型数据库的查询效率。传统的Neo4j安装需要预先配置Java运行时、调整系统参数、手动管理服务进程，对于只想快速验证图查询逻辑的开发者来说成本偏高。借助Docker镜像，可以在几秒钟内拉起一个具备完整功能的Neo4j实例，并且所有依赖都被隔离在容器内部，既不会污染宿主机环境，也便于在不同机器间迁移。
本文将从实际运维角度出发，依次介绍容器化部署Neo4j的优势、使用Docker Compose编排服务的完整配置，以及生产环境中需要关注的内存、认证和备份调优点。所有示例均以官方镜像neo4j为基础，不依赖第三方封装，方便你在自己的项目中直接参考。
容器化部署Neo4j的基础步骤
首先需要确认宿主机已经安装Docker引擎，并且当前用户具备执行docker命令的权限。Neo4j官方提供了多个版本的镜像标签，包括社区版、企业版以及特定大版本号。对于大多数开发场景，使用默认的latest标签即可，但为了确保行为可复现，建议显式指定主版本号，例如neo4j:5.26。拉取镜像的命令如下：
docker pull neo4j:5.26
镜像拉取完成后，最简单的启动方式是直接使用docker run命令。Neo4j默认会开放7474端口作为HTTP浏览器控制台，7687端口作为Bolt协议连接端口。容器内部的应用数据存放在/data目录，日志存放在/logs目录，导入文件可以从/import目录读取。如果不做任何卷挂载，容器删除后所有数据都会丢失，因此第一次启动时就应当规划好宿主机目录映射。下面是一个带数据卷和端口映射的基础启动命令：
docker run -d \ --name neo4j-dev \ -p 7474:7474 \ -p 7687:7687 \ -v neo4j-data:/data \ -v neo4j-logs:/logs \ -v neo4j-import:/var/lib/neo4j/import \ -e NEO4J_AUTH=neo4j/your_password \ neo4j:5.26
这里使用了Docker命名卷来保存数据，也可以换成宿主机绝对路径，例如-v /opt/neo4j/data:/data。环境变量NEO4J_AUTH用于设置初始用户名和密码，格式为用户名/密码。如果不设置该变量，默认用户名是neo4j，默认密码也是neo4j，首次登录浏览器控制台后会被要求修改密码。需要注意的是，NEO4J_AUTH只在数据目录为空时生效，如果卷中已有数据库，则不会覆盖已有密码。容器启动后，访问http://localhost:7474即可打开Neo4j Browser，在连接框中输入Bolt地址和账号密码就能执行Cypher查询。
使用Docker Compose编排Neo4j服务
对于需要同时管理多个服务或者希望配置可版本化的团队，Docker Compose是更合适的选择。通过一个YAML文件可以完整描述Neo4j的镜像版本、端口、卷、环境变量和依赖关系，避免每次启动都写一长串docker run参数。下面是一个可直接使用的docker-compose.yml示例：
services:
neo4j:
image: neo4j:5.26
container_name: neo4j-compose
ports:
- "7474:7474"
- "7687:7687"
volumes:
- ./neo4j/data:/data
- ./neo4j/logs:/logs
- ./neo4j/import:/var/lib/neo4j/import
- ./neo4j/plugins:/plugins
environment:
NEO4J_AUTH: neo4j/change_me_123
NEO4J_server_memory_heap_max__size: 1G
NEO4J_server_memory_pagecache_size: 512M
NEO4J_dbms_security_procedures_unrestricted: apoc.*
restart: unless-stopped
这个Compose文件做了几件重要的事。第一，将数据、日志、导入目录和插件目录都映射到当前项目下的neo4j子目录，这样即使容器被删除，数据也不会丢失，而且可以直接从宿主机查看日志文件。第二，通过环境变量设置了堆内存最大值为1G，页面缓存为512M。Neo4j是Java应用，堆内存如果不加限制，容器内存紧张时可能触发OOM Killer。页面缓存则决定了Neo4j能在内存中缓存多少图数据，合理配置能显著提升查询性能。第三，通过NEO4J_dbms_security_procedures_unrestricted放开了APOC扩展过程的调用权限，方便后续安装APOC插件后使用相关函数。
环境变量的映射规则是把Neo4j配置文件中的点号替换为双下划线。例如配置项server.memory.heap.max_size写成NEO4J_server_memory_heap_max__size。这样可以避免改动容器内的neo4j.conf文件，所有配置都集中在一个Compose文件中。如果某些配置在环境变量中无法表达，也可以把自定义的neo4j.conf挂载到容器的/conf目录。启动和停止服务只需要在Compose文件所在目录执行docker compose up -d和docker compose down命令，比手动管理容器更加直观。
生产环境调优与常见问题排查
容器化Neo4j在开发环境跑通之后，上生产前还需要关注几个关键点。首先是内存配置，默认情况下Neo4j会根据容器可用的总内存自动计算堆大小，但这个自动计算有时并不准确，尤其在宿主机内存较大而容器限制较小时。建议显式设置堆最大值和页面缓存，并且保证两者之和不超过容器可用内存的80%。例如一个总内存4G的容器，可以设置堆2G、页面缓存1G，其余留给操作系统和其他进程。如果设置过大，容器可能频繁触发OOM；设置过小，复杂查询时会出现OutOfMemoryError。
第二个常见问题是认证失败。有些用户启动容器后直接访问7474端口却无法登录，大概率是NEO4J_AUTH环境变量格式写错。正确的格式是用户名/密码，中间用正斜杠分隔，例如neo4j/secret123。如果密码中包含特殊字符，建议使用Compose文件而不是命令行，因为shell可能会对特殊字符进行解析。还有一种情况是数据卷中已经存在旧的数据库，此时修改NEO4J_AUTH不会改变已有密码，需要删除数据目录重新初始化，或者通过Cypher命令修改密码。
第三是备份与恢复。容器化部署后，最简单的备份方式是对数据卷做快照，但由于Neo4j写入过程中文件状态可能不一致，直接复制数据目录存在风险。更稳妥的做法是使用neo4j-admin backup命令，这个命令需要进入容器内部执行。例如对于社区版，可以先停掉写入，然后执行：
docker exec -it neo4j-compose neo4j-admin database dump neo4j --to-path=/backup
恢复时使用对应的load子命令。如果配置了CronJob定期执行备份，并把/backup目录挂载到宿主机，就能形成完整的备份方案。日志排查方面，可以通过docker logs neo4j-compose查看启动日志，如果容器反复重启，重点检查内存配置和端口冲突。Bolt端口7687被占用通常会导致容器启动后立即退出，日志中会出现Address already in use错误。将宿主机的映射端口改成其他空闲端口即可解决。
最后需要提醒的是，容器化Neo4j虽然方便，但生产环境如果涉及多节点因果集群，需要额外配置服务发现和网络互通，不建议直接用单机Compose文件硬套。对于中小规模应用，单机容器化配合定时备份和合理的JVM参数已经能提供稳定的图查询服务。关键配置集中在数据卷、内存上限和认证信息三处，保持这些参数清晰可见，可以大幅降低后期维护成本。