命名 · XB 现场笔记

Redis 的键名要起得清楚

Tue, 01 Jun 2027 00:00:00 +0000

Redis 键是平面键空间中的二进制安全名称，不是文件路径，也不是数据库表结构声明。冒号可以按约定分隔业务归属、环境、实体和标识，例如 cart:prod:string:42 能表达意图。但 Redis 不会把这些字段解释成类型检查或访问限制，不能仅凭名字就推断服务端已经替应用建立了约束。

让约定没有歧义

写入方、读取方、维护任务和迁移逻辑，应采用相同字段顺序与标识编码。不同前缀可以让两个服务分别存储同一个业务编号；若最后编码出来的完整名字相同，仍然会碰撞。命名规范帮助人和代码协作，并没有创建由 Redis 独立管理的命名空间。

类型标签也只是说明。SET 可以在名字带 hash 的键下写入字符串，之后 HSET 就会报 WRONGTYPE。排查时应用 TYPE 查看真实数据类型，序列化格式与类型要求则属于应用契约。不能把名字中的“列表”“哈希”当作当前数据已经符合预期的证据。

名字宜简短清晰，不必压缩成难懂缩写，也不要把整段文档塞进去。键名占内存并随命令传输，但对象开销和负载本身同样重要；没有测量就不能宣称一次改名显著加快查询。标识编码还应避免分隔符、通配符和集群花括号取得本来不希望赋予的含义。

模式匹配不等于模式删除

SCAN MATCH 接受 glob 模式。从游标零开始，把每次返回的新游标用于下一次调用，直到再次返回零。COUNT 是工作量提示，不保证精确返回多少条，也不是严格内存上限。某一页可能没有匹配项，但游标还不为零，不能据此提前结束。每次调用仍需要服务端工作，增量扫描不等于完全没有阻塞成本。

完整迭代保证能看到在迭代全过程始终存在、且符合模式的键，但可能重复返回；迭代中新增或删除的键没有同样保证。应用应按需要去重，或让处理逻辑可以安全重复。扫描不是快照，更不能把一个空页面当作集合已经遍历完毕。

DEL 的语义不同：它接收精确键名，不接收模式。参数末尾带星号，不会删除所有同前缀兄弟键；只有真的存在名字包含这个星号的键，才会删除那一个。命令行工具之外还有 shell 展开这一层，应正确引用参数，不要把终端的展开行为误认为 Redis 自己支持通配删除。

坏掉的样子

维护脚本若假定 DEL 会展开前缀，可能实际什么也没删，却报告清理完成。相反，先用宽泛模式收集 SCAN 结果，再无条件删除每个匹配，也可能误伤不属于自己的数据。必须核对精确目标与修改策略；而且发现与删除之间，同名键可能已经被重建，之前审阅过的名字不一定还指向同一个逻辑对象。

前缀也不是安全边界。访问限制应通过合适的 ACL 键模式和命令权限落实，必要时使用独立部署边界。键模式权限无法约束不携带键参数、直接作用于整个数据库的命令，所以给账户一个前缀模式不等于万事安全。服务名前缀也不会自动预留内存，更不构成淘汰策略隔离。

Redis Cluster 的哈希标签是命名约定之外一个会影响路由的明确机制。有效花括号标签决定槽计算所使用的字节；即便两个服务前缀不同，只要标签相同也能落在同一槽。这可以服务于有关联的多键操作，但若给所有键套上同一个固定标签，就可能把负载集中起来，而不是均匀分散。

快速验证

原有实验记录使用 macOS、Python 3.14.4、Redis 8.10.1 和 redis-py 8.1.0；本轮审阅没有重新执行服务实验，下面的结果说明保留原有观察范围。准备 POSIX 环境、C 编译器、make、curl、tar 与 Python 3.10 或更新版本。安装步骤仅用 libc 构建 Redis 核心，并把客户端装入临时虚拟环境。

