kratos-kit

module

v0.0.85 Latest Latest Go to latest Published: Sep 7, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/liujitcn/kratos-kit

Links

Open Source Insights

README ¶

kratos-kit

kratos-kit 是一个基于 Kratos 的工具库集合，提供应用引导、配置加载、日志、注册发现、链路追踪，以及缓存/队列/鉴权/OSS/数据库等通用能力。

仓库说明

该仓库是多模块（multi-module）结构，根目录与子目录都包含 go.mod。常用模块包括：

当前依赖基线为 github.com/go-kratos/kratos/v3 v3.0.0，日志接口已迁移到 Kratos v3 的 log/slog 体系。

api：protobuf 定义与代码生成（buf generate）
bootstrap：应用启动入口（配置加载 + 日志 + 注册中心 + tracer + kratos.App）
config：本地/远程配置加载与工厂注册；额外提供直接实现 Kratos config.Source 的文件、HTTP、Redis、Vault、ZooKeeper 和 S3 配置源
key：统一密钥接口、根密钥派生和 Secret Manager 适配；提供 File、Vault、AWS、Google、Azure 和 Kubernetes Secret
logger：日志工厂（std/zap/logrus/fluent/aliyun/tencent/zerolog）
registry：注册发现工厂（consul/etcd/eureka/kubernetes/nacos/polaris/servicecomb/zookeeper）
tracer：OpenTelemetry TracerProvider 与 exporter 工厂（std/zipkin/otlp-http/otlp-grpc）
tracing：OpenTelemetry 追踪适配层
ai：AI 客户端与编排封装（含 model、eino、langchaingo 子模块）
auth：认证与鉴权封装；认证支持 API Key、Basic、HMAC、JWT、mTLS、OAuth2、OIDC、Session，鉴权支持 Casbin、OPA、Cerbos 和 Zanzibar 适配端口
oauth：第三方 OAuth SDK 封装（直接使用 api 下 OAuth 配置，支持 GitHub、Gitee、Google、微信开放平台、微信公众号、微信小程序、企业微信、钉钉、飞书；闭环支持 state、PKCE、授权地址、code 换 token、用户信息，不包含业务登录态）
cache：内存/Redis 缓存封装
queue：内存/Redis 队列封装
locker：Redis 分布式锁封装
oss：本地/FTP/MinIO/阿里云 OSS/AWS S3 及兼容对象存储封装
translator：基于配置的统一机器翻译封装，内置 Google/百度/阿里云/火山引擎
database/gorm：GORM 客户端封装，提供多数据库 driver、连接池、迁移与可观测性，并内置审计字段填充、租户隔离和角色数据范围过滤；版本化迁移仅在脚本全部成功后记录，失败会记录错误并阻止应用启动
database/ent：Ent 底层数据库 driver 封装（含 mysql/postgres/sqlite driver 子模块，支持连接池配置、debug SQL 日志、迁移回调、表/字段注释与审计字段 mixin）
broker：消息发布订阅与 typed handler 封装，通用 TransportServer 可把任意 broker 接入 Kratos 应用生命周期；broker/nats 通过共享实现支持 Core NATS、JetStream、队列订阅、请求响应和消息追踪
workflow：工作流引擎封装（含 argo、conductor、goworkflows、temporal 子模块），公共包只定义跨引擎一致的 Client/Worker 生命周期接口
transport：通用传输辅助（含 keepalive、mcp、sse 子模块）
server/http、server/grpc、server/mcp、server/sse：HTTP、gRPC、MCP、SSE 服务端配置封装，详细说明见 server/README.md
encoding：直接适配 Kratos 的额外 codec（avro/bson/cbor/flatbuffers/gob/thrift/toml）；msgpack/xml/yaml 使用 Kratos v3 自带实现
health：应用级 readiness 检查聚合与 HTTP handler
metrics：Prometheus、OpenTelemetry OTLP、Datadog 指标适配
retry：支持 context、退避和抖动的通用重试
ratelimit：可注入 Kratos 服务端中间件的 Sentinel 和令牌桶限流器
swagger-ui：Swagger UI 嵌入与路由注册封装（支持 net/http 与 Kratos）
pprof：性能采样封装（当前支持 pyroscope）
captcha：验证码生成与存储封装
sdk：共享运行时入口，统一保存数据库、缓存、队列、OSS、锁和翻译器实例
runtime：运行时应用信息模型
utils：通用工具（TLS、Redis 配置辅助）
cmd/project-docs：收集当前项目约定 README 和根 docs 的 Go 命令
cmd/normalize-go-imports：通用 Go import 别名规范化命令，可安装后在任意项目目录执行
cmd/kratos-admin：生成包含前后端和项目脚本的完整项目
cmd/protoc-gen-go-redact：按 Proto 字段规则生成服务端响应脱敏代码，并维护可发布到 Buf 的 redact/v1 契约
redact：运行时脱敏接口、自定义规则注册和 gRPC 流式响应包装；策略解析器通过构造参数或请求上下文注入，不保存进程级默认策略实例，由 cmd/protoc-gen-go-redact 生成代码依赖

