# Neo4j 知识图谱（Knowledge Graph） 微语提供独立的图数据库 compose 文件 `compose/compose-neo4j.yaml`（一镜像一文件），包含 [Neo4j](https://github.com/neo4j/neo4j) 社区版（原生图数据库，用于知识图谱 / GraphRAG 能力验证），通过关键字 `neo4j` 按需启动，自动接入 `bytedesk-network`。 > **企业版高级功能**：应用侧知识图谱代码位于 `enterprise/ai` 模块（`com.bytedesk.ai.neo4j` 包），仅企业版/平台版可用，社区版发布镜像中不包含此功能。 - 官方文档： - 镜像： ## 启动 Neo4j `start.sh` / `stop.sh` 支持关键字 `neo4j`，用于启停 `compose/compose-neo4j.yaml`： ```bash cd deploy/docker # 方式 A（推荐）：在启动中间件/应用栈时附带 Neo4j ./start.sh middleware neo4j ./start.sh all neo4j # 全量栈 + 图数据库 ./stop.sh stop middleware neo4j ./stop.sh down middleware neo4j # 删除容器，数据卷保留 # 方式 B：仅 Neo4j（需先确保 bytedesk-network 存在；在 deploy/docker 目录执行） docker compose --env-file .env -f compose/compose-neo4j.yaml up -d ``` ## 访问地址 | 服务 | 地址 | 说明 | | --- | --- | --- | | Neo4j Browser | | 浏览器可视化与管理 | | Bolt 连接 | bolt://127.0.0.1:17687 | 源码本地运行时应用使用；docker 全量时应用容器内为 `bolt://neo4j-bytedesk:7687` | 默认账号 `neo4j` / `${NEO4J_PASSWORD}`（`.env` 中配置，默认 `bytedesk-neo4j`）。 ## 密码说明（重要） - `NEO4J_AUTH` 中的初始密码**仅对空数据卷首次启动生效**；复用已有 `neo4j-data` 卷时，修改 `.env` 中的 `NEO4J_PASSWORD` **不会**覆盖库内旧密码 - 若在 Browser 中已修改过密码，需同步更新 `.env` 的 `NEO4J_PASSWORD` 与应用侧 `BYTEDESK_AI_NEO4J_PASSWORD`，否则应用连接会认证失败 - 需要彻底重置密码时，先 `./stop.sh down middleware neo4j` 再手动删除 `neo4j-data` 数据卷（`docker volume rm bytedesk_neo4j-data`），或按 Neo4j 官方方式在库内改密 ## 启用应用侧知识图谱 Neo4j 启动后，还需在应用侧打开开关（默认关闭，不影响正常启动）： ```bash # .env 中配置（docker 全量启动时生效，容器内通过容器名访问） BYTEDESK_AI_NEO4J_ENABLED=true BYTEDESK_AI_NEO4J_URI=bolt://neo4j-bytedesk:7687 BYTEDESK_AI_NEO4J_PASSWORD=<与 NEO4J_PASSWORD 保持一致> # 或源码本地运行时，在 properties 中配置（宿主机端口） # bytedesk.ai.neo4j.enabled=true # bytedesk.ai.neo4j.uri=bolt://127.0.0.1:17687 ``` ## 测试接口（bytedesk.debug=true 时可用） ```bash # 1. 服务状态与连通性检查 curl http://127.0.0.1:9003/spring/ai/api/v1/neo4j/status # 2. 写入演示知识图谱（幂等，:BytedeskDemo 标签隔离，模拟 分类-[:CONTAINS]->FAQ、FAQ-[:RELATED_TO]->FAQ、FAQ-[:MENTIONS]->产品实体） curl -X POST http://127.0.0.1:9003/spring/ai/api/v1/neo4j/seed-demo # 3. 读取演示图谱节点与关系 curl "http://127.0.0.1:9003/spring/ai/api/v1/neo4j/graph-demo?limit=100" # 4. 清理演示图谱数据 curl -X POST http://127.0.0.1:9003/spring/ai/api/v1/neo4j/clear-demo ``` ## 说明 - 镜像固定 `neo4j:5.26.30`（5.x LTS 社区版），不使用 `latest`，避免大版本漂移 - 应用侧相关参数：`bytedesk.ai.neo4j.enabled`（开关）、`uri`、`username`、`password`、`database`、`connect-timeout-ms`、`max-connection-pool-size` - 开关关闭（默认）时应用不触发任何连库行为，不影响启动；演示数据统一打 `:BytedeskDemo {demo:true}` 标签，与业务数据完全隔离 - 本阶段仅做连通性与演示验证，GraphRAG 检索增强等业务能力见 `docs/plans/` 知识图谱业务规划