> For the complete documentation index, see [llms.txt](https://www.axisnow.io/zh/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.axisnow.io/zh/docs/edge/policies/objects.md).

# 对象

使用对象简化策略管理及其最佳实践

## 什么是对象 <a href="#what-is-an-object" id="what-is-an-object"></a>

对象是一组相同类型数据的集合，可将同类标识符（如 IP 地址、字符串等）进行聚合。在规则中引入对象通常意味着更少的策略规则，并且更易于大规模管理。

对象常见的用例包括但不限于：

* 当需要管理大量同类数据时（如大量 IP 地址白名单）；
* 当希望通过统一命名列表简化规则维护时（修改对象数据即可同步更新所有引用规则）。

## 两种类型 <a href="#types" id="types"></a>

<table data-search="false"><thead><tr><th width="110">类型</th><th>成员</th><th>可引用它的字段</th></tr></thead><tbody><tr><td>IP 地址</td><td>单个 IP 或 CIDR 网段，支持 IPv4 和 IPv6。客户端地址等于某个成员，或属于某个成员的网段，即为命中</td><td>客户端 IP 地址</td></tr><tr><td>字符串</td><td>任意文本，命中与否由对象的匹配方式决定</td><td>请求 Host、请求 URI 路径、请求 URI、请求完整 URL、User Agent、请求头 referer、TLS 客户端 JA4 指纹</td></tr></tbody></table>

### 字符串对象的匹配方式 <a href="#match-strategy" id="match-strategy"></a>

匹配方式在创建时选定，对整个对象生效；不同的匹配需求使用不同的对象。

<table data-search="false"><thead><tr><th width="120">匹配方式</th><th>命中条件</th><th>例子</th></tr></thead><tbody><tr><td>完全匹配</td><td>字段值与某个成员相等</td><td>成员 <code>/admin</code> 仅命中 <code>/admin</code></td></tr><tr><td>前缀匹配</td><td>字段值以某个成员开头</td><td>成员 <code>/api/</code> 命中 <code>/api/v1/users</code></td></tr><tr><td>后缀匹配</td><td>字段值以某个成员结尾</td><td>成员 <code>.php</code> 命中 <code>/login.php</code></td></tr><tr><td>部分匹配</td><td>字段值包含某个成员</td><td>成员 <code>sqlmap</code> 命中 <code>sqlmap/1.7 (http://sqlmap.org)</code></td></tr><tr><td>通配符匹配</td><td>字段值整体符合某个成员，<code>*</code> 匹配任意多个字符，<code>?</code> 匹配一个字符</td><td>成员 <code>/api/*/users</code> 命中 <code>/api/v1/users</code></td></tr></tbody></table>

**区分大小写**默认开启；User Agent 等大小写不固定的字段建议关闭。

{% hint style="info" %}
前缀匹配按字符比较，不识别路径边界：成员 `/api` 同样命中 `/apiary`。路径名单的成员应写作 `/api/`；若需同时覆盖 `/api` 本身，改用通配符对象，成员为 `/api` 与 `/api/*`。
{% endhint %}

## 在规则中引用 <a href="#reference" id="reference"></a>

对象为租户级，可被多条规则、多个插件共用。条件的匹配方式选择「在对象中」或「不在对象中」，可同时选择多个对象：「在对象中」任一命中即成立，「不在对象中」须全部未命中才成立。

* 空对象不命中任何值：「在对象中」不成立，「不在对象中」成立。清空白名单对象会使“不在白名单则阻断”的规则拦截全部请求；停用白名单应禁用规则，而非清空对象。
* 被规则引用的对象不能删除，须先解除引用。
* 规则中引用了不存在的对象时按求值出错处理，「在对象中」与「不在对象中」均不成立，见[条件表达式 › 求值](/zh/docs/edge/policies/rules/expressions.md#evaluation)。

## 维护成员 <a href="#manage" id="manage"></a>

单次最多添加 10000 条成员。类型、匹配方式和大小写设置创建后不可更改。成员也可通过 [Client API](/zh/docs/edge/api.md) 维护。

## 最佳实践 <a href="#best-practices" id="best-practices"></a>

对象将“名单”与“策略”分离：规则定义处置方式，对象决定处置范围。名单直接写在规则中时，每次变更都是一次规则修改，需要理解条件、动作与优先级，且同一份名单出现在多条规则里时必须逐条同步；放入对象后，变更只涉及成员本身，可以交由其他人员或外部系统执行。

### 多个站点共用一份办公网白名单 <a href="#shared" id="shared"></a>

<table data-search="false"><thead><tr><th width="100">项目</th><th>内容</th></tr></thead><tbody><tr><td>场景</td><td>后台、预发环境等多个站点只允许办公网访问，速率控制也要对办公网放宽；同一份出口名单出现在多条规则中</td></tr><tr><td>对象</td><td>IP 对象 <code>office-egress</code>，成员为办公网出口</td></tr><tr><td>规则</td><td><a href="/zh/docs/edge/policies/access-control.md">通用访问控制</a>：「请求 Host 在以下各项之中 <code>admin.example.com</code>，并且 客户端 IP 地址 不在对象中 <code>office-egress</code>」→ 阻断，预发等站点各一条同样的规则<br><a href="/zh/docs/edge/policies/rate-limiting.md">速率控制</a>：「客户端 IP 地址 在对象中 <code>office-egress</code>」→ 宽松阈值</td></tr></tbody></table>

合作方、CI 等来源各建独立对象，一条规则可同时引用多个；合作结束时解除引用并删除对象。

### 外部系统自动维护 IP 黑名单 <a href="#blocklist" id="blocklist"></a>

<table data-search="false"><thead><tr><th width="100">项目</th><th>内容</th></tr></thead><tbody><tr><td>场景</td><td>SIEM 或风控系统产出的恶意 IP 需要持续更新到边缘</td></tr><tr><td>对象</td><td>IP 对象 <code>blocklist-siem</code>，由外部系统通过 API 增删成员，每批附来源与日期备注，到期按备注清理</td></tr><tr><td>规则</td><td>「客户端 IP 地址 在对象中 <code>blocklist-siem</code>」→ 阻断，置于可信来源的跳过规则之后</td></tr></tbody></table>

短时的自动封禁应使用[通用访问控制](/zh/docs/edge/policies/access-control.md)与[速率控制](/zh/docs/edge/policies/rate-limiting.md)的 IP 封禁动作；对象适合有来源、有时效、需要留痕和复核的名单。

### 受保护路径和扫描器特征集中维护 <a href="#string-lists" id="string-lists"></a>

<table data-search="false"><thead><tr><th width="100">项目</th><th>内容</th></tr></thead><tbody><tr><td>场景</td><td>受保护路径、扫描器特征等名单随业务和日志持续增长</td></tr><tr><td>对象</td><td>受保护路径：字符串对象 <code>protected-paths</code>，前缀匹配，成员如 <code>/admin/</code>、<code>/internal/</code>、<code>/actuator/</code><br>扫描器特征：字符串对象 <code>scanner-ua</code>，部分匹配、关闭区分大小写，成员如 <code>sqlmap</code>、<code>nikto</code>、<code>masscan</code></td></tr><tr><td>规则</td><td>「请求 URI 路径 在对象中 <code>protected-paths</code>，并且 客户端 IP 地址 不在对象中 <code>office-egress</code>」→ 阻断<br>「User Agent 在对象中 <code>scanner-ua</code>」→ 阻断</td></tr></tbody></table>

部分匹配为子串命中，`bot`、`python` 等泛化词会误伤正常客户端，成员须有足够区分度。

### 注意事项 <a href="#notes" id="notes"></a>

* 一个对象一个用途，名称体现用途及放行或拦截的性质，如 `office-egress`、`blocklist-siem`、`protected-paths`。
* 修改对象前查看**引用**：被多条规则共用的名单，新增成员会同时受到所有引用规则的处置。
* 成员为字面值，匹配方式仅限上表五种，不支持正则表达式；需要正则的条件直接写在规则中，见[操作符和函数](/zh/docs/edge/policies/rules/operators-and-functions.md)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.axisnow.io/zh/docs/edge/policies/objects.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.