文章 | XB 现场笔记

文章是本站的原创长文。每篇都保持无脚本、来源可溯，并与本站记录的系统现实一致：一个小型、静态、公网服务如何被构建、加固并保持诚实。

让已经验证的产物逐级进入环境

预发布测试说明的是当时实际运行的产物与环境。生产部署前重新构建，会得到另一份输出，需要检查它的身份，或者重新验证它的行为。产物晋级指把已验证的那份文件继续交给下一个环境，并记录这次决定。它减少了一类不确定性，但不会让预发布与生产环境自动等价，也不会免除部署之后的运行检查。交付字节一致，是发布判断的一部分，而不是全部。明确究竟把什么向前传递使用不可变的软件包标识或内容摘要定位构建结果。会移动的标签、分支名乃至源码提交，本身都不足以唯一证明部署了哪些字节。同一源码的两次构建，可能因为工具链、依赖解析、嵌入设置或打包步骤而不同。可复现的重建确实可能得到完全相同的字节，但应先比较结果，再把它视为之前通过测试的同一产物，而不是仅凭源码相同推断。应区分构建阶段与发布阶段。发布组合包含特定产物及该部署需要的配置，运行过程再把这个组合放到真实依赖和数据之上。记录产物身份与合适的配置版本，同时避免泄露秘密。如果前端环境设置在打包时直接编译进 JavaScript，修改设置就会改变字节，也就是生成了另一份需要验证的产物。不能一边修改包内内容，一边继续沿用原包通过测试的身份。坏掉的样子某些流水线名义上在晋级产物，部署脚本却悄悄重新编译；另一些流程下载了正确归档，却又覆盖归档内部的配置文件。这两种操作都改变了测试时的输入。应明确哪些设置位于不可变负载之外，并通过应用已有的配置接口读取。校验和如果发生在后续修改之前，就不能继续代表运行时文件；核验时点与文件变化顺序必须一起审查。即便产物相同，数据库结构、功能开关、依赖版本、权限、资源限制或网络路径变化，也能让行为不同。晋级保证的是字节连续性，不是整个执行上下文都一致。部署后仍要验证关键生产行为；预发布结果无法在生产重现时，要比较真正相关的环境差异，而不是看到摘要相同就认定问题与发布无关。配置也是发布组合的一部分，需要可追溯的变化记录。回滚同样有前提。旧程序可能无法理解新写入的数据，或者无法适应已经完成的破坏性结构迁移。把指针切回旧产物，并不会撤销这些外部影响。恢复说明应关联数据兼容性、配置和依赖状态；不能反向恢复时，就应准备必要的向前修复。不能把“重新选择旧镜像”描述成所有故障都适用的完整回滚方案。快速验证把代码保存为 promote.py，执行 python3 promote.py。示例只使用 Python 标准库、临时目录和绑定回环地址的 HTTP 服务。它写出一份很小的应用文件，记录摘要，再复制进两个本地环境。production-simulation 只是临时目录的标签，不会触发外部部署，也不会接触真实生产配置。这个命名用于让输出清楚地区分两个运行位置。 from hashlib import sha256 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from pathlib import Path from tempfile import TemporaryDirectory from threading import Thread from urllib.request import ProxyHandler, build_opener import json import runpy import shutil source = 'def render(config):\n return {"build": "local-build-41", "tier": config["tier"]}\n' digest = sha256(source.encode()).hexdigest() def verify(path): if sha256(path.read_bytes()).hexdigest() != digest: raise ValueError('artifact changed') def handler(path, config): verify(path) render = runpy.run_path(str(path))['render'] class Handler(BaseHTTPRequestHandler): def do_GET(self): data = path.read_bytes() if self.path == '/artifact' else json.dumps(render(config)).encode() self.send_response(200) self.send_header('Content-Length', str(len(data))) self.end_headers() self.wfile.write(data) def log_message(self, *args): pass return Handler with TemporaryDirectory() as directory: root = Path(directory) artifact = root / 'build.py' artifact.write_text(source) opener = build_opener(ProxyHandler({})) observed = [] for tier in ('staging-local', 'production-simulation'): destination = root / tier destination.mkdir() deployed = destination / 'app.py' shutil.copyfile(artifact, deployed) config = {'tier': tier} server = ThreadingHTTPServer(('127.0.0.1', 0), handler(deployed, config)) thread = Thread(target=server.serve_forever) thread.start() try: origin = f'http://127.0.0.1:{server.server_port}' with opener.open(origin + '/artifact', timeout=5) as response: received_digest = sha256(response.read()).hexdigest() with opener.open(origin + '/', timeout=5) as response: rendered = json.load(response) assert received_digest == digest assert rendered == {'build': 'local-build-41', 'tier': tier} observed.append({'artifact_sha256': received_digest, 'response': rendered, 'config_sha256': sha256(json.dumps(config, sort_keys=True).encode()).hexdigest()}) finally: server.shutdown() thread.join() server.server_close() deployed.write_text(source + '# rebuilt\n') try: verify(deployed) except ValueError: changed_rejected = True else: changed_rejected = False assert changed_rejected print(json.dumps({'environments': observed, 'changed_copy_rejected': changed_rejected})) 每个服务启动之前，脚本都核对复制文件是否符合原始摘要，再加载其中的应用函数。请求 /artifact 会返回部署文件的真实字节；请求 / 则用该环境单独提供的配置执行应用函数。两次 HTTP 下载得到相同的产物摘要，两份应用响应也都声明 local-build-41。这些结果结合文件复制与实际请求，建立了本地传递的证据。 ...

