GrafeoDB/grafeo-server

[](https://github.com/GrafeoDB/grafeo-server/actions/workflows/ci.yml) [](https://codecov.io/gh/GrafeoDB/grafeo-server) [](https://hub.docker.com/r/grafeo/grafeo-server) [](https://hub.docker.com/r/grafeo/grafeo-server) [](https://hub.docker.com/r/grafeo/grafeo-server) [](https://hub.docker.com/r/grafeo/grafeo-server) [](LICENSE) # Grafeo 服务器 [Grafeo](https://github.com/GrafeoDB/grafeo) 引擎的图数据库服务器。提供 REST API、嵌入式 Web UI、GQL Wire Protocol (gRPC) 以及 Bolt v5.x wire protocol 来访问 Grafeo 的多语言查询引擎。 纯 Rust 编写，单一二进制文件。提供四个层级以满足不同的部署需求。 [](http://localhost:7474/studio/) ## 快速开始 ### Docker Hub ``` # 标准 - HTTP + Studio UI，所有查询语言 docker run -p 7474:7474 grafeo/grafeo-server # 带持久化存储 docker run -p 7474:7474 -v grafeo-data:/data grafeo/grafeo-server --data-dir /data ``` 提供四个镜像层级： | 层级 | 标签 | 传输层 | 语言 | AI/搜索 | Web UI | 二进制文件 | | ------------ | ---------------------- | ----------------- | --------- | ----------- | ------ | ------- | | **gwp** | `grafeo-server:gwp` | GWP (gRPC :7688) | GQL | No | No | ~7 MB | | **bolt** | `grafeo-server:bolt` | Bolt v5 (:7687) | Cypher | No | No | ~8 MB | | **standard** | `grafeo-server:latest` | HTTP (:7474) | 所有 6 种 | No | Studio | ~21 MB | | **full** | `grafeo-server:full` | HTTP + GWP + Bolt | 所有 6 种 | Yes + embed | Studio | ~25 MB | ``` # GWP - gRPC 线协议，仅 GQL docker run -p 7688:7688 grafeo/grafeo-server:gwp --data-dir /data # Bolt - Neo4j 兼容的线协议，Cypher docker run -p 7687:7687 grafeo/grafeo-server:bolt --data-dir /data # 完整 - 包含 AI、auth、TLS、schemas 的所有内容 docker run -p 7474:7474 -p 7687:7687 -p 7688:7688 grafeo/grafeo-server:full ``` 带版本号的标签：`grafeo-server:0.4.8`、`grafeo-server:0.4.8-gwp`、`grafeo-server:0.4.8-bolt`、`grafeo-server:0.4.8-full`。 请参阅 [Docker Hub 上的 grafeo/grafeo-server](https://hub.docker.com/r/grafeo/grafeo-server) 获取所有可用标签。 ### Docker Compose ``` docker compose up -d ``` 服务器访问地址为 `http://localhost:7474`。Web UI 访问地址为 `http://localhost:7474/studio/`。 ### 从源码构建 ``` # 构建 web UI（可选，编译时嵌入） cd client && npm ci && npm run build && cd .. # 构建并运行（默认：HTTP + Studio + 所有语言） cargo run -- --data-dir ./data # 或用于快速实验的内存模式 cargo run ``` ## API ### 查询（自动提交） ``` # GQL（默认） curl -X POST http://localhost:7474/query \ -H "Content-Type: application/json" \ -d '{"query": "INSERT (:Person {name: '\''Alice'\'', age: 30})"}' curl -X POST http://localhost:7474/query \ -H "Content-Type: application/json" \ -d '{"query": "MATCH (p:Person) RETURN p.name, p.age"}' # Cypher curl -X POST http://localhost:7474/cypher \ -H "Content-Type: application/json" \ -d '{"query": "MATCH (n) RETURN count(n)"}' # GraphQL curl -X POST http://localhost:7474/graphql \ -H "Content-Type: application/json" \ -d '{"query": "{ Person { name age } }"}' # Gremlin curl -X POST http://localhost:7474/gremlin \ -H "Content-Type: application/json" \ -d '{"query": "g.V().hasLabel('\''Person'\'').values('\''name'\'')"}' # SQL/PGQ curl -X POST http://localhost:7474/sql \ -H "Content-Type: application/json" \ -d '{"query": "CALL grafeo.procedures() YIELD name, description"}' # SPARQL（在 RDF 三元组存储上操作，与属性图分离） curl -X POST http://localhost:7474/sparql \ -H "Content-Type: application/json" \ -d '{"query": "PREFIX foaf: PREFIX ex: INSERT DATA { ex:alice a foaf:Person . ex:alice foaf:name \"Alice\" }"}' curl -X POST http://localhost:7474/sparql \ -H "Content-Type: application/json" \ -d '{"query": "PREFIX foaf: SELECT ?name WHERE { ?p a foaf:Person . ?p foaf:name ?name }"}' ``` ### 图算法（CALL 存储过程） 所有查询 endpoint 均支持用于 22 种以上内置图算法的 `CALL` 存储过程： ``` # 列出所有可用算法 curl -X POST http://localhost:7474/query \ -H "Content-Type: application/json" \ -d '{"query": "CALL grafeo.procedures() YIELD name, description"}' # PageRank curl -X POST http://localhost:7474/query \ -H "Content-Type: application/json" \ -d '{"query": "CALL grafeo.pagerank({damping: 0.85}) YIELD node_id, score"}' # 通过 Cypher 的连通分量 curl -X POST http://localhost:7474/cypher \ -H "Content-Type: application/json" \ -d '{"query": "CALL grafeo.connected_components() YIELD node_id, component_id"}' ``` 可用算法包括：PageRank、BFS、DFS、Dijkstra、Bellman-Ford、Connected Components、Strongly Connected Components、Louvain、Label Propagation、Betweenness/Closeness/Degree Centrality、Clustering Coefficient、Topological Sort、Kruskal、Prim、Max Flow、Min-Cost Flow、Articulation Points、Bridges、K-Core 等等。 ### 管理 数据库内省、维护和索引管理。可通过 HTTP 和 GWP (gRPC) 使用。 ``` # 数据库统计信息（节点/边/标签/属性计数，内存，磁盘） curl http://localhost:7474/admin/default/stats # WAL 状态 curl http://localhost:7474/admin/default/wal # 强制 WAL checkpoint curl -X POST http://localhost:7474/admin/default/wal/checkpoint # 数据库完整性验证 curl http://localhost:7474/admin/default/validate # 创建属性索引 curl -X POST http://localhost:7474/admin/default/index \ -H "Content-Type: application/json" \ -d '{"index_type": "property", "label": "Person", "property": "name"}' # 删除索引 curl -X DELETE http://localhost:7474/admin/default/index \ -H "Content-Type: application/json" \ -d '{"index_type": "property", "label": "Person", "property": "name"}' # 查询计划缓存统计 curl http://localhost:7474/admin/default/cache # 清除查询计划缓存 curl -X POST http://localhost:7474/admin/default/cache/clear ``` ### 搜索 向量、文本和混合搜索 endpoint。需要相应的引擎特性（`vector-index`、`text-index`、`hybrid-search`），仅在完整层级中可用。 ``` # 向量相似性搜索（通过 HNSW 索引的 KNN） curl -X POST http://localhost:7474/search/vector \ -H "Content-Type: application/json" \ -d '{"database": "default", "vector": [0.1, 0.2, 0.3], "top_k": 10}' # 全文 BM25 搜索 curl -X POST http://localhost:7474/search/text \ -H "Content-Type: application/json" \ -d '{"database": "default", "query": "graph database", "top_k": 10}' # 混合搜索（向量 + 文本及 rank fusion） curl -X POST http://localhost:7474/search/hybrid \ -H "Content-Type: application/json" \ -d '{"database": "default", "query": "graph database", "vector": [0.1, 0.2, 0.3], "top_k": 10}' ``` ### 批量查询 在单个请求中原子地执行多个查询。所有查询在一个隐式事务中运行——如果任何查询失败，整个批次将回滚。 ``` curl -X POST http://localhost:7474/batch \ -H "Content-Type: application/json" \ -d '{ "queries": [ {"query": "INSERT (:Person {name: '\''Alice'\''})"}, {"query": "INSERT (:Person {name: '\''Bob'\''})"}, {"query": "MATCH (p:Person) RETURN p.name"} ] }' ``` ### 事务 ``` # 开启事务 SESSION=$(curl -s -X POST http://localhost:7474/tx/begin | jq -r .session_id) # 在事务中执行 curl -X POST http://localhost:7474/tx/query \ -H "Content-Type: application/json" \ -H "X-Session-Id: $SESSION" \ -d '{"query": "INSERT (:Person {name: '\''Bob'\''})"}' # 提交 curl -X POST http://localhost:7474/tx/commit \ -H "X-Session-Id: $SESSION" # 或回滚 curl -X POST http://localhost:7474/tx/rollback \ -H "X-Session-Id: $SESSION" ``` ### WebSocket 连接到 `ws://localhost:7474/ws`，通过持久连接进行交互式查询执行。消息使用带有 JSON 标签的协议： ``` // Client → Server: query {"type": "query", "id": "q1", "query": "MATCH (n) RETURN n", "language": "cypher", "database": "default"} // Server → Client: result {"type": "result", "id": "q1", "columns": [...], "rows": [...], "execution_time_ms": 1.2} // Client → Server: ping {"type": "ping"} // Server → Client: pong {"type": "pong"} ``` `id` 字段是可选的，并会被回传用于请求/响应关联。 ### GQL 线协议 (GWP) gwp 和完整构建版本在端口 7688 上包含了基于 gRPC 的二进制 wire protocol，完全符合 GQL 类型系统 (ISO/IEC 39075)。请使用 [`gwp`](https://crates.io/crates/gwp) (0.1.6) Rust 客户端或任何 gRPC 客户端。 ``` use gwp::client::GqlConnection; use std::collections::HashMap; let conn = GqlConnection::connect("http://localhost:7688").await?; let mut session = conn.create_session().await?; let mut cursor = session.execute( "MATCH (n:Person) RETURN n.name", HashMap::new(), ).await?; let rows = cursor.collect_rows().await?; session.close().await?; ``` 使用 `--gwp-port` 或 `GRAFEO_GWP_PORT` 配置端口（默认值：7688）。 ### Bolt v5.x (BoltR) bolt 和完整构建版本在端口 7687 上包含了 Bolt v5.x wire protocol，与 Neo4j 驱动兼容。请使用 [`boltr`](https://crates.io/crates/boltr) (0.1.2) Rust 客户端或任何 Bolt v5 驱动（Python `neo4j`、JavaScript `neo4j-driver` 等）。 使用 `--bolt-port` 或 `GRAFEO_BOLT_PORT` 配置端口（默认值：7687）。 ### 健康检查 ``` curl http://localhost:7474/health ``` ### API 文档 交互式 Swagger UI 在 `http://localhost:7474/api/docs/` 提供，OpenAPI JSON 规范在 `http://localhost:7474/api/openapi.json` 提供。 ## 配置 所有设置均可作为 CLI 标志和环境变量（前缀为 `GRAFEO_`）使用。CLI 标志会覆盖环境变量。 | 变量 | CLI 标志 | 默认值 | 描述 | |----------|----------|---------|-------------| | `GRAFEO_HOST` | `--host` | `0.0.0.0` | 绑定地址 | | `GRAFEO_PORT` | `--port` | `7474` | HTTP 绑定端口 | | `GRAFEO_DATA_DIR` | `--data-dir` | _(无)_ | 持久化目录（省略则使用内存） | | `GRAFEO_READ_ONLY` | `--read-only` | `false` | 以只读模式打开所有数据库 | | `GRAFEO_SESSION_TTL` | `--session-ttl` | `300` | 事务会话超时（秒） | | `GRAFEO_QUERY_TIMEOUT` | `--query-timeout` | `30` | 查询执行超时秒数（0 = 禁用） | | `GRAFEO_GWP_PORT` | `--gwp-port` | `7688` | GQL Wire Protocol (gRPC) 端口 | | `GRAFEO_GWP_MAX_SESSIONS` | `--gwp-max-sessions` | `0` | 最大并发 GWP 会话数（0 = 无限制） | | `GRAFEO_BOLT_PORT` | `--bolt-port` | `7687` | Bolt v5.x wire protocol 端口 | | `GRAFEO_BOLT_MAX_SESSIONS` | `--bolt-max-sessions` | `0` | 最大并发 Bolt 会话数（0 = 无限制） | | `GRAFEO_CORS_ORIGINS` | `--cors-origins` | _(无)_ | 逗号分隔的允许来源（`*` 表示全部） | | `GRAFEO_LOG_LEVEL` | `--log-level` | `info` | Tracing 日志级别 | | `GRAFEO_LOG_FORMAT` | `--log-format` | `pretty` | 日志格式：`pretty` 或 `json` | | `GRAFEO_RATE_LIMIT` | `--rate-limit` | `0` | 每个 IP 每个窗口的最大请求数（0 = 禁用） | | `GRAFEO_RATE_LIMIT_WINDOW` | `--rate-limit-window` | `60` | 速率限制窗口（秒） | ### 认证（特性：`auth`） 需要使用 `--features auth` 或 `--features full` 进行构建。 | 变量 | CLI 标志 | 默认值 | 描述 | |----------|----------|---------|-------------| | `GRAFEO_AUTH_TOKEN` | `--auth-token` | _(无)_ | Bearer token / API 密钥 | | `GRAFEO_AUTH_USER` | `--auth-user` | _(无)_ | HTTP Basic 用户名（需要密码） | | `GRAFEO_AUTH_PASSWORD` | `--auth-password` | _(无)_ | HTTP Basic 密码（需要用户名） | 设置 auth token 后，所有 API endpoint 都将要求提供 `Authorization: Bearer ` 或 `X-API-Key: `。`/health`、`/metrics` 和 `/studio/` 豁免此要求。 ``` # Bearer token grafeo-server --auth-token my-secret-token # Basic auth grafeo-server --auth-user admin --auth-password secret # 这两种方法可以同时配置 ``` ### TLS（特性：`tls`） 需要使用 `--features tls` 或 `--features full` 进行构建。 | 变量 | CLI 标志 | 默认值 | 描述 | |----------|----------|---------|-------------| | `GRAFEO_TLS_CERT` | `--tls-cert` | _(无)_ | TLS 证书 (PEM) 路径 | | `GRAFEO_TLS_KEY` | `--tls-key` | _(无)_ | TLS 私钥 (PEM) 路径 | ``` grafeo-server --tls-cert cert.pem --tls-key key.pem ``` ### 示例 ``` # 最小化（内存模式，无 auth） grafeo-server # 带 auth 和速率限制的持久化 grafeo-server --data-dir ./data --auth-token my-token --rate-limit 100 # 带 TLS 的生产环境 grafeo-server --data-dir /data --tls-cert /certs/cert.pem --tls-key /certs/key.pem \ --auth-token $API_TOKEN --rate-limit 1000 --cors-origins "https://app.example.com" \ --log-format json ``` ## 特性标志 Grafeo Server 使用 Cargo 特性标志来控制编译时包含的功能。该架构将传输层（`http`、`gwp`）与核心数据库功能分离，从而允许为不同的部署场景构建最小化的版本。 ### 层级 | 层级 | Cargo 命令 | 传输层 | 内容 | |------|--------------|-----------|--------------| | **GWP** | `--no-default-features --features gwp` | GWP (gRPC) | GQL + 存储, ~7 MB | | **Bolt** | `--no-default-features --features bolt` | Bolt v5 | Cypher + 存储, ~8 MB | | **Standard** | _(默认)_ | HTTP | 所有语言，Studio UI，算法, ~21 MB | | **Full** | `--features full` | HTTP + GWP + Bolt | 包含 AI、auth、TLS 在内的一切功能, ~25 MB | ``` # 标准（默认） cargo build --release # GWP - gRPC 线协议，仅 GQL cargo build --release --no-default-features --features gwp # Bolt - Neo4j 兼容，仅 Cypher cargo build --release --no-default-features --features bolt # 完整 - 包含所有内容 cargo build --release --features full ``` ### 自定义构建 使用 `--no-default-features` 开始，然后根据需要挑选。下方的矩阵展示了各特性的兼容性。 **传输层**（选择一个或多个）： | 特性 | 描述 | 端口 | |---------|-------------|------| | `http` | 通过 axum 提供 REST API (Swagger, OpenAPI, WebSocket) | 7474 | | `gwp` | GQL Wire Protocol (gRPC) | 7688 | | `bolt` | Bolt v5 wire protocol（兼容 Neo4j） | 7687 | **查询语言**（单独选择或使用 `all-languages`）： | 特性 | 描述 | 备注 | |---------|-------------|-------| | `gql` | GQL (ISO/IEC 39075) | 适用于所有传输层 | | `cypher` | Cypher (openCypher 9.0) | 适用于所有传输层 | | `sparql` | SPARQL (W3C 1.1) | 隐含 `rdf` | | `gremlin` | Gremlin (Apache TinkerPop) | 适用于所有传输层 | | `graphql` | GraphQL | 适用于所有传输层 | | `sql-pgq` | SQL/PGQ (SQL:2023 GRAPH_TABLE) | 适用于所有传输层 | **引擎能力**： | 特性 | 描述 | 依赖 | |---------|-------------|----------| | `storage` | parallel + wal + spill + mmap | 无（推荐所有构建使用） | | `algos` | 通过 CALL 存储过程提供 22 种以上图算法 | 无 | | `ai` | vector-index + text-index + hybrid-search + cdc | 无 | | `rdf` | RDF 三元组存储 | 由 `sparql` 自动启用 | | `embed` | 进程内 ONNX 嵌入生成（~17 MB） | 无 | | `temporal` | 仅追加的版本化属性 | 无 | | `import` | LOAD DATA 格式支持 (jsonl-import + parquet-import) | 无 | | `metrics` | 引擎级别的 Prometheus 指标 | 无 | **服务器扩展**（需要 `http`）： | 特性 | 描述 | 依赖 | |---------|-------------|----------| | `studio` | 嵌入式 Web UI | `http` | | `auth` | Bearer token + HTTP Basic 认证 | 任意传输层 | | `tls` | 通过 rustls 提供内置 HTTPSRPCS | 任意传输层 | | `owl-schema` | OWL/Turtle 模式加载 | 无 | | `rdfs-schema` | RDFS 模式支持 | `owl-schema`（隐含） | | `json-schema` | JSON Schema 验证 | 无 | **兼容性说明**： - `studio` 需要 `http`（无独立 Studio） - `sparql` 隐含 `rdf`（始终会创建 RDF 存储） - `gwp` 使用端口 7688，`bolt` 默认使用端口 7687，可通过 `--gwp-port` / `--bolt-port` 配置 - `auth` 和 `tls` 适用于任何已启用的传输层 - 所有其他特性均可自由组合 **示例**： ``` # 无 Studio UI 的 HTTP API cargo build --release --no-default-features --features "http,all-languages,storage" # 标准 + auth cargo build --release --features auth # GWP + Bolt（两种线协议，无 HTTP） cargo build --release --no-default-features --features "gwp,bolt,gql,cypher,storage" # 最小化 AI 服务器（HTTP + GQL + 向量/文本搜索） cargo build --release --no-default-features --features "http,gql,storage,ai" # 边缘部署（GWP + GQL，无算法） cargo build --release --no-default-features --features "gwp,gql,storage" ``` ### Docker 构建目标 Dockerfile 支持与层级相匹配的四个构建目标： ``` docker build --target gwp -t grafeo-server:gwp . # GWP-only, port 7688 docker build --target bolt -t grafeo-server:bolt . # Bolt-only, port 7687 docker build --target standard -t grafeo-server:standard . # HTTP + UI, port 7474 (default) docker build --target full -t grafeo-server:full . # All ports ``` ### 特性发现 `/health` endpoint 会报告已编译到运行中服务器的特性： ``` { "status": "ok", "features": { "languages": ["gql", "cypher", "sparql", "gremlin", "graphql", "sql-pgq"], "engine": ["parallel", "wal", "spill", "mmap"], "server": ["gwp"] } } ``` ## 开发 ``` cargo build # Debug build cargo test # Run tests (default features) cargo test --features auth # Run tests including auth tests cargo fmt --all -- --check # Check formatting cargo clippy --all-targets -- -D warnings # Lint cargo deny check # License/advisory audit ``` ### Web UI 开发 ``` # 终端 1：服务器 cargo run # 终端 2：带 HMR 的 UI 开发服务器（将 API 代理到 :7474） cd client && npm run dev # 打开 http://localhost:5173 ``` ## 相关项目 - [Grafeo](https://github.com/GrafeoDB/grafeo)，可嵌入式图数据库引擎 - [grafeo-web](https://github.com/GrafeoDB/grafeo-web)，通过 WebAssembly 在浏览器中运行的 Grafeo - [anywidget-graph](https://github.com/GrafeoDB/anywidget-graph)，用于 Notebook 的交互式图可视化组件 ## 许可证 Apache-2.0

标签：Apache-2.0许可, Bolt协议, CNCF毕业项目, DNS解析, Docker容器, GQL查询语言, Grafeo数据库, gRPC协议, HTTP服务器, IP 地址批量处理, Python工具, REST API, Rust编程语言, TCP SYN 扫描, Web UI, 中间件, 单文件二进制, 可视化界面, 后端开发, 开源项目, 攻击面发现, 数据库引擎, 数据持久化, 暗色界面, 独立部署, 网络信息收集, 请求拦截, 远程访问