使用文档

快速开始

平台包含两类监控能力：异常监控和性能监控。两者接入方式不同，可以单独启用，也可以同时启用。

异常监控

通过服务器响应头启用浏览器 Reporting API，收集 CSP 违规、网络错误等浏览器原生异常。

接入方式：配置响应头

性能监控

通过页面加载 sdk.js 自动采集 FCP、LCP、CLS、FID、TTFB 等 Web 性能指标。

接入方式：加载脚本

1注册账号 - 访问平台并注册用户账号

2创建站点 - 在控制台中创建您的站点，获取专属 Token

3接入异常监控 - 在网站服务器配置 Reporting API 响应头

4接入性能监控 - 在页面中加载 sdk.js，开始采集性能指标

异常监控

异常监控依赖浏览器 Reporting API。创建站点后，进入「站点管理 → 站点详情 → 生成配置」，选择 Nginx、Apache、Node.js 或 IIS，复制系统生成的配置即可。

1. 配置上报端点

每个站点都有独立 Token，上报地址固定为 /api/report/<token>。

Nginx 异常监控配置 response headers

# Reporting API 上报端点
add_header Reporting-Endpoints 'default="https://api.reportapi.com/api/report/YOUR_SITE_TOKEN"' always;

# CSP 异常上报策略，可按业务需要调整
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'self'; form-action 'self'; report-to default;" always;
                            

2. 检查配置

将 YOUR_SITE_TOKEN 替换为站点创建后生成的实际 Token
异常上报 Token 放在 URL 中，不需要配置 Authorization 请求头
Nginx 配置建议放在 server 块中，并使用 always 确保错误响应也带上响应头
配置后重新加载服务器，例如 Nginx：sudo nginx -s reload

CSP 与测试模式

内容安全策略（CSP）可以帮助您监控资源加载违规和潜在 XSS 风险。首次接入建议先使用只上报不拦截的 Report-Only 模式。

CSP 灰度测试配置 report only

# 只上报，不阻断页面资源，适合灰度测试
add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https:; object-src 'none'; report-to default;" always;

# 验证无误后再切换为强制模式
add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https:; object-src 'none'; report-to default;" always;
                            

CSP 指令说明：

report-to default - 指定使用 Reporting-Endpoints 中名为 default 的端点
default-src 'self' - 默认只允许同源资源
script-src - 脚本源策略
style-src - 样式源策略
img-src - 图片源策略

注意：过于严格的 CSP 会影响页面功能。先使用 Content-Security-Policy-Report-Only 收集数据，确认无误后再切换到 Content-Security-Policy。

查看异常

登录控制台后，您可以：

异常列表

查看所有上报的异常信息
按类型、站点、时间筛选
搜索特定关键词
查看异常详情和完整数据

数据统计

今日/总计异常数量
CSP 违规统计
网络错误统计
站点健康状态

性能监控

性能监控需要在页面中加载平台提供的 sdk.js。SDK 会自动采集 Web 性能指标，并上报到 /api/report/performance/<token>。

和异常监控的区别：异常监控配置服务器响应头；性能监控加载页面脚本。只配置响应头不会自动采集性能指标。

接入 SDK

将以下脚本添加到需要监控的页面中，建议放在 </body> 前：

页面脚本接入 sdk.js

<!-- 建议放在 </body> 前 -->
<script
  src="https://api.reportapi.com/static/sdk.js"
  data-token="YOUR_SITE_TOKEN">
</script>
                            

说明：

将 YOUR_SITE_TOKEN 替换为站点创建后生成的实际 Token
性能监控依赖 sdk.js，不会通过 Reporting API 响应头自动采集
CSP 违规、浏览器原生异常上报依赖服务器响应头；性能指标依赖 SDK
如果页面配置了 CSP，需要允许加载 https://api.reportapi.com/static/sdk.js 并允许连接上报接口

CSP 放行示例

如果您的页面启用了严格 CSP，需要允许脚本加载和接口连接：

SDK CSP 放行 script + connect

script-src 'self' https://api.reportapi.com;
connect-src 'self' https://api.reportapi.com;
                            

支持指标

FCP - 首次内容绘制
LCP - 最大内容绘制
CLS - 累计布局偏移
FID - 首次输入延迟
TTFB - 首字节时间

手动上报示例

如果使用自有采集逻辑，也可以直接调用性能上报 API：

性能指标手动上报 curl

curl -X POST https://api.reportapi.com/api/report/performance/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      {
        "type": "LCP",
        "value": 2300,
        "url": "https://your-website.com/page",
        "deviceType": "desktop",
        "connectionType": "4g"
      }
    ]
  }'
                            

API 参考

上报接口

异常上报地址 endpoint

POST /api/report/<token>

请求体支持浏览器原生 Reporting API 的数组格式，也支持带 reports 字段的对象格式。

请求示例：

异常数据手动上报 curl

curl -X POST https://api.reportapi.com/api/report/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "reports": [
      {
        "type": "csp-violation",
        "url": "https://your-website.com/page",
        "body": {
          "blockedURL": "https://malicious.com/script.js",
          "effectiveDirective": "script-src",
          "documentURL": "https://your-website.com/page"
        }
      }
    ]
  }'
                            

响应示例：

响应示例 json

{
  "status": "accepted",
  "count": 1
}
                            

状态码

202 - 上报已接收
403 - Token 无效或站点不可用
429 - 当日上报额度已用完

常见问题

1. 为什么看不到异常监控数据？

可能的原因：

Token 配置错误
Nginx 响应头未生效
浏览器不支持 Reporting API
没有触发异常类型

2. 为什么看不到性能监控数据？

可能的原因：

页面没有加载 sdk.js
data-token 未配置或 Token 错误
CSP 阻止了 SDK 脚本加载或接口请求
页面刚加载完成，性能数据还没有完成采集和上报

3. 支持哪些浏览器？

Reporting API 支持的现代浏览器：

Chrome 69+
Firefox 78+
Edge 79+
Opera 56+

4. 数据保留多久？

默认情况下，异常数据保留 30 天。您可以在站点设置中调整保留期限。

5. 如何测试异常监控配置是否正确？

您可以在浏览器控制台中执行以下代码，触发一次 CSP 违规测试：

CSP 违规测试脚本 browser console

// 测试 CSP 违规上报
var script = document.createElement('script');
script.src = 'https://malicious.com/test.js';
document.head.appendChild(script);
                            

快速导航

使用文档

快速开始

异常监控

性能监控

异常监控

1. 配置上报端点

2. 检查配置

CSP 与测试模式

CSP 指令说明：

查看异常

异常列表

数据统计

性能监控

接入 SDK

CSP 放行示例

支持指标

手动上报示例

API 参考

上报接口

状态码

常见问题

1. 为什么看不到异常监控数据？

2. 为什么看不到性能监控数据？

3. 支持哪些浏览器？

4. 数据保留多久？

5. 如何测试异常监控配置是否正确？