mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-10-22 13:55:01 +03:00
Jack
881f646d2c
* fix(clients): balance renewal form layout and mode guidance Move renewal out of the traffic-reset half-column so its help and preview no longer leave a tall empty area beside the reset selector. Keep the mode, active schedule field and renewal limit in equal desktop columns, stack them on small screens, and preserve the bulk form's stacked layout. Keep monthly traffic-reset controls together in their own row and allow the first-cutoff button to wrap without shrinking its click target. Show fixed-duration guidance only for interval renewal and the month-end boundary note only for monthly renewal. Synchronize all thirteen locales and the client docs, remove obsolete zero-value mode-switching tooltips, and cover the help transitions through the real client form. Keep preview markup and existing monthly copy intact so the independent date-display work in #6662 can merge without overlapping these edits. This is presentation-only: saved values, expiry selection, renewal and traffic-reset calculations, APIs and database formats are unchanged. * refactor(clients): drop the renewal CSS that #6662 made redundant #6662 landed the full-width preview Space and the wrapping first-cutoff Button as inline styles, so ClientRenewalFields.css and its wrapper div styled the same two elements a second time; both are removed. * test(tuic): wait for downstream association activity refresh The UDP lifecycle regression can receive its QUIC response before the server's sending goroutine updates the association timestamp. Reading the protected field once then mistakes a valid scheduling order for a missing refresh, intermittently failing the race-enabled CI job. Wait for lastActive to advance under the registry mutex, bounded by a one-second deadline, before checking idle reaping. Retain the payload, association ID, idle-survival and shutdown assertions so a missing activity update still fails the test. This only changes test synchronization. Production relay behavior, renewal logic, network timeouts and CI configuration remain unchanged. --------- Co-authored-by: JacktheRanger <219502738+JacktheRanger@users.noreply.github.com> Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com>
146 lines
8.4 KiB
Plaintext
146 lines
8.4 KiB
Plaintext
---
|
||
title: Clients
|
||
description: Manage 3x-ui clients — credentials, traffic and expiry limits, IP limits, groups, bulk actions, external links, and online status.
|
||
icon: Users
|
||
---
|
||
|
||
A **client** is a single user, identified by a unique **email**. In the current
|
||
panel, clients are first-class records that can be attached to **multiple
|
||
inbounds** at once, with per-client traffic accounting.
|
||
|
||
## Client fields
|
||
|
||
| Field | Applies to | Meaning |
|
||
| -------------- | --------------------- | ------------------------------------------------------------------ |
|
||
| **Email** | all | Unique identifier used for accounting and lookups. |
|
||
| **ID (UUID)** | VLESS, VMess, TUIC | The client credential. |
|
||
| **Password** | Trojan, Shadowsocks, TUIC | The client credential. |
|
||
| **Auth** | Hysteria2 | The client credential. |
|
||
| **Flow** | VLESS | XTLS flow, e.g. `xtls-rprx-vision`. |
|
||
| **Limit IP** | all (except TUIC) | Max simultaneous source IPs (enforced via Fail2ban). |
|
||
| **Total (GB)** | all | Traffic quota; the client is disabled when exhausted. |
|
||
| **Expiry** | all | Date after which the client stops working. |
|
||
| **Auto renewal** | all | Disabled, fixed interval in days, calendar weekly, or calendar monthly. |
|
||
| **Telegram ID**| all | Links the client to a Telegram user for self-service/notifications.|
|
||
| **Sub ID** | all | Subscription identifier grouping this client's links. |
|
||
| **Group** | all | Optional client group for organization and bulk filtering. |
|
||
| **Comment** | all | Free-text note. |
|
||
|
||
<Callout type="info">
|
||
Reaching the **traffic** or **expiry** limit disables the client, and a client
|
||
disabled or deleted by hand counts too; the panel restarts Xray then
|
||
(`restartXrayOnClientDisable`, on by default).
|
||
</Callout>
|
||
|
||
## Limits and IP control
|
||
|
||
- **Traffic / expiry** caps disable the client when hit; a **Reset** period
|
||
auto-renews the quota.
|
||
- **Limit IP** caps simultaneous source IPs. Enforcement relies on Fail2ban —
|
||
see [Security](/docs/operations/security). You can view a client's recent IPs
|
||
and clear them from the client's actions.
|
||
- **Online status** and **last-online** times are tracked per client (and per
|
||
node in multi-node setups).
|
||
|
||
## Automatic renewal
|
||
|
||
The individual and bulk-create forms offer one renewal mode at a time:
|
||
|
||
In the individual form, the mode, its day/weekday setting, and the renewal limit
|
||
share a row on desktop and stack on mobile. Help and the read-only preview use
|
||
the full width below them. The bulk-create form keeps its stacked fields. Help
|
||
follows the selected mode; the day-1/month-end note appears only for monthly
|
||
renewal. Independent traffic-reset settings remain separate.
|
||
|
||
| Mode | API fields | Schedule |
|
||
| --- | --- | --- |
|
||
| Disabled | `reset=0`, `resetDay=0`, `resetWeekday=0` | The expiry is not renewed. |
|
||
| Fixed interval | `reset=N`, other two fields `0` | Add exactly N × 24 hours to the previous cutoff. |
|
||
| Calendar weekly | `resetWeekday=1..7`, other two fields `0` | Renew at panel-local midnight on Monday (1) through Sunday (7). |
|
||
| Calendar monthly | `resetDay=1..31`, `resetWeekday=0` | Renew at panel-local midnight on that day; missing dates clamp to the month's last day without losing the configured day. |
|
||
|
||
Calendar weeks stay on the selected weekday across daylight-saving changes;
|
||
they are not equivalent to a fixed seven-day interval. A skipped midnight uses
|
||
the first valid instant of that date; a repeated midnight uses the first one.
|
||
If a timezone skips the entire selected date, the next matching week is used.
|
||
Existing monthly clients
|
||
that also have `reset` set retain monthly precedence. The API rejects weekly
|
||
renewal combined with a positive `reset` or `resetDay`.
|
||
|
||
For a full calendar month, select **monthly, day 1** and set the initial cutoff
|
||
to the next month's first midnight. For example, `2030-09-01 00:00:00` is valid
|
||
through `2030-08-31 23:59:59`. Day 31 renews at the **start** of the 31st and is
|
||
not the same schedule. The existing optional month-end subscription-header
|
||
display remains a separate setting and is not enabled by this form.
|
||
|
||
The preview uses the panel's timezone and the same calendar/catch-up calculation
|
||
as automatic renewal. It shows the cutoff, last valid second, next expiry, and
|
||
allowances needed. It is informational: it does not save, activate, reserve, or
|
||
guarantee a future renewal. When no expiry is set, auto-renewal cannot run; an
|
||
explicit button can set the first calendar cutoff. Selecting a mode alone never
|
||
rewrites an existing expiry. First-use clients keep their initial duration, and
|
||
their calendar dates are available after activation.
|
||
|
||
Preview dates use the Gregorian format `YYYY-MM-DD HH:mm:ss UTC±HH:mm`,
|
||
preserving any fractional seconds in the cutoff. Each date includes its own
|
||
UTC offset, so a daylight-saving change can show different offsets before and
|
||
after renewal. The heading identifies the panel time zone; **Server local time**
|
||
means the server's `Local` setting, not the browser's time zone. For example,
|
||
`2026-09-27 05:00:00 UTC+00:00` is 13:00 in UTC+08:00. **Estimated renewals used**
|
||
is the allowance this preview would consume, including any catch-up periods,
|
||
not a count of renewals already performed. The first-cutoff button uses the same
|
||
date format; clicking it still requires saving the form to persist the change.
|
||
|
||
For legacy last-second calendar cutoffs, the renewal boundary includes the
|
||
existing free alignment to the following midnight. The last-valid-second
|
||
preview still uses the **stored expiry**, not that alignment: an exclusive
|
||
`23:59:59` cutoff is valid through `23:59:58`. Use a next-midnight cutoff for
|
||
full-day validity; the preview itself does not repair the initial expiry.
|
||
|
||
`resetMax=0` means unlimited renewals. A positive limit counts **each elapsed
|
||
period**, including offline catch-up, not each scheduler tick or attached inbound.
|
||
If the remaining allowances cannot reach a future cutoff, the client stays
|
||
expired and its traffic is not reset. Operator-disabled clients stay disabled.
|
||
|
||
Renewal already resets client traffic. The separate **periodic traffic reset**
|
||
does not move the expiry and is unchanged; keep it disabled unless you intend an
|
||
additional reset. Quarterly, yearly, and every-N-week/month schedules are not
|
||
part of these modes.
|
||
|
||
<Callout type="warn">
|
||
Upgrade the main panel and every participating node before enabling weekly
|
||
renewal. Older versions ignore `resetWeekday`; a weekly-only client would not
|
||
auto-renew and, after its expiry or quota is exhausted, can be deleted by
|
||
**delete depleted clients** because older versions lack the weekly protection.
|
||
Back up the database and convert weekly schedules to a renewal mode supported
|
||
by every participating version before downgrading. Merely disabling weekly
|
||
renewal does not protect a depleted client from deletion. Avoid depleted-client
|
||
cleanup while a mixed-version fleet or unconverted weekly clients remain.
|
||
Database upgrades default this new field to `0` and preserve existing limits
|
||
and dates.
|
||
</Callout>
|
||
|
||
## Share links and external links
|
||
|
||
Every client has share links and a QR code for its inbounds, plus a combined
|
||
[subscription](/docs/config/subscription). You can also attach **external
|
||
links** to a client — extra `vless://`, `vmess://`, `trojan://`, `ss://`,
|
||
`hysteria2://`, or `wireguard://` links, or a remote subscription URL — so they
|
||
appear alongside the panel-generated ones in the client's subscription.
|
||
|
||
To inspect exactly what a link contains, paste it into the
|
||
[share-link inspector](/docs/config/share-links).
|
||
|
||
## Bulk actions
|
||
|
||
For managing many clients at once, the panel supports bulk **create, enable,
|
||
disable, delete, attach/detach** (to inbounds), **reset traffic**, and
|
||
**adjust** (add days / add bytes / set flow). Maintenance actions also let you
|
||
delete **depleted** clients (quota/expiry exhausted) and **orphaned** clients
|
||
(not attached to any inbound).
|
||
|
||
<Callout type="warn">
|
||
A client's share link contains its credential. Treat links and QR codes like
|
||
passwords, and rotate the credential if one leaks.
|
||
</Callout>
|