Apache Cassandra

当您需要可扩展性和高可用性而不牺牲性能时，Apache Cassandra 数据库是正确的选择。在商用硬件或云基础设施上实现线性可扩展性和经验证的容错性，使其成为任务关键型数据的理想平台。Cassandra 对跨多个数据中心复制的支持是同类最佳的，可为您的用户提供更低的延迟，并让您安心，知道您可以抵御区域性中断。已知最大的 Cassandra 集群拥有超过 75,000 个节点，存储超过 10 PB 的数据。

— Apache Cassandra 主页

以下部分概述了 JanusGraph 与 Apache Cassandra 协同工作的各种方式。

Cassandra 存储后端

Cassandra 为客户端提供了两种协议：CQL 和 Thrift。在 Cassandra 4.0 中，Cassandra 将移除 Thrift 支持。JanusGraph 只支持 CQL 存储后端。

注意

如果 Cassandra 上启用了安全性，则用户必须拥有 对的 CREATE 权限，否则密钥空间必须由管理员提前创建，包括所需的表，或者用户必须拥有 对的 CREATE 权限。包含所需表的创建表文件位于 conf/cassandra/cassandraTables.cql 中。请在执行之前定义您的密钥空间。

本地服务器模式

Cassandra 可以作为独立数据库运行，与 JanusGraph 和最终用户应用程序位于同一本地主机上。在此模型中，JanusGraph 和 Cassandra 通过 localhost 套接字相互通信。在 Cassandra 上运行 JanusGraph 需要以下设置步骤：

下载 Cassandra，解压，并在 conf/cassandra.yaml 中设置文件系统路径。
使用预打包发行版中提供的默认配置文件将 Gremlin Server 连接到 Cassandra。
在 Cassandra 解压的目录中，在命令行中调用 bin/cassandra -f 启动 Cassandra。阅读输出以检查 Cassandra 是否成功启动。

现在，您可以如下创建 Cassandra JanusGraph
```
JanusGraph g = JanusGraphFactory.build().
set("storage.backend", "cql").
set("storage.hostname", "127.0.0.1").
open();
```

在 Gremlin 控制台中，您无法定义变量 conf 和 g 的类型。因此，只需省略类型声明即可。

本地容器模式

Cassandra 没有针对 Windows 或 OSX 的原生安装。在 OSX、Windows 或 Linux 上运行 Cassandra 最简单的方法之一是使用 Docker 容器。您可以通过一个 Docker 命令下载并运行 Cassandra。重要的是安装与您打算使用的 JanusGraph 版本兼容的版本。兼容版本可以在发布页面上特定版本的“测试兼容性”部分下找到。Cassandra Docker Hub 页面可以作为可用版本和有用命令的参考。端口的描述可以在此处找到。端口 9160 用于 Thrift 客户端 API。端口 9042 用于 CQL 原生客户端。端口 7000、7001 和 7099 用于节点间通信。Cassandra 3.11 版本是 JanusGraph 0.2.0 的最新兼容版本，并在下面的参考命令中指定。

docker run --name jg-cassandra -d -e CASSANDRA_START_RPC=true -p 9160:9160 \
  -p 9042:9042 -p 7199:7199 -p 7001:7001 -p 7000:7000 cassandra:3.11

远程服务器模式

当图需要扩展到单机范围之外时，Cassandra 和 JanusGraph 在逻辑上被分离到不同的机器中。在此模型中，Cassandra 集群维护图表示，任意数量的 JanusGraph 实例维护对 Cassandra 集群基于套接字的读/写访问。最终用户应用程序可以直接与 JanusGraph 在与 JanusGraph 相同的 JVM 中进行交互。

例如，假设我们有一个正在运行的 Cassandra 集群，其中一台机器的 IP 地址为 77.77.77.77，那么将 JanusGraph 连接到集群的方法如下（逗号分隔 IP 地址以引用多台机器）

JanusGraph graph = JanusGraphFactory.build().
  set("storage.backend", "cql").
  set("storage.hostname", "77.77.77.77").
  open();

在 Gremlin 控制台中，您无法定义变量 conf 和 g 的类型。因此，只需省略类型声明即可。

