使用WebTracking采集前端日志

1. 客户端请求凭证：前端应用向业务服务器发起请求，申请用于上传日志的临时访问凭证。

2. 服务器验证并获取临时凭证：业务服务器验证请求合法性后，使用预配置的RAM用户身份，调用阿里云STS的AssumeRole接口，申请扮演一个具备SLS写入权限的RAM角色。

3. STS签发临时凭证：STS验证角色权限后，生成包含AccessKey ID、AccessKey Secret和STS Token等信息的临时凭证。

4. 服务器下发凭证：业务服务器将临时凭证返回给前端应用。

5. 客户端上传日志：客户端使用该临时凭证，通过WebTracking SDK将采集到的日志上传至指定Logstore。

1. 创建供前端应用扮演的RAM角色

此角色是一个没有长期密钥的虚拟身份，专门用于被临时扮演以获取日志写入权限。

1.1 创建RAM角色

操作路径： 登录RAM控制台，在左侧导航栏，选择身份管理 > 角色，单击创建角色。

配置说明：

• 信任主体类型：选择云账号。

• 信任主体名称：选择当前云账号或指定其他云账号。

• 单击确定，输入角色名称sls-web-tracking。

1.2 创建仅允许写入日志的权限策略

此策略精确地限制了上述角色只能向指定的 Logstore 写入日志。

操作路径：在左侧导航栏，选择权限管理 > 权限策略，单击创建权限策略。

配置说明：

• 使用脚本编辑模式，粘贴以下脚本，并将<Project名称>、<Logstore名称>替换为实际的Project、Logstore名称。

  {
    "Version":"1",
    "Statement":[
      {
        "Effect":"Allow",
        "Action":[
          "log:PostLogStoreLogs",
          "log:PutLogs"
        ],
        "Resource":[
          "acs:log:*:*:project/<Project名称>/logstore/<Logstore名称>"
        ]
      }
    ]
  }

• 单击确定，输入策略名称post-logs-policy，完成创建。

1.3 为RAM角色授予日志写入权限

将上一步创建的写入权限赋予前端扮演的角色。

操作路径：在左侧导航栏，选择身份管理 > 角色，单击目标角色名称，进入角色详情页，在权限管理模块单击新增授权。

配置说明：

• 在新增授权面板中，搜索并选中上一步创建的自定义权限策略（sls-logstore-write-policy）。

• 单击确认授权，完成权限绑定。

2. 创建供后端服务使用的RAM用户

此用户拥有一个长期 AccessKey，用于向 STS 服务发起扮演角色的请求。

2.1 创建RAM用户

操作路径：  登录RAM控制台，在左侧导航栏，选择身份管理 > 用户，单击创建用户。

配置说明：

• 登录名称：仅支持英文字母、数字、半角句号（.）、短划线（-）和下划线（_），最多64个字符，如：sls-token-service。

• 访问方式：勾选使用永久 AccessKey 访问。

• 其余配置保持默认，单击确定，完成创建，并保存 AccessKey ID 和 AccessKey Secret信息。

  AccessKey Secret 仅在创建时显示一次，不支持后续查询，请务必立即保存至安全位置。

2.2 为RAM用户授予角色扮演的权限

操作路径：单击目标用户名称，进入用户详情页，切换到权限管理页签，单击新增授权。

配置说明：

• 在权限策略模块，勾选AliyunSTSAssumeRoleAccess策略。

• 其余配置保持默认，单击确认新增授权，完成权限绑定。

小结：后端服务使用 RAM 用户（AK/SK）扮演 sls-web-tracking 角色，生成临时安全凭证返回给前端应用，WebTracking SDK 使用临时凭证安全上传日志。

步骤二：搭建后端STS临时凭证服务

需搭建一个后端接口，用于接收前端的凭证请求，并安全地返回 STS 临时凭证，以下以Python + Flask 为例。

您可根据实际技术栈参考附录一：多语言STS示例，选择 Java、Node.js等其他语言实现。

1. 准备服务器环境

在实际部署时，您可以将调用STS服务的接口集成到自己的业务服务器中，而无需单独准备服务器，也可以将接口单独部署，只需确保该服务器满足如下要求：

• 前端应用可通过 HTTP(S) 访问该服务器。

• 安装Python3环境，推荐Python3.8及以上版本。

执行如下命令，安装调用阿里云STS服务接口所需的依赖库。

