gRPC reference guide

Using gRPC with Quarkus

如需实现 gRPC 服务或使用它，您需要 quarkus-grpc 扩展。它负责处理这两方面。

Using Maven

要启用 gRPC，请向项目添加以下依赖项：

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-grpc</artifactId>
</dependency>

接下来，确保在 Quarkus Maven 插件中启用了 `generate-code`阶段：

<plugin>
    <groupId>${quarkus.platform.group-id}</groupId>
    <artifactId>quarkus-maven-plugin</artifactId>
    <version>${quarkus.platform.version}</version>
    <extensions>true</extensions>
    <executions>
        <execution>
            <goals>
                <goal>build</goal>
                <goal>generate-code</goal>
                <goal>generate-code-tests</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Using Gradle

对于 Gradle，将以下依赖添加到项目：

implementation 'io.quarkus:quarkus-grpc'

Selecting a gRPC server

Quarkus 提供了两种实现 gRPC 服务器的方式：基于 Netty 的 gRPC Java 和 Vert.x。它们都支持 TLS。

基于 Vert.x 的服务器的一个优势在于能够使用一个服务器处理 HTTP 请求和 gRPC 请求。如果您想在同一个端口上公开 REST 和 gRPC 端点，这种情况很有用。而 gRPC Java（使用独立的服务器）服务器无法做到这一点。

如需选择 gRPC 服务器实现，请在 application.properties 文件中设置 quarkus.grpc.server.use-separate-server 属性：

quarkus.grpc.server.use-separate-server=false # Use the Vert.x based server

我们建议使用基于 Vert.x 的 gRPC 服务器，因为它更加灵活，与 Quarkus 生态系统集成的也更好。

您无法同时使用这两个服务器。

Selecting gRPC clients

对于服务器，Quarkus 为 gRPC 客户端提出了两个备选方案：gRPC Java 和 Vert.x。不同于服务器，您可以选择每个客户端的传输：

quarkus.grpc.clients.hello.use-quarkus-grpc-client=true # Use client using the Vert.x based transport

虽然这不是默认设置，但我们建议使用基于 Vert.x 的客户端，因为它更加灵活，与 Quarkus 生态系统集成的也更好。它不会更改您能使用的存根，因为它们是由 gRPC 框架生成的。但是，它会改变客户端与服务器的通信方式。

Configuring TLS for gRPC services

With the Vert.x based server

如果您使用基于 Vert.x 的服务器，则可以通过在 application.properties 文件中设置以下属性来配置 TLS：

quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false

quarkus.tls.key-store.p12.path=grpc-tls-keystore.p12
quarkus.tls.key-store.p12.password=*****

quarkus.http.insecure-requests=disabled

之前的配置使用了 centralized TLS configuration。这是建议采用的方法。

您也可以使用以下属性直接配置服务器：

quarkus.grpc.server.use-separate-server=false

quarkus.grpc.server.plain-text=false
quarkus.http.ssl.certificate.key-store-file=target/certs/grpc-tls-keystore.p12
quarkus.http.ssl.certificate.key-store-password=*****
quarkus.http.insecure-requests=disabled

当使用 JKS 或 P12 时，您可以使用 key-store-file 和 key-store-password 来配置密钥库文件及其密码。对于 PEM，请使用 certificate 和 key 属性：

quarkus.grpc.server.use-separate-server=false

quarkus.grpc.server.plain-text=false
quarkus.http.ssl.certificate.files=target/certs/grpc-tls.crt
quarkus.http.ssl.certificate.key-files=target/certs/grpc-tls.key
quarkus.http.insecure-requests=disabled

quarkus.http.insecure-requests 属性用于禁用不安全的请求。

启用 TLS 时，它会同时覆盖 HTTP 和 gRPC 流量。

With the gRPC Java server

如果您使用 gRPC Java 服务器，则可以通过在 application.properties 文件中设置以下属性来配置 TLS：

quarkus.grpc.server.ssl.certificate=tls/server.pem
quarkus.grpc.server.ssl.key=tls/server.key

quarkus.grpc.server.plain-text=false

该服务器只支持证书和密钥的 PEM 格式。

Configuring TLS for gRPC clients

对于服务器，您可以使用集中式 TLS 配置或直接配置客户端。

With the centralized TLS configuration

当使用 Quarkus（基于 Vert.x）客户端时，您可以通过在 application.properties 文件中设置以下属性来配置 TLS：

quarkus.tls.trust-store.p12.path=grpc-client-truststore.p12
quarkus.tls.trust-store.p12.password=password

quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true

Direct configuration

当使用 Quarkus（基于 Vert.x）客户端时，您可以通过在 application.properties 文件中设置以下属性来配置 TLS：

quarkus.grpc.clients.hello.plain-text=false # Use TLS
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true # Use client using the Vert.x based transport
quarkus.grpc.clients.hello.tls.enabled=true
quarkus.grpc.clients.hello.tls.trust-certificate-p12.path=target/certs/grpc-tls-truststore.jks
quarkus.grpc.clients.hello.tls.trust-certificate-p12.password=****

