📚 课程目录第3章 Neo4j环境搭建

3. Neo4j环境搭建

在反欺诈关系图谱项目中，环境搭建不是“装个软件”这么简单，而是决定后续数据导入、查询调试、团队协作与部署方式的基础设施选择。Neo4j 提供三种主流使用形态：面向个人学习与本地开发的 Neo4j Desktop、面向可复现与服务器部署的 Docker、以及面向云端托管与快速验证的 Neo4j Aura。理解它们的差异，比记住安装步骤更重要。

核心原理：三种形态解决不同问题

Neo4j 的本质是一个原生图数据库，数据以节点、关系、属性存储，Cypher 是它的声明式查询语言。无论使用哪种安装方式，最终都需要一个可连接的数据库实例，以及两个基本客户端：Neo4j Browser 用于可视化查询与结果浏览，Cypher Shell 用于命令行执行脚本与自动化。

Neo4j Desktop：本地图形化管理工具，内置数据库实例、插件与 Browser，适合学习、建模和单机实验。
Docker：以容器方式运行 Neo4j，环境隔离、版本可控、易于迁移，适合开发测试与 CI。
Neo4j Aura：官方云服务，免运维、开箱即用，适合快速验证、演示和小规模生产。

反欺诈课程建议：本地建模用 Desktop，团队共享与复现用 Docker，临时演示或跨地域协作用 Aura。三者并不互斥，可以组合使用。

方法流程：安装配置与基本使用

路径一：Neo4j Desktop。下载安装后创建本地 DBMS，设置密码并启动。Desktop 会自动管理端口，默认 Bolt 为 7687，HTTP 为 7474。启动后点击 Open 进入 Browser，即可执行 Cypher。Desktop 的优势是插件管理方便，例如 APOC 和 Graph Data Science 可通过界面安装。

路径二：Docker。推荐固定版本，避免“今天能跑明天不能跑”。以下命令启动一个带 APOC 的 Neo4j 5.x 实例：

docker run -d \
  --name neo4j-fraud \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/StrongPass123 \
  -e NEO4J_PLUGINS='["apoc"]' \
  -v neo4j_data:/data \
  neo4j:5.26

启动后访问 http://localhost:7474，使用 neo4j/StrongPass123 登录。若需在容器内执行命令，可使用：

docker exec -it neo4j-fraud cypher-shell -u neo4j -p StrongPass123

路径三：Neo4j Aura。在官网创建免费实例，选择区域后下载凭据文件，其中包含连接 URI、用户名和密码。Aura 默认启用 TLS，连接串形如 neo4j+s://xxxx.databases.neo4j.io。创建完成后可直接在浏览器打开 Aura 控制台中的 Query 页面，也可用 Cypher Shell 连接：

cypher-shell -a neo4j+s://xxxx.databases.neo4j.io -u neo4j -p YourPassword

Browser 基本使用。Browser 顶部命令栏输入 Cypher，按 Ctrl+Enter 执行。常用操作包括：:server connect 连接数据库、:param 设置参数、:history 查看历史。查询结果可切换 Graph、Table、Text 视图。反欺诈场景中，Graph 视图能直观看到“同一设备关联多个账户”的异常结构。

Cypher Shell 基本使用。Cypher Shell 适合批量执行与脚本化。常用参数如下：

参数	作用	示例
-a	指定连接地址	-a neo4j://localhost:7687
-u / -p	用户名与密码	-u neo4j -p pass
-f	执行 Cypher 文件	-f init.cypher
--format	输出格式	--format plain

例如批量初始化反欺诈图谱：

cypher-shell -a neo4j://localhost:7687 -u neo4j -p StrongPass123 \
  -f ./scripts/init_fraud_graph.cypher

案例场景：从零验证一个反欺诈查询

假设我们要验证“同一手机号关联多个身份证”的风险模式。在 Browser 中执行：

MATCH (p:Phone)<-[:USED_PHONE]-(a:Account)-[:HAS_ID]->(id:IDCard)
WITH p, collect(DISTINCT id.number) AS ids
WHERE size(ids) > 1
RETURN p.number AS phone, ids, size(ids) AS idCount
ORDER BY idCount DESC;

若结果为空，说明当前数据未覆盖该模式，需要先导入样本数据。这个“查询—发现无数据—补数据—再查询”的循环，是环境搭建完成后最应该做的第一件事：确认连接、权限、数据与查询链路全部打通。

常见误区：只验证“能连上”就认为环境可用。真正可用标准是：能写入、能查询、能执行多跳关系、能导出结果。建议用一条包含 CREATE、MATCH、RETURN 的最小脚本做冒烟测试。

误区与复盘

端口冲突：本地已装 Neo4j 又启动 Docker，导致 7474/7687 被占用。解决：改映射端口或停止旧实例。
密码策略：Neo4j 5 默认要求强密码，弱密码会导致容器启动失败。查看日志：docker logs neo4j-fraud。
Aura 连接串：必须使用 neo4j+s://，用 bolt:// 会连接失败。
数据持久化：Docker 未挂载 volume，容器删除后数据丢失。务必使用 -v 挂载。
Browser 与 Shell 混用：Browser 适合探索，Shell 适合自动化；不要把交互式调试结果直接当生产脚本。

复盘建议：为每套环境记录“版本、端口、认证、插件、数据卷、连接串”六要素，形成团队可复用的环境清单。反欺诈项目往往涉及多源数据与多人协作，环境一致性直接决定图谱结果的可信度。

完成本章后，你应当能够根据场景选择 Desktop、Docker 或 Aura，独立完成安装配置，并使用 Browser 与 Cypher Shell 执行基本查询与脚本。下一步的关键不是继续折腾环境，而是把真实的反欺诈数据建模成节点与关系，让图谱开始说话。