Here-string 提供文本并追加换行

Bash 的 here-string 会把一个词展开后的值送给命令的标准输入，并在末尾追加一个换行符。当变量里已经有少量文本，而目标程序从标准输入读取时，这种写法很方便。它省掉了额外的打印命令，但并不保证输入与变量逐字节相同，也不承诺内部一定使用内存、管道或文件。判断是否适用，应看接收方需要什么输入，而不是只比较命令行长度。接收命令读取之前先完成展开三个小于号之后的词可以包含变量展开、算术展开和命令替换，因此不一定是字面常量。单引号保留源码中的字面文本，双引号则允许通常的变量和命令展开。通过变量展开得到的字符串，即使包含美元符号和括号，也不会仅因出现在 here-string 中就被再次作为 shell 命令执行。源码中明确写出的替换语法与变量保存的数据必须区分。当前 Bash 不会对 here-string 的词执行分词或文件名展开，而是把结果作为一个字符串交付。这里引用变量仍能清楚表达意图，但不能把这种重定向上下文和普通命令参数位置混为一谈。后者使用未引用变量时仍可能按空白拆分，或把星号变成文件名。因此，某个值通过 here-string 正常到达，并不能证明在别处省略引号也安全。末尾追加换行是无条件发生的。原值没有换行时会多一个，原值已经有尾部换行时还会再多一个。空变量也因此产生包含一个换行字节的输入，而不是立即结束的零字节输入。对于按行处理的工具，这常常符合需求；对于严格长度、签名字节或特定结束字符的协议，则可能直接改变意义，不能把它当作原始字节透传方式。坏掉的样子 Shell 形成输入后，read 还会按自己的规则解释。默认分词可能移除首尾 IFS 空白，反斜杠也可能作为转义符处理。读取需要保留空格和反斜杠的一行时，应使用 IFS= read -r name。它保护的是这一行的内容；单次 read 仍然在第一个换行处结束，并不会自动把任意多行字符串全部装进变量。输入构造规则与消费者解析规则是两个阶段。带重定向的内建命令或循环可以在当前 shell 中运行，因此其中的赋值能够在后续代码中继续使用。相比把循环放进管道，这有助于避免 Bash 通常为管道阶段创建子 shell 导致的状态丢失。重定向本身不会包上一层子 shell，但如果表达式的其他地方明确使用子 shell 或命令替换，它们仍然具有通常的作用域与副作用，不能因为用了 here-string 就忽略。 ...

连接池用少量 Postgres 连接应付大量请求

