Canton API 配置

Canton 节点 Admin API、Ledger API 与 JSON API 配置。

配置 Admin API、Ledger API、JSON Ledger API 和 Canton 节点的缓存。

参与者节点公开管理 API、gRPC Ledger API 和可选的 JSON Ledger API。

本页面介绍如何配置适用于管理 API 和 gRPC Ledger API 的常规选项。有关仅适用于特定 API 的配置选项，请参阅管理 API、gRPC Ledger API 和 JSON Ledger API 页面。

端口

必须明确提供 Admin API、gRPC Ledger API 和 JSON Ledger API 的端口：

participant1 {
  storage.type = memory
  admin-api.port = 5012
  ledger-api.port = 5011
  http-ledger-api.port = 5013
}

请注意，如果禁用 JSON Ledger API，则不必提供其端口：

participant3 {
  ledger-api.port = 13031
  admin-api.port = 13032
  http-ledger-api.enabled = false
  storage.type = memory
}

保持活力

Canton 默认在所有 gRPC 连接上启用保持活动状态，以防止负载均衡器或防火墙在连接出现静默时终止长时间运行的 RPC 调用。

要调整连接的保持活动配置，请调整以下参数：

time
timeout
permit-keep-alive-time
permit-keep-alive-without-calls

您可以在 keep-alive-client 部分中调整同步器 Public API 客户端的前两个参数，或者在 keep-alive-server 部分中调整 Admin API 的服务器端和 gRPC Ledger API 的前两个参数。最后两个参数仅适用于服务器，因此您只能在管理 API 和 gRPC Ledger API 的 keep-alive-server 部分中调整它们。

gRPC 文档进一步描述了这些参数及其效果。

`permit-keep-alive-time` 指定允许客户端使用的最积极的保持活动时间。如果客户端使用比服务器的 `permit-keep-alive-time` 更积极的保持活动 `time`，则连接将终止，并出现 `GOAWAY` 错误，并以“too\_many\_pings”作为调试数据。将 `permit-keep-alive-without-calls` 设置为 `true` 允许客户端在任何正在进行的 gRPC 调用之外发送 ping 消息。否则，此类 ping 会导致`GOAWAY` 错误。

Canton 根据 API 为这些参数设置不同的默认值：

应用程序接口	管理API	账本 API
时间	40 多岁	10 分钟
超时	20 多岁	20 多岁
允许保持活动时间	20 多岁	10 秒
允许在没有呼叫的情况下保持活动状态	假	假

以下是演示如何为各种 API 配置 keep-alive 的示例：

sequencer-client {
    keep-alive-client {
        time = 60s
        timeout = 30s
    }
}

admin-api {
    keep-alive-server {
        time = 40s
        timeout = 20s
        permit-keep-alive-time = 20s
    }
}

ledger-api {
    keep-alive-server {
        time = 40s
        timeout = 20s
        permit-keep-alive-time = 20s
        permit-keep-alive-without-calls = true
    }
}

Netty 使用本机库

Canton 附带了本机库（对于某些处理器架构：x86_64、ARM64、S390_64），以便 Netty 网络访问库可以利用 Linux 上的 epoll 系统 call。这通常会提高性能并减轻 JVM 垃圾收集器的压力。

如果本机库适用于当前操作系统和架构，系统会自动选择本机库；如果本机库不可用，系统会自动选择标准 NIO 库。

要关闭使用本机库，请在运行 Canton 时进行以下设置：

-Dio.grpc.netty.shaded.io.netty.transport.noNative=true

即使这是预期的情况，回退到 NIO 也可能会导致日志中在 DEBUG 级别发出警告。

{/* COPIED_START source=“docs-website:docs/replicated/canton/3.4/参与方/howtos/configure/apis/admin_api.rst” hash=“eb18a523” */}

管理API配置

管理API参与者节点上的管理 API 和同步器上的管理 API 的性质和范围有一些重叠。例如，您会发现同步器和参与者节点 API 上有相同的密钥管理命令，而参与者有不同的命令来连接到多个同步器。

目前的配置很简单（请参阅下面的 TLS 示例），具体需要一个地址和一个端口。地址默认为127.0.0.1，如果未明确配置，则会分配默认端口。

您不应以不安全的方式公开公开 admin-api，因为它仅用于管理目的。

{/* COPIED_START source=“docs-website:docs/replicated/canton/3.4/参与方/howtos/configure/apis/ledger_api.rst” hash=“1c225af4” */}

gRPC 账本 API 配置

gRPC Ledger API 的配置与 Admin API 配置类似，只是组以 ledger-api 开头，而不是 admin-api 开头。

canton {
  参与方s {
    participant {
      ledger-api {
        port = 5011
        address = localhost
        auth-services = [{
          type = jwt-jwks
          url = "https://target.audience.url/jwks.json"
          target-audience = "https://rewrite.target.audience.url"
        }]
        jwt-timestamp-leeway {
          default = 5
          expires-at = 10
          issued-at = 15
          not-before = 20
        }
        keep-alive-server {
          time = 40s
          timeout = 20s
          permit-keep-alive-time = 20s
        }
        max-inbound-message-size = 20971520
      }
    }
  }
}

要配置 gRPC Ledger API 连接，您应该指定地址和端口。所有其他属性都是可选的，并且具有直观的默认值。

