从零搭建最小可用Neo4j服务器：基础配置、首次启动与连通性验证

“最小可用”的Neo4j服务器至少应满足四个条件：容器能够持续运行、HTTP管理界面可以访问、Bolt端口能够完成认证和查询、数据库文件在容器重建后仍然保留。为了减少Java版本和系统包依赖，下面使用Docker Compose部署Neo4j Community Edition，宿主机不需要单独配置Java运行环境。

操作环境以已安装Docker Engine和Compose插件的Linux服务器为准，Ubuntu 22.04、Ubuntu 24.04等系统均可按相同方式执行Docker命令。如果使用的是直接安装的软件包、旧版docker-compose或其他容器平台，应先核对命令和配置格式，不要混用服务管理方式。

部署前确认服务器状态

开始前需要具备以下条件：

可以执行docker和docker compose命令；
服务器能够拉取Neo4j官方容器镜像；
端口7474和7687未被其他程序占用；
数据目录所在磁盘有足够可用空间；
具备SSH登录能力，用于建立安全隧道和后续运维。

先检查系统、Docker和Compose版本：

cat /etc/os-release
uname -m
docker version
docker compose version

如果执行Docker命令时出现权限错误，应检查当前用户是否具备访问Docker守护进程的权限。不要通过chmod 777 /var/run/docker.sock解决，这会扩大Docker控制权限。可使用具备权限的运维账号，或按照当前发行版的Docker安装规范配置用户组。

检查计划使用的端口：

sudo ss -lntp | grep -E ':(7474|7687)\b' || true

没有输出通常表示端口未监听；如果已有程序占用，需要先确认对应进程，或者在Compose文件中更换宿主机端口，不能直接终止不明服务。

同时确认磁盘空间：

df -h
docker system df

Neo4j的数据量会随节点、关系、属性和索引增长。最小部署可以暂不进行复杂容量规划，但不应放在空间即将耗尽的分区上。

创建独立的部署目录

将Neo4j配置放入独立目录，便于后续备份、变更和回滚：

mkdir -p "$HOME/neo4j-min"
cd "$HOME/neo4j-min"
umask 077

下面生成一个由十六进制字符组成的随机密码，避免斜杠、空格、美元符号等字符影响.env解析：

password="$(od -An -N18 -tx1 /dev/urandom | tr -d ' \n')"
printf 'NEO4J_IMAGE=neo4j:community\nNEO4J_PASSWORD=%s\n' "$password" > .env
unset password
chmod 600 .env

neo4j:community是浮动镜像标签，适合完成首次部署验证，但其实际版本可能随镜像仓库更新。生产环境应从官方镜像仓库选择经过核验的精确Community版本标签，或者在拉取后记录镜像摘要。

可以先拉取并记录当前摘要：

docker pull neo4j:community
docker image inspect --format '{{index .RepoDigests 0}}' neo4j:community

如果需要可重复部署，可将输出的neo4j@sha256:...写入.env中的NEO4J_IMAGE，避免后续重新拉取时版本发生变化。

编写最小Compose配置

在刚创建的空目录中生成compose.yaml。该命令会覆盖同名文件，如果目录中已经存在配置，应先备份。

cat > compose.yaml <<'YAML'
services:
  neo4j:
    image: "${NEO4J_IMAGE}"
    restart: unless-stopped
    ports:
      - "127.0.0.1:7474:7474"
      - "127.0.0.1:7687:7687"
    environment:
      NEO4J_AUTH: "neo4j/${NEO4J_PASSWORD}"
      NEO4J_server_default__listen__address: "0.0.0.0"
    volumes:
      - neo4j_data:/data
      - neo4j_logs:/logs

volumes:
  neo4j_data:
    name: neo4j_min_data
  neo4j_logs:
    name: neo4j_min_logs
YAML

chmod 600 compose.yaml

这份配置只保留Neo4j服务器首次启动所需的核心项目：