连接池让许多应用请求在不同时间借用较少的 PostgreSQL 会话。复用能够摊薄建立连接的成本，也能限制同时借出的数量，但不会让已经过载的数据库自动变快。池本身又增加了一条队列，它的容量、等待时间和取消行为，都属于请求预算的一部分。应把这条队列作为服务行为来设计，而不是把它隐藏在一个“复用更快”的标签后面。坏掉的样子数据库后端处于 ClientRead，表示正在等待客户端发数据，并不表示应用请求正在等待借用连接。真正的池内等待者可能还没有数据库连接，因此服务器根本没有对应的后端可供观察。获取连接的等待应在池里测量，查询执行和锁等待应在服务器测量；把它们混成一个所谓数据库池等待事件，会掩盖实际瓶颈的位置。归还连接也不保证抹掉所有会话状态。Psycopg 的连接上下文在正常退出时提交，在异常离开上下文时回滚；额外重置取决于配置。已经提交的会话级设置，可以继续留给下一个借用者，即使没有泄漏未结束的事务。临时对象和其他会话资源同样需要明确策略，不能因为使用了连接池，就假定所有内容都会自动恢复到初始状态。快速验证准备 Python 3.10 或更新版本、PostgreSQL 18 可丢弃数据库，以及允许创建实验模式的角色。原演练使用以下依赖；本轮审阅没有重新执行并发数据库实验。安装方式为：python3 -m pip install "psycopg[binary]==3.3.5" "psycopg-pool==3.3.1"。使用已有认证配置，将 PG_DSN 设置为该测试数据库的连接串。把程序保存为 pool-demo.py，在安装依赖的同一个 Python 环境中运行： import os import time from concurrent.futures import ThreadPoolExecutor import psycopg from psycopg_pool import ConnectionPool, PoolTimeout, TooManyRequests dsn = os.environ['PG_DSN'] with psycopg.connect(dsn, autocommit=True) as admin: admin.execute('CREATE SCHEMA pool_demo') try: admin.execute('CREATE TABLE pool_demo.counter (n integer)') admin.execute('INSERT INTO pool_demo.counter VALUES (0)') with ConnectionPool( dsn, min_size=1, max_size=1, max_waiting=1, timeout=3, open=True, kwargs={'application_name': 'pool_example'}, ) as pool: pool.wait(timeout=3) def queued_request(): try: with pool.connection(timeout=1): raise AssertionError('holder should still own the only connection') except PoolTimeout: return 'PoolTimeout' with ThreadPoolExecutor(max_workers=1) as workers: with pool.connection() as held: original_pid = held.info.backend_pid waiting = workers.submit(queued_request) deadline = time.monotonic() + 0.5 while pool.get_stats()['requests_waiting'] != 1: if time.monotonic() >= deadline: raise TimeoutError('request did not enter the pool queue') time.sleep(0.005) state = admin.execute( 'SELECT state,wait_event_type,wait_event ' 'FROM pg_stat_activity WHERE pid=%s', (original_pid,) ).fetchone() assert state == ('idle', 'Client', 'ClientRead'), state print('waiting_in_pool', 1, 'server', state) try: with pool.connection(timeout=0.1): raise AssertionError('queue limit was not applied') except TooManyRequests: print('queue_limit', 'TooManyRequests') assert waiting.result(timeout=2) == 'PoolTimeout' print('queued_request', 'PoolTimeout') with pool.connection() as conn: assert conn.info.backend_pid == original_pid conn.execute("SET application_name='previous_borrower'") try: with pool.connection() as conn: conn.execute('UPDATE pool_demo.counter SET n=99') raise ValueError('simulated request failure') except ValueError as error: assert str(error) == 'simulated request failure' with pool.connection() as conn: value = conn.execute('SELECT n FROM pool_demo.counter').fetchone()[0] setting = conn.execute('SHOW application_name').fetchone()[0] assert value == 0 and setting == 'previous_borrower' assert conn.info.backend_pid == original_pid print('same_backend', True, 'rollback_value', value, 'retained_setting', setting) conn.execute('RESET application_name') finally: admin.execute('DROP SCHEMA pool_demo CASCADE') 池里只有一条连接，最多允许一个请求排队。主线程借走连接但不执行查询，工作线程尝试借用它。池报告一个等待者以后，独立观察连接看到被借走的数据库后端正空闲等待客户端读取事件。两种状态可以同时存在：应用已经排队，数据库会话却没有正在执行的查询。这正好说明为什么不能用服务器的空闲状态代替池的等待指标。 ...

