lingyue-zhibao/docs/neo4j-local-install.md

Neo4j 本地部署指南

1. 系统要求

硬件要求

• CPU: Intel/AMD x86-64 或 ARM
• 内存: 最低 2GB，推荐 16GB+
• 存储: 最低 10GB，推荐 SSD

软件要求

• 操作系统: Ubuntu 22.04/24.04, Debian 11-13, RHEL 8.x/9.x, CentOS 等
• Java: Java 21 或更高版本

---

2. 安装方法

方法 A: Debian/Ubuntu 系统（推荐）

步骤 1: 安装 Java 21

# 检查是否已安装 Java
java -version

# 如果没有，安装 OpenJDK 21
sudo apt update
sudo apt install openjdk-21-jdk -y

# 验证安装
java -version

步骤 2: 添加 Neo4j 仓库

# 创建密钥目录
sudo mkdir -p /etc/apt/keyrings

# 添加 GPG 密钥
wget -O - https://debian.neo4j.com/neotechnology.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/neotechnology.gpg
sudo chmod a+r /etc/apt/keyrings/neotechnology.gpg

# 添加仓库
echo 'deb [signed-by=/etc/apt/keyrings/neotechnology.gpg] https://debian.neo4j.com stable latest' | sudo tee /etc/apt/sources.list.d/neo4j.list

# 更新包列表
sudo apt update

步骤 3: 安装 Neo4j

# 安装 Neo4j Community Edition（免费）
sudo apt install neo4j -y

# 或者指定版本
# sudo apt install neo4j=1:5.15.0 -y

步骤 4: 配置并启动服务

# 设置初始密码（替换 your-password）
sudo neo4j-admin dbms set-initial-password your-password

# 启用开机自启
sudo systemctl enable neo4j

# 启动服务
sudo systemctl start neo4j

# 查看状态
sudo systemctl status neo4j

---

方法 B: Tarball 安装（更灵活）

步骤 1: 下载并解压

# 下载 Neo4j Community Edition
wget https://neo4j.com/artifact.php?name=neo4j-community-5.15.0-unix.tar.gz -O neo4j-community-5.15.0-unix.tar.gz

# 解压
tar -xzf neo4j-community-5.15.0-unix.tar.gz

# 移动到 /opt
sudo mv neo4j-community-5.15.0 /opt/neo4j

步骤 2: 创建用户和设置权限

# 创建 neo4j 用户
sudo useradd -r -s /bin/false neo4j

# 设置目录权限
sudo chown -R neo4j:neo4j /opt/neo4j

步骤 3: 配置环境变量

# 添加到 ~/.bashrc 或 /etc/profile
export NEO4J_HOME=/opt/neo4j
export PATH=$NEO4J_HOME/bin:$PATH

步骤 4: 创建 systemd 服务

sudo tee /etc/systemd/system/neo4j.service > /dev/null <<EOF
[Unit]
Description=Neo4j Graph Database
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/opt/neo4j/bin/neo4j console
Restart=on-abnormal
User=neo4j
Group=neo4j
Environment="NEO4J_CONF=/opt/neo4j/conf"
Environment="NEO4J_HOME=/opt/neo4j"
LimitNOFILE=60000
TimeoutSec=120

[Install]
WantedBy=multi-user.target
EOF

# 重新加载 systemd
sudo systemctl daemon-reload

# 设置初始密码
sudo -u neo4j /opt/neo4j/bin/neo4j-admin dbms set-initial-password your-password

# 启用并启动
sudo systemctl enable neo4j
sudo systemctl start neo4j

---

3. 配置 Neo4j

配置文件位置: /etc/neo4j/neo4j.conf 或 /opt/neo4j/conf/neo4j.conf

3.1 允许远程连接

sudo nano /etc/neo4j/neo4j.conf

找到并取消注释以下行：

# 监听所有接口（生产环境请谨慎）
server.default_listen_address=0.0.0.0

