kite

module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 16, 2026 License: MIT

README

kite

Go 实现的网易云能力服务 + 命令行工具。

两个产物共享同一套网易云核心(internal/netease/):一个 gRPC + grpc-gateway 服务,一个直连 engine 的 CLI。

产物

服务 (cmd/server)

gRPC(强类型 RPC,端口 :3722)+ grpc-gateway(REST 暴露,端口 :3721)双 server,收到 SIGINT/SIGTERM 优雅关闭。

出网代理:server 的 engine 走默认 transport,尊重标准环境变量 HTTPS_PROXY / HTTP_PROXY(无需额外配置,PRD-0018)。

go run ./cmd/server      # 直接运行
air                      # 热重载开发(.air.toml)
docker build -t kite .   # 容器镜像(仅 Dockerfile,无 compose)

环境变量 KITE_SERVER_PORT 覆盖 HTTP 端口;完整配置见 config.example.yaml。

curl localhost:3721/health
# {"code":0,"data":{"status":"ok"},"message":""}
CLI (cmd/kite)

直连 engine + endpoint 声明,不经 gRPC。网易云 9 域已全接入:登录(auth)、歌曲(song)、专辑(album)、歌手(artist)、歌单(playlist)、用户(user)、搜索(search)、推荐(recommend)、私人 FM(fm)。

go install github.com/VOD-Studio/kite/cmd/kite@latest
kite login               # 扫码登录
kite search 周杰伦        # 搜索(位置参数 ≡ --keyword)
kite song download 347230 --level 3   # 下载单曲(1标准 2较高 3无损 4Hi-Res)

上手流程见 使用手册;全命令参数查 kite <命令> --help 或 生成参考。

架构

三层运行时,共享 internal/netease/ 核心与 internal/service/ 业务层:

  • service 层:网易云业务逻辑,CLI 与 TUI 共同消费。
  • CLI(internal/cli/):输出导向(表格 / JSON),按领域分包,kit/ 是公共渲染层。
  • TUI(internal/tui/,规划中):bubbletea v2 完整客户端,与 CLI 平行不耦合。

gRPC 契约的唯一真相在 proto/netease/music/v1/。TUI 架构决策见 ADR。

开发

所有代码生成走根 Makefile:

make proto       # 改 proto 后重新生成 Go stub / gateway / OpenAPI 到 gen/
make proto-lint  # 检查 proto 规范
make docs        # 改命令树后重新生成 docs/cmd/(freshness 守护测试依赖此)
make clean       # 清除生成产物

go build ./cmd/server/    # 编译服务
go build ./cmd/kite/      # 编译 CLI
go test ./...             # 测试
go vet ./...              # 检查

环境依赖 Go 1.25。若环境缺 Go,make 无提示直接失败——请先安装,不要自行处理。

技术栈

  • Go 1.25 + gRPC + grpc-gateway(契约优先,proto 定义 RPC)
  • bubbletea v2 / lipgloss v2(TUI)、cobra(CLI 命令树)
  • OpenTelemetry 可观测性(OTLP exporter / Prometheus 指标 / 结构化日志)
  • Redis 缓存与会话存储(当前 noop,后续接入)
  • 网易云 weapi/eapi 加密自实现(Go 标准库,不依赖第三方音乐库)

文档

Directories

Path Synopsis
cmd
demo command
cmd/demo 盲文点阵进度条演示(展示 kit 正式 API 用法)。
 cmd/demo 盲文点阵进度条演示(展示 kit 正式 API 用法)。
kite command
Package main 是 kite 接口调试与实用 CLI 工具。
 Package main 是 kite 接口调试与实用 CLI 工具。
kite-docs command
Package main 生成 kite 全命令 markdown 参考(cobra GenMarkdownTree)。
 Package main 生成 kite 全命令 markdown 参考(cobra GenMarkdownTree)。
server command
Package main 是 kite 服务的入口。
 Package main 是 kite 服务的入口。
Package config 定义 kite 服务的配置结构。
 Package config 定义 kite 服务的配置结构。
Package errors 定义 kite 的统一错误模型。
 Package errors 定义 kite 的统一错误模型。
gen
go/netease/music/v1
Package musicv1 is a reverse proxy.
 Package musicv1 is a reverse proxy.
internal
cache
Package cache 定义缓存接口及其实现。
 Package cache 定义缓存接口及其实现。
cache/redis
Package redis 实现 Cache 接口的 Redis 存储。
 Package redis 实现 Cache 接口的 Redis 存储。