如果您使用 JKS 信任库，请使用以下配置：

quarkus.grpc.clients.hello.plain-text=false # Use TLS
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true # Use client using the Vert.x based transport
quarkus.grpc.clients.hello.tls.enabled=true
quarkus.grpc.clients.hello.tls.trust-certificate-jks.path=target/certs/grpc-tls-truststore.jks
quarkus.grpc.clients.hello.tls.trust-certificate-jks.password=****

如果您使用 PEM 证书作为信任库，请使用以下配置：

quarkus.grpc.clients.hello.plain-text=false # Use TLS
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true # Use client using the Vert.x based transport
quarkus.grpc.clients.hello.tls.enabled=true
quarkus.grpc.clients.hello.tls.trust-certificate-pem.certs=target/certs/grpc-client-ca.crt

使用 gRPC Java 客户端时，可以通过在 application.properties 文件中设置以下属性来配置 TLS：

quarkus.grpc.clients.hello.ssl.trust-store=target/certs/grpc-client-tls-ca.crt

gRPC Java 客户端仅支持 PEM 格式用于信任库。

Configuring mTLS

您可以为 gRPC 服务和客户端配置双向 TLS (mTLS)。

Using the centralized TLS configuration

使用 Quarkus HTTP 服务器 (quarkus.grpc.server.use-separate-server=false) 和 Quarkus gRPC 客户端 (quarkus.grpc.clients.hello.use-quarkus-grpc-client=true) 时，可以通过在 application.properties 文件中设置以下属性来配置 mTLS：

quarkus.tls.my-server.key-store.p12.path=target/certs/grpc-keystore.p12
quarkus.tls.my-server.key-store.p12.password=password
quarkus.tls.my-server.trust-store.p12.path=target/certs/grpc-server-truststore.p12
quarkus.tls.my-server.trust-store.p12.password=password

quarkus.tls.my-client.trust-store.p12.path=target/certs/grpc-client-truststore.p12
quarkus.tls.my-client.trust-store.p12.password=password
quarkus.tls.my-client.key-store.p12.path=target/certs/grpc-client-keystore.p12
quarkus.tls.my-client.key-store.p12.password=password

quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.tls-configuration-name=my-client
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true

quarkus.http.ssl.client-auth=REQUIRED # Enable mTLS
quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=my-server
quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false

Direct configuration

使用 gRPC Java 服务器时，可以通过在 application.properties 文件中设置以下属性来配置 mTLS：使用基于 Vert.x 的服务器和基于 Vert.x 的客户端时，可以通过在 application.properties 文件中设置以下属性来配置 mTLS：

# Server side:
quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false # Force the client to use TLS for the tests
quarkus.http.ssl.certificate.key-store-file=target/certs/grpc-keystore.jks
quarkus.http.ssl.certificate.key-store-password=****
quarkus.http.ssl.certificate.trust-store-file=target/certs/grpc-server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=****
quarkus.http.ssl.client-auth=REQUIRED # Force the client to authenticate, aka mTLS
quarkus.http.insecure-requests=disabled

# Client side:
quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.tls.trust-certificate-jks.path=target/certs/grpc-client-truststore.jks
quarkus.grpc.clients.hello.tls.trust-certificate-jks.password=****
quarkus.grpc.clients.hello.tls.key-certificate-jks.path=target/certs/grpc-client-keystore.jks
quarkus.grpc.clients.hello.tls.key-certificate-jks.password=****
quarkus.grpc.clients.hello.tls.enabled=true
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true

如果您对信任库和密钥证书使用 P12 格式，请使用以下配置：

# Server side
quarkus.grpc.server.use-separate-server=false
quarkus.grpc.server.plain-text=false # Force the client to use TLS for the tests
quarkus.http.ssl.certificate.key-store-file=target/certs/grpc-keystore.p12
quarkus.http.ssl.certificate.key-store-password=****
quarkus.http.ssl.certificate.trust-store-file=target/certs/grpc-server-truststore.p12
quarkus.http.ssl.certificate.trust-store-password=****
quarkus.http.ssl.client-auth=REQUIRED # Force the client to authenticate, aka mTLS
quarkus.http.insecure-requests=disabled

# Client side
quarkus.grpc.clients.hello.plain-text=false
quarkus.grpc.clients.hello.tls.trust-certificate-p12.path=target/certs/grpc-client-truststore.p12
quarkus.grpc.clients.hello.tls.trust-certificate-p12.password=****
quarkus.grpc.clients.hello.tls.key-certificate-p12.path=target/certs/grpc-client-keystore.p12
quarkus.grpc.clients.hello.tls.key-certificate-p12.password=****
quarkus.grpc.clients.hello.tls.enabled=true
quarkus.grpc.clients.hello.use-quarkus-grpc-client=true