Solidity权限管理实战：用数组实现白名单与多管理员机制-北京尧图网络

如果你装过软件、清理过系统盘大概率撞见过这样的弹窗你需要来自 administrators 的权限才能删除这个文件夹或者鼠标右键菜单里那个神秘的取得所有权。在操作系统里权限和所有权决定了一个用户能不能读写某个文件、能不能执行某个程序而在 Solidity 合约里权限和所有权决定的是一个地址能不能调用某个函数、能不能把合约里的资产转走。两者的底层逻辑其实惊人地相似——只是合约里的文件夹换成了函数文件权限换成了 owner 和 modifier。这篇博文是Solidity 合约设计与功能系列的第三篇主题是权限和所有权重点落在怎么用数组Array把一份名单变成一套门禁系统。适合正在从语法学习走向合约设计的开发者也适合想给自己的合约加上白名单、黑名单、多管理员机制的进阶玩家。我会从权限失控的真实教训讲起一步步拆解数组在权限管理中的声明、查询、删除、组合优化最后给出一份可以直接复制改造的完整合约。1. 一次权限失控的复盘合约里的所有权到底锁住了什么1.1 现实世界的权限问题在以太坊上会放大成资产问题Windows 的注册表权限弹窗让人头疼但最多就是删不掉文件、启动不了服务重启几回总能解决。链上合约的权限问题没有重启这个选项——如果权限设计失误攻击者拿到了不该有的调用权合约里的资产被转走就是一瞬间的事而且没有任何客服电话可以打没有管理员账户能强制冻结。我见过的很多早期合约事故事后复盘都会指向同一条根因权限控制写得过于单薄。常见写法是合约只有一个 owner关键函数挂一个 onlyOwner 修饰符。这种设计在逻辑上没错但它把整个合约的安全性压在了一把钥匙上——私钥一旦泄露、被钓鱼、被社工攻击者拿到 owner 权限后可以直接调用 withdraw、setOwner、migrate 这类高危函数。单点故障在传统系统里只是一个运维问题在链上就是资金清零的灾难。1.2 权限的本质是谁能做什么所有权的本质是最终谁能说了算在深入数组之前先把这两个概念掰开揉碎。权限Permission描述的是操作粒度某个地址能不能调用某个函数、能不能修改某个状态变量。在 Solidity 里最常见的实现方式是自定义 modifier在函数执行前用 require 做检查。比如modifier onlyAdmin() { require(isAdmin[msg.sender], not admin); _; }所有权Ownership描述的是控制权归属整个合约的最终决策权在谁手里。传统做法就是 OpenZeppelin 提供的 Ownable 模式——一个address public owner一个onlyOwner修饰符一个transferOwnership函数。它解决的是谁是合约的老板这个问题。但真实业务比这复杂得多。一个运营中的 DApp 通常有多个角色管理员能冻结异常账号操作员能录入数据财务能发起提现而 owner 只负责换人和升级逻辑。如果所有角色都挤在 owner 一把钥匙上那就回到单点故障了。这正是需要引入数组的场景——数组本身不是权限工具但它可以非常自然地承载一批拥有某种权限的地址。你要做白名单地址就是数组元素你要做多管理员管理员就是数组元素你要做黑名单被拉黑的地址还是数组元素。数组在权限体系里扮演的身份本质上是一本可翻看、可遍历的名册。2. 从 Ownable 到数组Solidity 访问控制的演进路径2.1 最基础的所有权模式constructor 里指定 owner先用最经典的代码回顾一下单人所有权模型。Ownable 的核心逻辑其实只有十几行pragma solidity ^0.8.0; contract SimpleOwnable { address public owner; event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); constructor() { owner msg.sender; } modifier onlyOwner() { require(msg.sender owner, caller is not owner); _; } function transferOwnership(address newOwner) external onlyOwner { require(newOwner ! address(0), new owner is zero address); emit OwnershipTransferred(owner, newOwner); owner newOwner; } }关键点有三个。第一owner 在 constructor 里被赋值为msg.sender也就是部署合约的地址——这一步我建议部署后立刻检查很多测试网事故是部署者用的账户和实际运营账户不是同一个顺手就埋了雷。第二onlyOwner修饰符本质是一个前置校验校验不通过直接 revert状态不回滚是不可能的因为整个交易都会回滚。第三transferOwnership必须留出来否则合约一旦部署owner 就永远钉死在初始地址上团队离职也好、私钥作废也好全都换不了人。2.2 单把钥匙的问题single point of failure单人所有权模型的最大风险业内叫 single point of failure单点故障。我举两个实际场景。场景一团队里三个开发共用一把部署私钥。某个人电脑中了木马私钥被窃取。攻击者拿到了 owner 权限但他不需要立刻转走资产——他先调用 transferOwnership 把 owner 改成自己的地址然后慢慢提走所有资金。整个过程合法合规链上记录清清楚楚任何人拿他都没办法。场景二owner 私钥没有泄露但使用方要求多个管理员都能审批白名单如果所有审批动作都只能 owner 触发那 owner 就成了流程瓶颈业务效率极低更糟的是owner 地址长期高频参与交易暴露面只会越来越大。所以单人所有权不是不能用于生产而是必须配合其他机制比如加时间锁TimelockController权限变更后延迟执行比如加多签钱包owner 由 multisig 地址充当。但如果你只是想要让一批地址都有权限直接从 Ownable 扩展到数组是最直观、最可控的路径。2.3 为什么这时候需要数组从一个人说了算到一群人说了算现在假设需求变成合约有 5 个管理员任何一个管理员都可以执行管理操作owner 可以动态增删管理员。如果你把每个管理员都写成一个独立的 bool 变量代码会变成噩梦mapping(address bool) public admins;这已经算优雅了但 mapping 有一个先天短板不可枚举。也就是说你能快速知道某个地址是不是管理员但你没法知道现在一共有几个管理员第三个管理员是谁。运营审计、权限迁移、向外部系统同步名单时这些信息都要靠事件日志倒推麻烦得要命。数组就不同了。address[] public admins天然支持长度查询、按索引访问、整体遍历。它和 mapping 的组合能同时拿到两个方向的好处。这正是权限系统发展到多角色阶段数组不可或缺的原因。3. 用数组承载权限名单声明、写入与查询的完整细节3.1 状态变量的声明与存储位置选择数组在 Solidity 里既可以是状态变量也可以是局部变量或参数。权限名单几乎一定是状态变量因为它要持久化。声明方式如下contract AccessControl { address[] public admins; mapping(address bool) public isAdmin; }这里我把 admins 声明成 publicSolidity 编译器会自动生成一个按索引读取的 getteradmins(uint256 index) returns (address)。有一点要注意public 数组的 getter 受限于 Solidity 的 ABI 类型外部调用者无法直接拿到整个数组只能一次取一个元素。如果需要把整个数组批量返回需要额外写一个函数比如function getAdmins() external view returns (address[] memory) { return admins; }这个函数返回 memory 数组。因为状态变量是 storage 类型直接返回时编译器会帮你复制一份到 memory代价是 gas 和数组长度成正比。所以这个函数只适合管理工具调用不适合在合约内部高频调用。storage、memory、calldata 三者之间的记忆方法我一直用这个类比storage 是仓库合约自己的长期货架memory 是临时桌面函数运行完就清空calldata 是只读的快递单只负责把外部数据送进来。权限名单必须放仓库不能放桌面。3.2 写入操作push 与初始化时的批量填充数组写入最常用的是 pushfunction addAdmin(address account) external onlyOwner { require(account ! address(0), zero address); require(!isAdmin[account], already admin); admins.push(account); isAdmin[account] true; emit AdminAdded(account); }这里有三个细节值得停下来讲。第一为什么要同时维护isAdmin这个 mapping因为数组查询是 O(n)每次 add 前要检查这个地址是不是已经在名单里如果直接用 for 循环遍历 admins一旦管理员数量膨胀到几百上千每次 O(n) 的 gas 会非常难看。用 mapping 做存在性检查是 O(1)代价只是多维护一份数据结构。第二push 之前先 require 非零地址。address(0) 在 Solidity 里是一个合法的值如果不拦截地址为 0 的管理员会被加入名单永远没人能操作它而且它还能本质性地占据一个名额。这种事在公共合约里发生过太多次了。第三初始化批量填充。如果你知道合约启动时需要一批固定管理员可以直接在 constructor 里循环 add也可以用一个批量添加函数function addAdmins(address[] calldata accounts) external onlyOwner { for (uint256 i 0; i accounts.length; i) { _addAdmin(accounts[i]); } } function _addAdmin(address account) internal { require(account ! address(0), zero address); require(!isAdmin[account], already admin); admins.push(account); isAdmin[account] true; emit AdminAdded(account); }注意我用的是 calldata 而不是 memory 来接收参数。calldata 参数在外部调用时不需要先从 calldata 复制到 memory能省一点 gas而且 calldata 天然只读不会出现误改参数的风险。这个习惯建议所有合约函数都保持。3.3 查询操作如何确认某个地址是否在白名单里查询分两种。一种是这个地址有没有权限用 mapping 判断require(isAdmin[msg.sender], not admin);另一种是把所有有权限的地址列出来用数组遍历function getAllAdmins() external view returns (address[] memory) { return admins; }实际管理后台通常会调用第二个函数把名单渲染到页面上。前端还可以配合 getter 逐个读取但那样 RPC 请求次数会很多体验不好所以一般还是写一个批量返回函数更省事。3.4 数组为什么不建议直接做唯一性约束有朋友写过这样的代码function addAdmin(address account) external onlyOwner { admins.push(account); // 不查重复 }短期内没问题但一旦重复添加同一个地址两次名单里就会出现两个相同元素。这会造成什么后果授权不受影响因为同一个地址本身就有权限但你在做管理员数量统计全部撤销这类操作时数据会变得自相矛盾。比如你遍历数组逐个撤回权限撤完发现名单长度还是 2因为重复元素导致撤销逻辑被循环多次。代码状态和业务预期不一致是最容易引发二次事故的隐患。所以唯一性检查必须做做的方式就在isAdminmapping 里判断而不是到数组里重扫。4. 权限名单的日常管理增删改查与边界处理4.1 删除元素的三种思路删除一个管理员比添加复杂得多因为 Solidity 数组没有内置的 remove 方法。常见思路有三条。思路一先找到索引再用最后一个元素覆盖掉要删的元素最后 pop。这是最推荐的写法因为它能保持数组紧凑、数据不空洞function removeAdmin(address account) external onlyOwner { require(isAdmin[account], not admin); for (uint256 i 0; i admins.length; i) { if (admins[i] account) { admins[i] admins[admins.length - 1]; admins.pop(); break; } } isAdmin[account] false; emit AdminRemoved(account); }这个方案的代价是改变了数组顺序——被删元素的位置换上了最后一个元素。如果你的业务不在乎管理员先后顺序它能做到 O(n) 定位后 O(1) 删除gas 最省。思路二如果管理员有明确的权重或排名顺序不能乱那就别用交换覆盖直接整体移位把被删位置之后的元素逐个往前搬最后 pop。代价是删除操作变成 O(n) 且 gas 更高适合小规模名单。思路三用 delete 操作把某个元素置零比如delete admins[i]。这不会缩短数组长度只会把对应位置的地址变成 address(0)。随后你遍历名单时必须额外判断元素是不是零地址否则会把零地址也当成管理员对待。这个方案最大的坑是数组长度不变时间一长 list 里全是空洞遍历效率低业务逻辑也容易出错。能用前两种就别用 delete。4.2 重复添加与索引错乱的坑删除操作里最容易踩的坑是边遍历边删除导致的索引错乱。很多新手会这么写function removeAllAdminsBadExample() external onlyOwner { for (uint256 i 0; i admins.length; i) { delete admins[i]; // 实际上没有缩短数组 } }这写的不是全部清空而是把每个位置归零。数组 length 还是原来的值isAdmin mapping 也没有更新。正确的批量清空有两种要么逐个 remove要么直接声明一个新的空数组重置状态变量function removeAllAdmins() external onlyOwner { delete admins; // 会把整个数组的长度归零 // 但还要清掉 isAdmin否则 isAdmin 里残留 true下次 add 时会误判 }有人会惊讶 delete 作用于数组时可以把长度归零对的delete admins会把整个 storage 数组重置成空数组。但你别忘了同步清掉 isAdmin。最稳妥的方式是重置以后把已有的 isAdmin 遍历一遍逐个置 false或者干脆在架构上不依赖 mapping 的旧值——这就是很多人最后选择用数组做遍历、用 mapping 做判断之后还要配套事件恢复数据的原因。4.3 length、delete 与 pop 的真实行为把三个操作并排对比一下array.push(item)数组长度 1元素追加到末尾。array.pop()移除最后一个元素长度 -1。无法取回被移除的值所以想用旧值时先存到内存变量。delete array[i]把第 i 个元素设为默认值address 是 address(0)uint 是 0长度不变。delete array整个数组长度归零重新变成空数组。类型是动态数组时可以这么干固定数组不行。在实际合约里pop 之前一定要确认数组非空否则会 revert。如果你用最后一个元素覆盖 pop的删除模式还有一种极端情况要处理要删的元素本来就是最后一个那覆盖和 pop 都作用于同一个位置这没问题——你把 admins[i] 赋值为 admins[admins.length - 1] 时 i 等于 length-1等于没覆盖然后 pop 弹出它干净利落。4.4 权限变更必须记录的事件与操作审计权限变更在链上是最敏感的操作。任何 addAdmin、removeAdmin、transferOwnership 都必须抛事件。事件不只是给前端听的更是给审计、给监控、给社区信任度看的event AdminAdded(address indexed account); event AdminRemoved(address indexed account); event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);indexed 关键字很重要。它能把这个字段变成可检索的主题topic允许链下工具按地址快速过滤历史事件。比如安全监控服务监听 AdminAdded 事件一旦发现新增管理员立即告警就需要这个 indexed 索引。没有 indexed 的字段是 data无法高效过滤只能把整个日志拉下来逐个解析成本高得多。5. 数组与 mapping 的组合拳可迭代与高效查询兼得5.1 为什么不用纯 mapping 管理权限纯 mapping 管理权限的问题前面已经说过一次但值得从数据结构角度再压一遍mapping 是无序键值对它没有长度的概念你不能知道一个 mapping 里到底有多少个键为 true 的地址。合约内部确实可以在每一次 add 时维护一个计数器但那只是数量不是名单——你仍然枚举不出所有管理员都是谁。权限管理需要可迭代性运营要导出名单给审计新合约要复制旧名单监管方要是抽查某批地址是否都有权限没有数组这些事全做不了。所以我的结论很明确权限管理的主体结构应该是数组mapping 只是加速判断用的辅助索引。二者结合查询走 mapping管理走数组。5.2 数组 mapping 的经典搭配再贴一次核心代码这次把 add/remove/getList 全部组织好contract AdminManager { address[] public admins; mapping(address bool) public isAdmin; event AdminAdded(address indexed account); event AdminRemoved(address indexed account); modifier onlyAdmin() { require(isAdmin[msg.sender], not admin); _; } function addAdmin(address account) external onlyAdmin { _addAdmin(account); } function removeAdmin(address account) external onlyAdmin { _removeAdmin(account); } function _addAdmin(address account) internal { require(account ! address(0), zero address); require(!isAdmin[account], already admin); admins.push(account); isAdmin[account] true; emit AdminAdded(account); } function _removeAdmin(address account) internal { require(isAdmin[account], not admin); for (uint256 i 0; i admins.length; i) { if (admins[i] account) { admins[i] admins[admins.length - 1]; admins.pop(); break; } } isAdmin[account] false; emit AdminRemoved(account); } function getAdmins() external view returns (address[] memory) { return admins; } }这里我把 add 和 remove 都挂上了onlyAdmin意味着管理员可以邀请别人成为管理员。这是多角色系统里常见的设计但你要想清楚权限收敛问题——如果管理员被攻破攻击者可以无限添加自己的同伙地址。所以我会建议生产项目里 add 权限只给 ownerremove 权限可以给 admin因为移除是收敛操作不会扩大攻击面。权限的添加必须比移除更严格。5.3 组合方案中的索引稳定性问题最后一个细节是索引稳定性。用交换最后一个元素再 pop的方式删除后数组中元素的顺序会变化。如果你在前端把 admins 数组的索引当作唯一 ID 使用比如数据库里存了一个 admin id 2对应 admins[2]删除操作会让所有索引错位追踪关系全部失效。解决办法有三个第一前端不要持久化数组索引每次查询后重新对照地址第二删除时用整体移位保持顺序牺牲 gas 换取索引稳定第三给每个管理员一个自增 id用 struct 封装数组只存 id 映射但这种设计复杂度就上一个台阶了。我的经验是权限系统的数组规模通常不会超过几百绝大多数项目用交换删除法没问题只要前后端约定好索引不可作为持久身份就够了。6. 完整示例一个带角色权限管理的合约落地实现6.1 合约代码走读把上面所有要点合并我给出一份带角色区分的完整合约。这里角色拆成两个BOSS 是 owner负责管理 ADMIN 列表ADMIN 可以执行业务操作。这样既有单人所有权owner又有数组承载的多权限名单admins还有映射加速和事件审计// SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract RoleBasedAccess { address public owner; address[] public admins; mapping(address bool) public isAdmin; event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); event AdminAdded(address indexed account); event AdminRemoved(address indexed account); modifier onlyOwner() { require(msg.sender owner, only owner); _; } modifier onlyAdmin() { require(isAdmin[msg.sender], only admin); _; } constructor() { owner msg.sender; } function transferOwnership(address newOwner) external onlyOwner { require(newOwner ! address(0), zero address); emit OwnershipTransferred(owner, newOwner); owner newOwner; } function addAdmin(address account) external onlyOwner { require(account ! address(0), zero address); require(!isAdmin[account], already admin); admins.push(account); isAdmin[account] true; emit AdminAdded(account); } function removeAdmin(address account) external onlyOwner { require(isAdmin[account], not admin); for (uint256 i 0; i admins.length; i) { if (admins[i] account) { admins[i] admins[admins.length - 1]; admins.pop(); break; } } isAdmin[account] false; emit AdminRemoved(account); } function getAdmins() external view returns (address[] memory) { return admins; } function adminCount() external view returns (uint256) { return admins.length; } // 业务示例只有管理员能调用的敏感操作 function ownerBalance() external view onlyOwner returns (uint256) { return address(this).balance; } function adminAction(uint256 amount) external onlyAdmin returns (bool) { // 业务逻辑占位 return true; } }这份合约已经把前面讲的模式完整跑通了。owner 负责管理名单admin 负责执行业务函数getAdmins 和 adminCount 供运营方查看名单。实际项目可以在此基础上扩展多角色把 isAdmin 替换成mapping(address uint8) public roles用 enum 定义角色等级数组改成每个角色一个数组按角色分别做增删。6.2 测试思路与边界用例写完合约不测试等于没写。我的建议是至少覆盖以下用例场景输入预期结果owner 部署合约部署者owner 部署者admins 为空非 owner 添加管理员普通地址调用 addAdminrevert报 only owner正常添加管理员owner 调用 addAdmin(addr)admins 长度 1isAdmin[addr] true重复添加管理员再次 addAdmin(addr)revert报 already admin添加零地址owner 调用 addAdmin(0x0)revert报 zero address正常移除管理员owner 调用 removeAdmin(addr)admins 长度 -1isAdmin[addr] false移除不存在管理员owner 调用 removeAdmin(0x0)revert报 not admin清理所有管理员owner 移除全部admins 为空isAdmin 全为 false特别要提醒一个结合测试的细节如果合约继承了 OpenZeppelin 的 Ownable它有自己内置的 renounceOwnership 函数可以直接把 owner 改成 address(0)。一旦执行这个合约就处于永远没有 owner的状态任何 onlyOwner 函数都无法再调用。看起来是彻底去中心化实际是自杀式操作。生产项目里我强烈建议把 renounceOwnership 覆盖掉并直接 revert防止误操作或者把它走时间锁延迟 48 小时执行给团队留反悔窗口。6.3 实战建议与容易忽略的细节最后说几条我在实际项目中总结出来的血泪经验。第一权限变更一定要配事件和链下监控。我见过不止一个项目把所有权限操作函数都写好了但前端根本没监听事件运营后台也不记录操作日志。等哪天有人偷偷 addAdmin 且立刻调用了提现函数你链下查记录都无从查起。从第一天就把 AdminAdded、AdminRemoved、OwnershipTransferred 的监控接好这是成本最低的安全投资。第二不要在上线后频繁改动权限逻辑。数组 mapping 这套模式的核心优点是简单、可审计、不会在升级时把状态弄丢。如果你上线后发现自己想换成别的存储结构就要处理数据迁移mapping 遍历迁移的 gas 可以烧掉你大半天的预算。所以设计阶段就把是否多角色角色是否需要枚举权限粒度是函数级还是操作级这些决策做完比事后重构成本低一个量级。第三owner 的冷热隔离。owner 私钥是最敏感的单点建议部署时用 multisig 钱包地址作为 owner或者用硬件钱包托管不要让 owner 地址参与普通业务操作。市面上有 Gnosis Safe 这类多签钱包可以直接充当 owner 地址用它来执行 transferOwnership 和管理员增删任何单个人都没办法独立改动权限出事概率大幅降低。第四数组规模要设上限。权限名单理论上不该膨胀到上千但如果业务开放了任何人申请加入管理员就可能在链上被人刷到数组爆炸。for 循环遍历在 Solidity 里的 gas 与长度线性相关removeAdmin 时数组越长越贵。我的建议是在内部维护uint256 public maxAdmins在 addAdmin 里加一道检查超过上限就 revert。这种防御在规模失控前就能拦住问题。结尾就落在这个建议上吧。看完这份合约设计你对数组和权限的关系应该有底了数组负责承载名册、提供可迭代能力mapping 负责加速判断、提供 O(1) 校验owner 负责收敛最终决策权事件负责让所有变更可追踪。我用这套组合写过白名单、黑名单、多签管理员、角色分级系统只要把 isAdmin 换成 roles mapping、把数组按角色拆开绝大多数业务都能覆盖。自己动手跑一轮测试网多试试上面表格里的边界用例你就能体会到权限设计这四个字在链上真正意味着什么。

Solidity权限管理实战：用数组实现白名单与多管理员机制

相关推荐

Unity Spine动画优化：同屏多实例性能优化实战

Qt+C++飞机大战开发指南：环境配置、信号槽与对象树避坑实战

HTML视频帧级精准控制：hyperframes技术实践指南

更多资讯

Coding Agent长期记忆：从易失忆到可持久化的实战拆解

本地部署RAG情感智能助手：原理、实现与调优实践

Gitlab MCP Server推荐：zereight/gitlab-mcp 接入 TaoToken 统一 Key 的配置清单

从零搭建AI工程体系：数据、模型、训练与推理全流程实战

网上支付跨行清算系统（IBPS）功能拆解与接入避坑指南

告别古法编程：Codex CLI 在 Windows 上的 AI 编程实战配置指南（TaoToken 统一接入）

今日更新

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？