cli
Package cli 装配 kite 的根命令。
 Package cli 装配 kite 的根命令。
cli/album
Package album 提供专辑相关命令。
 Package album 提供专辑相关命令。
cli/artist
Package artist 提供歌手相关命令。
 Package artist 提供歌手相关命令。
cli/auth
Package auth 提供 kite 的登录态命令:扫码/手机号登录、登录状态、登出。
 Package auth 提供 kite 的登录态命令:扫码/手机号登录、登录状态、登出。
cli/auth/qrtui
Package qrtui 提供扫码登录的 bubbletea 全屏界面。
 Package qrtui 提供扫码登录的 bubbletea 全屏界面。
cli/config
Package config 实现 kite config 命令组:config.toml 的查看与写入(PRD-0017)。
 Package config 实现 kite config 命令组:config.toml 的查看与写入(PRD-0017)。
cli/doctor
Package doctor 实现 kite doctor 命令:逐项环境自检。
 Package doctor 实现 kite doctor 命令:逐项环境自检。
cli/fm
Package fm 提供私人 FM 命令。
 Package fm 提供私人 FM 命令。
cli/kit
Package kit 的进度条行渲染 + diff 输出。
 Package kit 的进度条行渲染 + diff 输出。
cli/playlist
playlist download 命令:整单批量下载,worker 池并发 + 跳过已存在 + 失败汇总(PRD-0013)。
 playlist download 命令:整单批量下载,worker 池并发 + 跳过已存在 + 失败汇总(PRD-0013)。
cli/recall
Package recall 实现音乐召回池:补全与 recent 命令共用的候选数据基础设施。
 Package recall 实现音乐召回池:补全与 recent 命令共用的候选数据基础设施。
cli/recent
Package recent 提供 kite recent 命令:读召回池按 frecency 展示最近条目。
 Package recent 提供 kite recent 命令:读召回池按 frecency 展示最近条目。
cli/recommend
Package recommend 提供推荐相关命令。
 Package recommend 提供推荐相关命令。
cli/search
Package search 提供搜索相关命令。
 Package search 提供搜索相关命令。
cli/song
song download 命令:从 flag 解析到文件落盘的端到端垂直切片(PRD-0013 Phase C)。
 song download 命令:从 flag 解析到文件落盘的端到端垂直切片(PRD-0013 Phase C)。
cli/songdl
单曲下载核心:从拿到的 SongURL + Song 完成落盘,返回结构化 Outcome。
 单曲下载核心:从拿到的 SongURL + Song 完成落盘,返回结构化 Outcome。
cli/user
Package user 提供用户相关命令。
 Package user 提供用户相关命令。
cli/version
infra/redis
Package redis 提供 kite 的共享 Redis 客户端。
 Package redis 提供 kite 的共享 Redis 客户端。
netease/endpoint/album
Package album 定义专辑接口的声明。
 Package album 定义专辑接口的声明。
netease/endpoint/artist
Package artist 的扩展查询接口声明。
 Package artist 的扩展查询接口声明。
netease/endpoint/auth
Package auth 定义登录认证接口的声明。
 Package auth 定义登录认证接口的声明。
netease/endpoint/fm
Package fm 定义私人电台接口的声明。
 Package fm 定义私人电台接口的声明。
netease/endpoint/playlist
Package playlist 的浏览与发现接口声明。
 Package playlist 的浏览与发现接口声明。
netease/endpoint/recommend
Package recommend 定义推荐接口的声明。
 Package recommend 定义推荐接口的声明。
netease/endpoint/search
Package search 的辅助接口声明（建议/热搜/默认词）。
 Package search 的辅助接口声明（建议/热搜/默认词）。
netease/endpoint/song
Package song 的可用性检查接口声明。
 Package song 的可用性检查接口声明。
netease/endpoint/user
Package user 的社交接口解析辅助函数。
 Package user 的社交接口解析辅助函数。
netease/engine
Package engine 的熔断器。
 Package engine 的熔断器。
netease/model
Package model 的专辑实体映射与专辑详情解码。
 Package model 的专辑实体映射与专辑详情解码。
netease/session
Package session 的空实现。
 Package session 的空实现。
server
Package server 的 cookie interceptor。
 Package server 的 cookie interceptor。
service
Package service 的 AlbumService impl。
 Package service 的 AlbumService impl。
store/redis
Package redis 实现 SessionStore 接口的 Redis 存储。
 Package redis 实现 SessionStore 接口的 Redis 存储。
Package observability 提供 kite 的可观测性基础设施。
 Package observability 提供 kite 的可观测性基础设施。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.