HWID 设备限制
HWID 是客户端应用在请求订阅时一并发送的 设备标识符。面板据此判断请求订阅的是 同一台设备而不是新设备，从而可以限制设备数量。
该功能完全可选，且默认关闭。它只对
能够发送 x-hwid 请求头的客户端生效。
如何启用
限制在面板的 Subscription → Settings → HWID Device
Limit 区域中配置，而不是在 .env 中。共有三个参数：开关本身、默认
设备限制和给客户端的公告文本。对于单独的外部分组
可以覆盖设置，而每个用户都可以
设置自己的限制。
| 位置 | 设置什么 |
|---|---|
| 全局订阅设置 | 启用限制、默认限制、公告文本 |
| 外部分组 | 为其用户覆盖全局设置 |
| 用户卡片 | 单个用户的个人设备限制 |
如果用户没有设置限制，则应用默认限制。用户卡片中的值
0 会为他关闭限制：设备仍会被
记录，但订阅始终下发。
如果限制已启用而客户端没有发送 x-hwid 请求头，订阅将不会
下发。启用前请确认你的用户使用的是受支持的
客户端，否则他们会失去访问权限。
客户端发送哪些请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
x-hwid | 是 | 设备标识符 |
x-device-os | 否 | 平台，例如 iOS |
x-ver-os | 否 | 系统版本 |
x-device-model | 否 | 设备型号 |
user-agent | 否 | 应用及其版本 |
x-hwid 的值必须由 10–64 个字符组成：拉丁字母、数字、
符号 = 和 -。如果格式不符合，面板会丢弃整个请求头，
并视为未传递 HWID。
curl -H 'x-hwid: UE42LJXu4DbiCaBv' \
-H 'x-device-os: iOS' \
-H 'x-ver-os: 18.3' \
-H 'x-device-model: iPhone 14 Pro Max' \
https://sub.example.com/XXXXXXXXXXXX
作为响应，面板会添加服务请求头，客户端据此向用户 显示易懂的消息：
| 响应头 | 何时出现 |
|---|---|
x-hwid-active | 面板侧已启用限制 |
x-hwid-not-supported | 限制已启用，但客户端未发送 x-hwid |
x-hwid-max-devices-reached | 已达到设备上限 |
x-hwid-limit | 同上，用于兼容旧客户端 |
保存了什么
每台设备都会写入 hwid_user_devices 表。键是
「HWID + 用户」这一对，因此同一台设备对两个用户来说
算作两条记录。
| 列 | 内容 |
|---|---|
hwid | 设备标识符，最多 64 个字符 |
user_id | 订阅所有者 |
platform | 来自 x-device-os 的平台 |
os_version | 来自 x-ver-os 的系统版本 |
device_model | 来自 x-device-model 的型号 |
user_agent | 来自 user-agent 的应用 |
request_ip | 订阅请求的 IP 地址 |
created_at、updated_at | 设备首次和最后一次出现的时间 |
面板中可以看到什么
用户卡片中会显示他的设备列表：平台、系统 版本、型号、IP 和日期。可以逐个删除设备，也可以清空 整个列表——之后该设备将能重新连接。支持按 HWID 搜索。
在单独的 HWID 页面上汇总了：按平台和
应用的分布、唯一设备和记录总数、平均每用户
设备数，以及设备数最多的用户列表。这些数据也可通过 API 获取——命令
GET /api/hwid/devices、
GET /api/hwid/stats 和 GET /api/hwid/devices/top-users。
设备添加和删除事件（user_hwid_devices.added 和
user_hwid_devices.deleted）会发送到 Webhook。详情
见Webhook一节。
保留期限与隐私
hwid_user_devices 表是数据库中最敏感的表：其中保存着
设备标识符、型号、系统版本、user-agent 和 IP 地址。在你启用自动清理之前，
它不会被自动清理。
| 变量 | 默认值 | 作用 |
|---|---|---|
SERVICE_CLEAN_OLD_LOGS | false | 启用每周清理敏感表 |
HWID_DEVICES_RETENTION_DAYS | 90 | 设备保留多少天 |
计时从 updated_at 开始，即设备最后一次出现的时间：
活跃使用的设备会被保留，而超过期限未再出现的设备
会被删除。任务每周执行一次，在周一夜间。
如果不需要设备历史，可以缩短保留期限，或手动清理 表——通过面板的 Logs 区域或紧急 CLI。
删除设备会解除对订阅分享的防护：如果有空闲名额， 用户就能把它连接到新设备上。在批量清理前请比对 设备列表。