基础服务

  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"`
    // Deprecated: 使用 GRPCService 代替，优先级低于 GRPCService 配置
    GRPCAddress string `mapstructure:"grpc_address"`
    // Deprecated: 使用 HTTPService 代替，优先级低于 HTTPService 配置
    HTTPAddress   string       `mapstructure:"http_address"`
    PublicAddress string       `mapstructure:"public_address"`
    GRPCService   *GRPCService `mapstructure:"grpc_service"`
    HTTPService   *HTTPService `mapstructure:"http_service"`
    Integrations  struct {
        GRPC struct {
            Admin *bool `mapstructure:"admin"`
        }
    } `mapstructure:"integrations"`
    SecurityKey string `mapstructure:"security_key"`
}

配置参数

名称类型说明
root_pathstring服务注册的前缀，全局统一，一般同组织代码
namespacestring服务注册的空间，全局统一
service_codestring服务的代码，名称唯一且必填，格式：应用短名.接口版本.产品代码
api_endpointstring接口网关的地址
grpc_addressstring（Deprecated）服务所监听的 grpc 地址，请改用 grpc_service.address；如未设置，自动监听在 127.0.0.1 的随机端口
http_addressstring（Deprecated）服务所监听的 http 地址，请改用 http_service.address；如未设置，则不开启 gateway 服务
public_addressstring服务注册，外部网络可连接的 grpc 地址（一般等同于 grpc-address）
grpc_serviceobjectgRPC 监听的详细配置（地址、tls_server/tls_auto 证书等），见下方 TLS 场景
http_serviceobjectHTTP 监听的详细配置（地址、tls_server/tls_client 证书等），见下方 TLS 场景
integrationsobject内置集成服务开关，见下方「开启内置 admin 集成服务」
security_keystring内置服务使用的对称加密密钥（AES），建议 32 字节（AES-256）

应用场景

开启 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 协议。

开启内置 admin 集成服务

services:
  service_code: test1.v1.opsaid
  integrations:
    grpc:
      admin: true
  security_key: "0123456789abcdef0123456789abcdef"

配合已启用的关系数据 配置，启动时将：

  • 在 gRPC 服务上注册内置管理服务 KnownAdmin（api.known.admin.v1）；
  • 于同一数据库实例自动创建/迁移 lion 数据库结构（lion_* 前缀的表， 覆盖用户、角色、菜单、策略、部门、OAuth2 客户端等）。

说明：

  • admin 为三态开关：未配置（等同 false）不注册内置 admin 服务；
  • 该服务依赖 database.enable: true，未启用数据库时可降级；已启用数据库但连接失败会使 Init 返回错误。降级时 仅记录 admin service database unavailable 并跳过 lion 结构创建；
  • security_key 供内置 admin 服务做 AES 对称加密（如口令加密存储）， 建议使用 32 字节随机串；未设置时框架使用固定默认密钥兜底，生产必须显式替换。

使用 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” 文件内容根据实际情况做更改。

运行与密钥边界

生产明确设置 services.security_key，避免使用源码默认兜底。密钥变更涉及已有加密字段，应规划数据重加密。HTTP listener 的后台启动、健康检查与退出期限见启动与部署检查。


最后修改 October 4, 2026: 完善微单体架构、升级迁移、MCP 与部署文档 (#11) (6e8ab93)