README
¶
Lava
Lava 是一个面向 Go 微服务场景的中台集成框架，提供统一的服务抽象、调试能力、网关能力、隧道能力与开发工具链。
核心能力
- 统一服务抽象：HTTP / gRPC / 定时任务 / Tunnel Gateway
- 统一中间件模型：
lava.Middleware一套接口覆盖多组件 - 可观测性内建：日志、指标、调试路由（
/debug） - 网关能力：
pkg/gateway提供 HTTP/JSON 到 gRPC 的转换 - 本地开发工具：
watch、curl、devproxy、fileserver - Protobuf 工程化：
protobuf.yaml+task proto:*
快速开始
1) 环境要求
- Go
1.25+ - Task（推荐）
2) 获取源码
git clone https://github.com/pubgo/lava.git
cd lava
go mod tidy
3) 基础检查
task test
task lint
4) 构建并体验 CLI
go build -o lava .
./lava
当前入口命令（main.go）
以仓库根入口
main.go为准。
| 命令 | 说明 |
|---|---|
lava watch |
文件变更监听并自动执行命令 |
lava curl |
面向 Gateway 的 HTTP 调试客户端（支持 login） |
lava tunnel gateway |
启动 Tunnel Gateway |
lava fileserver <dir> |
本地目录静态文件服务 |
lava devproxy |
本地开发代理（DNS + HTTP 反向代理） |
双入口说明：根目录
main.go仅注册上表中的开发工具命令。HTTP/gRPC/Cron 等服务需通过core/lavabuilder装配独立二进制（见internal/examples/*、docs/architecture-v2.md）。不要在文档中假设./lava grpc等命令存在于根二进制。
架构速览
flowchart TD
U[开发者/调用方] --> CLI[lava CLI]
U --> HTTP[HTTP Client]
U --> GRPC[gRPC Client]
CLI --> CMDS[cmds/*]
HTTP --> SHTTP[servers/https]
GRPC --> SGWS[servers/gatewayserver]
SHTTP --> CORE[core/*]
SGWS --> CORE
SGWS --> GW[pkg/gateway]
CMDS --> CORE
CORE --> DEBUG["/debug routes"]
CORE --> OBS[logging/metrics/tracing]
CORE --> TUNNEL[core/tunnel]
文档导航
- 快速入门：
docs/quickstart.md - 开发工作流：
docs/development.md - 配置模型：
docs/configuration.md - 文档总览：
docs/README.md - 架构文档（含流程图）：
docs/architecture-v2.md - 设计文档（含关键抽象）：
docs/design-v2.md - zrpc 文档：
docs/zrpc.md - 命令文档：
docs/lava-command.md - 模块总览：
docs/modules/README.md- Core：
docs/modules/core.md - Servers：
docs/modules/servers.md - Clients：
docs/modules/clients.md - Pkg：
docs/modules/pkg.md - Cmds：
docs/modules/cmds.md
- Core：
Protobuf 流程
task proto:fmt
task proto:lint
task proto:gen
配置位于 protobuf.yaml，生成代码输出到 pkg/proto。
zrpc 快速入口
仓库已经内置一条基于 NATS 的 protobuf unary RPC 能力：
- runtime：
pkg/zrpc - server host：
servers/zrpcs - client：
clients/zrpcc - demo：
internal/examples/zrpcdemo
相关使用方式见：docs/zrpc.md
许可证
本项目使用 LICENSE 中定义的开源许可证。
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
clients
|
|
|
resty/examples
command
|
|
|
zrpcc
Package zrpcc provides a Lava-style zrpc client with lazy NATS connection, default middlewares (serviceinfo/metric/accesslog/recovery), and lifecycle APIs.
|
Package zrpcc provides a Lava-style zrpc client with lazy NATS connection, default middlewares (serviceinfo/metric/accesslog/recovery), and lifecycle APIs. |
|
cmds
|
|
|
core
|
|
|
debug
Package debug 提供全局 debug HTTP 路由聚合器（基于 Fiber）。
|
Package debug 提供全局 debug HTTP 路由聚合器（基于 Fiber）。 |
|
debug/bootstrap
Package bootstrap registers built-in debug routes on the global debug App.
|
Package bootstrap registers built-in debug routes on the global debug App. |
|
debug/debug
Package debug 注册 debug 控制台主页与全局鉴权中间件。
|
Package debug 注册 debug 控制台主页与全局鉴权中间件。 |
|
debug/featurehttp
Package featurehttp 提供 feature flags 的 HTTP 调试接口
|
Package featurehttp 提供 feature flags 的 HTTP 调试接口 |
|
discovery
Package discovery 提供服务发现的抽象接口，供 gRPC resolver 等客户端组件使用。
|
Package discovery 提供服务发现的抽象接口，供 gRPC resolver 等客户端组件使用。 |
|
encoding
Package encoding 提供编解码器（Codec）的全局注册表， 用于按名称（如 "json"、"proto"）或 HTTP Content-Type 选择对应的序列化实现。
|
Package encoding 提供编解码器（Codec）的全局注册表， 用于按名称（如 "json"、"proto"）或 HTTP Content-Type 选择对应的序列化实现。 |
|
flags
Package flags 提供 CLI 命令行参数（flag）的全局聚合注册表。
|
Package flags 提供 CLI 命令行参数（flag）的全局聚合注册表。 |
|
healthy
Package healthy 提供健康检查处理器（Handler）的全局注册表。
|
Package healthy 提供健康检查处理器（Handler）的全局注册表。 |
|
lavabuilder
Package lavabuilder 是 lava 应用的 DI 装配与 CLI 启动入口。
|
Package lavabuilder 是 lava 应用的 DI 装配与 CLI 启动入口。 |
|
leaderelection
Package leaderelection 预留的分布式选主模块（尚未实现）。
|
Package leaderelection 预留的分布式选主模块（尚未实现）。 |
|
lifecycle
Package lifecycle 定义服务生命周期钩子的抽象。
|
Package lifecycle 定义服务生命周期钩子的抽象。 |
|
logging
Package logging 提供日志工厂注册表与配置结构。
|
Package logging 提供日志工厂注册表与配置结构。 |
|
metrics
Package metrics 提供基于 uber-go/tally 的指标抽象与 Prometheus 驱动。
|
Package metrics 提供基于 uber-go/tally 的指标抽象与 Prometheus 驱动。 |
|
p2p
Package p2p 提供基于 ICE/STUN/TURN 的点对点连接能力。
|
Package p2p 提供基于 ICE/STUN/TURN 的点对点连接能力。 |
|
p2p/example
command
P2P 示例：本地内存信令 / tunnel gateway 全链路 / dev coturn 验证。
|
P2P 示例：本地内存信令 / tunnel gateway 全链路 / dev coturn 验证。 |
|
p2p/p2pbuilder
Package p2pbuilder 装配 P2P Coordinator：tunnel agent 信令、lifecycle 与 debug 端点。
|
Package p2pbuilder 装配 P2P Coordinator：tunnel agent 信令、lifecycle 与 debug 端点。 |
|
p2p/signaling/tunnelsig
Package tunnelsig 通过 tunnel gateway 控制流交换 ICE 信令。
|
Package tunnelsig 通过 tunnel gateway 控制流交换 ICE 信令。 |
|
p2p/turncred
Package turncred 生成 coturn TURN REST API 临时凭证（HMAC-SHA1）。
|
Package turncred 生成 coturn TURN REST API 临时凭证（HMAC-SHA1）。 |
|
pidfile
Package pidfile 管理进程 PID 文件的读写，用于进程存活检测与单实例守护。
|
Package pidfile 管理进程 PID 文件的读写，用于进程存活检测与单实例守护。 |
|
pidfile/pidfilebuilder
Package pidfilebuilder 提供 lifecycle 钩子，在服务启动后写入 PID 文件、停止后删除。
|
Package pidfilebuilder 提供 lifecycle 钩子，在服务启动后写入 PID 文件、停止后删除。 |
|
registry
Package registry 提供服务注册与撤销的抽象接口及 lifecycle 集成。
|
Package registry 提供服务注册与撤销的抽象接口及 lifecycle 集成。 |
|
registry/drivers/mdns
Package mdns is a multicast dns registry
|
Package mdns is a multicast dns registry |
|
rpcmeta
Package rpcmeta 定义描述单个 RPC 方法的元信息结构。
|
Package rpcmeta 定义描述单个 RPC 方法的元信息结构。 |
|
running
Package running 提供进程级运行态信息与全局 CLI flag 定义。
|
Package running 提供进程级运行态信息与全局 CLI flag 定义。 |
|
service
Package service 定义服务注册/发现领域模型（Service、Node、Instance 等）。
|
Package service 定义服务注册/发现领域模型（Service、Node、Instance 等）。 |
|
signals
Package signals 将操作系统的关停信号转换为 context 取消，用于服务优雅退出。
|
Package signals 将操作系统的关停信号转换为 context 取消，用于服务优雅退出。 |
|
supervisor/bootstrap
Package bootstrap provides shared supervisor wiring for CLI commands.
|
Package bootstrap provides shared supervisor wiring for CLI commands. |
|
supervisor/debug
Package debug 注册 Supervisor 的 debug UI 与 REST 控制 API。
|
Package debug 注册 Supervisor 的 debug UI 与 REST 控制 API。 |
|
tunnel
环境变量加载：与 CLI（cmds/tunnelcmd）使用同一套 TUNNEL_* 命名。
|
环境变量加载：与 CLI（cmds/tunnelcmd）使用同一套 TUNNEL_* 命名。 |
|
tunnel/example
command
Package main provides a simple example of using the tunnel package.
|
Package main provides a simple example of using the tunnel package. |
|
tunnel/example/auth
command
Demo: 代理鉴权 —— 配置 TUNNEL_AUTH_TOKEN 后，HTTP 代理要求客户端携带 token。
|
Demo: 代理鉴权 —— 配置 TUNNEL_AUTH_TOKEN 后，HTTP 代理要求客户端携带 token。 |
|
tunnel/example/grpc
command
Demo: gRPC over tunnel —— 经网关 gRPC 代理调用后端 gRPC 服务。
|
Demo: gRPC over tunnel —— 经网关 gRPC 代理调用后端 gRPC 服务。 |
|
tunnel/example/quickstart
command
Demo: 最简上手 —— Standalone Agent + HTTP 代理（单进程跑通）。
|
Demo: 最简上手 —— Standalone Agent + HTTP 代理（单进程跑通）。 |
|
tunnel/example/tls
command
Demo: TLS 传输 —— Agent ↔ Gateway 之间启用 TLS（yamux over TLS）。
|
Demo: TLS 传输 —— Agent ↔ Gateway 之间启用 TLS（yamux over TLS）。 |
|
tunnel/ratelimit
Package ratelimit 提供令牌桶速率限制，供 gateway 代理与 P2P 信令复用。
|
Package ratelimit 提供令牌桶速率限制，供 gateway 代理与 P2P 信令复用。 |
|
tunnel/testhelper
Package testhelper provides polling helpers for tunnel integration tests.
|
Package testhelper provides polling helpers for tunnel integration tests. |
|
tunnel/tunnelagent
Package tunnelagent 提供隧道代理客户端实现
|
Package tunnelagent 提供隧道代理客户端实现 |
|
tunnel/tunneldebug
Package tunneldebug 提供 Tunnel Gateway 的 Web 管理界面
|
Package tunneldebug 提供 Tunnel Gateway 的 Web 管理界面 |
|
internal
|
|
|
examples/fileserver
command
|
|
|
examples/grpcweb
command
Package main 提供 gRPC Web 示例服务
|
Package main 提供 gRPC Web 示例服务 |
|
examples/grpcwebsocket
command
Package main 提供 Gateway WebSocket 示例服务。
|
Package main 提供 Gateway WebSocket 示例服务。 |
|
examples/grpcwebsocket/verify
command
Command verify exercises every gateway frontend exposed by the grpcwebsocket example.
|
Command verify exercises every gateway frontend exposed by the grpcwebsocket example. |
|
examples/httpserver
command
|
|
|
examples/scheduler
command
|
|
|
examples/tunnel
command
|
|
|
examples/xz
command
|
|
|
examples/zrpcdemo
command
|
|
|
pkg
|
|
|
lava
Package lava defines transport-agnostic request/response contracts, middleware, and router interfaces shared across HTTP, gRPC, and zRPC components.
|
Package lava defines transport-agnostic request/response contracts, middleware, and router interfaces shared across HTTP, gRPC, and zRPC components. |
|
lavacontexts
Package lavacontexts 提供基于 context.Context 的请求级数据传递工具。
|
Package lavacontexts 提供基于 context.Context 的请求级数据传递工具。 |
|
wsproxy
Package wsproxy implements a websocket proxy for grpc-gateway backed services
|
Package wsproxy implements a websocket proxy for grpc-gateway backed services |
|
zrpc
Package zrpc implements protobuf RPC over NATS.
|
Package zrpc implements protobuf RPC over NATS. |
|
servers
|
|
|
serverhttp
Package serverhttp adapts fiber.Ctx to lava.Request and lava.Response for HTTP servers (gatewayserver, https).
|
Package serverhttp adapts fiber.Ctx to lava.Request and lava.Response for HTTP servers (gatewayserver, https). |
|
zrpcs
Package zrpcs hosts zrpc services on NATS with Lava supervisor integration.
|
Package zrpcs hosts zrpc services on NATS with Lava supervisor integration. |
|
tools
|
|
|
protoc-gen-zrpc-go
command
|
Click to show internal directories.
Click to hide internal directories.