database/gorm 的 Data 配置支持 database 与 databases 两种形式。多个固定数据源应按名称分别创建客户端和 data.Data，每个客户端启动时主动校验连接；跨数据源事务、Join 与请求级动态切库不在该封装的职责范围内。

其中 queue 模块内的 Redis Stream 实现默认会为生产者开启基于 MAXLEN 的长度裁剪；消费者在消费成功后会执行 XACK 并立即 XDEL 删除消息实体，保持“消费即删除”的队列语义。消费者执行 Shutdown 时会停止继续拉取新消息，并尽量处理完本地已拉取但尚未确认的消息后再退出。生产者和消费者同时提供 EnqueueContext、RunContext、RegisterWithLastIDContext，便于调用方按业务请求或后台任务生命周期控制 Redis 操作。

captcha 模块提供普通图形验证码和行为验证码两类能力：普通图形验证码支持数字、字符串、中文、算术；行为验证码支持滑动拼图、点击文字、旋转图片。所有验证码统一通过 Generate(ctx) 生成并自动写入 cache.Cache，通过 Verify(ctx, id, input) 校验并在成功后删除缓存。验证码图片只以 base64 或 JSON(base64) 返回给前端，不落盘、不对外返回答案。

workflow 模块按工作流引擎拆分为独立 Go 模块：workflow/argo 通过 Argo Server REST API 操作 Kubernetes Workflow；workflow/conductor 封装 Conductor SDK 和任务 Worker；workflow/goworkflows 提供进程内持久工作流客户端与 Worker；workflow/temporal 封装 Temporal 客户端、Worker、Signal、Query 和默认消息工作流。

安装

请按模块路径安装，而不是安装根模块。例如：

