网络安全策略 API 参考

引导您如何通过编程方式控制服务器的本地防火墙设置及允许访问的 IP 列表。

📋 概述

此 API 模块通过控制 GIIP [本地护卫] 功能，实时更新过滤服务器出入站流量的安全策略。

🔐 认证与请求头

所有请求必须包含通用的认证请求头。

• Header: x-giip-ak: [Your Access Key]
• Header: x-giip-sk: [Your Secret Key]

🚀 核心 API 端点

1. 查询各服务器安全规则 (Get Security Rules)

• URL: POST /api/security/rules/list
• 描述: 查询应用于特定服务器的入站/出站允许规则信息。
• 请求体 (Request Body):

{
  "serverIsn": 456
}

2. 添加允许的 IP (Add Allowed IP)

• URL: POST /api/security/rules/add
• 描述: 向防火墙策略中添加一个可以访问特定端口的新 IP 或网段。
• 请求体 (Request Body):

{
  "serverIsn": 456,
  "port": 8080,
  "allowedIp": "1.2.3.4",
  "description": "Dev Team Access"
}

3. 批量部署安全策略 (Deploy Policy)

• URL: POST /api/security/policy/deploy
• 描述: 为特定项目所属的所有服务器一次性应用标准安全策略。
• 请求体 (Request Body):

{
  "projectIsn": 123,
  "policyId": "P-SEC-001"
}

🔍 响应数据示例

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": {
    "affectedServers": 15,
    "status": "In Progress"
  }
}

💡 使用场景

• 动态 IP 白名单: 当居家办公员工连接 VPN 时，自动将其当前 IP 注册到服务器防火墙中。
• 自动响应入侵: 当安全监控系统检测到攻击 IP 时，立即调用 API 在全公司服务器中拦截该 IP。

🛡️ 巧用 Sk3 (高性能日志)

在进行修改安全策略或 IP 白名单等敏感的基础设施控制操作时，为了确保变更历史的完整性并获取详细的审计日志 (Audit Log)，建议使用 giipApiSk3 端点。

• 端点: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 安全优势: 若策略更新失败，系统会立即记录调用者的详细环境信息 (IP, UA) 和堆栈追踪 (StackTrace)，助力快速分析是入侵尝试还是配置错误的原因。
• 使用技巧: 将 text 命令与 jsondata 结合使用，可以在不丢失数据的情况下，安全地管理复杂的安全规则集，从而提升整体基础设施的安全水平。

🔧 故障排除

症状	原因	解决方法
所有请求均以 401/认证错误失败	缺少 x-giip-ak 或 x-giip-sk 请求头，或使用了无效的密钥	确认两个认证请求头均已包含，且所发放的 Access Key/Secret Key 正确无误
POST /api/security/rules/add 响应中的 RstVal 不为 0	缺少 serverIsn，或 allowedIp 格式（IP/网段）错误	按规范重新核对 Request Body 中的 serverIsn、port、allowedIp 值
批量部署策略后 affectedServers 返回 0	projectIsn 错误，或该项目下没有所属服务器	指定正确的 projectIsn 并确认项目下已注册服务器
传输复杂安全规则集时数据丢失	text 命令中的特殊字符未转义	在 giipApiSk3 端点上组合使用 text 与 jsondata 以安全传输参数

---

版本: 1.1 最后更新: 2026-04-11 源文件: giipv3/public/help/api-network-security.zh-CN.md

---

相关文档:

• API 结果代码指南 (RstVal)