# 安装 Flask Web 框架及阿里云 SDK 相关的依赖库
pip3 install Flask==3.1.2
pip3 install aiohttp==3.8.4
pip3 install alibabacloud-credentials==0.3.2
pip3 install alibabacloud-sts20150401==1.1.3
pip3 install alibabacloud-tea==0.3.2
pip3 install alibabacloud-tea-openapi==0.3.7
pip3 install alibabacloud-tea-util==0.3.8
pip3 install alibabacloud-tea-xml==0.0.2

2. 编写后端STS服务代码

创建一个HTTP接口 /get_sts_token，用于生成并返回STS临时凭证。

2.1 创建项目目录与文件

# 创建并进入项目目录
mkdir my_web_sample
cd my_web_sample
touch main.py

2.2 编辑main.py文件

请将以下代码粘贴至 main.py 文件，并将 <YOUR_ROLE_ARN> 替换为RAM 角色 sls-web-tracking 对应的 ARN， <YOUR_ROLE_SESSION_NAME> 替换为自定义的会话名称（例如role_session_test）。

import json
from flask import Flask, render_template
from alibabacloud_tea_openapi.models import Config
from alibabacloud_sts20150401.client import Client as Sts20150401Client
from alibabacloud_sts20150401 import models as sts_20150401_models
from alibabacloud_credentials.client import Client as CredentialClient

app = Flask(__name__)

# ================== 用户配置区 ==================
# 替换为您的 RAM 角色 ARN，格式：acs:ram::${accountId}:role/${roleName}
role_arn_for_sls_upload = '<YOUR_ROLE_ARN>'

# 设置角色会话名称（建议唯一标识请求来源）
role_session_name = '<YOUR_ROLE_SESSION_NAME>'  # 如：sls-web-session-001

# STS服务所在地域，例如cn-hangzhou。
region_id = 'cn-hangzhou'
# ==============================================

@app.route("/")
def hello_world():
    return render_template('index.html')

@app.route('/get_sts_token', methods=['GET'])
def get_sts_token():
    """
    接口：/get_sts_token
    方法：GET
    功能：调用 STS AssumeRole 接口获取临时安全令牌
    返回：JSON 格式的 Credentials 对象
    """
    # 初始化 CredentialClient 时不指定参数，代表使用默认凭据链。
    # 在本地运行程序时，可以通过环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET 指定 AK；
    # 在 ECS\ECI\容器服务上运行时，可以通过环境变量 ALIBABA_CLOUD_ECS_METADATA 来指定绑定的实例节点角色，SDK 会自动换取 STS 临时凭证。
    config = Config(
        region_id=region_id,
        credential=CredentialClient()
    )
    sts_client = Sts20150401Client(config=config)

    # 构造 AssumeRole 请求
    assume_role_request = sts_20150401_models.AssumeRoleRequest(
        role_arn=role_arn_for_sls_upload,
        role_session_name=role_session_name,
    )
      
    # 调用 STS 获取临时凭证
    response = sts_client.assume_role(assume_role_request)
    
    token = json.dumps(response.body.credentials.to_map())
    return token


app.run(host="0.0.0.0", port=80)

3. 启动后端服务

执行如下命令，使用步骤一中创建的RAM用户的访问密钥启动服务：

ALIBABA_CLOUD_ACCESS_KEY_ID=<YOUR_AK_ID> 
ALIBABA_CLOUD_ACCESS_KEY_SECRET=<YOUR_AK_SECRET> 
python3 main.py

4. 验证接口是否正常工作

发送测试请求：

curl http://<服务器公网IP地址>/get_sts_token

成功响应示例：

{
  "AccessKeyId": "STS.L4xxxxxx",
  "AccessKeySecret": "Dcyyyyyyyy",
  "Expiration": "2025-04-05T10:30:00Z",
  "SecurityToken": "CAISzxxxxxxxxxxx..."
}

验证要点：

• 返回字段包含 AccessKeyId, AccessKeySecret, SecurityToken。

• AccessKeyId 以 STS. 开头，表示是临时凭证。

• Expiration 表示过期时间，应在合理范围内。

步骤三：前端集成WebTracking SDK

在前端应用（浏览器或小程序）中集成 SDK，并配置 STS 插件以实现安全授权和日志上报。完整示例工程请参见附录二：前端应用示例工程。

