Redis CLIENT SETNAME标记连接方便监控与调试

在多服务共享同一个 Redis 实例的生产环境中，当服务器负载飙高或连接数暴涨时，面对 CLIENT LIST 命令输出的一大堆 IP 地址和端口，运维人员往往难以迅速定位具体的业务源头。Redis 提供的 CLIENT SETNAME 命令可以为每个连接打上易读的标签，从而将抽象的连接 ID 转化为具体的业务名称。下面通过具体步骤演示如何在命令行及代码中设置连接名称，并利用该功能进行快速排查。

1. 命令行快速设置与验证

这是最基础的操作方式，适用于临时的数据库运维或调试场景。

打开终端并连接到 Redis 服务器。

输入以下命令将当前连接命名为 ops_maintenance_session：

CLIENT SETNAME ops_maintenance_session

执行后，若无报错提示，通常表示设置成功。若需确认，输入查询命令：

CLIENT GETNAME

终端应返回字符串 ops_maintenance_session。若此时开启另一个终端窗口，使用 CLIENT LIST 命令查看所有连接，你会在原本枯燥的 IP 地址列表中找到带有 name=ops_maintenance_session 的条目。

2. 在 Python 应用中集成配置

对于 Python 开发者，通常使用 redis-py 库。在连接池或客户端初始化时设置名称是最可靠的方法。

打开 Python 项目中的配置文件（如 db_config.py 或 settings.py）。

创建 Redis 连接时，传入 client_name 参数。

import redis

# 创建连接池时指定名称
pool = redis.ConnectionPool(
    host='127.0.0.1', 
    port=6379, 
    db=0,
    client_name='user_service:payment_worker'  # 设置连接名称
)

r = redis.Redis(connection_pool=pool)

# 执行测试命令
r.ping()

保存文件并运行该脚本。

3. 在 Java (Spring Data / Jedis) 中设置名称

Java 环境下，根据使用的客户端不同，设置方式有所区别。以下以 Jedis 为例展示直接设置，以及 Spring Boot 中的配置方式。

使用 Jedis 原生 API

实例化 Jedis 对象后，立即调用 clientSetname 方法。

import redis.clients.jedis.Jedis;

public class RedisExample {
    public static void main(String[] args) {
        Jedis jedis = new Jedis("localhost", 6379);

        // 设置连接名称
        jedis.clientSetname("java:order_processor:instance_01");

        // 执行操作
        jedis.set("key", "value");
        jedis.close();
    }
}

使用 Spring Boot (自动配置)

编辑 application.properties 或 application.yml 配置文件。

添加或修改以下配置项：

# application.properties
spring.redis.client-name=inventory_service:sync_job

重启 Spring Boot 应用，应用连接到 Redis 后会自动携带该名称。

4. 在 Node.js (NodeRedis / ioredis) 中设置名称

Node.js 生态中常用的客户端是 ioredis 或 redis。以 ioredis 为例：

创建 redis_client.js 文件。

编写如下代码，在实例化时通过 options 传入名称：

const Redis = require('ioredis');

// 创建连接并指定名称
const redis = new Redis({
    host: '127.0.0.1',
    port: 6379,
    // 设置连接名称
    clientName: 'nodejs:api_gateway:worker_1'
});

redis.on('connect', () => {
    console.log('Connected to Redis with name set.');
});

运行脚本：node redis_client.js。

5. 利用名称进行监控与故障排查

当所有服务都设置了连接名称后，排查问题的效率将显著提升。

登录到 Redis 服务器。

执行 CLIENT LIST 命令。由于输出内容通常很长，建议使用 grep 进行过滤（假设怀疑是订单服务的问题）：

redis-cli CLIENT LIST | grep order_service

输出结果会包含该服务的所有连接信息。注意观察 name、addr（客户端 IP）、idle（空闲秒数）和 cmd（最后执行的命令）字段。

分析输出结果。若发现某台特定机器的连接 idle 时间极长但未释放，或者 name 为空（表示代码未配置），即可精准定位到具体的代码模块或服务器进行优化。

若发现某连接正在执行 KEYS * 这种危险命令导致服务器卡顿，且必须立即切断，可以执行 CLIENT KILL 命令。

通过 CLIENT LIST 找到该连接的 ID（例如 id=342），然后输入：

CLIENT KILL ID 342

或者直接根据名称模糊匹配杀掉连接（Redis 2.8.12+）：

CLIENT KILL SKIPME yes order_service

6. 制定合理的命名规范

为了防止名称混乱，需要制定统一的命名规则。建议采用“业务线：服务名：实例标识”的三段式结构。

遵循以下格式：

业务域:子模块:实例ID/功能

• 业务域：如 payment, user, inventory。
• 子模块：如 api, worker, scheduler。
• 实例标识：如 host_01, pid_1234。

反例：my_conn, test, redis_client。这些名称无法提供有效的上下文信息。

正例：payment:api_worker:server_01。

7. 进阶：使用 Lua 脚本批量统计连接数

当需要统计每个业务服务占用的连接数时，可以编写并执行以下 Lua 脚本，无需使用外部工具处理文本。

输入以下命令：

redis-cli --eval count_clients_by_name.lua

其中 count_clients_by_name.lua 的内容如下：

local clients = redis.call('CLIENT', 'LIST')
local counts = {}

for line in string.gmatch(clients, '[^\r\n]+') do
    local name = string.match(line, 'name=([^ ]+)')
    if name then
        counts[name] = (counts[name] or 0) + 1
    else
        counts['unnamed'] = (counts['unnamed'] or 0) + 1
    end
end

return counts

查看返回结果，你将得到一个类似 {'user_service:api': 10, 'order_service:worker': 5} 的统计列表，直观展示各服务的连接资源占用情况。