定义tls参数组来配置TLS
定义 auth-services 参数组来配置 JWT 授权
定义jwt-timestamp-leeway参数组来配置JWT leeway
定义 keep-alive-server 参数组来配置 gRPC keepalive
定义 max-inbound-message-size 参数来控制 gRPC 消息的最大大小

Ledger API 缓存

max-contract-state-cache-size和max-contract-key-state-cache-size参数分别控制Ledger API合约和合约密钥缓存的大小。修改这些参数会改变使用最近访问（创建或读取）的合约或合约密钥的交易仍然可以在内存中找到它的可能性，而不需要从数据库中查询它。当存在大量持续获取或用于非消耗性练习的环境合约时，更大的缓存可能会更有意义。较大的缓存还可以使大量合约通过创建 -> 存档 -> 创建后继循环轮换的用例受益。如果特定工作流程的性能依赖于大型缓存，请考虑显式调整这些参数。

  canton.参与方s.参与方.ledger-api.index-service {
      max-transactions-in-memory-fan-out-buffer-size = 10000 // default 1000
  }

内存扇出中的最大事务数

max-transactions-in-memory-fan-out-buffer-size参数控制内存中扇出缓冲区的大小。该缓冲区允许在事务流最终确定时从内存中提供服务，而不是从数据库中提供服务。确保此缓冲区足够大，以便应用程序不太可能从数据库传输事务。在大多数情况下，10 秒的缓冲区效果很好。例如，如果您预计吞吐量为 20 tx/s，请将此数字设置为 200。新的默认设置 1000 假定 100 tx/s。如果您的工作流程性能预计交易率大于 100 tx/s，请考虑明确调整这些参数。

canton.参与方s.参与方.ledger-api.index-service {
    max-transactions-in-memory-fan-out-buffer-size = 10000 // default 1000
}

{/* COPIED_START source=“docs-website:docs/replicated/canton/3.4/参与方/howtos/configure/apis/json_api.rst” hash=“a4b05afb” */}

JSON 账本 API 配置

JSON Ledger API 的配置与 gRPC Ledger API 配置类似。对应的参数组以http-ledger-api开头。```none theme={“theme”:{“light”:“github-light”,“dark”:“github-dark”}} canton { 参与方s { participant1 { http-ledger-api { enabled = true address = 0.0.0.0 port = 10010 port-file = ”./json.port” path-prefix = “my-prefix” websocket-config { http-list-max-elements-limit = 1000, http-list-wait-time = 2s, } daml-definitions-service-enabled = true } } } }


默认情况下启用 JSON Ledger API。如果您想禁用它，请将`enabled`字段设置为`false`。

## JSON Ledger API 端点

通过添加 `server` 参数组来配置 JSON API 端点。

* 指定`address`表示监听的IP地址。
* 指定`port`表示端口。
* 如果您希望参与者节点使用 JSON Ledger API 正在侦听的端口写入文本文件，请指定`port-file`。这作为同步依赖服务启动的工具非常有用，因为参与者节点仅在 JSON Ledger API 完全初始化后才写入文件。
* 如果您希望在自定义路径上提供 JSON Ledger API 内容而不是 `/`，请指定 `path-prefix`。

## 网络套接字

产生大型数据集的端点（`/v2/commands/completions`、`/v2/state/active-contracts`、`/v2/updates`、`/v2/updates/flats`和`/v2/updates/trees`）有两种类型：

* 能够在流中返回任意长结果集的websocket
* HTTP post 请求返回有限的结果列表

后一种类型的请求可以在参与者节点的配置中参数化。

* 设置`http-list-max-elements-limit`指定返回的最大行数。
* 设置`http-list-wait-time`指定发送结果之前等待的空闲时间的毫秒数。在开放式流（例如完成）的情况下需要此参数。 JSON Ledger API 从 gRPC 流中读取，当“等待”毫秒内没有新元素时 -> 结果将发送到客户端。

## Daml 定义服务

您可以通过将 `daml-definitions-service-enabled` 参数设置为 `true` 来启用实验性 `Daml Definitions Service`。

{/* COPIED_START source="docs-website:docs/replicated/canton/3.4/参与方/howtos/optimize/caching.rst" hash="89c687c5" */}

# 配置缓存

## Ledger API 缓存

`max-contract-state-cache-size`和`max-contract-key-state-cache-size`参数分别控制Ledger API合约和合约密钥缓存的大小。修改这些参数会改变使用最近访问（创建或读取）的合约或合约密钥的交易仍然可以在内存中找到它的可能性，而不需要从数据库中查询它。当存在大量持续获取或用于非消耗性练习的环境合约时，更大的缓存可能会更有意义。较大的缓存还可以使大量合约通过创建 -> 存档 -> 创建后继循环轮换的用例受益。如果特定工作流程的性能依赖于大型缓存，请考虑显式调整这些参数。

```conf theme={"theme":{"light":"github-light","dark":"github-dark"}}
  canton.参与方s.参与方.ledger-api.index-service {
      max-contract-state-cache-size = 100000      // default 1e4
      max-contract-key-state-cache-size = 100000  // default 1e4
  }

本文由 CC Privacy Club 根据 Canton Network 官方文档（CC-BY-4.0）整理翻译，仅供学习；实现细节以官方最新版本为准。