Linux服务器首次部署Neo4j,如何完成基础配置并验证数据库可用?
首次部署的目标,是让 Neo4j 在 Linux 服务器上启动为可管理的服务,并通过 Bolt 连接执行一条查询,确认数据库可用。下面以 Ubuntu 22.04/24.04、Neo4j Community 5.26.0、Java 17 为例,使用官方发行包安装;安装目录和版本号固定,便于核对与回滚。
本方案默认只允许服务器本机访问 Neo4j 的 HTTP 和 Bolt 端口,不将数据库端口直接开放到公网。若确实需要远程访问,应先明确访问来源,并通过防火墙限制来源地址;不要仅靠修改监听地址来实现公网开放。
Neo4j部署所依托的服务器资源,会影响数据库运行环境与业务服务的承载方式。A5idc数据提供香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器,覆盖Xeon Gold、AMD EPYC等平台,并有SSD或NVMe存储配置,可为数据库、业务后台及接口服务提供硬件与网络资源基础。
准备条件
需要具备一台可通过 SSH 管理的 Ubuntu 服务器、具有 sudo 权限的账户,以及能访问 Neo4j 发行包下载站点的网络。建议为服务器预留至少 2 GB 内存和数 GB 可用磁盘空间;实际需求取决于数据量和查询负载,这只是首次验证的参考配置,不是生产容量保证。
先确认操作系统、架构、磁盘空间及端口占用:
cat /etc/os-release
uname -m
df -h /opt
sudo ss -lntp | grep -E ':(7474|7687)\b' || true
Ubuntu 示例中,uname -m 通常输出 x86_64 或 aarch64。如果 7474(HTTP)或 7687(Bolt)已被其他程序占用,先确认占用进程及用途,不要直接结束进程。
安装 Java 运行环境和下载工具:
sudo apt update
sudo apt install -y openjdk-17-jre-headless curl
java -version
预期能看到 Java 17 版本信息。若系统当前使用其他 Java 主版本,先核实所选 Neo4j 版本的兼容要求,不要仅凭“Java 已安装”判断可运行。
安装 Neo4j
以下命令使用固定版本 5.26.0,下载包放在 /tmp,程序安装在 /opt/neo4j-5.26.0。如果要采用其他版本,应将后续路径、服务配置和下载地址中的版本号一并调整。
cd /tmp
curl -fLO https://dist.neo4j.org/neo4j-community-5.26.0-unix.tar.gz
tar -tzf neo4j-community-5.26.0-unix.tar.gz | head
tar 命令能列出包内目录,表示下载文件具备可读取的压缩包结构。若下载失败,先检查网络连接和下载地址;不要对不完整文件继续解压。
创建专用运行账户并解压程序:
sudo useradd --system --create-home --home-dir /var/lib/neo4j \
--shell /usr/sbin/nologin neo4j
sudo tar -xzf /tmp/neo4j-community-5.26.0-unix.tar.gz -C /opt
sudo ln -s /opt/neo4j-community-5.26.0 /opt/neo4j
sudo chown -R neo4j:neo4j /opt/neo4j-community-5.26.0
如果 neo4j 用户或 /opt/neo4j 链接已经存在,先检查现有安装,避免覆盖已有服务或目录。检查程序版本和目录权限:
/opt/neo4j/bin/neo4j --version
ls -ld /opt/neo4j /opt/neo4j-community-5.26.0
版本命令应输出 Neo4j 版本信息;目录应能通过 /opt/neo4j 指向此次安装目录。若版本命令提示 Java 不兼容,先停止后续操作并核对 Java 与 Neo4j 的版本组合。
设置基础配置与初始密码
首次启动前设置初始认证密码,避免使用默认凭据。以 Neo4j 运行账户执行管理命令:
sudo -u neo4j /opt/neo4j/bin/neo4j-admin dbms set-initial-password
若当前版本不支持交互式输入,会提示需要密码参数。此时不要把真实密码直接写入可公开的脚本或命令历史;可在受控终端中执行,并在部署后确认 shell 历史未保存敏感内容。初始密码应符合组织的密码策略,并妥善保管。
配置文件默认位于 /opt/neo4j/conf/neo4j.conf。先备份,再追加本机监听设置:
sudo cp -a /opt/neo4j/conf/neo4j.conf \
/opt/neo4j/conf/neo4j.conf.bak
sudo tee -a /opt/neo4j/conf/neo4j.conf >/dev/null <<'EOF'
# 首次部署:仅监听本机,避免数据库端口直接暴露到外部网络
server.default_listen_address=127.0.0.1
server.bolt.listen_address=127.0.0.1:7687
server.http.listen_address=127.0.0.1:7474
EOF
这里保留 Neo4j 自带配置,只增加明确的监听地址。若原文件已经配置了相同参数,应先编辑已有设置,不要重复追加多个互相冲突的值。检查配置项:
grep -nE '^(server\.default_listen_address|server\.bolt\.listen_address|server\.http\.listen_address)=' \
/opt/neo4j/conf/neo4j.conf
预期三项分别指向 127.0.0.1、127.0.0.1:7687 和 127.0.0.1:7474。这意味着只能从服务器本机连接;服务器外部无法直接访问这两个服务端口。
配置并启动 systemd 服务
创建一个由 systemd 管理的服务,让 Neo4j 随系统服务机制启动和停止:
sudo tee /etc/systemd/system/neo4j.service >/dev/null <<'EOF'
[Unit]
Description=Neo4j Graph Database
After=network.target
[Service]
Type=simple
User=neo4j
Group=neo4j
WorkingDirectory=/opt/neo4j
ExecStart=/opt/neo4j/bin/neo4j console
ExecStop=/bin/kill -TERM $MAINPID
TimeoutStopSec=120
Restart=on-failure
LimitNOFILE=60000
[Install]
WantedBy=multi-user.target
EOF
重新加载 systemd 配置、启动服务并设为开机启动:
sudo systemctl daemon-reload
sudo systemctl enable --now neo4j
sudo systemctl status neo4j --no-pager
服务正常时,状态应显示 active (running)。首次启动需要初始化数据库,等待一段时间后再检查;如果状态为 failed 或启动超时,先查看日志,不要反复重启。
sudo journalctl -u neo4j -n 100 --no-pager
日志中应能看到服务启动相关信息,且没有持续出现配置解析错误、端口占用或 Java 运行时错误。Neo4j 自身日志也可从安装目录查看:
sudo tail -n 80 /opt/neo4j/logs/neo4j.log
验证数据库可用
先检查监听情况:
sudo ss -lntp | grep -E ':(7474|7687)\b'
预期能看到 127.0.0.1:7474 和 127.0.0.1:7687 的监听记录。若没有监听记录,检查服务状态和 Neo4j 日志;若地址是 0.0.0.0,应检查配置文件中是否存在重复或未生效的监听项。
接着使用 Neo4j 自带的命令行客户端连接 Bolt。省略密码参数可交互输入,不必把密码直接写在命令行中:
sudo -u neo4j /opt/neo4j/bin/cypher-shell -u neo4j
首次认证时按提示输入初始密码。如果客户端要求更改初始密码,按提示设置新密码后重新连接。连接成功后,在提示符中执行:
RETURN 1 AS ok;
预期返回一行结果,ok 的值为 1。这同时验证了服务进程、Bolt 端口、认证和基本查询执行。可再查看数据库列表:
SHOW DATABASES;
正常情况下能看到 neo4j 数据库及其状态。输入 :exit 退出客户端。
需要验证 HTTP 监听时,可在服务器本机执行:
curl -I http://127.0.0.1:7474
返回 HTTP 响应说明该端口有服务响应;具体状态码可能随版本和端点行为变化,不能单独以 200 作为数据库可用的唯一判断。核心验收仍应以 Bolt 成功认证并执行查询为准。
如果需要从管理电脑使用浏览器,可选择 SSH 本地端口转发,而不是将端口直接开放到公网。例如在管理电脑上执行:

