自托管基础设施
本地 Redis 管理
启动、连接和排查 PureChatNext 缓存与次级存储使用的 Redis。
PureChatNext 可使用 Redis 保存 Better Auth 次级存储、微信渠道上下文和其他缓存数据。本地 Redis 通过 Docker Compose 手动启停，不随 pnpm dev 自动启动；在 Windows / macOS / Linux 上用法相同。
前置条件
- 已安装并启动 Docker Desktop（或兼容的 Docker Engine + Compose V2）
- 若尚未准备 compose 环境变量，先执行：
pnpm docker:setup:dev当前约定
- 镜像：
redis:8.8.1-alpine3.23（固定多架构 digest） - Compose 文件：
docker-compose/dev/docker-compose.yml - 容器名：由 Compose project 自动生成（不要依赖固定容器名）
- 连接地址：
redis://127.0.0.1:6379 - 持久化：RDB（
--save 60 1000）+ AOF - 认证：无密码（仅本地开发，端口只绑定
127.0.0.1） - 数据：Docker named volume
redis_data - 内存：默认
384mb，淘汰策略noeviction（可在 Compose.env调整）
环境变量
在 .env.local 中启用应用侧 Redis：
REDIS_URL=redis://127.0.0.1:6379
REDIS_DATABASE=0
REDIS_TLS=0
REDIS_PREFIX=purechat
DISABLE_REDIS=0本地实例不设置用户名、密码或 TLS，不应暴露到局域网或公网。
启停和状态检测
pnpm dev:docker # 启动 PostgreSQL + Redis + RustFS + SearXNG
pnpm dev:docker:down # 停止（保留数据卷）
pnpm dev:docker:reset # 清空卷后重建并 db:migrate单独查看 Redis：
docker compose -f docker-compose/dev/docker-compose.yml ps redis
docker compose -f docker-compose/dev/docker-compose.yml logs --tail=100 redis应用连接检查
docker compose -f docker-compose/dev/docker-compose.yml exec redis redis-cli PING
# PONG
pnpm exec tsx scripts/redis-seed.ts常见故障
端口被占用
# macOS / Linux
lsof -nP -iTCP:6379 -sTCP:LISTEN
# Windows PowerShell
Get-NetTCPConnection -LocalPort 6379 -ErrorAction SilentlyContinueRedis 启动失败
docker compose -f docker-compose/dev/docker-compose.yml logs --tail=100 redis