go get github.com/liujitcn/kratos-kit/bootstrap@latest
go get github.com/liujitcn/kratos-kit/config@latest
go get github.com/liujitcn/kratos-kit/key@latest
go get github.com/liujitcn/kratos-kit/logger@latest
go get github.com/liujitcn/kratos-kit/registry@latest
go get github.com/liujitcn/kratos-kit/tracer@latest
go get github.com/liujitcn/kratos-kit/transport/mcp@latest
go get github.com/liujitcn/kratos-kit/transport/sse@latest
go get github.com/liujitcn/kratos-kit/server/http@latest
go get github.com/liujitcn/kratos-kit/server/grpc@latest
go get github.com/liujitcn/kratos-kit/server/mcp@latest
go get github.com/liujitcn/kratos-kit/server/sse@latest
go get github.com/liujitcn/kratos-kit/config/redis@latest
go get github.com/liujitcn/kratos-kit/config/vault@latest
go get github.com/liujitcn/kratos-kit/config/zookeeper@latest
go get github.com/liujitcn/kratos-kit/config/oss@latest
go get github.com/liujitcn/kratos-kit/encoding/avro@latest
go get github.com/liujitcn/kratos-kit/encoding/bson@latest
go get github.com/liujitcn/kratos-kit/encoding/cbor@latest
go get github.com/liujitcn/kratos-kit/encoding/flatbuffers@latest
go get github.com/liujitcn/kratos-kit/encoding/thrift@latest
go get github.com/liujitcn/kratos-kit/health@latest
go get github.com/liujitcn/kratos-kit/metrics/prometheus@latest
go get github.com/liujitcn/kratos-kit/retry@latest
go get github.com/liujitcn/kratos-kit/ratelimit/sentinel@latest
go get github.com/liujitcn/kratos-kit/ratelimit/tokenbucket@latest
go get github.com/liujitcn/kratos-kit/oss/s3@latest
go get github.com/liujitcn/kratos-kit/auth/authn/engine/apikey@latest
go get github.com/liujitcn/kratos-kit/auth/authn/engine/oidc@latest
go get github.com/liujitcn/kratos-kit/auth/authz/engine/opa@latest
go get github.com/liujitcn/kratos-kit/auth/authz/engine/cerbos@latest
go get github.com/liujitcn/kratos-kit/broker/nats@latest
go get github.com/liujitcn/kratos-kit/swagger-ui@latest
go get github.com/liujitcn/kratos-kit/pprof@latest
go get github.com/liujitcn/kratos-kit/oauth@latest
go get github.com/liujitcn/kratos-kit/translator@latest
go get github.com/liujitcn/kratos-kit/ai/model@latest
go get github.com/liujitcn/kratos-kit/ai/eino@latest
go get github.com/liujitcn/kratos-kit/ai/langchaingo@latest
go get github.com/liujitcn/kratos-kit/database/gorm@latest
go get github.com/liujitcn/kratos-kit/database/gorm/driver/mysql@latest
go get github.com/liujitcn/kratos-kit/database/ent@latest
go get github.com/liujitcn/kratos-kit/database/ent/driver/mysql@latest
go get github.com/liujitcn/kratos-kit/workflow@latest
go get github.com/liujitcn/kratos-kit/workflow/argo@latest
go get github.com/liujitcn/kratos-kit/workflow/conductor@latest
go get github.com/liujitcn/kratos-kit/workflow/goworkflows@latest
go get github.com/liujitcn/kratos-kit/workflow/temporal@latest

项目文档收集命令使用 go install 安装：

go install github.com/liujitcn/kratos-kit/cmd/project-docs@latest
go install github.com/liujitcn/kratos-kit/cmd/protoc-gen-go-redact@latest
go get github.com/liujitcn/kratos-kit/redact@latest

命令从项目根目录扫描相对路径不超过三段的文件，只收集精确命名的 README.md，以及任意 docs 目录中的 Markdown。普通项目默认输出到 internal/projectdocs；包含 backend 的仓库默认输出到 backend/internal/docs。生成器只把无语言后缀的 Markdown 写入 assets/docs.json，不执行自动翻译，也不在文档节点中写入 locale。下游翻译工具可据此生成 docs.<locale>.json；生成的 docs.go 通过 DocsFS 嵌入构建时存在的全部 docs*.json。也可以通过 --output 或 -o 指定生成目录：

project-docs
project-docs --output ./backend/internal/docs

Go import 别名规范化命令可安装到 GOBIN，从任意项目目录预览或写回规范化结果：

go install github.com/liujitcn/kratos-kit/cmd/normalize-go-imports@latest
normalize-go-imports -root /path/to/project
normalize-go-imports -root /path/to/project -write

生成物不包含项目身份。服务加载后使用 AppInfo.Project 和 AppInfo.Name 生成稳定文档 ID，并与 OpenAPI/Swagger 保持一致。