语义化版本让兼容性承诺更明确

依赖版本有价值的前提，是发布者与使用者对公共契约有共同认识。语义化版本为变化提供一套表达：从 1.0.0 开始，不兼容的公共接口变化需要提升主版本，兼容的功能增加需要提升次版本，兼容的问题修复需要提升补丁版本。数字归纳的是发布者对这一版的判断，并不会自行检查实现，也不能保证应用升级之后必然正确运行。理解承诺边界，比只记住三个数字更有用。先声明兼容性覆盖哪些内容公共接口可以包括导出的函数、正式说明的命令参数、配置格式、响应字段和明确约定的错误行为。边界应写得足够清楚，才能判断一次变化是否违约。保持契约不变的内部重构，与删除已经承诺支持的参数，不属于同一类变化。修正原先违反文档契约的行为，可能仍是兼容的缺陷修复，即便有人曾经观察并依赖那个错误表现。仍需在变更说明中解释，并验证受影响的调用方。语义化版本规范要求：把公共功能标记为废弃时，应提升次版本；之后真正移除功能，则需要按不兼容变化处理。已经发布的某个版本，其内容不应继续变化，修正应通过另一个新版本交付。在相同版本标签背后替换文件，会破坏追溯：两个依赖声明完全相同的安装过程，可能得到不同的字节，排查问题时也无法再靠版本号明确区分。主版本为零表示初始开发阶段，公共接口不应被视为稳定。维护者可以为这一阶段声明额外约定，但使用者不能默认所有零主版本更新都兼容。预发布版本的优先级低于对应的正式版本；加号之后的构建元数据不参与优先级比较。因此，两个版本在排序意义上相等，不意味着它们的包内容、来源或文件摘要相同。兼容性、选择顺序与产物身份是不同问题。坏掉的样子标错的次版本即使满足依赖范围，也可能破坏已声明的契约。标号正确的发布，也可能暴露应用对内部实现细节的依赖。升级时仍应读变更说明，运行有代表性的集成验证；需要重复解析依赖时保留锁文件。锁文件记录当时选择了哪些版本，不能替这些版本证明行为正确，更不是来源真实性的证明。版本范围允许安装，只说明解析条件满足了。包管理器的范围语法又是另一层规则。语义化版本规范定义版本及优先级，具体工具决定约束怎样筛选候选。在 node-semver 中，插入符通常允许最左非零分量右侧的变化，所以 ^0.2.3 不接受 0.3.0，^0.0.3 也不接受 0.0.4。三个分量完整的波浪号范围，通常只允许同一次版本线内的补丁更新。不能把所有插入符都理解成“只要主版本不变就行”。预发布筛选还有附加规则。宽泛的稳定版本范围，不会自动接纳数值更高的测试版；明确允许某个预发布三元组后，才可能接纳该三元组后续的预发布版本。应验证实际解析器，而不是用普通字符串排序推断升级关系，也不要把数值更大直接等同于可被当前范围选择。不同生态的约束语法不能仅凭相似外观相互套用。快速验证本轮安装尝试在解析器断言执行之前以失败状态退出；这里没有把现有其他版本库的行为算成该固定版本示例的通过证据。将代码保存为 semver.py，在已有 Node 和 npm 的环境执行 python3 semver.py。实验需要访问公共 npm 仓库。脚本在临时目录安装 semver@7.7.2，隔离配置和缓存，关闭包安装脚本，再调用这个库真实的比较函数。它不会修改当前项目的依赖声明或锁文件；结束时临时安装目录随上下文清理。 from pathlib import Path from tempfile import TemporaryDirectory import json import os import subprocess with TemporaryDirectory() as directory: root = Path(directory) user_config = root / 'user.npmrc' global_config = root / 'global.npmrc' user_config.write_text('') global_config.write_text('') env = {'PATH': os.environ['PATH'], 'LC_ALL': 'C', 'NPM_CONFIG_USERCONFIG': str(user_config), 'NPM_CONFIG_GLOBALCONFIG': str(global_config), 'NPM_CONFIG_CACHE': str(root / 'cache')} subprocess.run(['npm', 'install', '--ignore-scripts', '--no-audit', '--no-fund', '--package-lock=false', '--registry=https://registry.npmjs.org', 'semver@7.7.2'], cwd=root, env=env, check=True, capture_output=True) script = r''' const s = require('semver'); const assert = require('node:assert/strict'); const cases = [ ['1.9.0', '^1.2.3', true], ['2.0.0', '^1.2.3', false], ['1.2.9', '~1.2.3', true], ['1.3.0', '~1.2.3', false], ['0.2.9', '^0.2.3', true], ['0.3.0', '^0.2.3', false], ['0.0.4', '^0.0.3', false], ['1.3.0-beta.1', '^1.2.3', false], ['1.3.0-beta.2', '^1.3.0-beta.1', true] ].map(([version, range, expected]) => { const accepted = s.satisfies(version, range); assert.equal(accepted, expected); return {version, range, accepted}; }); assert.equal(s.compare('1.2.3+build.1', '1.2.3+build.2'), 0); assert.equal(s.lt('1.3.0-beta.2', '1.3.0'), true); assert.equal(s.valid('1.02.3'), null); console.log(JSON.stringify({library: require('semver/package.json').version, cases, metadata_precedence_equal: true, prerelease_before_release: true, leading_zero_rejected: true})); ''' result = subprocess.run(['node', '-e', script], cwd=root, env=env, capture_output=True, text=True, check=True) print(json.dumps(json.loads(result.stdout))) 九个范围案例应当全部符合断言：^1.2.3 接受 1.9.0，拒绝 2.0.0；波浪号拒绝下一次版本；两个零主版本范围更加收敛。稳定范围拒绝 1.3.0-beta.1，明确指定预发布的范围则接受 1.3.0-beta.2。输出保留版本、范围与布尔结果，便于逐项看清究竟是哪条条件在起作用。 ...

