# 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

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

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

# 验证安装
java -version
```

#### 步骤 2: 添加 Neo4j 仓库

```bash
# 创建密钥目录
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

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

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

#### 步骤 4: 配置并启动服务

```bash
# 设置初始密码（替换 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: 下载并解压

```bash
# 下载 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: 创建用户和设置权限

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

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

#### 步骤 3: 配置环境变量

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

#### 步骤 4: 创建 systemd 服务

```bash
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 允许远程连接

```bash
sudo nano /etc/neo4j/neo4j.conf
```

找到并取消注释以下行：

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

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

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

### 3.2 内存配置（可选）

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

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

### 3.3 重启服务

```bash
sudo systemctl restart neo4j
```

---

## 4. 验证安装

### 4.1 浏览器访问

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

- 用户名: `neo4j`
- 密码: 你设置的密码

### 4.2 命令行测试

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

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

# 退出
:exit
```

### 4.3 查看日志

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

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

---

## 5. 灵越智报项目配置

### 5.1 修改环境变量

创建或编辑 `.env` 文件：

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

### 5.2 或直接修改 application.properties

```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 启动项目后初始化索引

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

---

## 6. 常用命令

```bash
# 启动 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 查询

```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: 服务启动失败

```bash
# 查看详细错误
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` 降低内存配置：

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

### 问题 4: 忘记密码

```bash
# 停止服务
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. **日志轮转**: 配置日志轮转避免磁盘占满