项目生成命令按项目名创建携带 Admin 能力的完整前后端目录，后端组合 kratos-core 与 kratos-admin/backend 业务宿主，前端通过管理端、uni-app 和 Taro CLI 生成：

go install github.com/liujitcn/kratos-kit/cmd/kratos-admin@latest
kratos-admin create shop-admin

前端生成会临时使用 npm 官方源解析 @liujitcn 包并刷新 dlx 执行缓存，自动获取最新 CLI，无需手动清理缓存或配置环境变量，也不会修改全局及项目 pnpm 配置。

生成时使用 backend@latest 及其 go.mod 声明的 API 依赖解析最新 Admin Backend/API，并生成 MySQL、Redis 及本地 Docker Compose 配置。扩展业务时在生成项目中增加自己的 Proto、Biz、 Data、Service、Module、Migration 和前端 CLI 模块，不复制 Admin 的 internal 代码。

快速开始

1. 引入需要的实现包（通过 `init` 自动注册）

import (
	_ "github.com/liujitcn/kratos-kit/config/etcd"
	_ "github.com/liujitcn/kratos-kit/logger/zap"
	_ "github.com/liujitcn/kratos-kit/registry/etcd"
)

2. 启动应用

package main

import (
	"github.com/go-kratos/kratos/v3"
	"github.com/liujitcn/kratos-kit/bootstrap"
)

func initApp(ctx *bootstrap.Context) (*kratos.App, func(), error) {
	app := bootstrap.NewApp(ctx)
	return app, func() {}, nil
}

func main() {
	ctx := bootstrap.NewContext(nil, nil)
	if err := bootstrap.RunApp(ctx, initApp); err != nil {
		panic(err)
	}
}

3. 创建 Ent 数据库客户端

database/ent 返回通用 entgo.io/ent/dialect.Driver 包装，业务项目需要用自己生成的 Ent client 接入：

package data

import (
	"context"

	configv1 "github.com/liujitcn/kratos-kit/api/gen/go/config/v1"
	entkit "github.com/liujitcn/kratos-kit/database/ent"
	_ "github.com/liujitcn/kratos-kit/database/ent/driver/mysql"

	"your-app/ent"
)

func NewEntClient(cfg *configv1.Data_Database) (*ent.Client, func(), error) {
	drv, cleanup, err := entkit.NewEntClient(cfg)
	if err != nil {
		return nil, nil, err
	}

	client := ent.NewClient(ent.Driver(drv))
	if cfg.GetEnableMigrate() {
		if err = client.Schema.Create(context.Background()); err != nil {
			cleanup()
			return nil, nil, err
		}
		if err = drv.RunRegisteredTableComments(context.Background()); err != nil {
			cleanup()
			return nil, nil, err
		}
	}
	return client, cleanup, nil
}

Ent 审计字段可在 schema 中复用 entkit.AuditMixin{}；字段注释通过 entsql.WithComments(true) 落库，表注释可用 entkit.RegisterTableComment("users", "用户表") 在迁移后回填。Doris 可通过 MySQL 协议访问，导入 database/ent/driver/mysql 后配置 driver: doris 即可；Doris 建表、分区、分桶等能力建议使用专用 SQL 管理，不建议依赖 Ent 自动迁移。

默认命令行参数（bootstrap/flag.go）：

-c, --conf：配置目录，默认 ../../configs
-e, --env：运行环境，默认 dev
-s, --chost：配置中心地址，默认 127.0.0.1:8500
-t, --ctype：配置中心类型，默认 consul
-d, --daemon：以守护进程方式运行（非 Windows）
-p, --project：覆盖 app-info 的项目标识
-a, --app-id：覆盖 app-info 的应用标识
-i, --instance-id：覆盖 app-info 的实例标识
-n, --name：覆盖 app-info 的应用名称
-v, --version：覆盖 app-info 的应用版本

app-info 字段的优先级为：启动参数 → 传入的 *configv1.AppInfo → 默认值。