# HTTP 端口（浏览器访问）
server.http.listen_address=:7474

# Bolt 端口（应用连接）
server.bolt.listen_address=:7687

3.2 内存配置（可选）

# 堆内存设置
server.memory.heap.initial_size=512m
server.memory.heap.max_size=2g

# 页面缓存（建议设置为可用内存的 50%）
server.memory.pagecache.size=1g

3.3 重启服务

sudo systemctl restart neo4j

---

4. 验证安装

4.1 浏览器访问

打开浏览器访问: http://localhost:7474

• 用户名: neo4j
• 密码: 你设置的密码

4.2 命令行测试

# 使用 cypher-shell 连接
cypher-shell -u neo4j -p your-password

# 运行测试查询
RETURN "Hello Neo4j!" AS message;

# 退出
:exit

4.3 查看日志

# 查看日志
sudo journalctl -u neo4j -f

# 或者
tail -f /var/log/neo4j/neo4j.log

---

5. 灵越智报项目配置

5.1 修改环境变量

创建或编辑 .env 文件：

# Neo4j 配置
NEO4J_ENABLED=true
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j

5.2 或直接修改 application.properties

# Neo4j 图数据库配置
neo4j.enabled=true
neo4j.uri=bolt://localhost:7687
neo4j.username=neo4j
neo4j.password=your-password
neo4j.database=neo4j
neo4j.connection-timeout-seconds=30
neo4j.max-connection-pool-size=50

5.3 启动项目后初始化索引

# 调用 API 初始化 Neo4j 索引
curl -X POST http://localhost:5232/api/v1/neo4j/init-indexes

---

6. 常用命令

# 启动 Neo4j
sudo systemctl start neo4j

# 停止 Neo4j
sudo systemctl stop neo4j

# 重启 Neo4j
sudo systemctl restart neo4j

# 查看状态
sudo systemctl status neo4j

# 查看日志
sudo journalctl -u neo4j -f

# 进入 Cypher Shell
cypher-shell -u neo4j -p your-password

---

7. 常用 Cypher 查询

-- 查看所有节点数量
MATCH (n) RETURN count(n);

-- 查看所有关系数量
MATCH ()-[r]->() RETURN count(r);

-- 查看节点标签统计
MATCH (n) RETURN labels(n), count(*) ORDER BY count(*) DESC;

-- 查看关系类型统计
MATCH ()-[r]->() RETURN type(r), count(*) ORDER BY count(*) DESC;

-- 删除所有数据（谨慎使用！）
MATCH (n) DETACH DELETE n;

-- 查看某文档的所有节点
MATCH (n {documentId: 'your-doc-id'}) RETURN n;

-- 查看某节点的所有关系
MATCH (n {id: 'your-node-id'})-[r]-(m) RETURN n, r, m;

---

8. 故障排查

问题 1: 服务启动失败

# 查看详细错误
sudo journalctl -u neo4j --no-pager -n 50

# 检查端口占用
sudo netstat -tlnp | grep 7687
sudo netstat -tlnp | grep 7474

问题 2: 连接被拒绝

1. 检查服务是否运行: sudo systemctl status neo4j
2. 检查防火墙: sudo ufw status
3. 检查配置文件中的 listen_address

问题 3: 内存不足

修改 neo4j.conf 降低内存配置：

server.memory.heap.initial_size=256m
server.memory.heap.max_size=512m
server.memory.pagecache.size=256m

问题 4: 忘记密码

# 停止服务
sudo systemctl stop neo4j

# 重置密码
sudo neo4j-admin dbms set-initial-password new-password --require-password-change=false

# 启动服务
sudo systemctl start neo4j

---

9. 生产环境建议

1. 使用强密码: 不要使用默认密码
2. 限制访问: 配置防火墙只允许应用服务器访问
3. 定期备份: 使用 neo4j-admin database dump 备份数据
4. 监控: 配置 Prometheus + Grafana 监控
5. 日志轮转: 配置日志轮转避免磁盘占满