高级 ACL 接口设计说明

本文档描述如何在不改动现有低级接口（login_post, acl_post.get_acl_rules, add_acl_post.add_acl_rule, edit_acl_post.edit_acl_rule, del_acl_post.del_acl_rule）的前提下，设计并实现一组高级接口，用于集中管理以备注前缀（例如 Test_）分组的 ACL 目的地址集合。

目标

从所有 ACL 规则中筛选出备注以 Test_（可在 config.json 中配置）为前缀的规则（例如 Test_1, Test_2 等）。
提取这些规则中 dst_addr 字段的所有 IP（逗号分隔），合并为一个全局去重的文本数组（字符串列表）。
基于该集合提供三个高级操作接口：
1. 查询所有 IP 集合（返回去重列表）
2. 添加一个 IP 到集合：如果新 IP 导致某个分组规则（如 Test_1）超过容量限制（例如 1000），则创建或选用下一个编号的 Test_n 规则；必要时使用添加或编辑低级接口来写回。重复 IP 不执行任何操作。
3. 删除一个 IP：从对应规则中删除该 IP（若规则变为空可选择删除规则或保留空规则），并更新/编辑/删除低级规则。

配置项

在 config.json 中新增或使用字段：
- test_prefix（string, 默认 "Test_"） — 用来匹配规则备注前缀。
- rule_ip_limit（int, 默认 1000） — 单条 ACL 规则允许的最大 IP 数量。

示例：

{
  "base_url": "http://103.236.55.143:8080/",
  "test_prefix": "Test_",
  "rule_ip_limit": 1000
}

数据契约

IP 集合类型：List[str]（去重，保留字符串格式的IP或IP段，按原样存储）
内部表示：Python set 用于去重，返回时转换为 list（可选按字典序排序）

高级接口签名（伪 API）

get_all_test_ips() -> List[str]
- 描述：返回合并后的去重 IP 列表
add_ip(ip: str) -> dict
- 描述：向集合添加单个 IP，返回操作结果 {"added": True/False, "rule": "Test_1", "row_id": 123, "message": "..."}
del_ip(ip: str) -> dict
- 描述：从集合删除单个 IP，返回操作结果 {"deleted": True/False, "rule": "Test_1", "message": "..."}

实现逻辑（详细步骤）

A. 获取并构建全局 IP 集合（get_all_test_ips）

使用现有低级接口 acl_post.get_acl_rules() 获取全部规则（Data.data 列表）。
从配置读取 test_prefix。
遍历规则列表，筛选 comment 字段以 test_prefix 开头的规则（例如 Test_1, Test_2）。
对每条匹配规则，读取 dst_addr 字段；如果 dst_addr 为空则跳过。否则：
- 以逗号拆分字符串，去除前后空白，保留原样（IP 或 IP 范围）。
- 将拆分出的元素加入一个 Python set 用于去重。
返回去重后的 sorted(list(set)) 或者原顺序 list（实现可配置）。

注意点：

dst_addr 可能包含 IP 段（例如 1.2.3.4-1.2.3.10）或单个IP，当前实现策略是直接作为字符串项存储，不做IP范围展开。
若需要支持范围展开（拆分多个IP），这是一个可选扩展（成本高，谨慎）。

B. 添加 IP（add_ip）

输入：单个字符串 ip（例如 8.8.8.8 或 1.2.3.4）。输出：操作结果字典，含是否添加成功、目标规则名/ID 等。

步骤：

调用 get_all_test_ips() 获取当前去重集合（set）。如果 ip 已存在，直接返回 {"added": False, "message": "already exists"}。
否则需要把 ip 放入某个 Test_n 规则中：
- 首先通过 acl_post.get_acl_rules() 获取所有匹配 test_prefix 的规则，并按 comment 中的编号从小到大排序（例如 Test_1, Test_2）。同时记录每个规则的 dst_addr 列表与 id（rule id）。
- 遍历这些规则（从编号最小的开始），对于每个规则计算当前 IP 数量，如果加入新 IP 后满足 current_count + 1 <= rule_ip_limit，则向该规则进行编辑（使用 edit_acl_post.edit_acl_rule(rule_id=..., dst_addr=new_dst_str, comment=...)），将新的 IP 附加到 dst_addr（注意去重），并返回该规则的信息（rule id/comment）。
- 如果所有已有规则都已满（或没有规则），则创建新的规则：
- 若没有任何匹配的 Test_* 规则，则创建 Test_1（使用 add_acl_post.add_acl_rule(dst_addr=ip, comment=f"{test_prefix}1")）；
- 否则创建 Test_{k+1}（k 为当前最大的编号），使用 add_acl_post.add_acl_rule(dst_addr=ip, comment=f"{test_prefix}{k+1}")。创建成功后返回新创建的 RowId。
成功写回后，返回 {"added": True, "rule": "Testk or Test{k+1}", "row_id": , "message": "ok"}

错误与回滚考虑：

在编辑时，如果低级接口返回失败（HTTP非200或Result不为Success），应记录错误并返回失败，不应丢失客户端数据。
可选的回滚：如果添加操作分为多步（例如先创建然后编辑），在部分失败情况下尝试回滚（例如删除新创建的规则）。为降低复杂度，初版可以不做复杂回滚，而是保持幂等性并记录失败信息供人工干预。

并发处理：

多个并发添加请求可能导致竞态（例如同时检测到 Test_k 未满并同时写入，超出 limit）。解决策略：
1. 在服务端加分布式锁（最佳，但超出本地实现范围）；
2. 在客户端（高级接口实现处）使用本地文件锁或线程锁，尽量序列化对 ACL 更新的操作；
3. 在写回后再次验证规则大小：编辑后重新读取规则并验证数量如超限则将多出的IP移到下一个规则或提示人工处理。

C. 删除 IP（del_ip）

输入：单个字符串 ip。步骤：

通过 acl_post.get_acl_rules() 获取所有匹配 test_prefix 的规则，并解析每条规则的 dst_addr 到列表形式。
- 找到包含目标 ip 的所有规则（即支持在多个规则中删除）。对于每个匹配的规则：
- 从该规则的 dst_addr 列表中移除该 ip。
- 如果移除后列表不为空，调用 edit_acl_post.edit_acl_rule(rule_id=..., dst_addr=new_dst_str, comment=...) 更新该规则；
- 如果移除后列表为空，默认应删除该规则（调用 del_acl_post.del_acl_rule(rule_id=...)），不保留空规则，以保持规则集合整洁并避免无用占位。
返回操作结果，包含受影响规则的列表（每个元素包含 rule_id、comment、action：edited 或 deleted），以及整体操作状态。

边缘情况：

IP 在多个规则中存在：默认行为为删除所有出现的地方，并返回受影响规则列表（而非只删除第一次出现）。
删除导致 hole（例如 Test_2 删除后 Test_1、Test_3 可能不连续），可以不强制重编号，保持 comment 名称不变以减少对外影响。

幂等性与幂等操作

add_ip 对已存在的 IP 操作应当是幂等的（不重复添加）。
del_ip 对不存在的 IP 操作也应当返回成功/无操作结果。

权限与认证

所有高级接口在内部依赖已有的登录与 sess_key 管理，不需要额外的认证步骤；但调用者应确保先执行登录流程并设置好全局 sess_key。

日志与监控

使用现有 log_util.log_request 记录每次低级请求及响应。
在高级接口处记录高层动作（add/del），包括原始IP、目标规则、操作结果与错误信息。

ADVANCED_ACL.md 7.3 KB Verlauf Originalformat