密钥与配置加解密

bootstrap.RunApp 默认启用配置密钥流程。启动顺序如下：

key.yaml / key.<env>.yaml（仅本地、未加密）
        ↓
读取 sdk.Runtime 中已设置的 Key 实例
        ↓（没有时按 key.type 创建；没有 key 配置时默认 file）
读取根密钥并派生 `kratos-kit:config` 的配置密钥
        ↓
使用 ENC[payload] 解密本地和远程配置
        ↓
初始化 logger、registry、tracer 和应用

独立 key.yaml 的内容直接对应 configv1.Key，不再嵌套在 Bootstrap：

type: vault
scope: prod/order-service
root_name: secret/data/kratos/prod/root
vault:
  address: http://127.0.0.1:8200
  value_key: value

如果没有 key.yaml，bootstrap 默认读取 ${conf}/root.key（默认即 configs/root.key），使用 file provider。如果本地根密钥文件不存在，file provider 初始化时会生成一次 32 字节随机根密钥并以 0600 权限保存；文件已存在时直接复用，不会覆盖已有根密钥。业务也可以在调用 RunApp 前自行创建 key.Key 并保存到 sdk.Runtime.SetKey，bootstrap 会优先复用该接口实例。

配置密文只需要在值上使用 ENC[...] 标记；标记可以占据整个值，也可以只嵌入需要保护的字符串片段。配置密钥由根密钥按 scope 和 kratos-kit:config 用途派生，该标识不写入密文。同一根密钥、范围和用途会得到相同的派生密钥，不同服务或用途应使用不同的 scope/purpose。已经按旧版本规则生成的 ENC[...] 密文不能直接使用新规则解密，需要先用旧规则解密后重新加密。

配置加载行为

config.LoadBootstrapConfig(configPath, env, keyValue) 的行为：

优先使用调用方传入的 keyValue；传入 nil 时复用 sdk.Runtime.GetKey()。
按 kratos-kit:config 派生配置密钥并解密敏感字段。
按 env 加载本地基础配置和环境覆盖配置。
若存在 ${configPath}/config.yaml，先读取其中 config.type，再创建对应远程配置源并合并加载。
扫描 configv1.Bootstrap 及已注册的自定义配置结构。

引导配置工厂支持的远程配置源类型由 config.type 决定，可选值见 config/types.go：apollo/consul/etcd/kubernetes/nacos/polaris。独立模块 config/fs、config/http、config/redis、config/vault、 config/zookeeper、config/oss 可直接作为 Kratos config.Source 使用。

AI 配置

AI 相关配置位于 bootstrap.ai，其中 ai.model 参照上游 kratos-bootstrap 的模型配置结构。旧的 client.llm 配置已移除。

云端 OpenAI 兼容 API：

ai:
  model:
    type: CLOUD_MODEL
    model_name: gpt-4o
    temperature: 0.7
    max_tokens: 4096
    timeout_seconds: 60
    max_retries: 3
    cloud:
      api_key: sk-xxx
      base_url: https://api.openai.com/v1
      organization: org_xxx

本地 Ollama：

ai:
  model:
    type: LOCAL_MODEL
    model_name: llama3
    timeout_seconds: 120
    local:
      host: 127.0.0.1
      port: 11434
      use_gpu: true

API 代码生成

make api

buf 模块根目录为 api/proto，同模块 proto 引用使用模块内路径，例如：

import "config/v1/tls.proto";

Agent 与 MCP Tool 生成

protoc-gen-go-agent-tool 用于从 proto service 生成 Eino Agent Tool 封装，生成文件后缀为 _agent_tool.go。生成后的构造函数返回 tool.InvokableTool，接收 XxxServiceServer，直接调用本进程内的服务端方法，不经过 gRPC client 或本地网络转换。