Basic Auth 携带的是可重复使用的凭据

HTTP Basic 认证把编码后的用户名与密码放进 Authorization 请求头。由于编码可逆，取得该请求头的值，往往就相当于取得凭据本身。Basic 确实定义了认证挑战与响应流程，但不会用密码学方式把响应绑定到服务器刚生成的一次性随机数。只要服务器继续接受这个账号和凭据，一份曾被接受的值就可能被再次使用。不能把“存在挑战流程”误解成“重放一定失败”。看清真正发生的交换服务器可以返回四零一，并通过 WWW-Authenticate: Basic 挑战声明 realm，客户端再带 Authorization 重试。客户端也可以在合适的保护空间内提前发送凭据。因此，带认证的请求会携带凭据，不意味着每个最初请求一开始就必须有它。realm 用于标识保护空间，并不会自动授予同名路径上的所有权限，更不能替代具体的资源访问控制。编码输入由用户标识、一个冒号和密码拼接。第一个冒号是分隔符，所以用户名不能包含冒号，密码则可以包含后续冒号。用户名和密码都不能包含控制字符；允许密码里出现冒号，并不意味着它可以包含任意字符。Base64 既不是加密，也不是密码哈希。涉及非 ASCII 凭据时还要考虑字符编码：RFC 7617 在兼容 ASCII 的条件下没有统一默认编码，并允许服务器挑战指明 UTF-8。仅验证一个 ASCII 示例，不等于已经覆盖所有国际化账号的编码与比较路径。 Basic 本身不定义会话令牌或通用退出登录协议。应用仍可以设置账号到期、禁用账号、改变授权或拒绝旧密码。因此，轮换密码并不是阻止泄露请求头继续生效的唯一办法。凭据的有效期与撤销方式，应依据服务器真实的账号策略定义，不能期待网络传输格式自动提供完整账号生命周期管理。客户端停止发送，与服务器已经拒绝旧值，也是不同事实。坏掉的样子在没有保护的网络链路上，能够读取请求头的人可以解码并再次使用。正确校验证书的 HTTPS 保护的是到 TLS 终点的传输，不会让终点本身、合法终止 TLS 的代理或疏忽的应用日志看不到凭据。还需要保护后续链路，并避免在日常追踪、报告和共享诊断文件中记录 Authorization 的真实值。传输加密不能替代服务端对凭据的妥善处理。权限过大的凭据会扩大泄露后果。账号应匹配具体任务及其生命周期，身份验证之后仍要执行授权。凭据有效，不等于每个操作都允许；realm 标签也不是租户隔离机制。客户端需要限制凭据发送位置，尤其关注重定向和脚本复用全局请求头的情况。把同一个认证头传给无关目的地址，超出了原来的保护空间，也破坏了凭据使用边界。重复的四零一可能来自凭据缺失、错误、到期或服务端不支持相应方式。在下面例子中，四零三表示已经识别的演示账号缺少目标权限，但不能据此认为所有服务返回四零三都证明认证已成功。应结合服务契约及响应中的认证挑战检查，不能仅凭一个数字推断完整的身份状态。认证结果和业务许可，应分别提供能够判断的证据。快速验证保存为 basic-auth.py，执行 python3 basic-auth.py。所有凭据都是刻意编造的演示值：用户名为 DEMO，密码为 NOT:A:SECRET。服务器只绑定回环地址，用明文 HTTP 展示协议机制；不要把这些值替换成真实凭据。实验没有测试 TLS、持久账号存储或生产认证服务，也不会读取当前环境的登录信息。 ...

