# redis-auth-proxy

**Repository Path**: slcnx/redis-auth-proxy

## Basic Information

- **Project Name**: redis-auth-proxy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Redis Auth Proxy

![Deployment Architecture](docs/images/deployment_architecture.png)

一个兼容 Redis 5.0 的认证代理，支持按连接追踪 AUTH 状态，并强制执行代理端的“只读”指令过滤。

## 核心特性

- **状态化认证追踪**：代理会拦截 `AUTH` 指令，仅在后端 Redis 返回 `+OK` 后才将当前 TCP 会话标记为已认证。
- **只读指令强制过滤**：认证通过后，代理仅允许执行白名单内的安全查询指令（如 `GET`, `SCAN`, `INFO` 等），从协议层封杀写操作。
- **高性能异步处理**：基于 Rust 开发，确保极低的转发延迟。

## 工作流程

代理的处理流程遵循以下标准化步骤：

1. **连接建立**：客户端连接代理端口（默认 6380），代理同时与后端 Redis 建立同步 TCP 连接。
2. **指令拦截**：
    - 代理首先解析客户端发送的 RESP 协议。
    - 如果是 `AUTH` 指令，转发至后端并根据返回结果更新会话的 `is_authenticated` 状态。
3. **安全校验**：
    - 对于非认证会话，拒绝执行任何非 `AUTH` 指令。
    - 对于已认证会话，校验指令是否在**只读白名单**中。
4. **转发与回传**：
    - 符合安全策略的指令将被转发至后端 Redis。
    - 获取执行结果后，原样回传给客户端。
5. **违规拦截**：尝试执行写指令（如 `SET`, `DEL`）时，代理直接返回 `-ERR proxy-enforced read-only mode`，指令不会到达后端。

## 快速开始

### 本地运行

```powershell
cargo run -- --help
```

可以通过命令行参数或环境变量进行配置（命令行优先级更高）：

```powershell
# 使用命令行参数
cargo run -- --listen 127.0.0.1:6381 --redis 127.0.0.1:6379 --read-only=false

# 使用环境变量
$env:REDIS_AUTH_PROXY_LISTEN = "127.0.0.1:6381"
$env:REDIS_AUTH_PROXY_READ_ONLY = "false"
cargo run
```

### 客户端连接

通过代理进行连接：

```powershell
redis-cli -h 127.0.0.1 -p 6380 -a redis-auth-proxy-pass --no-auth-warning ping
```

预期输出：

```text
PONG
```

### 只读校验测试

```powershell
redis-cli -h 127.0.0.1 -p 6380 -a redis-auth-proxy-pass --no-auth-warning set key value
```

预期输出：

```text
ERR proxy-enforced read-only mode
```

## Redis 5.0 测试环境

1. 复制环境文件示例并设置测试密码：
   ```powershell
   Copy-Item .env.example .env
   ```

2. 启动 Redis 5.0 容器：
   ```powershell
   docker compose up -d redis50
   ```

3. 验证直连 Redis 5.0：
   ```powershell
   redis-cli -h 127.0.0.1 -p 6379 -a redis-auth-proxy-pass --no-auth-warning ping
   ```

## 容器化构建

1. 构建代理镜像：
   ```powershell
   docker build -t redis-auth-proxy:local .
   ```

2. 联调运行：
   ```powershell
   docker compose up -d redis50 proxy
   ```

## 测试与性能压测

1. 运行自动化测试：
   ```powershell
   cargo test
   ```

2. 运行本地延迟对比测试：
   ```powershell
   .\scripts\benchmark.ps1 -Requests 10000 -Clients 50
   ```

详细的压测数据请参考 [docs/performance-report.md](docs/performance-report.md)。我们的性能目标是代理引入的平均延迟增量不超过 1ms。