带 Gremlin 服务器的远程服务器模式

Gremlin Server 可以包装在上一小节中定义的每个 JanusGraph 实例周围。通过这种方式，最终用户应用程序不必是基于 Java 的应用程序，因为它可以作为客户端与 Gremlin Server 通信。这种部署类型非常适合多语言架构，其中用不同语言编写的各种组件需要引用图并对其进行计算。

使用 bin/janusgraph-server.sh 启动 Gremlin Server，然后在外部 Gremlin Console 会话中使用 bin/gremlin.sh，您可以通过网络发送 Gremlin 命令

:plugin use tinkerpop.server
:remote connect tinkerpop.server conf/remote.yaml
:> g.addV()

在这种情况下，每个 Gremlin 服务器都将配置为连接到 Cassandra 集群。以下显示了 Gremlin 服务器配置中特定于图的片段。有关完整示例和如何配置服务器的更多信息，请参阅 JanusGraph 服务器。

...
graphs: {
  g: conf/janusgraph-cql.properties
}
scriptEngines: {
  gremlin-groovy: {
    plugins: { org.janusgraph.graphdb.tinkerpop.plugin.JanusGraphGremlinPlugin: {},
               org.apache.tinkerpop.gremlin.server.jsr223.GremlinServerGremlinPlugin: {},
               org.apache.tinkerpop.gremlin.tinkergraph.jsr223.TinkerGraphGremlinPlugin: {},
               org.apache.tinkerpop.gremlin.jsr223.ImportGremlinPlugin: {classImports: [java.lang.Math], methodImports: [java.lang.Math#*]},
               org.apache.tinkerpop.gremlin.jsr223.ScriptFileGremlinPlugin: {files: [scripts/empty-sample.groovy]}}}}
...

有关 Gremlin Server 的更多信息，请参阅 Apache TinkerPop 文档

CQL 特定配置

有关所有 Cassandra 特定配置选项以及通用 JanusGraph 配置选项的完整列表，请参阅配置参考。

在配置 CQL 时，建议考虑以下 CQL 特定配置选项

read-consistency-level: Cassandra 读取操作的一致性级别
write-consistency-level: Cassandra 写入操作的一致性级别
replication-factor: 要使用的复制因子。复制因子越高，图数据库对机器故障的鲁棒性越强，但代价是数据重复。对于生产系统，应覆盖默认值以确保鲁棒性。建议值为 3。此复制因子只能在最初创建密钥空间时设置。对于现有密钥空间，此值将被忽略。
keyspace: 存储 JanusGraph 图的密钥空间的名称。允许多个 JanusGraph 图在同一个 Cassandra 集群中共存。

有关 Cassandra 一致性级别和可接受值的更多信息，请参阅此处。一般来说，更高的级别更一致、更健壮，但延迟也更高。

全局图操作

JanusGraph over Cassandra 支持全局顶点和边迭代。但是，请注意，所有这些顶点和/或边都将加载到内存中，这可能导致 OutOfMemoryException。使用 JanusGraph with TinkerPop’s Hadoop-Gremlin 以有效地迭代大型图中的所有顶点或边。

部署在 DataStax Astra 上

Astra DB 简化了云原生 Cassandra 应用程序开发。它将部署时间从数周缩短到数分钟，并提供了前所未有的无服务器、按需付费定价以及多云和开源的自由和灵活性。

— DataStax Astra

下载适用于您的 Astra 数据库的安全连接压缩包。

当从 JanusGraph 连接到 Astra DB 时，最好直接使用安全捆绑连接文件，而无需解压缩它。有多种方法可以将安全捆绑连接文件传递给 JanusGraph 配置，以便使用 DataStax 驱动程序连接到 Astra DB。

内部字符串配置

将属性 storage.cql.internal.string-configuration 设置为 datastax-java-driver { basic.cloud.secure-connect-bundle= }，并设置用户名、密码和密钥空间详细信息。

例如

gremlin.graph=org.janusgraph.core.JanusGraphFactory
storage.backend=cql
storage.cql.keyspace=<keyspace name which was created in AstraDB>
storage.username=<clientID>
storage.password=<clientSecret>
storage.cql.internal.string-configuration=datastax-java-driver { basic.cloud.secure-connect-bundle=<path-to-secure-bundle-zip-file> }

此外，您可以通过设置 jvm 参数来传递安全捆绑文件，如下所示，并从上述列表中删除该属性 (storage.cql.internal.string-configuration)。

-Ddatastax-java-driver.basic.cloud.secure-connect-bundle=

内部文件配置

如果您希望将 Astra 连接相关属性外部化到单独的文件中，并在该文件中指定安全捆绑包和凭据信息，则将属性 storage.cql.internal.file-configuration 设置为外部配置文件。

例如

gremlin.graph=org.janusgraph.core.JanusGraphFactory
storage.backend=cql
storage.cql.keyspace=<keyspace-name>
# Link to the external file that DataStax driver understands
storage.cql.internal.file-configuration=<path-to-astra.conf>

astra.conf（外部文件）

datastax-java-driver {
  basic.cloud {
    secure-connect-bundle = "<path-to-secure-bundle-zip-file>"
  }
  advanced.auth-provider {
    class = PlainTextAuthProvider
    username = "<clientID>"
    password = "<clientSecret>"
  }
}

注意：客户端 ID 和客户端密钥需要根据本文档从您的 Astra 帐户生成并复制。

要了解有关 DataStax 驱动程序不同配置选项的更多信息，请参阅 DataStax 驱动程序配置文档。

部署在 Amazon Keyspaces 上

Amazon Keyspaces（适用于 Apache Cassandra）是一种可扩展、高可用且托管的 Apache Cassandra 兼容数据库服务。Amazon Keyspaces 是无服务器的，因此您只需为使用的资源付费，服务可以根据应用程序流量自动扩展表。

— Amazon Keyspaces

注意

对 Amazon Keyspaces 的支持是实验性的。除非您已经根据您的用例对其进行了彻底测试，否则我们不建议在生产系统中使用它。

请按照以下步骤设置 Amazon Keyspaces 集群并在其上部署 JanusGraph。在执行这些说明之前，请确保您已遵循本指南注册 AWS 并设置您的身份和访问管理。

创建凭据

您需要生成特定于服务的凭据。有关详细信息，请参阅本指南。

生成服务专用凭证后，您将获得类似于以下内容的输出

{
    "ServiceSpecificCredential": {
        "CreateDate": "2019-10-09T16:12:04Z",
        "ServiceName": "cassandra.amazonaws.com",
        "ServiceUserName": "alice-at-111122223333",
        "ServicePassword": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        "ServiceSpecificCredentialId": "ACCAYFI33SINPGJEBYESF",
        "UserName": "alice",
        "Status": "Active"
    }
}

请将 ServiceUserName 和 ServicePassword 保存在安全位置，稍后在 JanusGraph 配置中需要它们。

设置 SSL/TLS

使用以下命令下载 Starfield 数字证书

curl https://certs.secureserver.net/repository/sf-class2-root.crt -O

将 Starfield 数字证书转换为 trustStore 文件

openssl x509 -outform der -in sf-class2-root.crt -out temp_file.der
keytool -import -alias cassandra -keystore cassandra_truststore.jks -file temp_file.der

现在您将在本地看到一个 cassandra_truststore.jks 文件生成。您稍后将需要此文件和您的 truststore 密码。

有关更多详细信息，请参阅此文档。请注意，您不需要遵循该文档的所有步骤，因为它适用于直接使用 Java 客户端连接到 Amazon Keyspaces 的用户。

配置

以下是完整的配置示例。与标准 Apache Cassandra 或 ScyllaDB 不同，Amazon Keyspaces 仅支持部分功能。因此，需要一些特定的配置。

# Basic settings for CQL
gremlin.graph=org.janusgraph.core.JanusGraphFactory
storage.backend=cql
storage.hostname=cassandra.<your-datacenter, e.g. ap-east-1>.amazonaws.com
storage.port=9142
storage.username=<your-service-username>
storage.password=<your-service-password>
storage.cql.keyspace=janusgraph
storage.cql.local-datacenter=<your-datacenter, e.g. ap-east-1>

# Wait for 30 seconds after each table creation, since
# Amazon Keyspace creates tables asynchronously. Remember to
# remove this option from config file after the creation of the graph.
storage.cql.init-wait-time=30000

# SSL related settings
storage.cql.ssl.enabled=true
storage.cql.ssl.truststore.location=<your-trust-store-location>
storage.cql.ssl.truststore.password=<your-trust-store-password>

# Amazon Keyspaces does not support user-generated timestamps
# Thus, the below config must be turned off
graph.assign-timestamp=false

# We strongly recommend you to turn on this config. It will
# prohibit all full-scan attempts. This is because Amazon keyspace
# diverges from Apache Cassandra and might result in incomplete
# results when a full-scan is executed. See issue #3390 for more
# details
query.force-index=true

# Amazon Keyspaces only supports LOCAL QUORUM consistency
storage.cql.only-use-local-consistency-for-system-operations=true
storage.cql.read-consistency-level=LOCAL_QUORUM
storage.cql.write-consistency-level=LOCAL_QUORUM
log.janusgraph.key-consistent=true
log.tx.key-consistent=true

# Amazon Keyspaces does not have metadata available to clients
# Thus, we need to tell JanusGraph that metadata are disabled,
# and provide a hint of which partitioner AWS is using. Valid
# partitioner-names are: Murmur3Partitioner, RandomPartitioner,
# and DefaultPartitioner
storage.cql.metadata-schema-enabled=false
storage.cql.metadata-token-map-enabled=false
storage.cql.partitioner-name=Murmur3Partitioner

现在您应该能够通过 gremlin 控制台或 Java 代码，使用上述配置文件打开图。

已知问题

Amazon Keyspaces 按需创建表。如果您是第一次连接到它，您可能会看到如下错误消息
```
unconfigured table janusgraph.system_properties
```
同时，您应该能够在 Amazon Keyspaces 控制台 UI 上看到相同的表正在创建。创建过程通常需要几秒钟。创建完成后，您可以再次打开图，错误将消失。不幸的是，您必须对所有表遵循相同的过程。为了解决这个问题，您可以在配置文件中设置 storage.cql.init-wait-time=30000，以便在创建每个表后等待 30 秒（或您认为合适的任何其他持续时间）。创建图后，您应该删除此配置。或者，如果您熟悉 JanusGraph，您也可以手动在 AWS 上创建表。通常需要九个表：edgestore、edgestore_lock_、graphindex、graphindex_lock_、janusgraph_ids、system_properties、system_properties_lock_、systemlog 和 txlog。

部署在 Amazon EC2 上

Amazon Elastic Compute Cloud (Amazon EC2) 是一种 Web 服务，可在云中提供可调整大小的计算容量。它旨在让开发人员更容易进行网络规模计算。

— Amazon EC2

注意

以下文档可能部分过时。

请按照以下步骤在 EC2 上设置 Cassandra 集群并在 Cassandra 上部署 JanusGraph。要遵循这些说明，您需要一个拥有已建立的身份验证凭据的 Amazon AWS 账户以及一些基本的 AWS 和 EC2 知识。

设置 Cassandra 集群

这些用于配置和启动 DataStax Cassandra Community Edition AMI 的说明基于 DataStax AMI 文档，并侧重于与 JanusGraph 部署相关的方面。

设置安全组

导航到 EC2 控制台仪表板，然后单击“网络与安全”下的“安全组”。
创建一个新的安全组。点击入站。将“创建新规则”下拉菜单设置为“自定义 TCP 规则”。添加一个源自 0.0.0.0/0 的端口 22 规则。添加一个源自安全组成员的端口 1024-65535 规则。如果您不想在安全组成员之间打开所有非特权端口，那么至少打开 7000、7199 和 9160 端口。提示：“源”下拉菜单在输入“sg”后会自动完成安全组标识符，因此您无需提前准备好确切的值。

启动 DataStax Cassandra AMI

在所需区域“启动 DataStax AMI
在请求实例向导的实例详细信息页面上，将“实例数量”设置为所需的 Cassandra 节点数量。将“实例类型”设置为至少 m1.large。我们推荐 m1.large。
在请求实例向导的“高级实例选项”页面上，在“用户数据”下将单选按钮设置为“文本”，然后将此内容填充到文本框中
```
--clustername [cassandra-cluster-name]
--totalnodes [number-of-instances]
--version community
--opscenter no
```
此配置中的 [实例数量] 必须与上一向导页面中配置的 EC2 实例数量匹配。[cassandra-cluster-name] 可以是用于标识的任何字符串。例如
```
--clustername janusgraph
--totalnodes 4
--version community
--opscenter no
```
在请求实例向导的“标签”页面上，您可以应用任何所需的配置。这些标签仅存在于 EC2 管理级别，对 Cassandra 守护进程的配置或操作没有影响。
在请求实例向导的“创建密钥对”页面上，选择现有密钥对或创建一个新密钥对。连接到这些实例需要包含所选密钥对私有部分的 PEM 文件。
在请求实例向导的“配置防火墙”页面上，选择之前创建的安全组。
在最终向导页面上审查并启动实例。

验证实例启动成功

SSH 进入任何 Cassandra 实例节点：ssh -i [your-private-key].pem ubuntu@[public-dns-name-of-any-cassandra-instance]
运行 Cassandra nodetool nodetool -h 127.0.0.1 ring 来检查 Cassandra 令牌环的状态。您应该在该命令的输出中看到与前一步骤中启动的实例数量相同的节点。

请注意，AMI 配置每个实例需要几分钟。成功配置后，当您通过 SSH 连接到实例时，会出现一个 shell 提示符。

启动 JanusGraph 实例

启动额外的 EC2 实例以运行 JanusGraph，这些实例要么配置为远程服务器模式，要么配置为带 Gremlin-Server 的远程服务器模式，如上所述。您只需记下 Cassandra 集群实例之一的 IP 地址，并将其配置为主机名。要运行的特定 EC2 实例和特定配置取决于您的用例。

Amazon Linux AMI 上的 JanusGraph 实例示例

在 Cassandra 集群的同一区域启动 Amazon Linux AMI。根据您需要的资源量选择所需的 EC2 实例类型。使用默认配置选项，并选择与上一步中配置的 Cassandra 集群相同的密钥对和安全组。
通过 ssh -i [your-private-key].pem ec2-user@[public-dns-name-of-the-instance] SSH 到新创建的实例。您可能需要稍等片刻，等待实例启动。
使用 wget 下载当前的 JanusGraph 发行版，并将其解压到本地主目录。启动 Gremlin 控制台以验证 JanusGraph 是否成功运行。有关如何解压 JanusGraph 和启动 Gremlin 控制台的更多信息，请参阅入门指南

使用 vi janusgraph.properties 创建配置文件并添加以下行：

storage.backend = cql
storage.hostname = [IP-address-of-one-Cassandra-EC2-instance]

您可以添加此页面或配置参考中找到的其他配置选项。

再次启动 Gremlin Console 并键入以下内容：

gremlin> graph = JanusGraphFactory.open('janusgraph.properties')
==>janusgraph[cql:[IP-address-of-one-Cassandra-EC2-instance]]

注意

您已成功将此 JanusGraph 实例连接到 Cassandra 集群，并可以开始操作该图。

从 EC2 外部连接到 EC2 中的 Cassandra 集群

在安全组中打开常用的 Cassandra 端口（9042、7000、7199）是不够的，因为 Cassandra 节点默认广播其 EC2 内部 IP，而不是其公共 IP。

结果行为是，您可以通过连接到任何 Cassandra 节点上的端口 9042 来打开集群上的 JanusGraph 图，但所有对该图的请求都会超时。这是因为 Cassandra 告诉客户端连接到无法访问的 IP。

要解决此问题，请将 /etc/cassandra/cassandra.yaml 中每个实例的“broadcast-address”属性设置为其公共 IP，然后重新启动实例。对集群中的所有节点执行此操作。集群恢复后，nodetool 会报告允许从本地机器连接的正确公共 IP。

更改“broadcast-address”属性允许您从 EC2 外部连接到集群，但也可能意味着源自 EC2 内部的流量必须往返于 Internet 才能到达集群。因此，这种方法仅适用于开发和测试。