文章标题旁是标有 OBSERVE、DECIDE、ACT 的三个通用面板，以及箭头和圆形仪表。

Service 给一组 Pod 一个稳定的虚拟地址

选择器让 Service 从一段固定列表变成动态视图：新增移除都在后台完成，Pod 重启时客户端无需改任何配置。先声明，再分配地址普通 ClusterIP Service 在对象存续期间提供虚拟地址，并在集群 DNS 支持下提供稳定发现名称。带选择器的 Service 还声明本命名空间中哪些 Pod 是预期后端。其他形态不同：无头服务不分配虚拟 IP，ExternalName 使用 DNS 间接引用，无选择器服务可以配合单独管理的 EndpointSlice。不能把每种 Service 都套进同一种分配流程。地址稳定仅限 Service 对象存续期间，不是某个名称出现之后永远占用同一个地址。删除重建可能得到新地址。客户端应遵守约定的发现方式，并适当重新解析，而不是把抄下来的 ClusterIP 当成永久基础设施身份。这层稳定性主要隔离后端更替，不能消除对象本身重建和发现系统变化带来的影响。选择器就是实时成员 EndpointSlice 控制器异步协调匹配 Pod 与端点条件。未就绪 Pod 可以继续出现在对象中，只是 ready 为 false，并非一定从所有端点对象里消失。消费者根据这些条件选择路由目标。publishNotReadyAddresses 会改变普通就绪解释，终止中端点又有额外处理细节，不能仅凭列表存在地址就断言后端应接收普通流量。标签一致也不能证明请求健康。端口错误、不适当探针或过期数据路径仍然可能导致失败。应同时检查预期选择器与实际 EndpointSlice，再验证应用行为。自动协调减少手工维护后端名单，但不承诺瞬间更新，也不会消除所有漂移。控制面对象、节点转发和客户端连接各有自己的状态及更新时序。 Pod 变了地址依旧稳定稳定目的地允许替换后端，而不必向调用方逐个公布 Pod IP，但不保证每次请求都不中断。已有连接可能仍关联旧后端，新连接依赖已经收敛的路由状态；没有可用端点的 Service 也不能制造缺失容量。不能因为名称没有改变，就认为所有连接已经自动迁移到新进程。 ...

功能开关把发布与暴露解耦

