访问 Neo4j

运行在 Kubernetes 上的 Neo4j 可通过 Kubernetes Service 进行访问。Neo4j 针对不同的应用和操作目的提供了多种接口。有关更多详细信息，请参阅 Neo4j 端口。

支持的 Kubernetes Service

Neo4j 支持以下 Kubernetes Service

  • 默认 Service (Default Service) — 一个 ClusterIP Service，用于从 Kubernetes 集群内部发起的 Neo4j 数据库 neo4j/bolt 和 http(s) 连接。

  • 管理 Service (Admin Service) — 一个“无头”（仅限 DNS）Service，包含所有用于在 Kubernetes 内部进行 Neo4j 管理连接的 Neo4j 端口。它仅在 Kubernetes 集群内部可用，且对它的访问应受到保护。管理 Service 可用于 Neo4j DBMS 管理、执行备份以及收集指标。

  • 内部 Service (Internal Service) — 一个“无头”（仅限 DNS）内部 Service，包含 Neo4j 集群所需的所有 Neo4j 端口。

  • Neo4j Service — 一个 LoadBalancer Service，用于从 Kubernetes 集群外部发起的 neo4j/bolt 和 http(s) 连接。

以下是每个 Neo4j 接口和部署类型的默认 Kubernetes Service 列表

Neo4j 接口 默认端口 默认 Service 管理 Service Neo4j Service

