Velocity-BPA/n8n-nodes-opsgenie

# n8n-nodes-opsgenie 一个用于 **Opsgenie**（Atlassian 基于云的告警和事件管理平台）的综合性 n8n 社区节点。此集成支持针对告警管理、值班调度、事件响应和团队协调的工作流自动化。     ## 功能特性 - **12 个资源类别**，包含 100 多个操作，实现对 Opsgenie API 的完整覆盖 - **告警管理** - 创建、确认、关闭、暂停、升级和管理告警 - **事件响应** - 创建和管理带有时间线跟踪的事件 - **值班调度** - 管理日程、轮换和值班分配 - **团队协调** - 创建团队、管理成员和配置路由规则 - **用户管理** - 包含通知偏好的完整用户生命周期管理 - **升级策略** - 配置多级升级工作流 - **心跳监控** - 通过心跳检查监控系统健康状态 - **策略管理** - 创建具有复杂过滤条件的告警和通知策略 - **Webhook 触发器** - 实时处理告警、事件和日程事件 - **多区域支持** - 同时支持 US 和 EU 的 Opsgenie 区域 ## 安装 ### 社区节点（推荐） 1. 打开 n8n 2. 前往 **Settings** > **Community Nodes** 3. 选择 **Install** 4. 输入 `n8n-nodes-opsgenie` 5. 同意风险提示并点击 **Install** ### 手动安装 ``` # 导航到你的 n8n 安装目录 cd ~/.n8n # 安装包 npm install n8n-nodes-opsgenie # 重启 n8n ``` ### 开发安装 ``` # 克隆 repository git clone https://github.com/Velocity-BPA/n8n-nodes-opsgenie.git cd n8n-nodes-opsgenie # 安装 dependencies npm install # 构建 project npm run build # 创建指向 n8n custom nodes 目录的 symlink mkdir -p ~/.n8n/custom ln -s $(pwd) ~/.n8n/custom/n8n-nodes-opsgenie # 重启 n8n ``` ## 凭证设置 ### Opsgenie API 凭证 | 字段 | 描述 | |-------|-------------| | **API Key** | 来自您的 Opsgenie API 集成的 GenieKey | | **区域** | US (api.opsgenie.com) 或 EU (api.eu.opsgenie.com) | ### 获取 API Key (GenieKey) 1. 登录您的 Opsgenie 账号 2. 前往 **Settings** > **Integrations** 3. 点击 **Add integration** 并选择 **API** 4. 复制生成的 **API Key** 5. 根据需要配置 API 访问权限 ## 资源与操作 ### 告警 (17 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建新告警 | | Get | 通过 ID、别名或 tinyId 获取告警详情 | | Get All | 列出带有过滤和分页的告警 | | Close | 关闭告警 | | Acknowledge | 确认告警 | | Unacknowledge | 取消确认告警 | | Snooze | 将告警暂停指定的持续时间 | | Escalate | 将告警升级给下一响应人 | | Assign | 将告警分配给用户 | | Add Team | 添加团队作为响应人 | | Add Responder | 添加用户、团队或日程作为响应人 | | Add Note | 为告警添加备注 | | Add Tags | 为告警添加标签 | | Remove Tags | 从告警中移除标签 | | Add Details | 添加自定义键值对详情 | | Execute Action | 对告警执行自定义操作 | | Get Request Status | 检查异步请求状态 | ### 事件 (11 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建新事件 | | Get | 获取事件详情 | | Get All | 列出带有过滤条件的事件 | | Close | 关闭事件 | | Resolve | 解决事件 | | Add Responder | 为事件添加响应人 | | Add Note | 添加时间线条目 | | Add Tag | 为事件添加标签 | | Remove Tag | 从事件中移除标签 | | Get Timeline | 获取事件时间线条目 | | Delete Timeline | 删除时间线条目 | ### 团队 (12 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建新团队 | | Get | 获取团队详情 | | Get All | 列出所有团队 | | Update | 更新团队属性 | | Delete | 删除团队 | | Get Members | 列出团队成员 | | Add Member | 向团队添加用户 | | Remove Member | 从团队中移除用户 | | Get Logs | 获取团队活动日志 | | Get Routing Rules | 列出团队路由规则 | | Create Routing Rule | 创建新路由规则 | | Delete Routing Rule | 删除路由规则 | ### 用户 (12 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建新用户 | | Get | 获取用户详情 | | Get All | 列出所有用户 | | Update | 更新用户属性 | | Delete | 删除用户 | | Get Teams | 列出用户的团队成员身份 | | Get Forwarding Rules | 列出转发规则 | | Create Forwarding Rule | 创建转发规则 | | Delete Forwarding Rule | 删除转发规则 | | Get Contacts | 列出用户联系方式 | | Add Contact | 添加联系方式 | | Delete Contact | 删除联系方式 | ### 日程 (9 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建新日程 | | Get | 获取日程详情 | | Get All | 列出所有日程 | | Update | 更新日程属性 | | Delete | 删除日程 | | Get On-Calls | 获取当前值班人员 | | Get Next On-Calls | 获取下一班值班人员 | | Get Timeline | 获取日程时间线 | | Export iCal | 将日程导出为 iCal 文件 | ### 升级 (5 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建升级策略 | | Get | 获取升级详情 | | Get All | 列出所有升级 | | Update | 更新升级策略 | | Delete | 删除升级 | ### 集成 (6 个操作) | 操作 | 描述 | |-----------|-------------| | Get | 获取集成详情 | | Get All | 列出所有集成 | | Enable | 启用集成 | | Disable | 禁用集成 | | Authenticate | 验证集成 | | Get Actions | 获取集成操作 | ### 服务 (5 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建服务 | | Get | 获取服务详情 | | Get All | 列出所有服务 | | Update | 更新服务属性 | | Delete | 删除服务 | ### 维护 (6 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建维护窗口 | | Get | 获取维护详情 | | Get All | 列出维护窗口 | | Update | 更新维护窗口 | | Delete | 删除维护窗口 | | Cancel | 取消活动维护 | ### 心跳 (8 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建心跳监控 | | Get | 获取心跳详情 | | Get All | 列出所有心跳 | | Update | 更新心跳设置 | | Delete | 删除心跳 | | Enable | 启用心跳 | | Disable | 禁用心跳 | | Ping | 发送心跳 Ping | ### 策略 (8 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建告警/通知策略 | | Get | 获取策略详情 | | Get All | 列出策略 | | Update | 更新策略 | | Delete | 删除策略 | | Enable | 启用策略 | | Disable | 禁用策略 | | Change Order | 更改策略执行顺序 | ### 通知规则 (7 个操作) | 操作 | 描述 | |-----------|-------------| | Create | 创建用户通知规则 | | Get | 获取规则详情 | | Get All | 列出用户的通知规则 | | Update | 更新通知规则 | | Delete | 删除通知规则 | | Enable | 启用通知规则 | | Disable | 禁用通知规则 | ## 触发器节点 **Opsgenie Trigger** 节点可实时接收来自 Opsgenie 的 webhook 事件。 ### 支持的事件 - 告警已创建、已确认、已关闭、已暂停 - 告警已升级、已分配、已添加团队 - 告警已添加备注、已添加/移除标签 - 事件已创建、已关闭、已解决 - 心跳已过期 - 日程值班人员已更改 ### Webhook 设置 1. 在 n8n 中，添加一个 **Opsgenie Trigger** 节点并复制 webhook URL 2. 在 Opsgenie 中，前往 **Settings** > **Integrations** 3. 添加一个新的 **Webhook** 集成 4. 粘贴 n8n 的 webhook URL 5. 配置事件过滤器并启用所需的事件类型 6. 保存并激活集成 ## 使用示例 ### 从监控系统创建告警 ``` { "message": "High CPU Usage on Production Server", "alias": "cpu-alert-prod-001", "description": "CPU usage exceeded 90% for 5 minutes", "priority": "P2", "responders": [ { "type": "team", "name": "DevOps" } ], "tags": ["production", "infrastructure", "cpu"], "details": { "server": "prod-web-01", "metric": "cpu_usage", "value": "95%" } } ``` ### 创建带有受影响服务的事件 ``` { "message": "Payment Gateway Outage", "description": "Payment processing is failing for all customers", "priority": "P1", "impactedServices": ["payment-service-id"], "responders": [ { "type": "team", "name": "Payments Team" }, { "type": "user", "username": "oncall@company.com" } ], "notifyStakeholders": true } ``` ### 自动升级工作流 1. **触发器**：Opsgenie Trigger (Alert Created) 2. **检查**：如果优先级为 P1 且在 5 分钟内未得到确认 3. **操作**：升级给下一响应人 4. **通知**：向事件频道发送 Slack 消息 ## Opsgenie 概念 ### 告警优先级 - **P1** - 严重：系统宕机，需要立即采取行动 - **P2** - 高：主要功能受到影响 - **P3** - 中等：部分用户受到影响 - **P4** - 低：轻微问题 - **P5** - 信息：无需立即采取行动 ### 响应人类型 - **User**：按用户名或 ID 标识的单个用户 - **Team**：根据路由规则通知的整个团队 - **Escalation**：遵循升级策略规则 - **Schedule**：通知当前值班人员 ### 标识符类型 许多资源支持多种标识符类型： - **id**：Opsgenie 的唯一标识符 (UUID) - **name**：人类可读的名称（团队、日程、升级） - **alias**：用户定义的去重键（告警） - **tiny**：短 ID 格式（告警） ## 错误处理 该节点处理常见的 Opsgenie API 错误： | 错误码 | 描述 | 解决方案 | |------------|-------------|------------| | 400 | 无效参数 | 检查请求体格式 | | 401 | 无效 API 密钥 | 验证凭证中的 GenieKey | | 403 | 权限不足 | 检查 API 集成权限 | | 404 | 未找到资源 | 验证资源 ID/名称是否存在 | | 409 | 冲突 | 资源已存在 | | 422 | 验证错误 | 检查必填字段 | | 429 | 超出速率限制 | 实施退避重试 | ### 速率限制 - **默认**：每个账号每分钟 3,000 次请求 - 请求头 `X-RateLimit-Remaining` 和 `X-RateLimit-Reset` 跟踪使用情况 - 告警操作是异步的 - 使用 "Get Request Status" 验证是否完成 ## 安全最佳实践 1. **API 密钥安全** - 将 API 密钥存储在 n8n 凭证中，切勿直接写入工作流 - 针对不同的用例使用单独的 API 集成 - 定期轮换 API 密钥 2. **权限控制** - 为 API 集成授予所需的最低权限 - 尽可能使用团队范围的 API 密钥 3. **数据处理** - 注意告警详情中的敏感数据 - 对敏感的自定义字段使用加密 ## 开发 ``` # 安装 dependencies npm install # 构建 project npm run build # 运行 tests npm test # 运行 tests 并生成 coverage npm run test:coverage # Lint 代码 npm run lint # 修复 linting 问题 npm run lint:fix # 格式化代码 npm run format # 用于开发的 Watch mode npm run dev ``` ## 作者 **Velocity BPA** - 网站: [velobpa.com](https://velobpa.com) - GitHub: [Velocity-BPA](https://github.com/Velocity-BPA) ## 许可证 此 n8n 社区节点基于 **Business Source License 1.1** 授权。 ### 免费使用 允许用于个人、教育、研究和内部商业用途。 ### 商业用途 在任何 SaaS、PaaS、托管平台、托管服务或付费自动化产品中使用此节点需要商业许可。 有关许可咨询：**licensing@velobpa.com** 详情请参见 [LICENSE](LICENSE)、[COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md) 和 [LICENSING_FAQ.md](LICENSING_FAQ.md)。 ## 支持 - **问题反馈**: [GitHub Issues](https://github.com/Velocity-BPA/n8n-nodes-opsgenie/issues) - **文档**: [Opsgenie API Docs](https://docs.opsgenie.com/docs/api-overview) - **n8n 社区**: [n8n Community Forum](https://community.n8n.io) ##致谢 - Atlassian 的 [Opsgenie](https://www.atlassian.com/software/opsgenie) 提供事件管理平台 - [n8n](https://n8n.io) 提供工作流自动化平台 - n8n 社区提供节点开发最佳实践

标签：API集成, Atlassian, BPA, escalation policy, heartbeat监控, Incident Response, IT运维, MITM代理, n8n, n8n社区节点, npm包, On-Call排班, Opsgenie, Socks5代理, SRE工具, TypeScript, Webhook触发器, 可观测性, 告警升级, 告警管理, 团队协作, 多区域支持, 安全插件, 工作流自动化, 自动化攻击, 自动化编排, 警报路由, 运维自动化