protoc-gen-go-mcp-tool 用于从 proto service 生成 MCP Tool 注册代码，生成文件后缀为 _mcp_tool.go。Agent 与 MCP 生成器都基于标准 gRPC 方法路径生成 Tool 名称，例如 /admin.v1.AuthService/GetUserInfo 会生成 admin_v1_auth_service_get_user_info。外部如需复用同一转换规则，可调用 utils.ToolNameFromRPCPath。

当请求或响应消息存在递归字段引用时，Agent 与 MCP 生成器会将 Tool 的 schema 泛型降级为 any，再在执行时转换为真实 proto 请求，避免 JSON Schema 生成阶段出现递归循环错误。

protoc --go-agent-tool_out=. path/to/service.proto
protoc --go-mcp-tool_out=. path/to/service.proto
protoc --go-redact_out=. path/to/service.proto

开发命令

make plugin   # 安装 protoc 相关插件
make cli      # 安装 kratos/buf、normalize-go-imports 等命令行工具
make fmt # 运行 normalize-go-imports，再使用 goimports 格式化
make api      # 生成 api 代码
make gen      # 一键生成并整理 api 代码
make tag      # 默认从仓库根目录递归检查 go.mod 并自动打/推送 tag（含根模块）
make tag MODULE=auth       # 从 auth 目录开始递归检查 go.mod 并打 tag
make tag MODULE=auth/authn # 从 auth/authn 目录开始递归检查 go.mod 并打 tag

依赖版本基线更新时，需要同步整理各子模块的 go.mod/go.sum，并逐模块执行 go test -mod=readonly ./...。api 子模块承载公共 proto 契约和生成代码，配置契约或依赖基线同步发布时，需要确认新的 api/v* tag 跟随发布，避免下游引用到旧生成代码。

子模块文档

来源与版权说明

本仓库大部分代码参考或来源于以下开源项目，并在此基础上结合当前业务需求进行了整理与调整：

若涉及版权或授权边界问题，请优先以上游项目许可证与仓库声明为准，并联系维护者处理。

Directories ¶

Path	Synopsis
ai
eino module
langchaingo module
model module
api module
auth module
authn module
authn/engine/jwt module
authn/middleware module
authz module
authz/engine/casbin module
authz/middleware module
bootstrap module
broker module
cache module
captcha module
circuitbreaker module
cmd
internal/utils module
normalize-go-imports module
project-docs module
protoc-gen-go-agent-tool module
protoc-gen-go-mcp-local-tool module
protoc-gen-go-mcp-tool module
protoc-gen-go-redact module
protoc-gen-go-service module
config module
apollo module
consul module
etcd module
kubernetes module
nacos module
polaris module
database
ent module
ent/driver module
gorm module
gorm/driver module
gorm/driver/bigquery module
gorm/driver/mysql module
gorm/driver/oracle module
gorm/driver/postgres module
gorm/driver/sqlite module
gorm/driver/sqlserver module
gorm/migration module
key module
locker module
logger module
aliyun module
fluent module
tencent module
zap module
zerolog module
metrics module
prometheus module
oauth module
oss module
s3 module
pprof module
queue module
redisqueue module
ratelimit module
tokenbucket module
redact module
registry module
consul module
etcd module
eureka module
kubernetes module
nacos module
polaris module
servicecomb module
zookeeper module
retry module
rpc module
runtime
sdk
server
grpc module
http module
mcp module
sse module
swagger-ui module
tracer module
tracing module
translator module
transport module
cron module
hptimer module
keepalive module
mcp module
queue module
sse module
utils module
workflow module
argo module
conductor module
goworkflows module
temporal module

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

kratos-kit

仓库说明

安装

快速开始

1. 引入需要的实现包（通过 init 自动注册）

2. 启动应用

3. 创建 Ent 数据库客户端

密钥与配置加解密

配置加载行为

AI 配置

API 代码生成

Agent 与 MCP Tool 生成

开发命令

子模块文档

来源与版权说明

Directories ¶

1. 引入需要的实现包（通过 `init` 自动注册）