插件

向 Neo4j Helm Chart 部署添加 Neo4j 插件有三种推荐方法。您可以使用

使用自动插件下载添加插件

您可以配置 Neo4j 部署以自动下载并安装插件。如果插件需要许可证，则必须在 Secret 中提供这些许可证。

安装 GDS 社区版 (CE)

GDS 社区版不需要许可证。要添加 GDS CE，请配置 Neo4j 的 values.yaml 并设置 env 以下载插件

neo4j:
  name: licenses
  acceptLicenseAgreement: "yes"
  edition: enterprise
volumes:
  data:
    mode: defaultStorageClass
env:
  NEO4J_PLUGINS: '["graph-data-science"]'
config:
  dbms.security.procedures.unrestricted: "gds.*"

安装 GDS 企业版 (EE) 和 Bloom 插件

要安装 GDS EE 和 Bloom，您必须为每个插件提供许可证。您需要在 Kubernetes Secret 中提供这些许可证。

  1. 创建包含许可证的 Secret

    kubectl create secret  generic --from-file=gds.license,bloom.license gds-bloom-license

  2. 配置 Neo4j values.yaml 文件，使用该 Secret 作为 /licenses 卷挂载，并设置 env 以下载插件

    neo4j:
  name: licenses
  acceptLicenseAgreement: "yes"
  edition: enterprise
volumes:
  data:
    mode: defaultStorageClass
  licenses:
    disableSubPathExpr: true
    mode: volume
    volume:
      secret:
        secretName: gds-bloom-license
        items:
          - key: gds.license
            path: gds.license
          - key: bloom.license
            path: bloom.license
env:
  NEO4J_PLUGINS: '["graph-data-science", "bloom"]'
config:
  gds.enterprise.license_file: "/licenses/gds.license"
  dbms.security.procedures.unrestricted: "gds.*,apoc.*,bloom.*"
  server.unmanaged_extension_classes: "com.neo4j.bloom.server=/bloom,semantics.extension=/rdf"
  dbms.security.http_auth_allowlist: "/,/browser.*,/bloom.*"
  dbms.bloom.license_file: "/licenses/bloom.license"

使用自定义容器镜像添加插件

将插件添加到运行在 Kubernetes 中的 Neo4j 的最佳方法是创建一个新的 Docker 容器镜像，其中同时包含 Neo4j 和 Neo4j 插件。这样，您可以在构建容器时确保使用与容器内 Neo4j 版本相匹配的正确插件版本，并确保生成的镜像封装了所有 Neo4j 运行时依赖项。

Neo4j Bloom 插件需要一个许可证激活密钥，该密钥需要放置在 Neo4j Docker 容器可访问的目录中（例如，挂载到 /licenses，这是默认设置）。要获取有效许可证，请联系您的 Neo4j 客户代表或使用 联系 Neo4j 表单。

构建基于官方 Neo4j Docker 镜像且不覆盖官方镜像 ENTRYPOINT 和 COMMAND 的 Docker 容器镜像，是与 Neo4j Helm Chart 配合使用的推荐方法，如下面的 Dockerfile 示例所示

ARG  NEO4J_VERSION
FROM neo4j:${NEO4J_VERSION}

# copy my-plugins into the Docker image
COPY my-plugins/ /var/lib/neo4j/plugins

# install the apoc core plugin that is shipped with Neo4j
RUN cp /var/lib/neo4j/labs/apoc-* /var/lib/neo4j/plugins

Docker 镜像构建完成后，将其推送到 Kubernetes 集群可访问的容器仓库中。

CONTAINER_REPOSITORY="my-container-repository.io"
IMAGE_NAME="my-neo4j"

# export this so that it's accessible as a docker build arg
export NEO4J_VERSION=2026.03.1-enterprise

docker build --build-arg NEO4J_VERSION --tag ${CONTAINER_REPOSITORY}/${IMAGE_NAME}:${NEO4J_VERSION} .
docker push ${CONTAINER_REPOSITORY}/${IMAGE_NAME}:${NEO4J_VERSION}

要使用您创建的镜像，请在 Neo4j Helm 部署的 values.yaml 文件中，将 image.customImage 设置为使用该镜像。

