Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

Migrate cache backend from Valkey 8 to apache/kvrocks:2.16.0 (#19374)

xugangqianga36615c6fab2
diff --git a/.github/workflows/kvrocks-parity.yml b/.github/workflows/kvrocks-parity.yml
new file mode 100644
index 0000000000..8c8c3a4fd0
--- /dev/null
+++ b/.github/workflows/kvrocks-parity.yml
@@ -0,0 +1,67 @@
+name: Kvrocks Parity
+
+# Regression fence for the Valkey -> apache/kvrocks:2.16.0 migration. Runs the
+# //go:build integration parity tests (internal/engine/redis, internal/agent/canvas)
+# against a real Kvrocks instance. These tests are NOT part of the default
+# `go test` run, so this workflow is what actually executes them in CI.
+on:
+ push:
+ branches: [main]
+ pull_request:
+ workflow_dispatch:
+
+# Only one in-flight run per ref; cancel superseded runs on PR pushes.
+concurrency:
+ group: kvrocks-parity-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ kvrocks-parity:
+ runs-on: ubuntu-latest
+ env:
+ # CI=true makes the parity tests hard-fail (not skip) if Kvrocks is absent.
+ CI: "true"
+ KV_PASSWORD: ci-test-pass
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-go@v5
+ with:
+ go-version: "1.26"
+ cache: true
+
+ # Pinned to 2.16.0+ on purpose (TTL contract + no maxmemory). Reuse the repo
+ # entrypoint script so this job also exercises the deployment's conf renderer.
+ # `-e REDIS_PASSWORD` forwards the password into the container so the
+ # entrypoint can render requirepass; without it Kvrocks starts open and the
+ # parity tests fail to AUTH.
+ - name: Start Kvrocks
+ run: |
+ docker run -d --name kvrocks -p 6379:6379 -e REDIS_PASSWORD \
+ -v "${{ github.workspace }}/docker/kvrocks-entrypoint.sh:/etc/kvrocks/entrypoint.sh:ro" \
+ --user 0:0 --entrypoint /bin/sh apache/kvrocks:2.16.0 -c "/etc/kvrocks/entrypoint.sh"
+ env:
+ REDIS_PASSWORD: ci-test-pass
+
+ - name: Wait for Kvrocks
+ env:
+ REDIS_PASSWORD: ci-test-pass
+ run: |
+ for i in $(seq 1 30); do
+ if docker exec kvrocks redis-cli -a "${REDIS_PASSWORD}" ping 2>/dev/null | grep -q PONG; then
+ echo "Kvrocks ready"; break
+ fi
+ sleep 1
+ done
+
+ - name: Run parity tests
+ run: |
+ CGO_ENABLED=0 go test -tags integration -count=1 -timeout 300s \
+ ./internal/engine/redis/... ./internal/agent/canvas/...
+ env:
+ KV_ADDR: "localhost:6379"
+ KV_PASSWORD: ci-test-pass
+
+ - name: Stop Kvrocks
+ if: always()
+ run: docker rm -f kvrocks
diff --git a/docker/docker-compose-base.yml b/docker/docker-compose-base.yml
index 751451035b..5dce3477c1 100644
--- a/docker/docker-compose-base.yml
+++ b/docker/docker-compose-base.yml
@@ -267,7 +267,9 @@ services:
retries: 120
redis:
- # swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/valkey/valkey:8
+ # Valkey 8 is the cache/queue backend for the Python services. The Go
+ # services use a separate `kvrocks` service (defined below) so the Python
+ # path is left unchanged by the Valkey -> apache/kvrocks migration.
image: valkey/valkey:8
command: ["redis-server", "--requirepass", "${REDIS_PASSWORD}", "--maxmemory", "128mb", "--maxmemory-policy", "volatile-lru"]
env_file: .env
@@ -284,6 +286,42 @@ services:
timeout: 10s
retries: 120
+ kvrocks:
+ # Apache Kvrocks: a RocksDB-backed, Redis-protocol-compatible store used
+ # ONLY by the Go services (ragflow-cpu / ragflow-gpu), which override
+ # REDIS_HOST=kvrocks in docker-compose-go.yml. The Python services keep
+ # using the `redis` (Valkey) service above, so this is a dual-backend setup.
+ # Pinned to 2.16.0+ on purpose (see docker/kvrocks-entrypoint.sh): older
+ # tags such as kvrocks/kvrocks:latest (== 2.0.6) carry a TTL contract bug
+ # that breaks the RunTracker CAS lease, and they reject the Redis-style
+ # maxmemory/maxmemory-policy settings.
+ image: apache/kvrocks:2.16.0
+ # Kvrocks' config file does not expand ${ENV} and its CLI rejects
+ # `--requirepass` as a flag, so the entrypoint renders the config (including
+ # the password from REDIS_PASSWORD) at startup. `user: "0"` lets it write the
+ # config and the RocksDB data dir regardless of the mounted volume ownership.
+ entrypoint: ["/bin/sh", "/etc/kvrocks/entrypoint.sh"]
+ user: "0:0"
+ env_file: .env
+ # No host port publish: the Go services reach Kvrocks over the internal
+ # docker network at `kvrocks:6379`. Gated to the Go stack profile so the
+ # Python-only stack does not spin up an unused container.
+ profiles:
+ - ragflow-go
+ volumes:
+ - kvrocks_data:/var/lib/kvrocks
+ - ./kvrocks-entrypoint.sh:/etc/kvrocks/entrypoint.sh:ro
+ networks:
+ - ragflow
+ restart: unless-stopped
+ healthcheck:
+ # The Kvrocks image ships redis-cli and requirepass is enforced, so ping
+ # with the password. (The image has no nc, so a raw-tcp probe is wrong.)
+ test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
+ interval: 10s
+ timeout: 10s
+ retries: 120
+
jaeger:
profiles:
- jaeger
@@ -426,6 +464,8 @@ volumes:
driver: local
redis_data:
driver: local
+ kvrocks_data:
+ driver: local
tei_data:
driver: local
kibana_data:
diff --git a/docker/docker-compose-go.yml b/docker/docker-compose-go.yml
index aa8915c847..4ad60768c5 100644
--- a/docker/docker-compose-go.yml
+++ b/docker/docker-compose-go.yml
@@ -69,6 +69,10 @@ services:
- ./service_conf.yaml.template:/ragflow/conf/service_conf.yaml.template
- ./entrypoint-go.sh:/ragflow/entrypoint.sh
env_file: .env-go
+ # Route the Go services' cache/queue backend to the separate Kvrocks service
+ # (overriding REDIS_HOST=redis from .env-go). The Python services keep Valkey.
+ environment:
+ - REDIS_HOST=kvrocks
networks:
- ragflow
restart: unless-stopped
@@ -125,6 +129,10 @@ services:
- ./service_conf.yaml.template:/ragflow/conf/service_conf.yaml.template
- ./entrypoint.sh:/ragflow/entrypoint.sh
env_file: .env-go
+ # Route the Go services' cache/queue backend to the separate Kvrocks service
+ # (overriding REDIS_HOST=redis from .env-go). The Python services keep Valkey.
+ environment:
+ - REDIS_HOST=kvrocks
networks:
- ragflow
restart: unless-stopped
diff --git a/docker/kvrocks-entrypoint.sh b/docker/kvrocks-entrypoint.sh
new file mode 100755
index 0000000000..56353d4526
--- /dev/null
+++ b/docker/kvrocks-entrypoint.sh
@@ -0,0 +1,38 @@
+#!/bin/sh
+# Kvrocks entrypoint for the RAGFlow cache service.
+#
+# Kvrocks 2.16.0 does NOT support ${ENV} expansion inside its config file and
+# rejects `--requirepass` as a CLI flag (gflags intercepts the config key before
+# Kvrocks' own handler runs). To preserve the password-based auth from the
+# previous Valkey deployment without committing the secret, we render the config
+# from the REDIS_PASSWORD environment variable (injected via the compose
+# env_file) at container start.
+#
+# This service is configured with `user: "0"` so the entrypoint can write the
+# generated config and the RocksDB data directory regardless of the mounted
+# volume's ownership; kvrocks then runs as root. (The upstream image normally
+# drops to an unprivileged user via its own entrypoint, which we override here.)
+#
+# Config keys verified against apache/kvrocks:2.16.0:
+# bind, port, dir, requirepass
+# Intentionally omitted (invalid in kvrocks 2.16.0): maxmemory, maxmemory-policy.
+set -eu
+
+# REDIS_PASSWORD is mandatory: the previous Valkey deployment always required it,
+# and an unauthenticated cache/queue backend is a security exposure. Refuse to
+# start rather than silently run open.
+: "${REDIS_PASSWORD:?REDIS_PASSWORD must be set (inject via compose env_file or -e)}"
+
+# KVROCKS_DIR overrides the RocksDB data/config dir (defaults to the compose
+# mount point). Test harnesses use it to redirect writes to a temp dir.
+KVROCKS_DIR="${KVROCKS_DIR:-/var/lib/kvrocks}"
+mkdir -p "$KVROCKS_DIR"
+
+{
+ echo "bind 0.0.0.0"
+ echo "port 6379"
+ echo "dir $KVROCKS_DIR"
+ printf 'requirepass %s\n' "$REDIS_PASSWORD"
+} > "$KVROCKS_DIR/kvrocks.conf"
+
+exec kvrocks -c "$KVROCKS_DIR/kvrocks.conf" --dir "$KVROCKS_DIR"
diff --git a/helm/values.yaml b/helm/values.yaml
index e5b5dec0f6..353a8f25b6 100644
--- a/helm/values.yaml
+++ b/helm/values.yaml
@@ -222,6 +222,12 @@ mysql:
service:
type: ClusterIP
+# NOTE: The docker-compose deployment migrated from Valkey 8 to
+# apache/kvrocks:2.16.0 (see docker/kvrocks-entrypoint.sh). This Helm/Kubernetes
+# path is intentionally LEFT on Valkey: the template invokes `redis-server`
+# directly with Valkey-specific flags (helm/templates/redis.yaml), which Kvrocks
+# rejects. A Kvrocks-on-K8s migration is a separate workstream and must rewrite
+# the redis template, not just swap this image.
redis:
enabled: true
image:
diff --git a/internal/agent/canvas/kvrocks_runtracker_parity_test.go b/internal/agent/canvas/kvrocks_runtracker_parity_test.go
new file mode 100644
index 0000000000..89fe4d68b8
--- /dev/null
+++ b/internal/agent/canvas/kvrocks_runtracker_parity_test.go
@@ -0,0 +1,225 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+//go:build integration
+
+// Package canvas holds the RunTracker CAS regression guard for the
+// Valkey→Kvrocks migration. RunTracker relies on four inline Lua scripts that
+// use HGET/HSET/DEL/EXISTS/SET(PX)/PEXPIRE to implement a distributed
+// active-run lease. These scripts must behave identically on Kvrocks 2.16.0,
+// otherwise the agent runtime could lose its single-owner guarantee or fail to
+// cancel/stale-clean runs. This file drives the real RunTracker against a live
+// apache/kvrocks:2.16.0 and asserts the lease semantics.
+//
+// Run (KV_ADDR/KV_PASSWORD mirror the redis parity test):
+//
+// KV_ADDR=localhost:6379 KV_PASSWORD=<pw> bash build.sh --test-integration ./internal/agent/canvas/...
+package canvas
+
+import (
+ "os"
+ "testing"
+ "time"
+
+ "github.com/redis/go-redis/v9"
+)
+
+func newKVRunTracker(t *testing.T) (*RunTracker, *redis.Client) {
+ t.Helper()
+ addr := os.Getenv("KV_ADDR")
+ if addr == "" {
+ if os.Getenv("CI") != "" {
+ t.Fatal("KV_ADDR not set: RunTracker Kvrocks parity tests require a live apache/kvrocks:2.16.0 in CI")
+ }
+ t.Skip("KV_ADDR not set; skipping RunTracker Kvrocks parity test")
+ }
+ client := redis.NewClient(&redis.Options{
+ Addr: addr,
+ Password: os.Getenv("KV_PASSWORD"),
+ })
+ t.Cleanup(func() { _ = client.Close() })
+ if err := client.Ping(t.Context()).Err(); err != nil {
+ t.Fatalf("kvrocks ping %s: %v", addr, err)
+ }
+ return NewRunTrackerWithClient(client, 30*time.Second), client
+}
+
+// TestRunTrackerKvrocksCAS walks every RunTracker Lua script against Kvrocks
+// and asserts the single-owner lease contract holds.
+func TestRunTrackerKvrocksCAS(t *testing.T) {
+ rt, client := newKVRunTracker(t)
+ ctx := t.Context()
+ const (
+ userID = "u1"
+ canvasID = "c1"
+ runA = "run-a"
+ runB = "run-b"
+ tokenA = "tok-a"
+ tokenB = "tok-b"
+ wrongTok = "tok-z"
+ sessionID = "kvp-session-1"
+ )
+
+ cleanup := func() {
+ client.Del(ctx, activeSessionKey(sessionID), cancelKey(sessionID))
+ }
+ t.Cleanup(cleanup)
+
+ t.Run("RegisterExclusivity", func(t *testing.T) {
+ cleanup()
+ ok, err := rt.RegisterActiveSession(ctx, ActiveSession{
+ SessionID: sessionID, Token: tokenA, UserID: userID, CanvasID: canvasID, RunID: runA,
+ })
+ if err != nil {
+ t.Fatalf("register A: %v", err)
+ }
+ if !ok {
+ t.Fatal("register A returned false, want true (first owner)")
+ }
+ got, err := rt.GetActiveSession(ctx, sessionID)
+ if err != nil {
+ t.Fatalf("get A: %v", err)
+ }
+ if got == nil || got.RunID != runA || got.Token != tokenA {
+ t.Fatalf("get A = %+v, want RunID=run-a Token=tok-a", got)
+ }
+ // A second, different owner must be rejected while A holds the lease.
+ ok, err = rt.RegisterActiveSession(ctx, ActiveSession{
+ SessionID: sessionID, Token: tokenB, UserID: userID, CanvasID: canvasID, RunID: runB,
+ })
+ if err != nil {
+ t.Fatalf("register B: %v", err)
+ }
+ if ok {
+ t.Fatal("register B returned true, want false (lease already owned by A)")
+ }
+ got, _ = rt.GetActiveSession(ctx, sessionID)
+ if got.RunID != runA {
+ t.Fatalf("after rejected B, active RunID = %s, want run-a", got.RunID)
+ }
+ })
+
+ t.Run("ReleaseWrongTokenKeepsLease", func(t *testing.T) {
+ cleanup()
+ if ok, _ := rt.RegisterActiveSession(ctx, ActiveSession{
+ SessionID: sessionID, Token: tokenA, UserID: userID, CanvasID: canvasID, RunID: runA,
+ }); !ok {
+ t.Fatal("register A failed")
+ }
+ ok, err := rt.ReleaseActiveSession(ctx, sessionID, wrongTok)
+ if err != nil {
+ t.Fatalf("release wrong: %v", err)
+ }
+ if ok {
+ t.Fatal("release with wrong token succeeded, want false")
+ }
+ if got, _ := rt.GetActiveSession(ctx, sessionID); got == nil {
+ t.Fatal("lease lost after wrong-token release, want retained")
+ }
+ })
+
+ t.Run("ReleaseThenReRegister", func(t *testing.T) {
+ cleanup()
+ if ok, _ := rt.RegisterActiveSession(ctx, ActiveSession{
+ SessionID: sessionID, Token: tokenA, UserID: userID, CanvasID: canvasID, RunID: runA,
+ }); !ok {
+ t.Fatal("register A failed")
+ }
+ ok, err := rt.ReleaseActiveSession(ctx, sessionID, tokenA)
+ if err != nil {
+ t.Fatalf("release A: %v", err)
+ }
+ if !ok {
+ t.Fatal("release A returned false, want true")
+ }
+ // After release, a new owner may take over.
+ ok, err = rt.RegisterActiveSession(ctx, ActiveSession{
+ SessionID: sessionID, Token: tokenB, UserID: userID, CanvasID: canvasID, RunID: runB,
+ })
+ if err != nil {
+ t.Fatalf("register B after release: %v", err)
+ }
+ if !ok {
+ t.Fatal("register B after release returned false, want true")
+ }
+ got, _ := rt.GetActiveSession(ctx, sessionID)
+ if got.RunID != runB || got.Token != tokenB {
+ t.Fatalf("after re-register, active = %+v, want RunID=run-b Token=tok-b", got)
+ }
+ })
+
+ t.Run("RefreshLease", func(t *testing.T) {
+ cleanup()
+ if ok, _ := rt.RegisterActiveSession(ctx, ActiveSession{
+ SessionID: sessionID, Token: tokenA, UserID: userID, CanvasID: canvasID, RunID: runA,
+ }); !ok {
+ t.Fatal("register A failed")
+ }
+ ok, err := rt.RefreshActiveSession(ctx, sessionID, tokenA)
+ if err != nil {
+ t.Fatalf("refresh A: %v", err)
+ }
+ if !ok {
+ t.Fatal("refresh with correct token returned false, want true")
+ }
+ ok, err = rt.RefreshActiveSession(ctx, sessionID, wrongTok)
+ if err != nil {
+ t.Fatalf("refresh wrong: %v", err)
+ }
+ if ok {
+ t.Fatal("refresh with wrong token returned true, want false")
+ }
+ })
+
+ t.Run("CancelMarker", func(t *testing.T) {
+ cleanup()
+ if ok, _ := rt.RegisterActiveSession(ctx, ActiveSession{
+ SessionID: sessionID, Token: tokenA, UserID: userID, CanvasID: canvasID, RunID: runA,
+ }); !ok {
+ t.Fatal("register A failed")
+ }
+ // Wrong token must not publish a cancel marker.
+ ok, err := rt.RequestCancelActiveSession(ctx, sessionID, wrongTok)
+ if err != nil {
+ t.Fatalf("cancel wrong: %v", err)
+ }
+ if ok {
+ t.Fatal("cancel with wrong token returned true, want false")
+ }
+ if n, _ := client.Exists(ctx, cancelKey(sessionID)).Result(); n != 0 {
+ t.Fatal("cancel marker set by wrong token, want absent")
+ }
+ // Correct token publishes a PX-scoped cancel marker.
+ ok, err = rt.RequestCancelActiveSession(ctx, sessionID, tokenA)
+ if err != nil {
+ t.Fatalf("cancel A: %v", err)
+ }
+ if !ok {
+ t.Fatal("cancel with correct token returned false, want true")
+ }
+ if n, _ := client.Exists(ctx, cancelKey(sessionID)).Result(); n != 1 {
+ t.Fatal("cancel marker not present after correct cancel")
+ }
+ ttl, err := client.TTL(ctx, cancelKey(sessionID)).Result()
+ if err != nil {
+ t.Fatalf("cancel marker TTL: %v", err)
+ }
+ // RequestCancelTTL is 24h; the marker must carry a positive expiry.
+ if ttl <= 0 {
+ t.Fatalf("cancel marker TTL = %v, want > 0", ttl)
+ }
+ })
+}
diff --git a/internal/engine/redis/kvrocks_config_test.go b/internal/engine/redis/kvrocks_config_test.go
new file mode 100644
index 0000000000..278c68bfd5
--- /dev/null
+++ b/internal/engine/redis/kvrocks_config_test.go
@@ -0,0 +1,84 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+// Package redis holds deployment-config regression guards for the
+// Valkey->Kvrocks migration. These are plain unit tests (no external service):
+// they assert that the deployment artifacts (CI workflow, compose file) encode
+// the required fixes so a future edit cannot silently regress the migration.
+package redis
+
+import (
+ "os"
+ "path/filepath"
+ "runtime"
+ "strings"
+ "testing"
+)
+
+// repoRoot walks up from this source file to the module root (go.mod).
+func repoRoot(t *testing.T) string {
+ t.Helper()
+ _, file, _, ok := runtime.Caller(0)
+ if !ok {
+ t.Fatal("runtime.Caller failed")
+ }
+ dir := filepath.Dir(file)
+ for {
+ if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
+ return dir
+ }
+ parent := filepath.Dir(dir)
+ if parent == dir {
+ t.Fatal("repo root (go.mod) not found")
+ }
+ dir = parent
+ }
+}
+
+func readFile(t *testing.T, path string) string {
+ t.Helper()
+ b, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read %s: %v", path, err)
+ }
+ return string(b)
+}
+
+// TestKvrocksDeploymentConfig guards the deployment artifacts that the parity
+// integration tests cannot reach on their own: the CI workflow must forward the
+// password into the container, and the compose healthcheck must authenticate
+// now that requirepass is enforced.
+func TestKvrocksDeploymentConfig(t *testing.T) {
+ root := repoRoot(t)
+
+ t.Run("WorkflowForwardsRedisPassword", func(t *testing.T) {
+ wf := readFile(t, filepath.Join(root, ".github/workflows/kvrocks-parity.yml"))
+ if !strings.Contains(wf, "-e REDIS_PASSWORD") {
+ t.Fatal("kvrocks-parity.yml: the docker run must forward REDIS_PASSWORD into the container (-e REDIS_PASSWORD); without it Kvrocks starts unauthenticated and the parity tests fail to AUTH")
+ }
+ })
+
+ t.Run("ComposeHealthcheckAuthenticates", func(t *testing.T) {
+ compose := readFile(t, filepath.Join(root, "docker/docker-compose-base.yml"))
+ // requirepass is enforced, so the healthcheck must authenticate. The
+ // Kvrocks image ships redis-cli (but not nc), so the probe is
+ // `redis-cli -a ${REDIS_PASSWORD} ping`. A bare PING would be rejected
+ // and mark the service permanently unhealthy.
+ if !strings.Contains(compose, "redis-cli") || !strings.Contains(compose, "${REDIS_PASSWORD}") {
+ t.Fatal("docker-compose redis healthcheck must use `redis-cli -a ${REDIS_PASSWORD} ping` (the Kvrocks image has no nc); a bare PING fails now that requirepass is enforced")
+ }
+ })
+}
diff --git a/internal/engine/redis/kvrocks_deploy_test.go b/internal/engine/redis/kvrocks_deploy_test.go
new file mode 100644
index 0000000000..8fc22224c2
--- /dev/null
+++ b/internal/engine/redis/kvrocks_deploy_test.go
@@ -0,0 +1,110 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+//go:build integration
+
+package redis
+
+import (
+ "os"
+ "os/exec"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/redis/go-redis/v9"
+)
+
+// TestKvrocksEntrypointRequiresPassword drives the real entrypoint script with a
+// stub `kvrocks` on PATH so we can assert its pre-exec behavior without a real
+// Kvrocks binary. It guards Improvement 1: the entrypoint must refuse to start
+// without REDIS_PASSWORD (the previous Valkey deployment always required it) and
+// must render requirepass from it.
+func TestKvrocksEntrypointRequiresPassword(t *testing.T) {
+ root := repoRoot(t)
+ ep := filepath.Join(root, "docker/kvrocks-entrypoint.sh")
+ if _, err := os.Stat(ep); err != nil {
+ t.Fatalf("entrypoint not found: %v", err)
+ }
+
+ // runEntrypoint executes the entrypoint with a stub `kvrocks` on PATH and a
+ // temp KVROCKS_DIR, injecting (or omitting) REDIS_PASSWORD.
+ runEntrypoint := func(t *testing.T, password string) error {
+ t.Helper()
+ dir := t.TempDir()
+ stub := filepath.Join(dir, "kvrocks")
+ if err := os.WriteFile(stub, []byte("#!/bin/sh\n"), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ cmd := exec.Command("sh", ep)
+ env := []string{
+ "PATH=" + dir + ":" + os.Getenv("PATH"),
+ "KVROCKS_DIR=" + dir,
+ "HOME=" + dir,
+ }
+ if password != "" {
+ env = append(env, "REDIS_PASSWORD="+password)
+ }
+ cmd.Env = env
+ return cmd.Run()
+ }
+
+ t.Run("MissingPasswordFails", func(t *testing.T) {
+ if err := runEntrypoint(t, ""); err == nil {
+ t.Fatal("entrypoint should fail (non-zero) when REDIS_PASSWORD is unset")
+ }
+ })
+
+ t.Run("RendersRequirepass", func(t *testing.T) {
+ dir := t.TempDir()
+ stub := filepath.Join(dir, "kvrocks")
+ if err := os.WriteFile(stub, []byte("#!/bin/sh\n"), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ cmd := exec.Command("sh", ep)
+ cmd.Env = []string{
+ "PATH=" + dir + ":" + os.Getenv("PATH"),
+ "KVROCKS_DIR=" + dir,
+ "HOME=" + dir,
+ "REDIS_PASSWORD=ci-test-pass",
+ }
+ if err := cmd.Run(); err != nil {
+ t.Fatalf("entrypoint failed with password set: %v", err)
+ }
+ conf, err := os.ReadFile(filepath.Join(dir, "kvrocks.conf"))
+ if err != nil {
+ t.Fatalf("read conf: %v", err)
+ }
+ if !strings.Contains(string(conf), "requirepass ci-test-pass") {
+ t.Fatalf("conf missing requirepass: %q", string(conf))
+ }
+ })
+}
+
+// TestKvrocksRequirepassEnforced asserts that the live Kvrocks enforces
+// requirepass: a client without a password cannot PING. This is the runtime
+// contract that Blocker A (workflow must forward -e REDIS_PASSWORD) and
+// Improvement 1 (entrypoint requires the password) both produce.
+func TestKvrocksRequirepassEnforced(t *testing.T) {
+ _ = newKVClient(t) // ensures a live, password-protected Kvrocks
+ ctx := t.Context()
+ addr := os.Getenv("KV_ADDR")
+ noAuth := redis.NewClient(&redis.Options{Addr: addr})
+ defer func() { _ = noAuth.Close() }()
+ if err := noAuth.Ping(ctx).Err(); err == nil {
+ t.Fatal("PING without password succeeded; requirepass not enforced")
+ }
+}
diff --git a/internal/engine/redis/kvrocks_parity_test.go b/internal/engine/redis/kvrocks_parity_test.go
new file mode 100644
index 0000000000..ee640698c6
--- /dev/null
+++ b/internal/engine/redis/kvrocks_parity_test.go
@@ -0,0 +1,371 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+//go:build integration
+
+// Package redis holds the regression guard for the Valkey→Kvrocks migration.
+// These tests drive the real application Client (internal/engine/redis) against
+// a live apache/kvrocks:2.16.0 instance and assert that every command family
+// the codebase relies on behaves compatibly with Redis/Valkey. They are the
+// "no regression" guard: if a future Kvrocks bump or config change breaks any
+// contract the app depends on, these tests turn red.
+//
+// Run (mirrors the deployment: the entrypoint renders the config, including the
+// password from REDIS_PASSWORD, at startup):
+//
+// docker run -d -p 6379:6379 \
+// -v $(pwd)/docker/kvrocks-entrypoint.sh:/etc/kvrocks/entrypoint.sh:ro \
+// -e REDIS_PASSWORD=<pw> --user 0:0 --entrypoint /bin/sh \
+// apache/kvrocks:2.16.0 -c "/etc/kvrocks/entrypoint.sh"
+// KV_ADDR=localhost:6379 KV_PASSWORD=<pw> bash build.sh --test-integration ./internal/engine/redis/...
+//
+// Without KV_ADDR the test skips locally for convenience, but fails hard (CI=true)
+// so a misconfigured CI job never turns green without a live Kvrocks.
+package redis
+
+import (
+ "os"
+ "testing"
+ "time"
+
+ "github.com/google/uuid"
+ "github.com/redis/go-redis/v9"
+)
+
+// newKVClient wires a Client against a live Kvrocks.
+//
+// Guard policy: the parity tests are a regression fence, so a missing backend
+// must be loud, not silent. KV_ADDR unset in CI (CI=true) is a misconfigured
+// job and fails hard; unset outside CI simply skips (local convenience). A set
+// but unreachable KV_ADDR always fails (the Ping below), so a CI run that forgot
+// to start Kvrocks can never pass green.
+func newKVClient(t *testing.T) *Client {
+ t.Helper()
+ addr := os.Getenv("KV_ADDR")
+ if addr == "" {
+ if os.Getenv("CI") != "" {
+ t.Fatal("KV_ADDR not set: Kvrocks parity tests require a live apache/kvrocks:2.16.0 in CI")
+ }
+ t.Skip("KV_ADDR not set; skipping Kvrocks parity test (needs apache/kvrocks:2.16.0)")
+ }
+ c := &Client{
+ client: redis.NewClient(&redis.Options{
+ Addr: addr,
+ Password: os.Getenv("KV_PASSWORD"),
+ }),
+ luaDeleteIfEqual: redis.NewScript(luaDeleteIfEqualScript),
+ luaTokenBucket: redis.NewScript(luaTokenBucketScript),
+ }
+ t.Cleanup(func() { _ = c.client.Close() })
+ if err := c.client.Ping(t.Context()).Err(); err != nil {
+ t.Fatalf("kvrocks ping %s: %v", addr, err)
+ }
+ return c
+}
+
+// TestKvrocksParity exercises the full command surface the application uses.
+// It is one test with subtests so a single backend connection is reused.
+func TestKvrocksParity(t *testing.T) {
+ c := newKVClient(t)
+ ctx := t.Context()
+ // One-shot unique prefix: Kvrocks data persists across test processes, so
+ // a fresh prefix each run prevents cross-run key collisions.
+ prefix := "kvp:" + uuid.NewString() + ":"
+
+ t.Run("String", func(t *testing.T) {
+ k := prefix + "str"
+ if !c.Set(ctx, k, "v1", time.Minute) {
+ t.Fatal("Set failed")
+ }
+ if v, _ := c.Get(ctx, k); v != "v1" {
+ t.Fatalf("Get = %q, want v1", v)
+ }
+ if ok, _ := c.Exist(ctx, k); !ok {
+ t.Fatal("Exist = false, want true")
+ }
+ // SetNX must not overwrite an existing key.
+ if c.SetNX(ctx, k, "v2", time.Minute) {
+ t.Fatal("SetNX overwrote existing key")
+ }
+ if v, _ := c.Get(ctx, k); v != "v1" {
+ t.Fatalf("SetNX side effect: Get = %q, want v1", v)
+ }
+ if n, _ := c.IncrBy(ctx, k+"-c", 5); n != 5 {
+ t.Fatalf("IncrBy = %d, want 5", n)
+ }
+ if n, _ := c.IncrBy(ctx, k+"-c", 3); n != 8 {
+ t.Fatalf("IncrBy = %d, want 8", n)
+ }
+ if n, _ := c.DecrBy(ctx, k+"-c", 2); n != 6 {
+ t.Fatalf("DecrBy = %d, want 6", n)
+ }
+ if !c.Expire(ctx, k, 10*time.Second) {
+ t.Fatal("Expire failed")
+ }
+ if tt := c.TTL(ctx, k); tt <= 0 || tt > 10*time.Second {
+ t.Fatalf("TTL = %v, want (0,10s]", tt)
+ }
+ if !c.Delete(ctx, k) {
+ t.Fatal("Delete failed")
+ }
+ if ok, _ := c.Exist(ctx, k); ok {
+ t.Fatal("Exist = true after Delete, want false")
+ }
+ })
+
+ t.Run("Hash", func(t *testing.T) {
+ k := prefix + "hash"
+ c.client.Del(ctx, k)
+ if err := c.client.HSet(ctx, k, map[string]any{
+ "a": "1", "b": "2",
+ }).Err(); err != nil {
+ t.Fatalf("HSet: %v", err)
+ }
+ got, err := c.client.HGetAll(ctx, k).Result()
+ if err != nil {
+ t.Fatalf("HGetAll: %v", err)
+ }
+ if got["a"] != "1" || got["b"] != "2" {
+ t.Fatalf("HGetAll = %v, want a=1 b=2", got)
+ }
+ // TokenBucket Lua exercises HMGET/HMSET/EXPIRE inside Kvrocks.
+ tb := &TokenBucket{client: c, key: k + "-tb", capacity: 2, rate: 0.1}
+ if ok, _ := tb.Allow(ctx, 1); !ok {
+ t.Fatal("TokenBucket first call denied, want allowed")
+ }
+ if ok, _ := tb.Allow(ctx, 1); !ok {
+ t.Fatal("TokenBucket second call denied, want allowed")
+ }
+ if ok, _ := tb.Allow(ctx, 1); ok {
+ t.Fatal("TokenBucket third call allowed, want denied (bucket exhausted)")
+ }
+ })
+
+ t.Run("Set", func(t *testing.T) {
+ k := prefix + "set"
+ c.client.Del(ctx, k)
+ if !c.SAdd(ctx, k, "m1") {
+ t.Fatal("SAdd m1 failed")
+ }
+ if !c.SAdd(ctx, k, "m2") {
+ t.Fatal("SAdd m2 failed")
+ }
+ if !c.SIsMember(ctx, k, "m1") {
+ t.Fatal("SIsMember m1 = false, want true")
+ }
+ if c.SIsMember(ctx, k, "mX") {
+ t.Fatal("SIsMember mX = true, want false")
+ }
+ members, err := c.SMembers(ctx, k)
+ if err != nil {
+ t.Fatalf("SMembers: %v", err)
+ }
+ if len(members) != 2 {
+ t.Fatalf("SMembers len = %d, want 2", len(members))
+ }
+ if !c.SRem(ctx, k, "m1") {
+ t.Fatal("SRem m1 failed")
+ }
+ if c.SIsMember(ctx, k, "m1") {
+ t.Fatal("SIsMember m1 = true after SRem, want false")
+ }
+ })
+
+ t.Run("ZSet", func(t *testing.T) {
+ k := prefix + "zset"
+ c.client.Del(ctx, k)
+ if !c.ZAdd(ctx, k, "a", 1) {
+ t.Fatal("ZAdd a failed")
+ }
+ if !c.ZAdd(ctx, k, "b", 5) {
+ t.Fatal("ZAdd b failed")
+ }
+ if !c.ZAdd(ctx, k, "c", 10) {
+ t.Fatal("ZAdd c failed")
+ }
+ if n := c.ZCount(ctx, k, 0, 6); n != 2 {
+ t.Fatalf("ZCount(0,6) = %d, want 2", n)
+ }
+ got, err := c.ZRangeByScore(ctx, k, 0, 6)
+ if err != nil {
+ t.Fatalf("ZRangeByScore: %v", err)
+ }
+ if len(got) != 2 || got[0] != "a" || got[1] != "b" {
+ t.Fatalf("ZRangeByScore = %v, want [a b]", got)
+ }
+ popped, err := c.ZPopMin(ctx, k, 1)
+ if err != nil {
+ t.Fatalf("ZPopMin: %v", err)
+ }
+ if len(popped) != 1 || popped[0].Member.(string) != "a" {
+ t.Fatalf("ZPopMin = %v, want [a]", popped)
+ }
+ // After ZPopMin removed "a"(score 1), remaining b(5) and c(10).
+ // Removing the [0,6] range must drop only "b" -> 1 removed.
+ if n := c.ZRemRangeByScore(ctx, k, 0, 6); n != 1 {
+ t.Fatalf("ZRemRangeByScore(0,6) = %d, want 1", n)
+ }
+ })
+
+ t.Run("Stream", func(t *testing.T) {
+ q := prefix + "stream"
+ c.client.Del(ctx, q)
+ if !c.QueueProduct(ctx, q, map[string]string{"hello": "world"}) {
+ t.Fatal("QueueProduct failed")
+ }
+ // Consumer group creation is implicit in QueueConsumer.
+ msg, err := c.QueueConsumer(ctx, q, "grp", "cons", "")
+ if err != nil {
+ t.Fatalf("QueueConsumer: %v", err)
+ }
+ if msg == nil {
+ t.Fatal("QueueConsumer returned nil message")
+ }
+ // QueueProduct stored {"hello":"world"} under the stream "message"
+ // field; GetMessage() returns the JSON-decoded payload map.
+ if got := msg.GetMessage()["hello"]; got != "world" {
+ t.Fatalf("consumed payload hello = %v, want world", got)
+ }
+ if !msg.Ack(ctx) {
+ t.Fatal("Ack failed")
+ }
+ pending, err := c.GetPendingMsg(ctx, q, "grp")
+ if err != nil {
+ t.Fatalf("GetPendingMsg: %v", err)
+ }
+ if len(pending) != 0 {
+ t.Fatalf("GetPendingMsg len = %d, want 0 (acked)", len(pending))
+ }
+ // XRange round-trips the stored entry (RequeueMsg path).
+ ranged, err := c.client.XRange(ctx, q, "-", "+").Result()
+ if err != nil {
+ t.Fatalf("XRange: %v", err)
+ }
+ if len(ranged) == 0 {
+ t.Fatal("XRange returned no entries")
+ }
+ })
+
+ t.Run("LuaDeleteIfEqual", func(t *testing.T) {
+ k := prefix + "die"
+ c.client.Del(ctx, k)
+ if !c.Set(ctx, k, "expect", time.Minute) {
+ t.Fatal("Set failed")
+ }
+ // Wrong expected value must not delete.
+ if c.DeleteIfEqual(ctx, k, "wrong") {
+ t.Fatal("DeleteIfEqual deleted on wrong value")
+ }
+ if ok, _ := c.Exist(ctx, k); !ok {
+ t.Fatal("key gone after wrong DeleteIfEqual")
+ }
+ // Correct expected value deletes.
+ if !c.DeleteIfEqual(ctx, k, "expect") {
+ t.Fatal("DeleteIfEqual failed on correct value")
+ }
+ if ok, _ := c.Exist(ctx, k); ok {
+ t.Fatal("key still present after correct DeleteIfEqual")
+ }
+ })
+
+ t.Run("TokenBucketStrict", func(t *testing.T) {
+ // EvalTokenBucketStrict is the fail-closed counterpart used by the webhook
+ // rate limiter (agent_webhook_security.go). It shares the TokenBucket Lua
+ // but must surface its result/errors to the caller rather than silently
+ // passing traffic. Verify the allow/deny sequence on Kvrocks.
+ k := prefix + "tbs"
+ c.client.Del(ctx, k)
+ ok, err := c.EvalTokenBucketStrict(ctx, k, 2, 0.1)
+ if err != nil {
+ t.Fatalf("call 1: %v", err)
+ }
+ if !ok {
+ t.Fatal("call 1: expected allowed")
+ }
+ if ok, err = c.EvalTokenBucketStrict(ctx, k, 2, 0.1); err != nil || !ok {
+ t.Fatalf("call 2: ok=%v err=%v, want allowed", ok, err)
+ }
+ ok, err = c.EvalTokenBucketStrict(ctx, k, 2, 0.1)
+ if err != nil {
+ t.Fatalf("call 3: %v", err)
+ }
+ if ok {
+ t.Fatal("call 3: expected denied (bucket exhausted), got allowed")
+ }
+ })
+
+ t.Run("PipelineSetNX", func(t *testing.T) {
+ k := prefix + "pipe"
+ c.client.Del(ctx, k)
+ if !c.Transaction(ctx, k, "v", time.Minute) {
+ t.Fatal("Transaction (pipeline SetNX) failed")
+ }
+ // Second call hits an existing key: SetNX inside the pipeline does not
+ // overwrite, so the value must remain "v" (Transaction returns on
+ // Exec success, not SetNX success — assert the value, not the bool).
+ c.Transaction(ctx, k, "v2", time.Minute)
+ if v, _ := c.Get(ctx, k); v != "v" {
+ t.Fatalf("pipeline SetNX overwrote existing key: Get = %q, want v", v)
+ }
+ })
+
+ t.Run("TTLContract", func(t *testing.T) {
+ // Kvrocks >= 2.11 reads metadata.Expired() on the read path, so a key
+ // whose TTL elapsed must report EXISTS=0 immediately (no 2-3s
+ // compaction lag). This is the exact bug that 2.0.6 had and that
+ // motivated pinning apache/kvrocks:2.16.0. Guard it.
+ k := prefix + "ttl"
+ c.client.Del(ctx, k)
+ if !c.Set(ctx, k, "x", 1200*time.Millisecond) {
+ t.Fatal("Set with TTL failed")
+ }
+ if ok, _ := c.Exist(ctx, k); !ok {
+ t.Fatal("key should exist before TTL elapses")
+ }
+ time.Sleep(1500 * time.Millisecond)
+ if ok, _ := c.Exist(ctx, k); ok {
+ t.Fatal("EXISTS=1 long after TTL elapsed: Kvrocks read-path expiry broken (regression of 2.0.6 bug)")
+ }
+ if tt := c.TTL(ctx, k); tt != -2 {
+ t.Fatalf("TTL = %v, want -2 (key gone)", tt)
+ }
+ })
+
+ t.Run("Auth", func(t *testing.T) {
+ // The live client authenticated at connect time. A second client with
+ // a wrong password must fail to PING (NOAUTH), proving requirepass is
+ // enforced — important because Kvrocks rejects multi-user ACLs.
+ pw := os.Getenv("KV_PASSWORD")
+ if pw == "" {
+ t.Skip("KV_PASSWORD empty; auth-enforcement check skipped")
+ }
+ bad := redis.NewClient(&redis.Options{Addr: os.Getenv("KV_ADDR"), Password: "definitely-wrong"})
+ defer func() { _ = bad.Close() }()
+ if err := bad.Ping(ctx).Err(); err == nil {
+ t.Fatal("PING with wrong password succeeded; requirepass not enforced")
+ }
+ })
+
+ t.Run("Info", func(t *testing.T) {
+ // Info must not panic on Kvrocks' differently-shaped INFO output.
+ info := c.Info(ctx)
+ if info == nil {
+ t.Fatal("Info returned nil")
+ }
+ // server_mode is empty on Kvrocks (field name differs) — that is
+ // acceptable and only affects monitoring, not functionality.
+ })
+}