ssh -L 7474:127.0.0.1:7474 -L 7687:127.0.0.1:7687 user@服务器地址
保持 SSH 会话运行后,再从管理电脑访问 http://127.0.0.1:7474。其中 user@服务器地址 替换为实际 SSH 账户和服务器地址。该方式要求 SSH 本身已按管理规范限制访问;它不改变 Neo4j 只监听服务器本机的配置。
常见失败处理
服务无法启动
查看 systemd 状态和最近日志:
sudo systemctl status neo4j --no-pager
sudo journalctl -u neo4j -n 100 --no-pager
- 日志提示端口已占用:用
sudo ss -lntp找出占用程序,确认是否应更换 Neo4j 端口或停止冲突服务。不要在未确认业务影响前结束进程。 - 日志提示 Java 版本或运行时错误:执行
java -version,核对 Neo4j 版本与 Java 兼容性。 - 日志提示配置错误:检查
neo4j.conf中相关设置是否重复、拼写是否正确,并与备份文件比较。 - 日志提示权限不足:检查
/opt/neo4j-community-5.26.0及其子目录是否由neo4j账户拥有。仅对本次安装目录修正所有者,不要对/opt或系统目录做递归权限变更。
客户端无法连接或认证失败
先在服务器上确认 Bolt 端口监听在 127.0.0.1:7687,再确认客户端连接的是本机地址。服务器外部直接连接失败符合本方案的默认安全设置;不能因此判断数据库未启动。
认证失败时,确认使用的是刚设置的密码,并留意首次登录是否要求修改密码。不要通过关闭认证或使用默认密码来绕过登录问题。若需重置密码,应先按对应 Neo4j 版本的管理流程处理,并确认不会影响已有数据。
验收与回滚检查
部署完成后,至少核对以下项目:
java -version显示符合所选版本要求的 Java 运行环境。systemctl status neo4j显示服务处于active (running)。- 7474 和 7687 仅监听
127.0.0.1,没有意外绑定到所有网卡。 cypher-shell能完成认证,RETURN 1 AS ok;返回1。- 初始密码已更改并妥善保存;如需远程管理,使用受控访问方式。
回滚时,先停止并禁用服务:
sudo systemctl disable --now neo4j
sudo systemctl status neo4j --no-pager
确认服务已停止后,再移除此次创建的 systemd 单元,并重新加载配置:
sudo rm /etc/systemd/system/neo4j.service
sudo systemctl daemon-reload
删除前确认该服务文件确由本次部署创建,避免影响其他安装。若要撤销配置改动,可先备份当前配置,再恢复先前保存的版本:
sudo cp -a /opt/neo4j/conf/neo4j.conf \
/opt/neo4j/conf/neo4j.conf.before-rollback
sudo cp -a /opt/neo4j/conf/neo4j.conf.bak \
/opt/neo4j/conf/neo4j.conf
不要把删除程序目录当作默认回滚步骤:数据库文件可能保存在安装目录下,删除目录会造成数据丢失。确需移除程序前,先确认数据是否需要保留,并对数据库及配置制定独立备份方案;没有确认备份可用之前,保留 /opt/neo4j-community-5.26.0 和相关数据目录。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/6292.html



