Skip to content
BranchesTags

Repository files navigation

edgecache

edgecache 是 NexusMC 当前的 Go 旁车缓存服务，主要用于承接论坛、资源区、找服玩、视频区这类读多写少、可共享复用的数据面缓存。

它的目标不是替代 apps/server，而是作为一个独立的共享缓存层，逐步把高频公开读缓存从 Node.js 进程内迁到 Go sidecar，并为后续传输层和失效模型演进留出空间。

它解决什么问题

当前 edgecache 主要承担这几件事：

  • 提供独立于 apps/server 的共享缓存服务
  • 组合 L1 内存缓存 + 可选 Redis L2
  • 承接公开内容的高频读缓存
  • 从通配清理逐步过渡到版本型失效
  • 为 HTTP -> gRPC 迁移提供可灰度的演进路径

一句话说，它是缓存旁车，不是业务后端。

当前能力

core

  • 纯 Go 内存缓存
  • LRU 淘汰
  • TTL 过期
  • 统计信息
  • 按模式清理

redis

  • 可选 Redis L2
  • pub/sub 失效广播

server

  • HTTP API
  • 可选 gRPC API
  • 健康检查
  • 缓存统计
  • forum 版本命名空间接口

client

  • apps/edgecache/packages/edgecache-client
    • 独立 TS/JS SDK
  • apps/server/packages/edgecache-client
    • 当前 apps/server 实际使用的 workspace 包

bridge

  • apps/server 已接入这层 bridge
  • 支持 get / set / del / clear / mget / mset
  • 支持 forum 列表版本号读取与 bump

和 apps/server 的关系

是否必须启动 edgecache 才能启动论坛后端？

不是必须。

当前 apps/server 对 edgecache 的关系是“可选增强”：

  • 如果设置了 EDGECACHE_ENABLED=true
    • 后端会尝试访问 edgecache
    • 命中时直接使用 sidecar 返回的数据
  • 如果 edgecache 没启动、不可达或者未启用
    • apps/server 仍然可以正常启动
    • 读路径会自动回退到本地缓存或数据库逻辑

也就是说：

  • edgecache 不是论坛后端的启动前置条件
  • 但如果要观察 sidecar 的实际收益，建议一起启动

和 Redis 的分工

推荐把 Redis 的用途拆成两类：

  • apps/edgecache
    • 使用 EDGECACHE_REDIS_*
    • 负责共享缓存层的 Redis L2
  • apps/server
    • 使用 SOCKET_REDIS_URL
    • 只负责 Socket.IO 多实例广播等实时基础设施能力

长期方向不是“后端完全不用 Redis”，而是：

  • 后端不再直接把 Redis 当自己的缓存层
  • edgecache 成为共享缓存 Redis 的主入口
  • 后端只保留基础设施导向的 Redis 用法

传输模型

当前有两条访问路径：

HTTP

这是现在的默认主路径，支持：

  • TCP HTTP
  • Unix Domain Socket HTTP
  • Windows named pipe HTTP

gRPC

这是现在的灰度路径。

当 apps/server 设置 EDGECACHE_TRANSPORT=grpc 时：

  • 会优先走 gRPC
  • 如果 gRPC 请求失败，会自动回退到 HTTP

这样可以先做灰度试跑，而不是一次性硬切。

快速启动

先复制配置：

cp .env.example .env

然后在 apps/edgecache 目录启动：

go run ./cmd/edgecache

或者在仓库根目录启动：

npm run dev:edgecache

常见配置示例

1. 本地 TCP HTTP

apps/edgecache/.env

EDGECACHE_LISTEN_NETWORK=tcp
EDGECACHE_LISTEN_ADDRESS=:4410

apps/server/.env

EDGECACHE_ENABLED=true
EDGECACHE_TRANSPORT=http
EDGECACHE_URL=http://127.0.0.1:4410

2. 本地 Unix Socket HTTP

apps/edgecache/.env

EDGECACHE_LISTEN_NETWORK=unix
EDGECACHE_LISTEN_ADDRESS=./run/edgecache.sock

apps/server/.env

EDGECACHE_ENABLED=true
EDGECACHE_TRANSPORT=http
EDGECACHE_SOCKET_PATH=./run/edgecache.sock

3. Windows named pipe HTTP

apps/edgecache/.env

EDGECACHE_LISTEN_NETWORK=npipe
EDGECACHE_LISTEN_ADDRESS=edgecache-http

apps/server/.env

EDGECACHE_ENABLED=true
EDGECACHE_TRANSPORT=http
EDGECACHE_SOCKET_PATH=\\.\pipe\edgecache-http

4. gRPC 灰度试跑

apps/edgecache/.env