配置项	作用	当前设置的边界
`NEO4J_AUTH`	设置初始管理员账号和密码	默认用户名为`neo4j`，密码来自`.env`
`7474`	提供HTTP管理界面	仅绑定宿主机回环地址
`7687`	提供Bolt数据库连接	仅绑定宿主机回环地址
`/data`	保存数据库文件	使用Docker命名卷持久化
`/logs`	保存Neo4j日志	使用独立命名卷
`restart: unless-stopped`	宿主机或Docker重启后恢复容器	手动停止的容器不会被强制启动

容器内部监听0.0.0.0，但宿主机端口绑定在127.0.0.1，因此外部网络不能直接访问。这不是配置冲突：前者决定容器内监听范围，后者决定宿主机如何发布端口。

这种方式避免把未配置TLS和访问控制策略的Neo4j端口直接暴露到公网。远程管理可通过SSH隧道完成。

完成首次启动

先检查Compose语法和变量是否完整：

docker compose config --quiet

该命令成功时通常不会输出内容。如果出现NEO4J_PASSWORD未设置等提示，应检查.env是否位于compose.yaml同一目录，以及当前命令是否在正确目录执行。

启动Neo4j服务器：

docker compose up -d

查看容器状态：

docker compose ps

首次启动需要初始化数据库目录和认证信息，短时间内处于启动过程并不一定表示故障。继续查看日志：

docker compose logs --tail=200 neo4j

判断是否成功时，不要只看容器是否为running。还应确认日志中没有持续重复的启动异常、认证初始化错误、存储锁冲突或进程退出记录。

如需持续观察：

docker compose logs -f neo4j

按Ctrl+C只会退出日志查看，不会停止Neo4j容器。

分层验证Neo4j服务器

检查HTTP入口

在服务器本机执行：

curl -sS -o /dev/null -w 'HTTP状态码：%{http_code}\n' http://127.0.0.1:7474/

返回成功类HTTP状态码，说明宿主机端口发布、容器HTTP监听和Neo4j Web入口已经连通。但这一层只验证HTTP服务，不能证明Bolt认证和数据库查询正常。

如果系统没有安装curl，可以通过SSH隧道在管理电脑的浏览器中验证，不必为了单次检查随意安装额外软件包。

检查Bolt端口和数据库认证

进入容器内置的cypher-shell：

docker compose exec neo4j cypher-shell -u neo4j

按照提示输入.env中的密码。可在受控终端查看密码：

sed -n 's/^NEO4J_PASSWORD=//p' .env

注意避免在屏幕共享、终端录制或多人会话中执行。进入Cypher交互界面后运行：

RETURN 1 AS ok;

能够返回ok和数值1，表示以下链路均已通过：

Neo4j进程正在运行；
Bolt连接器可以建立连接；
用户认证成功；
数据库能够接受并执行查询。

退出交互界面：

:exit

对于首次可用性验证，RETURN 1比创建测试节点更安全，因为它不会向数据库写入测试数据。

从管理电脑验证远程连通性

由于端口只绑定在服务器的127.0.0.1，应通过SSH隧道访问。在管理电脑上执行：

ssh -N \
  -L 7474:127.0.0.1:7474 \
  -L 7687:127.0.0.1:7687 \
  ops@服务器地址

将ops和服务器地址替换为实际SSH账号及地址。隧道保持运行时，在管理电脑访问：

http://127.0.0.1:7474/browser/

连接地址使用：

bolt://127.0.0.1:7687

用户名为neo4j，密码来自.env。如果服务器本机验证正常，而通过隧道无法访问，应优先检查SSH命令、SSH登录权限和管理电脑本地端口占用，而不是修改Neo4j配置。

首次启动失败时的检查顺序

容器启动后立即退出

先查看容器退出状态和应用日志：

docker compose ps -a
docker compose logs --tail=300 neo4j

如需判断是否发生内存不足退出，可执行：

cid="$(docker compose ps -q neo4j)"
if [ -n "$cid" ]; then
  docker inspect --format 'OOMKilled={{.State.OOMKilled}} ExitCode={{.State.ExitCode}} Error={{.State.Error}}' "$cid"
fi

OOMKilled=true表示容器进程可能被内存限制或宿主机内存压力终止；
非零退出码但没有OOM记录，应继续根据Neo4j日志判断；
日志中出现存储锁信息时，应检查是否有另一个Neo4j实例正在使用同一数据卷。

不要在没有确认数据用途的情况下删除数据卷或锁文件。

提示端口已被占用

重新检查监听进程：

sudo ss -lntp | grep -E ':(7474|7687)\b' || true

如果不能释放原端口，可只修改Compose中的宿主机端口：

ports:
  - "127.0.0.1:17474:7474"
  - "127.0.0.1:17687:7687"

修改后重新创建容器：

docker compose up -d

此时服务器本机验证地址应改为127.0.0.1:17474，SSH隧道的远端目标也应改为17474和17687。容器内部端口仍然保持7474和7687。

密码修改后仍然认证失败

NEO4J_AUTH主要用于空数据目录的首次认证初始化。数据库已经完成初始化后，仅修改.env并重启容器，通常不会同步修改数据库中的现有密码。

如果知道当前密码，应先使用当前密码登录，再在Cypher会话中执行密码变更。不要把真实密码直接写入共享脚本或Shell历史记录。

如果忘记密码但数据必须保留，不应通过删除数据卷“修复”，应按照当前Neo4j版本的官方密码恢复流程处理。只有在确认这是尚未写入业务数据的全新环境时，才可以重建空数据卷。

本机可访问，外部无法访问

当前配置本来就不允许外部直接访问7474和7687。正确处理方式是建立SSH隧道，而不是盲目改成：

ports:
  - "0.0.0.0:7474:7474"
  - "0.0.0.0:7687:7687"

将端口发布到所有网卡会扩大访问范围，而且Docker端口发布与宿主机防火墙规则之间还存在实现差异。确实需要局域网或跨服务器直连时，应先确定可信来源地址、宿主机绑定地址、防火墙策略以及Bolt加密方案，再调整监听范围。

停止、重启与失败回滚

正常停止Neo4j服务器：

docker compose stop

重新启动：

docker compose start

修改Compose配置后重新创建容器：

docker compose up -d

如果本次部署失败，可以移除容器和网络，同时保留数据卷：

docker compose down

docker compose down默认不会删除命名卷，修正配置后可再次执行：

docker compose up -d

如果需要回滚配置，变更前应复制配置文件：

cp compose.yaml compose.yaml.before-change
cp .env .env.before-change
chmod 600 .env.before-change

.env.before-change包含认证信息，应与原文件使用相同的访问权限，并在不再需要时按组织的凭据管理规范处理。

只有在确认数据卷中没有业务数据、无需保留认证信息和数据库文件时，才可以执行以下完全重置命令：

docker compose down -v

该命令会删除本部署声明的命名卷，现有Neo4j数据和日志将无法通过重新启动容器恢复。已经写入业务数据时，应先使用与当前Neo4j版本匹配的官方备份或数据库转储工具，不能把删除卷作为常规排障步骤。

上线前验收清单

docker compose ps显示Neo4j容器持续运行，而不是反复重启；
日志中没有持续出现认证、存储锁、磁盘空间或内存退出错误；
http://127.0.0.1:7474/能够在服务器本机返回有效HTTP响应；
cypher-shell可以使用neo4j账号登录并执行RETURN 1 AS ok；
管理电脑通过SSH隧道能够打开Neo4j Browser并建立Bolt连接；
/data已挂载到命名卷neo4j_min_data；
.env权限为仅部署账号可读，密码未写入公开脚本和操作记录；
已记录实际使用的Neo4j镜像标签或摘要；
7474和7687没有直接暴露到非可信网络；
删除卷、升级镜像或修改认证配置前已有明确的备份与回滚方案。

Neo4j 容器部署基础配置连通性验证 Neo4j服务器

上一篇 Kubernetes集群上线前如何加固：API端口、身份认证、RBAC与审计检查