基础服务

  3 分钟阅读  

简要概述

描述服务的基础信息。

配置示例

services:
  root_path: grpc-kit
  namespace: example
  service_code: test1.v1.opsaid
  api_endpoint: api.grpc-kit.com
  grpc_address: 0.0.0.0:10081
  http_address: 0.0.0.0:10080

数据结构

// ServicesConfig 基础服务配置，用于设定命名空间、注册的路径、监听的地址等
type ServicesConfig struct {
    RootPath      string `mapstructure:"root_path"`
    Namespace     string `mapstructure:"namespace"`
    ServiceCode   string `mapstructure:"service_code"`
    APIEndpoint   string `mapstructure:"api_endpoint"`
    GRPCAddress   string `mapstructure:"grpc_address"`
    HTTPAddress   string `mapstructure:"http_address"`
    PublicAddress string `mapstructure:"public_address"`
}

配置参数

名称 类型 说明
root_path string 服务注册的前缀，全局统一，一般同组织代码
namespace string 服务注册的空间，全局统一
service_code string 服务的代码，名称唯一且必填，格式：应用短名.接口版本.产品代码
api_endpoint string 接口网关的地址
grpc_address string 服务所监听的grpc地址（如未设置，自动监听在127.0.0.1的随机端口）
http_address string 服务所监听的http地址（如未设置，则不开启gateway服务）
public_address string 服务注册，外部网络可连接的grpc地址（一般等同于grpc-address）

应用场景

开启 http 监听

services:
  service_code: test1.v1.opsaid
  http_address: 127.0.0.1:8080
  grpc_address: 127.0.0.1:10081

启动服务，将会在 127.0.0.1 上的 8080 监听 http 协议请求，这些请求会自动转化为 grpc 协议至 127.0.0.1 的 10081 端口。

关闭 http 监听

services:
  service_code: test1.v1.opsaid
  grpc_address: 127.0.0.1:10081

启动服务，将仅在 127.0.0.1:10081 端口监听 grpc 协议。

使用 TLS 加密 gRPC 或 HTTP 连接

  1. 本地 HTTP Server 手工配置 TLS 证书
services:

  # http 服务配置
  http_service:
    enabled: true
    address: 127.0.0.1:8080

    # 手工配置服务端证书，优先级低于 tls_auto
    tls_server:
      cert_file: "./config/tls/http.crt"
      key_file: "./config/tls/http.key"
  1. 本地 HTTP Server 自动配置 TLS 证书
services:

  # http 服务配置
  http_service:
    enabled: true
    address: 127.0.0.1:8080

   # 通过 acme 自动申请服务端证书，优先级高于 tls_server
    tls_auto:
      acme:
        email: "support@grpc-kit.com"
        cache_dir: "./config/tls/"
        domains:
          - test.grpc-kit.com
          - demo.grpc-kit.com

域名需解析到公网 IP 上，而且应用必须可通过该 IP 访问到。这里自动化证书通过 TLS-ALPN-01 实现。

  1. 本地 GRPC Service 使用单向 TLS 证书
services:

  # grpc 服务配置
  grpc_service:
    enabled: true
    address: 127.0.0.1:10081

    tls_server:
      cert_file: "./config/tls/grpc-server.crt"
      key_file: "./config/tls/grpc-server.key"

  # http 服务配置
  http_service:

    tls_server:
      ca_file: "./config/tls/grpc-server-ca.crt"

客户端配置了 grpc 服务端的 ca 用于验证服务端连接是否合法有效性。

  1. 本地 GRPC Service 使用双向 mTLS 证书
services:

  # grpc 服务配置
  grpc_service:
    enabled: true
    address: 127.0.0.1:10081

    # 如果配置了 mTLS 也需要在 http_service.tls_client 加上相应证书，否则 http 转 grpc 接口不可用 
    tls_server:
      cert_file: "./config/tls/grpc-server.crt"
      key_file: "./config/tls/grpc-server.key"
      ca_file: "./config/tls/grpc-client-ca.crt"

  # http 服务配置
  http_service:

    tls_server:
      ca_file: "./config/tls/grpc-server-ca.crt"
      cert_file: "./config/tls/grpc-client.crt"
      key_file: "./config/tls/grpc-client.key"

对于使用 mTLS 两边的证书可以来不不同的 ca 签发。

通过 openssl 生成证书

  1. 创建 ca
cat > ca-csr.conf << EOF
[ req ]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn

[ dn ]
C = CN
CN = demo-ca

[ v3_ext ]
basicConstraints=critical,CA:true,pathlen:1
keyUsage=critical,digitalSignature,keyCertSign,cRLSign
EOF

openssl genrsa -out ca.key 2048
openssl req -new -key ca.key -out ca.csr -config ca-csr.conf
openssl x509 -req -in ca.csr -signkey ca.key -out ca.crt -days 3650 -extensions v3_ext -extfile ca-csr.conf
  1. 创建 http 服务证书
cat > ca-csr.conf << EOF
[ req ]
default_bits = 2048
prompt = no
default_md = sha256
req_extensions = req_ext
distinguished_name = dn

[ dn ]
C = CN
CN = http

[ req_ext ]
subjectAltName = @alt_names

[ alt_names ]
IP.1 = 127.0.0.1
IP.2 = 10.5.39.39
DNS.1 = localhost
DNS.2 = opsaid-test6-v1.default.svc

[ v3_ext ]
authorityKeyIdentifier=keyid,issuer:always
basicConstraints=CA:FALSE
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth
subjectAltName=@alt_names
EOF

openssl genrsa -out http.key 2048
openssl req -new -key http.key -out http.csr -config http-csr.conf
openssl x509 -req -in http.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out http.crt -days 3650 -extensions v3_ext -extfile http-csr.conf

其中 grpc 服务证书方法同 http，以上 “*-csr.conf” 文件内容根据实际情况做更改。



最后修改 02.01.2024: docs: 添加 openssl 示例 (be6fdfa)