许多插件需要额外的 Neo4j 配置才能正常工作。插件配置应在 Helm 部署 values.yaml 文件的 config 对象上设置。在某些情况下，插件配置可能会导致 Neo4j 的严格配置验证失败。通过设置 server.config.strict_validation.enabled: "false" 可以禁用严格配置验证。

使用插件卷添加插件

向 Neo4j Helm 部署添加 Neo4j 插件的另一种方法是使用 plugins 卷挂载。使用此方法，插件 jar 文件存储在挂载到 Neo4j 容器 /plugins 目录的持久卷 (Persistent Volume) 上。

Neo4j Bloom 插件需要一个许可证激活密钥，该密钥需要放置在 Neo4j Docker 容器可访问的目录中（例如，挂载到 /licenses，这是默认设置）。要获取有效许可证，请联系您的 Neo4j 客户代表或使用 联系 Neo4j 表单。

设置持久化 plugins 卷的最简单方法是共享用于存储 Neo4j 数据的持久卷。此示例展示了如何在 Neo4j Helm 部署的 values.yaml 文件中进行配置

# neo4j-values.yaml
volumes:
  data:
    # your data volume configuration
    ...

  plugins:
    mode: "share"
    share:
      name: "data"

配置卷挂载的不同方法的详细信息，请参阅 将卷挂载映射到持久卷。

现在的 Neo4j 容器拥有一个由持久卷支持的空 /plugins 目录。可以使用 kubectl cp 将插件 jar 文件复制到该卷上。由于它由持久卷支持，即使 Neo4j Pod 重启或迁移，插件文件也会持久存在。

Neo4j 仅在启动时加载插件。因此，一旦所有插件就位，您必须重启 Neo4j Pod 以加载它们。

例如：

# Copy plugin files into the Neo4j container
kubectl cp my-plugins/* <namespace>/<neo4j-pod-name>:/plugins/

# Restart Neo4j
kubectl rollout restart statefulset/<neo4j-statefulset-name>

# Verify plugins are still present after restart
kubectl exec <neo4j-pod-name> -- ls /plugins

仅配置和安装 APOC core

APOC core 库随 Neo4j 一起提供，位于 labs 文件夹中。

如果 APOC core 是您想要添加到 Neo4j 的 唯一 插件，则无需执行上述插件安装步骤。相反，您可以通过在 values.yaml 文件中添加以下设置来升级部署，从而配置 Helm 部署以使用 APOC core

  1. 通过直接指向 labs 文件夹中 APOC core 库的位置，并加载和解除对您所需函数和过程的限制来配置 APOC core（有关详细信息，请参阅 APOC 安装指南）。例如

    config:
  server.directories.plugins: "/var/lib/neo4j/labs"
  dbms.security.procedures.unrestricted: "apoc.*"
  server.config.strict_validation.enabled: "false"
  dbms.security.procedures.allowlist: "apoc.math.*,apoc.cypher.*"

  2. 在 apoc_config 下，配置您需要的 APOC 设置，例如

    apoc_config:
  apoc.trigger.enabled: "true"
  apoc.jdbc.neo4j.url: "jdbc:foo:bar"
  apoc.import.file.enabled: "true"

  3. 运行 helm upgrade 以应用更改

    helm upgrade <release-name> neo4j/neo4j -f values.yaml

  4. Helm 升级 rollout 完成后，通过使用 cypher-shell 或 Neo4j Browser 运行以下 Cypher 查询来验证 APOC core 是否已配置

    RETURN apoc.version()

使用 APOC-extended 为插件别名配置凭据

Neo4j Helm Chart 支持使用挂载在指定路径上的 Kubernetes Secret 为插件的别名配置凭据。此功能适用于通过 APOC-extended 实现的 apoc.jdbc.<aliasname>.url 和 apoc.es.<aliasname>.url。

Secret 必须提前创建，并且必须包含名为 URL 的键，否则 Helm Chart 会抛出错误。例如： kubectl create secret generic jdbcsecret --from-literal=URL="jdbc:mysql://30.0.0.0:3306/Northwind?user=root&password=password"

在 apoc_credentials 下，配置 aliasName、secretName 和 secretMountPath。例如

apoc_credentials: {}
#   jdbc:
#    aliasName: "jdbc"
#    secretName: "jdbcsecret"
#    secretMountPath: "/secret/jdbcCred"
#
#   elasticsearch:
#     aliasName: "es"
#     secretName: "essecret"
#     secretMountPath: "/secret/esCred"