Bolt (neo4j:// 和 bolt:// 协议)

7687

是

是*

是

Neo4j 浏览器 HTTP

7474

是

是*

是

Neo4j 浏览器 HTTPS

7473

是

是*

是

Neo4j Cypher HTTP API

7474

是

是*

是

Neo4j Cypher HTTPS API

7473

是

是*

是

Neo4j 备份

6362

否

是

否 但可配置

Graphite 监控

2003

否

是

否

Prometheus 指标

2004

否

是

否

Java 管理扩展 (JMX)

3637

否

否 但可配置

否
Neo4j 接口 默认端口 默认 Service 管理 Service 内部 Service Neo4j Service

Bolt (neo4j:// 和 bolt:// 协议)

7687

是

是*

是

是

Neo4j 浏览器 HTTP

7474

是

是*

是

是

Neo4j 浏览器 HTTPS

7473

是

是*

是

是

Neo4j Cypher HTTP API

7474

是

是*

是

是

Neo4j Cypher HTTPS API

7473

是

是*

是

是

Neo4j 备份

6362

否

是

是

否

Graphite 监控

2003

否

否 但可配置

否 但可配置

否

Prometheus 指标

2004

否

否 但可配置

否 但可配置

否

Java 管理扩展 (JMX)

3637

否

否 但可配置

否 但可配置

否

集群发现管理

5000

否

否

是

否

集群事务

6000

否

否

是

否

集群 RAFT

7000

否

否

是

否

集群路由连接器

7688

否

否

是

否

*管理 Service 会绕过健康检查。这使得它可以在数据库处于不健康状态时，用于建立管理目的的连接。但是，请勿将其用于需要数据库处于健康状态的应用连接。

从 Kubernetes 内部访问 Neo4j 的应用程序

使用 DNS 访问 Neo4j

要从同一 Kubernetes 集群中的应用程序访问 Neo4j，请使用 Neo4j Service 的 DNS 地址 <release-name>.<namespace>.svc.<cluster domain>。

默认集群域为 cluster.local，默认命名空间为 default。通常，Neo4j Service 的 DNS 地址为 <release-name>.default.svc.cluster.local。

例如，如果在 default 命名空间中使用发布名称 my-release，则集群的 DNS 地址将为 my-release.default.svc.cluster.local，用于 Neo4j 驱动程序的 bolt 地址应为 neo4j://my-release.default.svc.cluster.local:7687。

为了允许在 Kubernetes 内部运行的应用程序访问 Neo4j 集群，您还可以使用通过 neo4j/neo4j-cluster-headless-service Helm chart 安装的 Neo4j 无头 (headless) Service。有关更多信息和详细示例，请参阅 使用无头 Service 访问 Neo4j 集群。

使用 K8s 标签选择器访问 Neo4j

或者，可以通过 Kubernetes Service 发现功能，使用标签选择器搜索来定位 Kubernetes 中的 Neo4j Service（默认）。

helm.neo4j.com/service=default/admin/internals,helm.neo4j.com/instance=<release-name>

例如：

# install neo4j
helm install "my-release" …
# lookup installed service
kubectl get service -l helm.neo4j.com/service=default,helm.neo4j.com/instance=my-release
helm.neo4j.com/service=neo4j,helm.neo4j.com/instance=<release-name>

以下是如何查找已安装 Service 的示例

# Neo4j service:

kubectl get service -l helm.neo4j.com/service=default,helm.neo4j.com/instance=my-release

# Admin service:

kubectl get service -l helm.neo4j.com/service=admin,helm.neo4j.com/instance=my-release

# internals service:

kubectl get service -l helm.neo4j.com/service=internals,helm.neo4j.com/instance=my-release

从 Kubernetes 外部访问 Neo4j 的应用程序

要从 Kubernetes 集群外部的应用程序访问 Neo4j，您可以使用 LoadBalancer Service 或 Ingress 控制器。

使用 LoadBalancer 访问 Neo4j

Neo4j Helm chart 提供了一个 LoadBalancer Service，用于从 Kubernetes 集群外部访问 Neo4j。安装 Neo4j Helm chart 时，默认会创建 LoadBalancer Service。该 LoadBalancer Service 默认配置为暴露 Neo4j 端口 7687、7474、7473 和 6362（备份）。

可以使用 kubectl 找到 LoadBalancer 的外部 IP

  • Service 名称基于 neo4j.name 的值 —— <my-neo4j-name>-lb-neo4j

    kubectl get service `<my-neo4j-name>-lb-neo4j` -ocustom-columns=ip:.status.loadBalancer.ingress[].ip

  • 使用标签选择器

    kubectl get service -l helm.neo4j.com/service=neo4j,helm.neo4j.com/name=<release-name> -ocustom-columns=ip:.status.loadBalancer.ingress[].ip

如果您使用的 Kubernetes LoadBalancer 实现支持设置静态 IP，则可以通过在 Neo4j Helm 发布中设置 services.neo4j.spec.loadBalancerIP 来配置 LoadBalancer 的 IP 地址。如果未明确设置静态 IP 地址，Kubernetes 不保证动态分配的 IP 地址不会更改。

在互联网上暴露 Neo4j 数据库时，建议使用静态 IP 并在暴露的 Service 上配置 SSL。有关更多信息，请参阅 配置 SSL。

如果您有静态 IP，则可以将 DNS 与它们关联并获取受信任的证书。

外部 Service 上暴露的端口可以在 Helm 发布中通过更改 services.neo4j 对象进行配置。默认值为

services:
  neo4j:
    enabled: true
    annotations: { }
    spec:
      type: LoadBalancer
      loadBalancerIP: NULL
    ports:
      http:
        enabled: true # Set this to false to remove HTTP from this service (this does not affect whether http is enabled for the neo4j process)
        # uncomment to publish http on port 80 (neo4j default is 7474)
        #port: 80
        #targetPort: 7474
        #name: http
        #nodePort: <your-nodeport>, enabled only when type set to NodePort
      https:
        enabled: true # Set this to false to remove HTTPS from this service (this does not affect whether https is enabled for the neo4j process)
        # uncomment to publish http on port 443 (neo4j default is 7473)
        #port: 443
        #targetPort: 7473
        #name: https
        #nodePort: <your-nodeport>, enabled only when type set to NodePort
      bolt:
        enabled: true # Set this to false to remove BOLT from this service (this does not affect whether https is enabled for the neo4j process)
        # Uncomment to explicitly specify the port to publish Neo4j Bolt (7687 is the default)
        #port: 7687
        #targetPort: 7687
        #name: tcp-bolt
        #nodePort: <your-nodeport>, enabled only when type set to NodePort
      backup:
        enabled: false # Set this to true to expose backup port externally (n.b. this could have security implications. Backup is not authenticated by default)
        # Uncomment to explicitly specify the port to publish Neo4j Backup (6362 is the default)
        #port: 6362
        #targetPort: 6362
        #name: tcp-backup
        #nodePort: <your-nodeport>, enabled only when type set to NodePort

在 services.neo4j 对象上禁用/启用端口会将其从负载均衡器中移除，但不会影响它在 Neo4j 中是否被禁用/启用。

除非在 Neo4j 配置中强制执行 SSL-with-client-auth，否则备份是不安全的。

有关详细示例，请参阅 从 Kubernetes 外部访问 Neo4j 集群。

自定义 Kubernetes 资源

Neo4j Helm chart 会创建各种 Kubernetes 资源。其中一些可以通过向 Helm 部署 values 文件添加额外配置来进行自定义。

以下是支持的 K8s 资源自定义列表

自定义项 values.yaml 字段 类型

为 Neo4j Pod 设置 pod securityContext

securityContext

PodSecurityContext

向 Service 添加注解

services.default.annotations

ClusterIP Service 的注解对象。

services.admin.annotations

无头 (DNS) Service 的注解对象。

services.neo4j.annotations

LoadBalancer Service 的注解对象。
自定义项 values.yaml 字段 类型

为 Neo4j Pod 设置 pod securityContext

securityContext

PodSecurityContext

向 Service 添加注解

services.default.annotations

ClusterIP Service 的注解对象。

services.admin.annotations

无头 (DNS) Service 的注解对象。

services.internal.annotations

内部 Service 的注解对象。

向负载均衡器 Service 添加注解

services.neo4j.annotations

LoadBalancer Service 的注解对象。

访问 Neo4j 进行 DBMS 管理和监控

Neo4j Helm chart 会创建用于 Neo4j 管理的管理 Service。管理 Service 是 Kubernetes 中的“无头”Service，不依赖于 Neo4j 健康检查。因此，即使 Neo4j 不健康，它也允许连接到 Neo4j。通常，这对应用程序来说不是理想的，但对于管理和调试非常有用。

使用 DNS 访问 Neo4j

要在 Kubernetes 内部访问管理 Service，请使用 DNS 地址 <release-name>-admin.<namespace>.svc.<cluster domain>。

例如，如果在 default 命名空间中使用发布名称 my-release，则集群的 DNS 地址将为 my-release-admin.default.svc.cluster.local。

管理 Service 可用于访问一系列 Neo4j 接口

  • Neo4j Bolt：通过 Cypher 命令进行 Neo4j 管理。

  • Neo4j 备份：用于执行数据库备份。

  • Graphite：用于指标收集。

  • Prometheus：用于指标收集。

  • Java 管理扩展 (JMX)：用于指标收集和 JVM 管理。

使用 kubectl 访问 Neo4j 进行故障排除

要获取用于故障排除的交互式 cypher-shell 控制台，请使用此命令

kubectl run -it --rm --image neo4j:2026.03.1 cypher-shell -- cypher-shell -a bolt://my-release-admin.default.svc.cluster.local

通常，neo4j:// 协议用于连接到 Neo4j。但是，在故障排除时，会使用直接的 bolt:// 协议，因为它允许在某些 neo4j:// 连接无法成功的情况下进行连接。