redis_lab=$(mktemp -d)
curl --fail --location --output "$redis_lab/redis.tar.gz" https://download.redis.io/releases/redis-8.10.1.tar.gz
tar -xzf "$redis_lab/redis.tar.gz" -C "$redis_lab"
make -C "$redis_lab/redis-8.10.1" build redis -j2 MALLOC=libc
export REDIS_SERVER="$redis_lab/redis-8.10.1/src/redis-server"
python3 -m venv "$redis_lab/venv"
"$redis_lab/venv/bin/python" -m pip install redis==8.1.0

在同一终端用 "$redis_lab/venv/bin/python" 运行下方代码。它在 /tmp 启动只用私有 Unix 套接字的 Redis，关闭 TCP 和持久化，结束时仅停止自己的进程并清理运行目录。下载需要联网，实验不会连接已有 Redis 实例。

from contextlib import contextmanager
import os
from pathlib import Path
import subprocess
from tempfile import TemporaryDirectory
import time

import redis
from redis.backoff import NoBackoff
from redis.retry import Retry


@contextmanager
def instance():
 with TemporaryDirectory(prefix="redis-lab-", dir="/tmp") as directory:
 endpoint = str(Path(directory) / "redis.sock")
 process = subprocess.Popen([
 os.environ["REDIS_SERVER"], "--port", "0",
 "--unixsocket", endpoint, "--unixsocketperm", "700",
 "--save", "", "--appendonly", "no", "--dir", directory,
 "--maxmemory-policy", "noeviction",
 ], stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
 client = redis.Redis(unix_socket_path=endpoint, decode_responses=False,
 socket_timeout=2, retry=Retry(NoBackoff(), 0))
 try:
 deadline = time.monotonic() + 5
 while True:
 assert process.poll() is None, "Redis exited during startup"
 try:
 if client.ping():
 break
 except redis.ConnectionError:
 if time.monotonic() >= deadline:
 raise
 time.sleep(0.02)
 yield client
 finally:
 client.close()
 if process.poll() is None:
 process.terminate()
 try:
 _, errors = process.communicate(timeout=5)
 except subprocess.TimeoutExpired:
 process.kill()
 process.communicate()
 raise
 assert process.returncode == 0, errors.decode()


with instance() as client:
 client.set("cart:prod:string:42", "cart-value")
 client.set("billing:prod:string:42", "billing-value")
 assert client.get("cart:prod:string:42") == b"cart-value"
 assert client.get("billing:prod:string:42") == b"billing-value"
 client.set("cart:prod:hash:42", "not-a-hash")
 assert client.type("cart:prod:hash:42") == b"string"
 try:
 client.hset("cart:prod:hash:42", "item", "value")
 except redis.ResponseError as error:
 assert "WRONGTYPE" in str(error)
 else:
 raise AssertionError("a type label unexpectedly enforced a schema")
 print("namespaces separate exact names; a hash label does not create a hash value")

 prefix = "cart:prod:string:"
 expected = {f"{prefix}{number}".encode() for number in range(24)}
 for key in expected:
 client.set(key, "value")
 expected.add(b"cart:prod:string:42")
 cursor, found, pages = 0, set(), 0
 while True:
 cursor, keys = client.scan(cursor=cursor, match=prefix + "*", count=3)
 assert all(key.startswith(prefix.encode()) for key in keys)
 found.update(keys)
 pages += 1
 assert pages < 1000, "unexpected nontermination in this bounded test"
 if cursor == 0:
 break
 assert found == expected
 print("SCAN reaches cursor zero and finds the stable fixture, with duplicates deduplicated")

 assert client.delete(prefix + "*") == 0
 assert all(client.exists(key) for key in expected)
 client.set(prefix + "*", "literal-star")
 assert client.delete(prefix + "*") == 1
 assert all(client.exists(key) for key in expected)
 print("DEL treats the asterisk literally; it does not expand a key pattern")

 from redis.crc import key_slot

 assert key_slot(b"cart:{customer-42}:items") == key_slot(b"billing:{customer-42}:total")
 assert key_slot(b"cart:{customer-42}:items") == key_slot(b"customer-42")
 print("matching hash tags select the same slot across different service prefixes")

第一组在 cart 与 billing 前缀下分别写值，再故意向名字标注 hash 的键写入字符串。TYPE 返回 string，HSET 失败，证明可读标签不会强制建立类型。它们只是不同的完整键名，不是具有目录继承关系的路径。

稳定测试数据包含二十五个匹配的字符串键。扫描循环持续到游标归零，用集合消化可能的重复，也接受页大小变化。测试中的次数上限只是捕获这份小型固定数据上的异常不终止，不是生产通用扫描上限，也没有验证并发增删时的集合完整性。

第一次删除“前缀加字面星号”返回零，二十五个键都还在。创建完全等于那个名称的键后，再删就返回一，其它兄弟键仍保留。实验没有实施通配清理，也没有删除任何共享数据。

最后使用固定版本客户端的 key_slot 计算，确认两个不同前缀、都带 customer-42 标签的键会算出同一个槽。这是在客户端进行的计算，不是实际搭建 Redis Cluster 的路由验收。四条摘要均有断言支撑，但不验证 ACL 强制执行、并发删除安全、集群路由或内存节省。

来源

Redis 键与值，二进制安全键名及命名约定，已核验 2026-09-08。
Redis SCAN，游标保证、重复结果与 COUNT 提示，已核验 2026-09-08。
Redis DEL，精确键参数删除，已核验 2026-09-08。
Redis TYPE，检查真实值类型，已核验 2026-09-08。
Redis ACL 文档，键模式与独立的命令权限，已核验 2026-09-08。
Redis Cluster 规范，哈希标签与槽分布，已核验 2026-09-08。
redis-py 8.1.0 键槽计算，实验使用的客户端哈希算法，已核验 2026-09-08。
Redis 8.10.1 构建说明，仅编译核心及选择分配器，已核验 2026-09-08。

有用的主机名应区分本地身份、服务名称与查询范围

Tue, 01 Dec 2026 00:00:00 +0000

有用的名称为人和软件提供一个可以跨地址变化继续使用的引用，但这个引用需要明确范围与负责人。机器的本地主机名、服务 DNS 名称和实例标识可以有意不同。清楚命名有助于理解日志和部署，而不是假定一个标签自动建立系统中的所有其他身份。规划名称时，应先说明它标识的是哪类对象，以及希望保持稳定多久。

坏掉的样子

设置本地主机名，本身不会向权威区域发布 A 或 AAAA。注册可能由独立部署或网络管理软件完成，但那条流程必须实际存在。反过来，修改 DNS 地址也不会重命名内核的本地主机名。混淆两者，会产生本地标签看似正确、客户端却无法发现服务的机器。排障时应分别检查本地状态、注册动作和权威数据，不能用其中一个代替其他证据。

短名称依赖查询上下文。即使两台机器都使用正常 DNS 配置，service 在不同搜索域下仍可能指向不同目的地。复制的运行手册命令因此可能到达与作者测试不同的环境。配置中不能容忍歧义时，应使用完整目标 DNS 名称；交互操作使用短名时，也应保留解释它所需的上下文。名称看起来一样，并不意味着它在所有进程里具有相同范围。

人类可读的含义也有限制。app-prod-01 可以提示角色、环境与实例，却不是权限、归属或当前工作负载的权威证据。复用旧实例名称还可能混淆历史日志。服务名称与替换机器的生命周期不同时，应分别命名，并使用运维元数据记录变化事实，不要试图把所有信息都塞进主机名。方便阅读的前缀也不能成为授予访问权限的依据。

快速验证

将脚本保存为 check-hostnames.py，准备 Docker 后执行 python3 check-hostnames.py。固定环境使用 BIND 9.18.49、dnsmasq 2.90 和 Python 3.11，解析器及 NSS 配置都位于可丢弃容器中。本实验关闭转发缓存，使搜索域和地址变化可以直接观察，不必等待上一代缓存寿命；这项设置用于隔离变量，不代表所有生产客户端都应关闭缓存：

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid
recipe='FROM python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84\nRUN apt-get update && apt-get install -y --no-install-recommends bind9=1:9.18.49-1~deb12u2 bind9-dnsutils=1:9.18.49-1~deb12u2 dnsmasq-base=2.90-4~deb12u2 python3-dnspython=2.3.0-1 && rm -rf /var/lib/apt/lists/*\nCMD ["/usr/bin/python3"]\n'
program=r"""
from contextlib import ExitStack,contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import json,re,signal,subprocess,time
import dns.exception,dns.message,dns.query,dns.rcode,dns.rdatatype

def run(*args,check=True):
 result=subprocess.run(args,capture_output=True,text=True,timeout=15)
 if check:assert result.returncode==0,(args,result.returncode,result.stdout,result.stderr)
 return result
def query(name,kind='A',port=1053):
 return dns.query.udp(dns.message.make_query(name,kind),'127.0.0.1',port=port,timeout=1)
def values(response,kind='A'):
 wanted=dns.rdatatype.from_text(kind)
 return [item.to_text() for rrset in response.answer if rrset.rdtype==wanted for item in rrset]
def show(response):
 def section(records):return [{'name':str(rr.name),'type':dns.rdatatype.to_text(rr.rdtype),'ttl':rr.ttl,'data':[item.to_text() for item in rr]} for rr in records]
 return {'rcode':dns.rcode.to_text(response.rcode()),'answer':section(response.answer),'authority':section(response.authority)}
def wait(predicate,timeout=15):
 deadline=time.monotonic()+timeout
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except (OSError,dns.exception.Timeout):pass
 time.sleep(.05)
 raise AssertionError('DNS fixture condition did not become true')
def stop(process):
 if process.poll() is None:
 process.terminate()
 try:process.wait(timeout=5)
 except subprocess.TimeoutExpired:process.kill();process.wait(timeout=5)

@contextmanager
def lab(records,soa_ttl=8,minimum=4,extra=''):
 with TemporaryDirectory(prefix='xbcatm-dns-') as directory,ExitStack() as stack:
 root=Path(directory);zone=root/'zone';conf=root/'named.conf';log=root/'named.log';serial=1
 def save(body):
 zone.write_text(f'$ORIGIN lab.test.\n$TTL 30\n@ {soa_ttl} IN SOA ns.lab.test. hostmaster.lab.test. ({serial} 60 60 3600 {minimum})\n@ IN NS ns.lab.test.\nns IN A 127.0.0.1\n'+body+'\n')
 run('named-checkzone','lab.test',str(zone))
 save(records)
 conf.write_text(f'''options {{ directory "{root}"; listen-on port 1053 {{127.0.0.1;}}; listen-on-v6 {{none;}};
recursion no; dnssec-validation no; notify no; querylog yes; max-cache-size 8m; pid-file "{root}/named.pid"; session-keyfile none;
{extra} }};
controls {{}};
zone "lab.test" {{ type primary; file "{zone}"; }};
''')
 run('named-checkconf',str(conf))
 output=stack.enter_context(log.open('w'))
 authority=subprocess.Popen(['named','-g','-c',str(conf),'-n','1','-U','1'],stdout=output,stderr=subprocess.STDOUT)
 stack.callback(stop,authority)
 def ready():
 assert authority.poll() is None,log.read_text()
 response=query('lab.test.','SOA');return response.rcode()==0 and response.answer[0][0].serial==serial
 wait(ready)
 def update(body):
 nonlocal serial
 serial+=1;save(body);authority.send_signal(signal.SIGHUP);wait(ready)
 def cache(port=1054,upstream=1053,size=150,options=()):
 logfile=root/('cache-'+str(port)+'.log');stream=stack.enter_context(logfile.open('w'))
 command=['dnsmasq','--no-daemon','--conf-file=/dev/null','--no-resolv','--no-hosts','--bind-interfaces',
 '--listen-address=127.0.0.1','--port='+str(port),'--server=127.0.0.1#'+str(upstream),
 '--cache-size='+str(size),'--log-queries','--log-facility=-',*options]
 process=subprocess.Popen(command,stdout=stream,stderr=subprocess.STDOUT);stack.callback(stop,process)
 def cache_ready():
 assert process.poll() is None,logfile.read_text()
 return query('lab.test.','SOA',port).rcode()==0
 wait(cache_ready);return process,logfile
 def queries(name,kind='A'):
 return sum(bool(re.search(r'query: '+re.escape(name.rstrip('.'))+r' IN '+kind+r'\b',line)) for line in log.read_text().splitlines())
 yield root,update,cache,queries
import socket
records='service 30 IN A 127.0.0.2\nservice.branch 30 IN A 127.0.0.3\n_echo._tcp 30 IN SRV 0 0 8080 service.lab.test.'
with lab(records) as (root,update,cache,queries):
 cache(port=53,size=0)
 nss=Path('/etc/nsswitch.conf');nss.write_text(re.sub(r'^hosts:.*$','hosts: dns',nss.read_text(),flags=re.M))
 def search(domain):Path('/etc/resolv.conf').write_text('nameserver 127.0.0.1\nsearch '+domain+'\noptions timeout:1 attempts:1\n')
 def address(name):
 return json.loads(run('/usr/bin/python3','-c','import socket,json,sys;print(json.dumps(sorted({r[4][0] for r in socket.getaddrinfo(sys.argv[1],80,socket.AF_INET,socket.SOCK_STREAM)})))',name).stdout)
 local_name=socket.gethostname();unpublished=query(local_name+'.lab.test.');assert unpublished.rcode()==dns.rcode.NXDOMAIN
 lower=query('service.lab.test.');mixed=query('SeRvIcE.LaB.TeSt.');assert values(lower)==values(mixed)==['127.0.0.2']
 search('lab.test');first=address('service');absolute_first=address('service.lab.test.');assert first==absolute_first==['127.0.0.2']
 search('branch.lab.test');second=address('service');absolute_second=address('service.lab.test.');assert second==['127.0.0.3'] and absolute_second==first
 update(records.replace('service 30 IN A 127.0.0.2','service 30 IN A 127.0.0.4'));changed=address('service.lab.test.')
 assert changed==['127.0.0.4'] and socket.gethostname()==local_name
 invalid=root/'invalid.zone';invalid.write_text((root/'zone').read_text()+'bad_name IN A 127.0.0.1\n')
 check=run('named-checkzone','-k','fail','lab.test',str(invalid),check=False)
 assert check.returncode!=0 and 'bad owner name' in check.stdout+check.stderr
 assert values(query('_echo._tcp.lab.test.','SRV'),'SRV')==['0 0 8080 service.lab.test.']
 print(json.dumps({'local_hostname_published_in_zone':False,'case_insensitive_A':values(mixed),
 'short_name_by_search_domain':{'lab.test':first,'branch.lab.test':second},'absolute_name_unchanged_by_search':[absolute_first,absolute_second],
 'DNS_address_after_change':changed,'local_hostname_unchanged':True,'invalid_host_owner_rejected':check.returncode,'underscore_SRV_owner_accepted':True},sort_keys=True))
"""
name='xbcatm-dns-'+uuid.uuid4().hex[:10]
def docker(*args,**kwargs):return subprocess.run(['docker',*args],capture_output=True,text=True,timeout=300,**kwargs)
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'Dockerfile').write_text(recipe)
 built=docker('build','-t',name,str(root));assert built.returncode==0,built.stderr
 result=docker('run','--rm','-i','--name',name,'--network','none','--memory','384m','--pids-limit','128',name,
 '/usr/bin/python3','-',input=program)
 assert result.returncode==0,result.stderr
 print(json.dumps(json.loads(result.stdout),sort_keys=True))