部署代码和向用户开放功能，是不同动作。功能开关可以在代码部署后选择运行路径，支持渐进开放和快速关闭；前提是旧路径仍兼容，配置也真正到达负责求值的进程。开关控制一次决定，不会撤销部署或新行为已经造成的全部效果。讨论回滚时，应明确能停止什么、不能恢复什么，而不是把关闭按钮当作万能撤销。在明确的门控后部署发布开关通常默认选择既有路径，让新实现先接受验证。不过部署阶段仍可能变化：导入、启动钩子、表结构迁移、依赖和资源使用，都可能位于被保护分支之外。因此关闭开关不能保证用户完全无感。应同时测试关闭和开启状态的真实产物，包括启动流程，以及两条路径与已有数据的兼容性，避免只看功能入口是否隐藏。关闭开关可以阻止后续请求进入新路径，却不会撤销已经完成的写入、已发送消息、迁移或在途工作。回滚窗口内应让两条路径都能处理相关数据格式，并定义部分执行后可能需要的修复。紧急关闭只有在传播延迟和实际停止边界符合响应计划时才有效；控制台显示关闭，不代表所有正在运行的操作已经中止。按含义选择默认行为对于尚未完成的发布功能，未知配置时退回旧路径可能是安全选择。但这是具体开关的语义，不是任何情况下 false 都安全。关闭保护性检查，或者反转名为 disable-validation 的开关，可能产生相反结果。应明确备用值、配置新鲜度，以及无法求值时的处理，不能只用“失败为关”四个字替代对实际行为的审查。在合适的操作边界求值一次，并在该操作内部复用决定。多个服务或独立请求之间，需要明确传递兼容决定的方式；每个进程本地求值一次，不会自然形成全局一致性。权限校验也应独立存在。客户端控制显示的开关，不能变成服务器接受受保护操作的授权凭证，否则隐藏按钮并没有真正限制访问。用稳定身份逐步开放把稳定用户标识与稳定开关键一起散列，可以形成可重复的分组。改变身份字段、盐值或分桶算法，即使百分比不变，也可能让用户重新分组。用户比例也不等于请求比例：少量重度用户可能产生大量流量。因此解释放量指标前，先记录分配单位，确认观察的是账号、请求还是其他业务实体，不能把几个百分比直接互换。紧急关闭应覆盖普通分桶选择，并具有经过测试的配置传递路径。SDK 缓存和配置服务故障，可能让部分实例继续使用旧值。应按实际求值的变体观察错误与延迟，不能把控制面修改成功当作每次请求已经切换的证明。放量节奏应依据服务风险和观察延迟决定，不存在对所有业务都适用的固定百分比或等待时间。坏掉的样子临时发布开关如果没有删除负责人，会变成长期分支。应指定负责人和退出条件，在回滚窗口结束后删除不再需要的路径。运维开关和权益控制则可能有意长期存在，需要持续测试和维护，不能要求所有开关都很快过期。区分类型，才能既避免死配置堆积，又保留真正需要的长期运行控制。互相矛盾的开关还可能形成无人测试的组合。可行时集中决定规则，定义优先级，同时验证备用与开启路径。日志只保留足以诊断不一致的非敏感上下文，避免无限保留真实用户标识。本例使用的名字全部是合成测试数据；把这份内存审计列表搬到生产环境前，还需另行设计保留、访问和脱敏规则。快速验证把代码保存为 flag_check.py，用 Python 3.10 或更新版本运行。原始实验记录使用 Python 3.14.4，本轮用 Python 3.12.14 重新执行其决定逻辑。脚本只模拟一个百分比发布开关、紧急关闭、稳定用户分桶和内存审计列表。百分比假定已通过零至一百的输入验证，不包含真实配置下载、SDK 缓存或身份服务。 import hashlib class Flag: """One percentage flag with kill switch, default-closed, and audit log.""" def __init__(self, key, percent): self.key = key self.percent = percent self.killed = False self.audit = [] def _bucket(self, user): digest = hashlib.sha256(f"{self.key}:{user}".encode()).hexdigest() return int(digest, 16) % 100 def evaluate(self, user): if self.killed: decision, reason = False, "killed" elif not user: decision, reason = False, "default-closed" else: hit = self._bucket(user) < self.percent decision, reason = hit, ("in-bucket" if hit else "out-of-bucket") self.audit.append({"user": user, "decision": decision, "reason": reason}) return decision flag = Flag("new-checkout", 20) users = [f"user-{i}" for i in range(200)] # 1. Default closed: a missing user never gets the new path. assert flag.evaluate("") is False assert flag.evaluate(None) is False # 2. Stickiness: the same user gets the same answer twice. first = flag.evaluate("user-1024") second = flag.evaluate("user-1024") assert first == second # 3. Kill switch overrides every bucket. flag.killed = True assert flag.evaluate("user-1024") is False assert flag.evaluate("user-7") is False flag.killed = False # 4. The dial moves exposure for a fixed fixture set. open_20 = sum(flag.evaluate(u) for u in users) flag.percent = 100 open_100 = sum(flag.evaluate(u) for u in users) flag.percent = 0 open_0 = sum(flag.evaluate(u) for u in users) flag.percent = 20 assert open_0 == 0 assert 0 < open_20 < len(users) assert open_100 == len(users) # 5. A different bucketing key disagrees somewhere: the inconsistency to avoid. session_flag = Flag("new-checkout-session", 20) mismatch = [u for u in users if flag.evaluate(u) != session_flag.evaluate(u)] assert mismatch, "expected at least one user where two flag keys disagree" # 6. Audit log holds one entry per evaluation with its reason. assert len(flag.audit) == 2 + 2 + 2 + 200 * 3 + 200 assert len(session_flag.audit) == 200 assert all(set(e) == {"user", "decision", "reason"} for e in flag.audit) print(f"default-closed empty user: off; sticky user-1024: {'on' if first else 'off'} twice") print(f"dial 0/20/100 over 200 users: {open_0}/{open_20}/{open_100}") print(f"killed flag forces off; different flag keys disagree on {len(mismatch)} users, e.g. {mismatch[0]}") print(f"audit entries: flag={len(flag.audit)}, session_flag={len(session_flag.audit)}") print("PASS: default-closed, sticky bucketing, kill switch, dial, and audit log behave as asserted") 在百分之二十时，缺失用户保持关闭，紧急关闭覆盖全部具名用户，同一用户重复求值保持稳定。两百个固定测试用户在零、二十、一百三档，分别有零、三十五、两百人开启。三十五是这组输入的确定结果，不保证任意有限用户集合都精确达到百分之二十，也不说明相同比例的请求会使用新路径。 ...

