租户端配置

租户侧的配置都在管理端完成，共三块：Site 与 API Key、域名白名单、全局开关。本文说明每一项的含义、操作步骤与注意事项。

Site 与 API Key

什么是 Site

Site（站点）是租户旗下的一个商城站点，会话按 Site 隔离。一个租户可建多个 Site（如多个商城域名），每个 Site 独立 API Key，便于区分流量与单独停用。

创建 Site 获取 API Key

1. 登录管理端 → 设置 → Site 管理（/settings/sites）
2. 点击 新建 Site：填写站点名称（如 "Demo Mall"）与商城域名（如 shop.example.com，仅作展示记录，不参与校验）
3. 创建成功后 立即复制 API Key（sk_ 开头）

API Key 管理

操作	说明
查看	创建后只完整展示一次，之后仅显示前缀；遗失可重新生成
重新生成	二次确认后生成新 Key，旧 Key 立即失效，商城需同步更新
停用 Site	停用后 SDK 分发返回 404、所有上报被拒（等于强制该站点下线）
删除 Site	二次确认；有关联历史订单的站点不可删除

⚠️ API Key 即站点身份凭证：所有上报请求都携带它，泄露等于他人可冒用你的站点上报。只允许放进商城页面的 HTML/构建产物，严禁出现在日志、仓库、公共前端资源里。

域名白名单

作用

控制哪些域名允许加载 SDK 并上报。管理端 设置 → 全局设置（/settings/general）→「域名白名单」：

• 留空 = 不限制：任何域名都可加载你的 SDK（仅凭 API Key 校验）
• 配置后强制：白名单外的域名上报一律 403（校验依据是请求的 Origin 头，无 Origin 时取 Referer）

这是租户级配置，作用于所有 Site。强烈建议生产环境配置，防止 API Key 泄露后被人冒用嵌入其他站点。

匹配规则

写法	匹配范围	示例
shop.example.com	该域名精确匹配（忽略大小写与端口）	https://shop.example.com:8443 也命中
*.example.com	任意子域（不含裸域）	shop.example.com、api.example.com 命中；example.com 不命中
https://shop.example.com:8443	完整 origin 精确匹配（含 scheme/端口）	特殊端口场景

要点：

• 多个条目用逗号/换行分隔（管理端为 Tag 输入框）
• 本地联调记得把 localhost、127.0.0.1 加入白名单，否则本地页面上报被 403 拦截
• 变更即时生效，无需重启服务
• 若你的网关反代会"清洗请求头"，务必放行 Origin/Referer，否则白名单校验拿不到来源域名

常见配置示例

场景	白名单
商城在 shop.example.com	shop.example.com
商城子域较多（shop./m./api.）	*.example.com（注意裸域不命中，需同时加 example.com）
本地联调	localhost, 127.0.0.1

全局开关

管理端 设置 → 全局设置 的「全局服务开关」，作用于租户下所有 Site：

状态	效果
开启	SDK 正常分发与上报，会话控制流程激活
关闭	① SDK 分发端点返回空脚本，商城不挂载 window.SessionControl；② 服务端硬校验拦截所有上报（已缓存旧 SDK 的浏览器也无法上报）。商城完全走原生结算流程

用途：

• 紧急熔断：出现异常时一键关闭，所有商城立即退回原生结算，无需逐个站点处理
• 灰度上线：先关闭接入，验证商城原生流程稳定后再开启

因为关闭时 SDK 为空脚本，商城接入代码必须做防空判断（if (window.SessionControl)），这是无侵入降级的保障。

同源与反代要求（接入前提）

SDK 内置上报地址是相对路径 /api/shopper/session/*，请求发到承载商城页面的那个域（无 baseURL 可配）。因此页面域下的 /api/* 必须能路由到平台：

拓扑 A：平台域直接承载商城页（同域部署，无需反代）
拓扑 B：商城域反代 /api/* 到平台（推荐，商城保持自有域名）

Nginx 反代示例（拓扑 B，商城侧）：
location /api/ {
    proxy_pass https://api.example.com;          # 平台域名
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # Origin/Referer 头默认透传，请勿在网关层清洗
}

页面在 shop.example、平台在 api.example 的跳域直连不支持。同理，租户自己的建单等接口要避开 /api 前缀（示例用 /order/create），避免与平台反代路径冲突。