finally:
 docker('rm','-f',name);docker('image','rm',name)

脚本读取容器本地主机名，再查询该标签位于 lab.test 下的名称。由于没有发布相应区域记录，权威返回 NXDOMAIN。这说明当前环境缺少这项注册，不是在断言所有安装都不会自动注册主机名。对 service.lab.test 分别使用全小写与混合大小写查询，都返回 127.0.0.2，展示 DNS 中 ASCII 名称比较不区分大小写。

搜索域为 lab.test 时，新应用进程查询 service 得到 127.0.0.2；改为 branch.lab.test 后，同一短输入得到 127.0.0.3。而绝对名称 service.lab.test. 在两个上下文中都返回 127.0.0.2。末尾根点明确标记这个实验中的绝对 DNS 名称，使结果不依赖搜索列表补全。这个对照解释了短命令为何可能随运行环境改变目标。

随后权威把 service.lab.test 改到 127.0.0.4，新查询看到新地址，本地主机名却保持原样。这验证 DNS 映射与机器标签独立。它不证明已有连接自动移动，也不证明其他缓存立即刷新；那些行为有各自寿命，被有意排除在此次关闭缓存的比较之外。稳定名称的价值，是让调用方保留引用，而不是取消所有迁移与状态管理工作。

最后，A 记录候选所有者 bad_name 在 named-checkzone -k fail 下被判为不合格主机名称；有效的 _echo._tcp SRV 所有者仍被接受并可查询。这区分了严格主机地址名称检查与更广泛的 DNS 命名空间。服务标签使用下划线，不表示普通主机名适用同样规则，也不表示每个 DNS 标签都必须按主机标签验证。