按所需操作选择 B-tree 或哈希索引

PostgreSQL 默认的 B-tree 索引支持多种常见需求，包括等值、范围、有序访问和唯一性约束；哈希索引提供的则是更窄的等值访问路径。两者的选择应先从需要支持的运算符与数据约束开始，再进入性能测量。说哈希“只要是等值就一定更快”，或者规划器“几乎从来不会选它”，都是用未经负载验证的概括代替具体问题。先确认能力，再比较成本，顺序不能颠倒。先检查能力，再比较耗时 B-tree 按运算符类和排序规则保留键的顺序，因此既能定位单个等值键，也可能支持有界范围与 ORDER BY，省掉额外排序。它还可以为 IS NULL 和 IS NOT NULL 提供索引访问。不过，存在索引不等于强制使用索引；查询需要读取很大一部分表时，规划器仍可能选择其他路径。这并不改变索引在语义上支持哪些操作。文本模式另有条件。像 LIKE 'abc%' 这样由常量构成、锚定开头的前缀，可以利用合适的 B-tree 路径，但排序规则和运算符类会影响适用性。非 C 区域设置下，可能需要专门支持模式匹配的运算符类。开头带通配符的匹配，也不会因为创建了普通 B-tree 就自动变成高选择性的有序范围。不能把“支持部分前缀匹配”写成“所有 LIKE 都能一趟索引解决”。 PostgreSQL 哈希索引保存四字节哈希码，而不是完整列值。它支持等值，不保留键顺序，只支持单个索引列，也不能检查唯一性。对于较大值，较小的索引条目可能有利于某些等值负载，但读取堆记录进行复核、访问桶和溢出页仍有成本。数据结构的名字本身不能证明某次真实查询谁会胜出。坏掉的样子把 B-tree 换成哈希索引，可能失去原有的范围或有序访问路径，也会失去 IS NULL 的索引访问能力：PostgreSQL 哈希索引不支持这个条件。更严重的是，把承担唯一性要求的索引替换成哈希索引，因为后者根本无法提供对应约束。即使点查偶尔更快，也不能用性能收益替代数据完整性契约。空值语义需要单独核对。默认唯一 B-tree 允许多个空值，因为唯一性检查把它们视为彼此不同。如果应用要求最多只能出现一个空值，应在唯一约束或索引上明确使用 NULLS NOT DISTINCT，而不能从“唯一”两个字直接推导。索引支持怎样访问，与它强制哪些数据规则，是关联但不同的两项决定。验证时必须分别看查询结果和约束行为。 ...