1. 安装SDK依赖

使用 npm 安装 WebTracking SDK 及其 STS 插件：

npm install --save @aliyun-sls/web-track-browser
npm install --save @aliyun-sls/web-sts-plugin

2. 初始化 SDK 并配置 STS 身份验证

在前端项目中创建一个用于初始化日志采集器的 JavaScript 文件，例如index.js。该文件负责初始化 SlsTracker 实例，配置 STS 临时凭证插件。

2.1 引入核心模块

import SlsTracker from "@aliyun-sls/web-track-browser";
import createStsPlugin from "@aliyun-sls/web-sts-plugin";

2.2 配置日志服务基础信息

请根据您的实际资源信息填写以下参数：

const opts = {
  host: "${endpoint}", // 所在地域的服务入口。例如cn-hangzhou.log.aliyuncs.com
  project: "${project}", // Project 名称
  logstore: "${logstore}", // Logstore 名称
  time: 10, // 发送日志的时间间隔，默认是10秒
  count: 10, // 发送日志的数量大小，默认是10条
  topic: "topic", // 自定义日志主题
  source: "source",
  tags: {
    tags: "tags",
  },
};

2.3 配置STS插件以实现安全授权

为保障安全性，前端应用不应持有长期 AccessKey。推荐通过后端服务获取临时安全令牌（STS Token），并通过插件动态刷新。

const stsOpt = {
  accessKeyId: "",
  accessKeySecret: "",
  securityToken: "",
  
  // 刷新 STS Token 的异步函数
  refreshSTSToken: () =>
    new Promise((resolve, reject) => {
      const xhr = new window.XMLHttpRequest();
      xhr.open("GET", "http://<ECS实例公网IP地址>/get_sts_token", true);
      xhr.send();
      
      xhr.onreadystatechange = () => {
        if (xhr.readyState === 4) {
          if (xhr.status === 200) {
            let credential = JSON.parse(xhr.response);
            // 更新临时凭证
            stsOpt.accessKeyId = credential.AccessKeyId;
            stsOpt.accessKeySecret = credential.AccessKeySecret;
            stsOpt.securityToken = credential.SecurityToken;
            resolve();
          } else {
            reject("Wrong status code.");
          }
        }
      };
    }),
   // （可选）自定义刷新频率，默认 5 分钟（300000ms）
  // refreshSTSTokenInterval: 300000,
  
  // （可选）设置 token 过期前多久提前刷新（单位毫秒）
  // stsTokenFreshTime: undefined,
};

2.4 初始化Tracker实例并启用STS插件

// 创建 tracker 实例
const tracker = new SlsTracker(opts);

// 创建并注册 sts 插件
const stsPlugin = createStsPlugin(stsOpt);
tracker.useStsPlugin(stsPlugin);

3. 在业务代码中上报日志

在需要追踪用户行为的地方，调用 tracker.send() 方法。

document.getElementById("loginButton").addEventListener("click", () => {
  const username = document.getElementById("username").value;
  
  tracker.send({
    eventType: "login",
    username: username,
  });
  
  console.log("Login event tracked for:", username);
});

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <title>用户行为监控示例</title>
</head>
<body>
  <input type="text" id="username" placeholder="请输入用户名" />
  <button id="loginButton">登录</button>

  <!-- 使用模块化脚本 -->
  <script type="module" src="/static/js/index.js"></script>
</body>
</html>

<!-- 待办事项页面：支持输入任务名称并添加 -->
<input placeholder="请输入任务名称" bindinput="onInput" />
<button bindtap="onAddTodo">Add Todo</button>

// 引入已初始化的 tracker 实例（建议全局单例管理）
const { tracker } = require('../../utils/tracker');

Page({
  data: {
    inputValue: ''
  },

  onInput(e) {
    this.setData({ inputValue: e.detail.value });
  },

  onAddTodo() {
    const todoTitle = this.data.inputValue.trim();
    if (!todoTitle) return;

    // 上报“添加待办”事件
    tracker.send({
      eventType: "add_todo",
      title: todoTitle,
      timestamp: Date.now(),
      platform: "mini-program",
      appId: my.getAppId ? my.getAppId() : wx.getAccountInfoSync().miniProgram.appId
    });

    console.log('Todo added and event tracked:', todoTitle);

    // 其他业务逻辑...
    this.setData({ inputValue: '' });
  }
});