按对象寿命与使用者选择名称

采用有文档、可预测的约定，提供足够信息区分环境和实例，同时避免在公开名称中放入敏感或频繁变化的细节。替换稳定服务名背后的机器时，应有意识地更新发现数据与服务配置，保留所需地址重叠期。稳定拼写便于调用方继续引用，但 TLS、路由和应用状态仍需提前准备。名称设计应支持这些操作，而不是掩盖它们的存在。

资产清单和故障证据中，应并列记录完整域名与本地主机名。显示时可以保留大小写，但不要把仅 ASCII 大小写不同的 DNS 名称当成两个服务。关联数据集时，也应按标识符实际规则规范化；任意应用标识或 URL 路径可能具有与 DNS 主机名不同的大小写语义。不能因为某一层比较不敏感，就对整条字符串执行同样转换。

部署前，依据消费这些名称的系统规则检查生成结果。DNS 标签、证书身份、操作系统主机名与服务发现标签彼此相关，却不是可互换的验证范围。内核接受一个名称，不等于它适合作普通互联网主机名。让人的理解和技术范围都保持明确，名称才能在日常操作、替换实例和复盘历史时持续提供帮助，而不成为另一种隐含假设。

来源

RFC 1123 Internet host requirements，主机名推荐语法与命名要求，已核验 2026-09-12。
RFC 4343 DNS case insensitivity，DNS 中 ASCII 名称不区分大小写的比较，已核验 2026-09-12。
Python 3.11 socket documentation，gethostname 与应用地址查询，已核验 2026-09-12。
RFC 2782：DNS SRV 记录，服务与协议标签有意使用下划线前缀，已核验 2026-10-15。

命名 · XB 现场笔记

Redis 的键名要起得清楚

让约定没有歧义

模式匹配不等于模式删除

坏掉的样子

快速验证

来源

延伸阅读

有用的主机名应区分本地身份、服务名称与查询范围

坏掉的样子

快速验证

按对象寿命与使用者选择名称

延伸阅读

来源