服务注册与分布式协调 / 系统课时
批量迁移开放节点的 ACL
批量迁移开放节点的 ACL
批量收紧 world:anyone 的真正难点不是执行 setAcl,而是避免把仍在运行的旧客户端一次性锁死。本节给出一条可回退的迁移顺序:先盘点开放节点和真实访问者,再做单节点金丝雀,最后按批次移除开放 ACL,并在每一步验证认证客户端仍能访问。
学习目标
- 找出仍使用
world:anyone的节点,并区分“开放”与“确实需要匿名读取”。 - 设计带金丝雀、版本检查和回退路径的分批
setAcl顺序。 - 用脚本验证迁移后不再残留
world:anyone,同时确认目标身份仍能读取节点。
先盘点再改 ACL
ZooKeeper ACL 作用在单个 znode 上,不会因为父节点已经收紧就自动覆盖子节点。因此迁移前必须拿到明确的节点清单,并逐节点查看 ACL;不要只检查 /app 就推断整棵子树已经安全,也不要直接对权限需求不同的整棵树执行同一条递归 setAcl。
盘点时至少记录三类信息:当前 ACL、实际客户端身份、该节点需要的权限。r、w、c、d、a 应按真实操作分配,例如纯配置消费者通常只需要 r,而专门的迁移账号可保留 r 与 a 以便读取状态、修改 ACL 和执行回退。
用金丝雀控制迁移顺序

推荐顺序是先让客户端具备认证能力,再收紧 ACL,而不是反过来。一次变更批次可以按下面的顺序执行:
- 发布客户端凭据并确认新版本已经能完成认证,但暂时不移除开放 ACL。
- 选择一个低风险节点作为金丝雀,读取当前
aclVersion。 - 使用带版本条件的
setAcl -v写入目标 ACL,避免覆盖并发发生的 ACL 修改。 - 立刻用目标业务身份访问该节点,并再次读取 ACL,确认
world:anyone已消失。 - 金丝雀稳定后再扩到小批次;任一节点失败就停止下一批,并先恢复可用性。
不要为了省事一开始就使用 setAcl -R 覆盖整棵业务树。递归命令适合 ACL 模型完全一致、已经验证过的子树;对于混合了配置、选主、锁和临时节点的路径,逐类分批更容易控制影响面。
批量执行与验证脚本
下面脚本演示两个已审批节点的迁移。它假设业务账号 app-reader 只需要读取权限,迁移账号 zk-migrator 保留 r 与 a;<ID> 是与各自用户名、口令对应的 digest 摘要,<PASSWORD> 需要替换为真实凭据。脚本先迁移第一个节点作为金丝雀,再处理剩余节点;如果业务账号验证失败,会立即恢复 world:anyone:cdrwa 加目标 ACL,优先恢复服务可用性。
#!/usr/bin/env bash
set -euo pipefail
ZK_SERVER="127.0.0.1:2181"
ZK_CLI="bin/zkCli.sh"
MIGRATOR_USER="zk-migrator"
MIGRATOR_PASS="<PASSWORD>"
MIGRATOR_DIGEST="<ID>"
APP_USER="app-reader"
APP_PASS="<PASSWORD>"
APP_DIGEST="<ID>"
TARGET_ACL="digest:${MIGRATOR_USER}:${MIGRATOR_DIGEST}:ra,digest:${APP_USER}:${APP_DIGEST}:r"
ROLLBACK_ACL="world:anyone:cdrwa,${TARGET_ACL}"
PATHS=(
"/app/config/db"
"/app/config/feature"
)
run_as_migrator() {
local command="$1"
{
printf 'addauth digest %s:%s\n' "$MIGRATOR_USER" "$MIGRATOR_PASS"
printf '%s\n' "$command"
printf 'quit\n'
} | "$ZK_CLI" -server "$ZK_SERVER" 2>&1
}
run_as_app() {
local command="$1"
{
printf 'addauth digest %s:%s\n' "$APP_USER" "$APP_PASS"
printf '%s\n' "$command"
printf 'quit\n'
} | "$ZK_CLI" -server "$ZK_SERVER" 2>&1
}
acl_version() {
local path="$1"
run_as_migrator "stat ${path}" |
awk -F' = ' '/aclVersion =/{print $2; exit}'
}
set_acl_cas() {
local path="$1"
local acl="$2"
local version
version="$(acl_version "$path")"
test -n "$version"
run_as_migrator "setAcl -v ${version} ${path} ${acl}"
}
verify_target() {
local path="$1"
local acl_out app_out
acl_out="$(run_as_migrator "getAcl ${path}")"
app_out="$(run_as_app "get ${path}")"
! grep -q "'world,'anyone" <<<"$acl_out"
! grep -Eq 'Insufficient permission|AuthFailed|KeeperErrorCode = NoAuth' <<<"$app_out"
}
for i in "${!PATHS[@]}"; do
path="${PATHS[$i]}"
set_acl_cas "$path" "$TARGET_ACL" >/dev/null
if verify_target "$path"; then
if [[ "$i" -eq 0 ]]; then
printf 'CANARY OK %s\n' "$path"
else
printf 'BATCH OK %s\n' "$path"
fi
else
set_acl_cas "$path" "$ROLLBACK_ACL" >/dev/null || true
printf 'ROLLBACK %s\n' "$path" >&2
exit 1
fi
done
printf 'MIGRATION COMPLETE\n'预期输出如下;实际节点路径应以你的审批清单为准。
CANARY OK /app/config/db
BATCH OK /app/config/feature
MIGRATION COMPLETE脚本使用 aclVersion 做条件更新,目的是在 ACL 被其他管理员并发修改时停止,而不是静默覆盖对方的变更。回退 ACL 重新开放全部权限只是演示“先恢复可用性”的应急动作;正式变更应在迁移前保存每个节点的原始 ACL 快照,并在失败时恢复原值,而不是长期保留宽松权限。
验收与停止条件
完成一个批次后,至少要同时满足两类验收:安全侧确认目标节点不再包含计划移除的 world:anyone 条目;业务侧使用真实服务身份执行读、写、创建或删除等它实际需要的操作。只看 getAcl 正确,不代表应用一定已经携带了正确凭据。
出现以下任一情况都应停止扩大批次:认证失败、ACL 版本冲突、目标账号缺少实际业务权限、节点类型与预期不符,或仍有旧客户端未完成凭据发布。先恢复失败节点并解决根因,再重新从金丝雀开始,通常比继续推进后集中处理故障更安全。
当节点规模很大时,批量迁移的核心不是“把命令跑得更快”,而是让每次权限收紧都有可验证的前置条件、有限影响面和明确回退路径。做到这一点,开放 ACL 才能从一次高风险大改,变成可观察、可暂停的连续治理过程。