mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-10-17 19:35:02 +03:00
Jack
54d1712544
* fix(clients): clarify renewal preview times and estimates The preview rendered RFC3339 strings directly and labeled the server's Local zone without explaining which clock it represented. Its renewal count also looked like a record of renewals already performed. Display readable dates with an explicit UTC offset while preserving the server's wall time, per-date DST offset and fractional cutoff precision. Explain the panel/server timezone and read-only preview, and label the renewal count as estimated allowance consumption in all 13 locales. Let the first-cutoff button wrap on narrow screens and update the English and Chinese client documentation plus display/form regression coverage. This changes presentation only: renewal calculations, stored expiry values, API payloads and first-use behavior remain unchanged. * test(clients): remove redundant renewal preview copy checks The locale-only preview case repeated the Local timezone branch without covering a distinct behavior. Exact textContent comparisons after matching the same text with getByText also only pinned constant wording, contrary to the repository's testing guidance. Remove that duplicate case, its locale setup and the redundant copy assertions. Keep the UTC, per-boundary DST offset, fractional precision and original datetime checks, together with the existing real form-save tests. Production rendering, translations and renewal behavior are unchanged. --------- Co-authored-by: JacktheRanger <219502738+JacktheRanger@users.noreply.github.com>
125 lines
7.9 KiB
Plaintext
125 lines
7.9 KiB
Plaintext
---
|
||
title: 客户端
|
||
description: 管理 3x-ui 客户端——凭据、流量与到期限制、IP 限制、分组、批量操作、外部链接以及在线状态。
|
||
icon: Users
|
||
---
|
||
|
||
**客户端**是由唯一的**电子邮箱**标识的单个用户。在当前版本的
|
||
面板中，客户端是一等记录，可以同时关联到**多个入站**，并对每个客户端单独进行流量统计。
|
||
|
||
## 客户端字段
|
||
|
||
| 字段 | 适用于 | 含义 |
|
||
| -------------- | --------------------- | ------------------------------------------------------------------ |
|
||
| **Email** | 全部 | 用于统计和查询的唯一标识符。 |
|
||
| **ID (UUID)** | VLESS、VMess、TUIC | 客户端凭据。 |
|
||
| **Password** | Trojan、Shadowsocks、TUIC | 客户端凭据。 |
|
||
| **Auth** | Hysteria2 | 客户端凭据。 |
|
||
| **Flow** | VLESS | XTLS 流控，例如 `xtls-rprx-vision`。 |
|
||
| **Limit IP** | 全部（TUIC 除外） | 最大同时连接的源 IP 数量（通过 Fail2ban 强制执行）。 |
|
||
| **Total (GB)** | 全部 | 流量配额；用尽后客户端将被禁用。 |
|
||
| **Expiry** | 全部 | 该日期之后客户端停止工作。 |
|
||
| **自动续期** | 全部 | 关闭、固定天数、日历每周或日历每月。 |
|
||
| **Telegram ID**| 全部 | 将客户端关联到 Telegram 用户，用于自助服务/通知。 |
|
||
| **Sub ID** | 全部 | 用于对该客户端链接分组的订阅标识符。 |
|
||
| **Group** | 全部 | 可选的客户端分组，便于组织管理和批量筛选。 |
|
||
| **Comment** | 全部 | 自由文本备注。 |
|
||
|
||
<Callout type="info">
|
||
达到**流量**或**到期**限制会禁用客户端，手动禁用或删除客户端同样如此；
|
||
此时面板会重启 Xray（`restartXrayOnClientDisable`，默认开启）。
|
||
</Callout>
|
||
|
||
## 限制与 IP 控制
|
||
|
||
- **流量 / 到期**上限达到时会禁用客户端；**Reset** 周期可
|
||
自动续期配额。
|
||
- **Limit IP** 限制同时连接的源 IP 数量。其强制执行依赖于 Fail2ban——
|
||
参见 [安全](/docs/operations/security)。你可以查看某个客户端最近使用的 IP，
|
||
并从该客户端的操作中清除它们。
|
||
- 系统会按客户端（在多节点部署中还会按节点）跟踪**在线状态**和**最后在线**时间。
|
||
|
||
## 自动续期
|
||
|
||
单个客户端和批量创建表单使用统一的续期模式选择：
|
||
|
||
| 模式 | API 字段 | 续期规则 |
|
||
| --- | --- | --- |
|
||
| 关闭 | `reset=0`、`resetDay=0`、`resetWeekday=0` | 不自动延长到期时间。 |
|
||
| 固定天数 | `reset=N`，另两个字段为 `0` | 从上次截止时间增加 N × 24 小时。 |
|
||
| 日历每周 | `resetWeekday=1..7`，另两个字段为 `0` | 在面板时区每周一（1）至周日（7）的零点续期。 |
|
||
| 日历每月 | `resetDay=1..31`、`resetWeekday=0` | 在面板时区指定日的零点续期；短月取月末，之后仍按原配置日续期。 |
|
||
|
||
日历每周跨夏令时仍保持指定星期，不等于固定 7 天。若零点不存在，使用
|
||
该日期第一个有效时刻；零点重复时取第一次。若时区跳过整天，则使用
|
||
下一周的同一星期。旧配置同时填写
|
||
`reset` 和 `resetDay` 时继续以每月续期为准。API 不允许每周续期与正数
|
||
`reset` 或 `resetDay` 同时启用。
|
||
|
||
整自然月应选**每月、1 日**，首次截止时间设置为下月 1 日零点。例如
|
||
`2030-09-01 00:00:00` 表示有效至 `2030-08-31 23:59:59`。
|
||
31 日表示在 31 日**开始时**续期，并不是同一边界。订阅头原有的可选
|
||
月末显示设置仍独立存在，本表单不会自动开启它。
|
||
|
||
日期预览使用面板时区和后端实际续期的同一套计算，显示截止时间、最后
|
||
有效秒、下次到期时间及需要消耗的续期次数。预览不会保存、激活或预留
|
||
续期，也不保证未来一定续期。未设到期时间时自动续期无法运行，可以
|
||
明确点击按钮设置首次日历截止时间；仅选择模式不会修改已有到期时间。
|
||
“首次使用后开始”保留原来的初始天数，激活后才能确定日历日期。
|
||
|
||
预览日期使用公历格式 `YYYY-MM-DD HH:mm:ss UTC±HH:mm`，截止时间中的小数秒
|
||
会原样保留。每个日期分别标注 UTC 偏移，因此跨夏令时续期前后的偏移可能不同。
|
||
标题注明面板时区；**服务器本地时区**指服务器的 `Local` 设置，不是浏览器时区。
|
||
例如 `2026-09-27 05:00:00 UTC+00:00` 对应 UTC+08:00 的 13:00。
|
||
**预计消耗续期次数**是本次预览预计使用的额度，包含补续周期，不是已经执行的
|
||
续期次数。设置首个周期截止时间的按钮使用同样的日期格式；点击后仍需保存表单
|
||
才会持久化修改。
|
||
|
||
旧配置以最后一秒为日历截止时间时，续期边界包含原有的不计次数向下个
|
||
零点对齐规则。但最后有效秒仍按**已存储的到期时间**计算，不会假装
|
||
初始时间已被修改：排他截止时间 `23:59:59` 实际有效至 `23:59:58`。
|
||
整天有效应使用下一个零点，预览本身不会修复首次截止时间。
|
||
|
||
最大续期次数 `resetMax=0` 表示不限次数。正数上限按**每个经过的周期**
|
||
计数，包括离线补续，不按定时任务执行次数或关联入站数量计数。剩余
|
||
次数不足以续到未来时，客户端继续过期且不会重置流量；手动禁用的
|
||
客户端保持禁用。
|
||
|
||
自动续期本身会重置客户端流量。独立的**定期流量重置**不延长到期时间，
|
||
这次未改变其规则；除非需要额外重置，否则保持关闭。本次不包含季度、
|
||
年度和每 N 周/月的续期。
|
||
|
||
<Callout type="warn">
|
||
启用每周续期前，需要升级主面板及所有参与节点。旧版本会忽略
|
||
`resetWeekday`，仅配置每周的客户端将无法自动续期，且在到期或流量
|
||
耗尽后，可能被**删除已耗尽客户端**操作删除，因为旧版没有每周续期
|
||
的清理保护。降级前应备份数据库，并将每周配置转换为所有参与版本
|
||
都支持的续期模式；仅关闭每周续期并不能防止耗尽后的删除。存在
|
||
混合版本或尚未转换的每周客户端时，应避免执行耗尽客户端清理。
|
||
数据库升级默认将新字段设为 `0`，保留已有日期和限制。
|
||
</Callout>
|
||
|
||
## 分享链接与外部链接
|
||
|
||
每个客户端都有针对其各入站的分享链接和二维码，外加一个合并的
|
||
[订阅](/docs/config/subscription)。你还可以为客户端附加**外部
|
||
链接**——额外的 `vless://`、`vmess://`、`trojan://`、`ss://`、
|
||
`hysteria2://` 或 `wireguard://` 链接，或一个远程订阅 URL——使它们
|
||
与面板生成的链接一起出现在该客户端的订阅中。
|
||
|
||
要查看链接的确切内容，可将其粘贴到
|
||
[分享链接检查器](/docs/config/share-links)中。
|
||
|
||
## 批量操作
|
||
|
||
为便于一次性管理大量客户端，面板支持批量**创建、启用、
|
||
禁用、删除、关联/解除关联**（到入站）、**重置流量**以及
|
||
**调整**（增加天数 / 增加字节 / 设置 flow）。维护操作还允许你
|
||
删除**已耗尽**的客户端（配额/到期用尽）和**孤立**的客户端
|
||
（未关联到任何入站）。
|
||
|
||
<Callout type="warn">
|
||
客户端的分享链接包含其凭据。请像对待密码一样对待链接和二维码，
|
||
一旦泄露应立即轮换凭据。
|
||
</Callout>
|