EDGECACHE_LISTEN_NETWORK=tcp
EDGECACHE_LISTEN_ADDRESS=:4410

EDGECACHE_GRPC_ENABLED=true
EDGECACHE_GRPC_LISTEN_NETWORK=tcp
EDGECACHE_GRPC_LISTEN_ADDRESS=127.0.0.1:4411

apps/server/.env

EDGECACHE_ENABLED=true
EDGECACHE_TRANSPORT=grpc
EDGECACHE_GRPC_ENDPOINT=127.0.0.1:4411

# 灰度期间保留 HTTP fallback
EDGECACHE_URL=http://127.0.0.1:4410

当前接口

HTTP 接口

  • GET /healthz
  • GET /v1/cache/get
  • POST /v1/cache/set
  • POST /v1/cache/mget
  • POST /v1/cache/mset
  • POST /v1/cache/del
  • POST /v1/cache/clear
  • GET /v1/cache/stats
  • GET /v1/forum/version?namespace=...
  • POST /v1/forum/version/bump

gRPC 服务

  • 服务名：edgecache.v1.EdgeCacheService

协议草案：

  • proto/edgecache.proto

迁移说明：

  • docs/grpc-migration-plan.md

版本型失效

像下面这些列表型 key，现在尽量使用带版本号的命名：

  • posts:list:{...}:v{n}
  • boards:hot:list:{...}:v{n}
  • resource:list:{...}:v{n}
  • video:list:{...}:v{n}

这样做的好处：

  • 避免长期依赖昂贵的通配清理
  • 更适合多实例部署
  • 更方便做 namespace 级失效

已迁移的缓存域

当前已经逐步接入 edgecache 的缓存域包括：

论坛

  • boards:hot:list:*
  • posts:list:*
  • post:{id}
  • post:{id}:content

资源区

  • resource:list:*
  • resource:{id}
  • resource:summary:{id}
  • resource:sidebar:{id}
  • resource:content:{id}
  • resource:platforms
  • resource:collections
  • resource:version-groups
  • resource:official-tag-groups
  • resource:game-versions:*
  • resource:categories:*
  • resource:categories-flat:*
  • resource:game-versions-flat:*

找服玩

  • player:list:*
  • player:{id}
  • player:{id}:ping-history:*
  • player:help-config
  • player:platforms
  • player:categories:*
  • player:versions:*

视频区

  • video:list:*
  • video:categories:*
  • video:{id}
  • video:summary:{id}
  • video:{id}:replies:*

消息 / 通知中心读缓存

  • inbox:{userId}:notifications:*
  • inbox:{userId}:messages:*
  • inbox:{userId}:rooms:*

环境变量

基础监听

  • EDGECACHE_LISTEN_NETWORK
  • EDGECACHE_LISTEN_ADDRESS
  • EDGECACHE_ADDR（兼容旧配置）

gRPC 监听

  • EDGECACHE_GRPC_ENABLED
  • EDGECACHE_GRPC_LISTEN_NETWORK
  • EDGECACHE_GRPC_LISTEN_ADDRESS

L1 缓存

  • EDGECACHE_L1_MAX_SIZE
  • EDGECACHE_L1_CLEANUP_SECONDS

Redis L2

  • EDGECACHE_REDIS_ENABLED
  • EDGECACHE_REDIS_URL
  • EDGECACHE_REDIS_PREFIX
  • EDGECACHE_REDIS_CHANNEL
  • EDGECACHE_NODE_ID

目录结构

edgecache/
├── core/                     # L1 缓存核心
├── redis/                    # Redis bridge / L2
├── server/                   # HTTP + gRPC 服务层
├── proto/                    # proto 草案 / 后续协议
├── packages/
│   └── edgecache-client/     # 独立 TS/JS 客户端
└── cmd/                      # 可执行入口

apps/server/packages/
└── edgecache-client/         # apps/server 当前使用的 workspace SDK

当前更适合的使用范围

现阶段最适合 edgecache 的场景：

  • 公开内容缓存
  • 共享读缓存
  • 列表版本失效
  • 命中率与热点观测

暂时不建议把它直接扩成：

  • 消息队列
  • 强一致业务中枢
  • 事件总线替代品

建议的演进路线

更稳的路线还是这条：

  1. 先把主要公开读缓存域迁完
  2. 补齐观测与命中率可见性
  3. 稳定 gRPC 灰度路径
  4. 再逐步过渡到更强类型的 proto/codegen 传输层
  5. 最后再评估是否继续拆更多基础设施

最后一句

如果你现在的问题是“这个服务是不是立刻必需”，那通常答案是：

  • 对正确性来说：不是
  • 对性能和后续架构演进来说：是，而且值得渐进式接入

About

NexusMC 论坛缓存端

www.nexusmc.cn/

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages