diff --git a/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.54 Label Mapping API.md b/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.54 Label Mapping API.md
new file mode 100644
index 00000000..a696879b
--- /dev/null
+++ b/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.54 Label Mapping API.md
@@ -0,0 +1,211 @@
+Configure Label Mapping API to automatically call your external API when alert events arrive, enabling dynamic enrichment and correlation of alert information. With this feature, you can automatically attach information from external data sources such as CMDB, HR systems, and more to your alerts.
+
+## I. Overview
+
+The Label Mapping API allows you to build custom external services to enrich alert labels. The workflow is as follows:
+
+1. Flashduty receives an alert event
+2. The system sends event information and the list of expected labels to your API based on configuration
+3. Your API queries external data sources (such as CMDB, databases, etc.)
+4. The API returns the computed enrichment labels
+5. Flashduty attaches the returned labels to the alert
+
+
+
+## II. API Specification
+
+### Request Method
+
+
+
+POST, Content-Type:"application/json"
+
+
+
+### Request Payload:
+
+
+
+| Field | Type | Required | Description |
+| :--------: | :-------------------: | :--: | :--------- |
+| result_label_keys | []string | Yes | List of expected label keys to return, configured by users in Flashduty |
+| event | [Event](#Event) | Yes | Complete information of the current alert event |
+
+
+**Event**:
+
+| Field | Type | Required | Description |
+| :--------: | :-------------------: | :--: | :--------- |
+| account_id | int64 | Yes | Account ID |
+| channel_id | int64 | Yes | Channel ID |
+| data_source_id | int64 | Yes | Data source ID |
+| data_source_type | string | Yes | Data source type, e.g., prometheus, zabbix, etc. |
+| title | string | Yes | Alert title |
+| title_rule | string | No | Title rule |
+| description | string | No | Alert description |
+| alert_key | string | Yes | Alert unique identifier |
+| alert_id | string | Yes | Alert ID |
+| event_severity | string | Yes | Event severity, enum: Critical, Warning, Info |
+| event_status | string | Yes | Event status, enum: Critical, Warning, Info, Ok |
+| event_time | int64 | Yes | Event time, Unix timestamp in seconds |
+| labels | map[string]string | No | Alert original label key-value pairs |
+| images | []string | No | List of alert-related images |
+
+
+
+### Request Example
+
+
+
+```json
+{
+ "result_label_keys": ["owner_team", "service_tier", "host_ip"],
+ "event": {
+ "account_id": 1,
+ "channel_id": 20,
+ "data_source_id": 15,
+ "data_source_type": "prometheus",
+ "description": "CPU usage for instance '10.0.1.101:9100' is over 95%",
+ "title": "High CPU Usage on instance 10.0.1.101:9100",
+ "title_rule": "",
+ "alert_key": "d41d8cd98f00b204e9800998ecf8427e",
+ "alert_id": "62d6c0f6b8f1b2b3c4d5e6f7",
+ "event_severity": "Critical",
+ "event_status": "Critical",
+ "event_time": 1678886400,
+ "labels": {
+ "region": "us-east-1",
+ "service": "service-A",
+ "env": "production",
+ "instance": "10.0.1.101:9100"
+ },
+ "images": []
+ }
+}
+```
+
+
+
+### Response Specification
+
+
+
+**Successful Response:**
+
+| Field | Type | Required | Description |
+| :--------: | :-------------------: | :--: | :--------- |
+| result_labels | map[string]string | Yes | Returned enrichment label key-value object |
+
+- HTTP Status Code: `200 OK`
+- Response body must be a JSON object containing the `result_labels` field
+- Keys in `result_labels` must be label names specified in the request's `result_label_keys`
+- If a label cannot be retrieved, it **should not** be included in the response
+
+**Successful Response Example:**
+
+```json
+{
+ "result_labels": {
+ "owner_team": "team-database",
+ "service_tier": "tier-1",
+ "host_ip": "10.0.1.101"
+ }
+}
+```
+
+**Failure Response:**
+
+| Status Code | Meaning |
+| :--------: | :--------- |
+| 404 Not Found | No data available for enrichment based on the event information |
+| 400 Bad Request | Request body format error or event object missing required fields |
+| 5xx | Unexpected internal API error (e.g., database connection failure) |
+
+> **Note:** Returning `200 OK` status code with an empty `result_labels: {}` object will also be treated as "no results", but using the `404` status code is the more standard approach.
+
+
+
+
+
+## III. Configure Mapping Service
+
+When configuring label mapping in Flashduty, you need to first create a mapping service, then reference that service in your label enrichment rules.
+
+### Mapping Service Field Description
+
+
+
+| Field | Type | Required | Description |
+| :--------: | :-------------------: | :--: | :--------- |
+| api_name | string | Yes | Human-readable service name for selection and reference in the UI, e.g., "CMDB Asset Query API" |
+| description | string | No | Detailed description of the service |
+| url | string | Yes | API request URL, supports template variables |
+| headers | map[string]string | No | HTTP request headers for passing custom authentication, subject to [security blacklist](#HeaderBlacklist) restrictions |
+| timeout | int | No | Request timeout (in seconds)，scope: 1~3 |
+| retry_count | int | No | Number of retries after request failure, ，scope: 0~1 |
+| insecure_skip_verify | bool | No | Skip certificate verification for HTTPS requests |
+| status | string | No | Service status, e.g., enabled, disabled |
+
+
+
+### Label Enrichment Rule Configuration
+
+When configuring label enrichment rules, you only need to focus on the following settings:
+
+1. **result_label_keys**: Specify the list of labels you expect to retrieve from the API. Flashduty will automatically combine this list with the current `event` object into a request body and send it to your API
+2. **Mapping Service**: Select or configure the API service URL, Headers, and other information
+
+
+
+## IV. Header Security Constraints
+
+To prevent security bypasses, request smuggling, IP spoofing, and cache poisoning, the following Headers are **prohibited** when customizing API request headers. The system gateway will automatically filter or reject requests containing these Headers.
+
+
+
+| Category | Blacklisted Headers | Risk Description |
+| :--- | :--- | :--- |
+| **Authentication & Authorization** | `authorization`, `proxy-authorization`, `cookie`, `x-api-key`, `x-access-token` | Prevents credential leakage or unauthorized hijacking of existing authentication contexts |
+| **IP & Geolocation Spoofing** | `x-forwarded-for`, `x-real-ip`, `true-client-ip`, `x-client-ip` | Prevents clients from spoofing source IP to bypass rate limits or allowlists/blocklists |
+| **Host & Routing Manipulation** | `host`, `x-forwarded-host`, `x-forwarded-proto`, `x-internal-id`, `x-user-id` | Prevents Host injection attacks, redirect loops, or spoofing internal system IDs |
+| **Protocol & Request Smuggling** | `transfer-encoding`, `upgrade`, `connection` | Prevents request smuggling attacks exploiting HTTP protocol differences |
+
+
+
+### Header Best Practices
+
+1. **Allowlist Mode**: It is recommended to only allow custom Headers prefixed with `X-Custom-` or `X-Enrich-`
+2. **Length Limits**: The Key or Value length of a single Header should not exceed 1024 bytes
+3. **Format Validation**: Header Values must not contain line breaks (`\r`, `\n`) to prevent Header injection attacks
+
+## V. Best Practices
+
+1. **Performance First:** This API is on the critical path of alert processing and must ensure low latency. Queries to external data sources should be as fast as possible, and implementing caching is recommended.
+
+2. **Clear Error Handling:** Make good use of HTTP status codes (especially `404`) to convey clear execution results.
+
+3. **Idempotency:** The API design should be as idempotent as possible. Multiple calls for the same `event` should return the same result.
+
+4. **Security:** The API must be protected through authentication and authorization mechanisms. Using custom Headers (e.g., `X-Custom-Auth`) for passing authentication information is recommended.
+
+## VI. FAQ
+
+1. **Is there a response timeout for the service?**
+
+ - The service must respond within the configured timeout period; exceeding this is considered a failure
+
+2. **What happens if the API returns a failure?**
+
+ - The alert will be processed normally, but no enrichment labels will be attached
+ - Based on the configured retry count, the system may retry the request
+
+3. **Can result_label_keys be changed dynamically?**
+
+ - Yes, you can modify the list of expected labels in Flashduty at any time without modifying the API code
+
+4. **How do I secure my API?**
+
+ - It's recommended to add an `Authorization` header in the mapping service configuration
+ - You can verify the request source IP on the API side
+ - Using HTTPS for encrypted transmission is recommended
+
diff --git "a/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.1 \345\221\212\350\255\246\351\233\206\346\210\220/8.1.54 \346\240\207\347\255\276\346\230\240\345\260\204API.md" "b/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.1 \345\221\212\350\255\246\351\233\206\346\210\220/8.1.54 \346\240\207\347\255\276\346\230\240\345\260\204API.md"
new file mode 100644
index 00000000..716201c6
--- /dev/null
+++ "b/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.1 \345\221\212\350\255\246\351\233\206\346\210\220/8.1.54 \346\240\207\347\255\276\346\230\240\345\260\204API.md"
@@ -0,0 +1,212 @@
+配置标签映射 API，当告警事件到达时，Flashduty 将自动调用您配置的外部 API 获取增强标签，实现告警信息的动态丰富和关联。通过此功能，您可以将 CMDB、HR 系统等外部数据源的信息自动附加到告警上。
+
+## 一、功能概述
+
+标签映射 API 允许您构建自定义的外部服务来增强告警标签。工作流程如下：
+
+1. Flashduty 接收到告警事件
+2. 系统根据配置，将事件信息和期望获取的标签列表发送到您的 API
+3. 您的 API 查询外部数据源（如 CMDB、数据库等）
+4. API 返回计算得到的增强标签
+5. Flashduty 将返回的标签附加到告警上
+
+
+
+## 二、API 规范
+
+### 请求方式
+
+
+
+POST, Content-Type:"application/json"
+
+
+
+### 请求 Payload：
+
+
+
+| 字段 | 类型 | 必含 | 释义 |
+| :--------: | :-------------------: | :--: | :--------- |
+| result_label_keys | []string | 是 | 期望返回的标签 Key 列表，由用户在 Flashduty 中配置 |
+| event | [Event](#Event) | 是 | 当前告警事件的完整信息 |
+
+
+**Event**:
+
+| 字段 | 类型 | 必含 | 释义 |
+| :--------: | :-------------------: | :--: | :--------- |
+| account_id | int64 | 是 | 账户 ID |
+| channel_id | int64 | 是 | 协作空间 ID |
+| data_source_id | int64 | 是 | 数据源 ID |
+| data_source_type | string | 是 | 数据源类型，如 prometheus、zabbix 等 |
+| title | string | 是 | 告警标题 |
+| title_rule | string | 否 | 标题规则 |
+| description | string | 否 | 告警描述 |
+| alert_key | string | 是 | 告警唯一标识 |
+| alert_id | string | 是 | 告警 ID |
+| event_severity | string | 是 | 事件严重程度，枚举值：Critical、Warning、Info |
+| event_status | string | 是 | 事件状态，枚举值：Critical、Warning、Info、Ok |
+| event_time | int64 | 是 | 事件时间，Unix 秒时间戳 |
+| labels | map[string]string | 否 | 告警原始标签 KV |
+| images | []string | 否 | 告警关联图片列表 |
+
+
+
+### 请求示例
+
+
+
+```json
+{
+ "result_label_keys": ["owner_team", "service_tier", "host_ip"],
+ "event": {
+ "account_id": 1,
+ "channel_id": 20,
+ "data_source_id": 15,
+ "data_source_type": "prometheus",
+ "description": "CPU usage for instance '10.0.1.101:9100' is over 95%",
+ "title": "High CPU Usage on instance 10.0.1.101:9100",
+ "title_rule": "",
+ "alert_key": "d41d8cd98f00b204e9800998ecf8427e",
+ "alert_id": "62d6c0f6b8f1b2b3c4d5e6f7",
+ "event_severity": "Critical",
+ "event_status": "Critical",
+ "event_time": 1678886400,
+ "labels": {
+ "region": "us-east-1",
+ "service": "service-A",
+ "env": "production",
+ "instance": "10.0.1.101:9100"
+ },
+ "images": []
+ }
+}
+```
+
+
+
+### 响应规范
+
+
+
+**成功响应：**
+
+| 字段 | 类型 | 必含 | 释义 |
+| :--------: | :-------------------: | :--: | :--------- |
+| result_labels | map[string]string | 是 | 返回的增强标签 KV 对象 |
+
+- HTTP 状态码：`200 OK`
+- 响应体必须是包含 `result_labels` 字段的 JSON 对象
+- `result_labels` 的 Key 必须是请求中 `result_label_keys` 指定的标签名
+- 如果某个标签无法获取，**不应**在响应中包含该 Key
+
+**成功响应示例：**
+
+```json
+{
+ "result_labels": {
+ "owner_team": "team-database",
+ "service_tier": "tier-1",
+ "host_ip": "10.0.1.101"
+ }
+}
+```
+
+**失败响应：**
+
+| 状态码 | 含义 |
+| :--------: | :--------- |
+| 404 Not Found | 根据 event 信息无法找到任何可用于增强的数据 |
+| 400 Bad Request | 请求体格式错误或 event 对象缺少关键字段 |
+| 5xx | API 内部发生非预期的错误（如数据库连接失败） |
+
+> **提示：** 返回 `200 OK` 状态码 + 空的 `result_labels: {}` 对象也会被视为"无结果"，但使用 `404` 状态码是更规范的做法。
+
+
+
+
+
+## 三、配置映射服务
+
+在 Flashduty 中配置标签映射时，您需要先创建一个映射服务，然后在标签增强规则中引用该服务。
+
+### 映射服务字段说明
+
+
+
+| 字段名 | 类型 | 必填 | 释义 |
+| :--------: | :-------------------: | :--: | :--------- |
+| api_name | string | 是 | 服务的可读名称，用于在 UI 中选择和引用，例如 "CMDB 资产查询 API" |
+| description | string | 否 | 对该服务的详细描述 |
+| url | string | 是 | API 的请求 URL，支持使用模板变量 |
+| headers | map[string]string | 否 | HTTP 请求头，用于传递自定义认证信息，受[安全黑名单](#HeaderBlacklist)限制 |
+| timeout | int | 否 | 请求超时时间（单位：秒），可取值：1~3 |
+| retry_count | int | 否 | 请求失败后的重试次数，可取值：0~1 |
+| insecure_skip_verify | bool | 否 | 请求 HTTPS 时跳过证书验证 |
+| status | string | 否 | 服务状态，如 enabled、disabled |
+
+
+
+### 标签增强规则配置
+
+配置标签增强规则时，只需要关注以下配置：
+
+1. **result_label_keys**：指定期望从 API 获取的标签列表，Flashduty 会自动将此列表和当前的 `event` 对象组合成请求体发送给您的 API
+2. **映射服务**：选择或配置 API 服务的 URL、Headers 等信息
+
+
+
+## 四、Header 安全约束
+
+为了防止安全绕过、请求走私、IP 伪造及缓存污染，在自定义 API 请求头时，**禁止**使用以下 Header。系统网关将自动过滤或拒绝包含这些 Header 的请求。
+
+
+
+| 分类 | 禁用 Header | 风险说明 |
+| :--- | :--- | :--- |
+| **认证与授权** | `authorization`, `proxy-authorization`, `cookie`, `x-api-key`, `x-access-token` | 防止凭证泄露或非法劫持已有的认证上下文 |
+| **IP 与地理位置伪造** | `x-forwarded-for`, `x-real-ip`, `true-client-ip`, `x-client-ip` | 防止客户端伪造来源 IP 以绕过频率限制或黑白名单 |
+| **主机与路由操控** | `host`, `x-forwarded-host`, `x-forwarded-proto`, `x-internal-id`, `x-user-id` | 防止 Host 注入攻击、重定向循环或伪造内部系统 ID |
+| **协议与请求走私** | `transfer-encoding`, `upgrade`, `connection` | 防止利用 HTTP 协议差异进行的请求走私攻击 |
+
+
+
+### Header 最佳实践
+
+1. **白名单模式**：建议仅允许以 `X-Custom-` 或 `X-Enrich-` 为前缀的自定义 Header
+2. **长度限制**：单个 Header 的 Key 或 Value 长度不应超过 1024 字节
+3. **格式校验**：Header 的 Value 严禁包含换行符（`\r`、`\n`），以防止 Header 注入攻击
+
+## 五、最佳实践
+
+1. **性能优先：** 此 API 位于告警处理的关键路径上，必须保证低延迟。对外部数据源的查询应尽可能快，建议实现缓存机制。
+
+2. **明确的错误处理：** 善用 HTTP 状态码（特别是 `404`）来传递清晰的执行结果。
+
+3. **幂等性：** API 的设计应尽可能幂等。对于同一个 `event`，多次调用应返回相同的结果。
+
+4. **安全性：** API 必须通过认证和授权机制进行保护，推荐使用自定义 Header（如 `X-Custom-Auth`）传递认证信息。
+
+## 六、常见问题
+
+1. **服务是否有响应超时时间？**
+
+ - 服务需要在配置的超时时间内返回响应，超时则认为响应失败
+
+2. **如果 API 返回失败会怎样？**
+
+ - 告警会正常处理，但不会附加增强标签
+ - 根据配置的重试次数，系统可能会重试请求
+
+3. **result_label_keys 可以动态变化吗？**
+
+ - 是的，您可以在 Flashduty 中随时修改期望获取的标签列表，无需修改 API 代码
+
+4. **如何保护我的 API 安全？**
+
+ - 推荐在映射服务配置中添加 `Authorization` 请求头
+ - 可以在 API 端验证请求来源 IP
+ - 建议使用 HTTPS 加密传输
+
+
diff --git a/src/en.ts b/src/en.ts
index 5976fafa..d9607288 100644
--- a/src/en.ts
+++ b/src/en.ts
@@ -84,7 +84,11 @@ import Templates from "../flashduty/en/1. On-call/4. Configure On-call/4.7 Templ
/** ⬇️⬇️⬇️⬇️ Other ⬇️⬇️⬇️⬇️ */
import Link from "../flashduty/en/1. On-call/8. Integrations/8.6 Other/8.6.1 Link Integration.md?raw";
/** ⬆️⬆️⬆️⬆️ Other ⬆️⬆️⬆️⬆️ */
-
+
+
+/** ⬇️⬇️⬇️⬇️ Label Mapping API ⬇️⬇️⬇️⬇️ */
+import LabelMappingAPI from '../flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.54 Label Mapping API.md?raw';
+/** ⬆️⬆️⬆️⬆️ Label Mapping API ⬆️⬆️⬆️⬆️ */
const docs = {
CustomAlert,
@@ -155,6 +159,7 @@ const docs = {
Cloudflare,
WecomAlert,
ServiceDeskPlusSync,
- Harbor
+ Harbor,
+ LabelMappingAPI
};
export default docs;
diff --git a/src/zh.ts b/src/zh.ts
index 0602079f..a1339255 100644
--- a/src/zh.ts
+++ b/src/zh.ts
@@ -84,6 +84,10 @@ import Templates from "../flashduty/zh/1. On-call/3. 配置管理/4.7 配置通
import Link from "../flashduty/zh/1. On-call/5. 集成引导/8.6 其他集成/8.6.1 Link 集成指引.md?raw";
/** ⬆️⬆️⬆️⬆️ Other ⬆️⬆️⬆️⬆️ */
+
+/** ⬇️⬇️⬇️⬇️ Label Mapping API ⬇️⬇️⬇️⬇️ */
+import LabelMappingAPI from "../flashduty/zh/1. On-call/5. 集成引导/8.1 告警集成/8.1.54 标签映射API.md?raw";
+/** ⬆️⬆️⬆️⬆️ Label Mapping API ⬆️⬆️⬆️⬆️ */
const docs = {
CustomAlert,
Email,
@@ -153,6 +157,7 @@ const docs = {
Cloudflare,
WecomAlert,
ServiceDeskPlusSync,
- Harbor
+ Harbor,
+ LabelMappingAPI
};
export default docs;