# Renaming: 3x-ui / x-ui → L-UI / l-ui / lui-agent

Base: `8158ced` (panel V2.6.0 / agent A2.5.0). This batch is a pure
rename: **no version bump, no feature change, no production change,
no Gitea change, no release**. Versions stay V2.6.0 / A2.5.0; the
version bump is left to the release step (see Pending below).

## Mapping (exact — do not invent other aliases)

| old | new | where it shows up |
| --- | --- | --- |
| display brand `3x-ui` / `x-ui` | `L-UI` | panel UI, i18n, README, docs |
| panel binary / process | `l-ui` | release asset, `ps`, `/usr/bin/l-ui` (Docker), `l-ui setting …` |
| agent binary / process | `lui-agent` | release asset, `ps`, `lui-agent agent …` |
| install dir | `/usr/local/l-ui` | panel + agent binaries |
| config / state dir | `/etc/l-ui` | `agent.json`, `node_token_key.json`, env files |
| panel DB | `/etc/l-ui/l-ui.db` | driven by `internal/config/name` (`l-ui`) via `GetName()` + `GetDBFolderPath()` — no separate DB-name constant |
| probe DB | `/etc/l-ui/probe.db` | name unchanged, directory moved (`probe/store.go` joins `GetDBFolderPath()`) |
| cert dir | `/etc/l-ui/cert` | panel + subscription share it |
| binary dir | `/usr/local/l-ui/bin` | `DefaultBinFolder`; sing-box live config `config-singbox.json` lives here |
| log dir | `/var/log/l-ui` | panel log, agent log, sing-box log |
| panel service | `l-ui.service` | systemd units `l-ui.service.{debian,arch,rhel}`, OpenRC `l-ui.rc` |
| agent service | `lui-agent.service` | `systemd/lui-agent.service`, OpenRC `openrc/lui-agent` |
| management CLI | `l-ui.sh` | was `x-ui.sh`; Docker copies it to `/usr/bin/l-ui` |
| panel release assets | `l-ui-linux-amd64`, `l-ui-linux-arm64` (+ `.sha256`) | `scripts/release-build.sh`, `selfupdate.AssetName` |
| agent release assets | `lui-agent-linux-amd64`, `lui-agent-linux-arm64` (+ `.sha256`) | `scripts/release-build.sh`, `selfupdate.AgentAssetName` |
| agent version marker | `agent-version.txt` | name unchanged |
| env prefix | `LUI_` | every `XUI_` variable, code + scripts + docs + tests (inventory below) |
| source dir (Linux agent) | `cmd/lui-agent` | was `cmd/xui-agent`; `release-build.sh` builds `./cmd/lui-agent` |
| Gitea repo (PLACEHOLDER) | `rogue/l-ui` | see Pending — **not yet real** |

## Environment variables renamed

Code reads **only** the new `LUI_` prefix. There is no dual-read
fallback in code: an old unit file that still exports `XUI_*` will
silently lose those settings, which is why the migration doc
(`docs/migration-l-ui.md`) has an explicit unit-env translation
table. Old units must be replaced, not edited in place.

Full inventory (from a whole-tree scan; `LUI_DB_*` below is a docs
glob, not a variable):

`LUI_ACCESS_URL`, `LUI_ACME_EMAIL`, `LUI_ACME_HTTP_PORT`,
`LUI_API_TOKEN`, `LUI_B1_OLD_BACKUP`, `LUI_B2_OLD_DB`,
`LUI_BIN_FOLDER`, `LUI_DB_CACHE_MB`, `LUI_DB_DSN`,
`LUI_DB_FOLDER`, `LUI_DB_JOURNAL_MODE`, `LUI_DB_MAX_IDLE_CONNS`,
`LUI_DB_MAX_OPEN_CONNS`, `LUI_DB_MMAP_MB`, `LUI_DB_SYNCHRONOUS`,
`LUI_DB_TYPE`, `LUI_DEBUG`, `LUI_DOMAIN`, `LUI_ENABLE_FAIL2BAN`,
`LUI_GOGC`, `LUI_HOME` (install-agent.sh only), `LUI_INIT_SYSTEM`
(install-agent.sh only), `LUI_INIT_WEB_BASE_PATH`, `LUI_IN_DOCKER`,
`LUI_LOG_FOLDER`, `LUI_LOG_LEVEL`, `LUI_MAIN_FOLDER`,
`LUI_MEMORY_LIMIT`, `LUI_MEMORY_RELEASE_INTERVAL`,
`LUI_NODE_TOKEN_KEY`, `LUI_NODE_TOKEN_KEY_FILE`,
`LUI_NODE_TOKEN_KEY_TEST`, `LUI_NONINTERACTIVE`,
`LUI_ORPHAN_DUMMY`, `LUI_PANEL_PORT`, `LUI_PASSWORD`, `LUI_PORT`,
`LUI_PPROF`, `LUI_RELEASE_BASE_URL`, `LUI_RELEASE_LATEST_URL`,
`LUI_ROOT` (install-agent.sh only), `LUI_SCALE_DB_PATH`,
`LUI_SCALE_SIZES`, `LUI_SCALE_TEST`, `LUI_SELFUPDATE_SYSTEMD`,
`LUI_SERVER_IP`, `LUI_SERVICE`, `LUI_SERVICE_NAME`,
`LUI_SINGBOX_BIN`, `LUI_SKIP_HSTS`, `LUI_SMOKE_VERSION`,
`LUI_SOURCEMAP`, `LUI_SSL_IPV6`, `LUI_SSL_MODE`,
`LUI_TEST_PG_DSN`, `LUI_TUNNEL_HEALTH_COOLDOWN`,
`LUI_TUNNEL_HEALTH_FAILURES`, `LUI_TUNNEL_HEALTH_INTERVAL`,
`LUI_TUNNEL_HEALTH_MONITOR`, `LUI_TUNNEL_HEALTH_PROXY`,
`LUI_TUNNEL_HEALTH_TIMEOUT`, `LUI_TUNNEL_HEALTH_URL`,
`LUI_UPDATE_RUN_ID`, `LUI_UPDATE_STATUS_FILE`, `LUI_UPDATE_TAG`,
`LUI_URL` (install scripts only), `LUI_USERNAME`,
`LUI_WEB_BASE_PATH`.

## sing-box orphan-core check (special re-verification)

The orphan scan (`internal/agent/singbox.go`,
`singboxCmdlineMatchesConfig`) matches a core process by the exact
argv triple `run -c <live config path>`. Both sides use the same
source: the live path is `filepath.Join(config.GetBinFolderPath(),
"config-singbox.json")`, and the agent sets `LUI_BIN_FOLDER` to
`DefaultBinFolder` (`/usr/local/l-ui/bin`) when unset. So the rename
propagates to both the writer and the matcher automatically; there
is no hardcoded old path in `singbox.go`. After migration the only
cores the new agent will reap are cores started with
`/usr/local/l-ui/bin/config-singbox.json` — a core still running
the old `/usr/local/x-ui/bin/config-singbox.json` is **not** matched
and must be killed by the migration step (see migration doc), or it
will hold the inbound ports and the new core will fail to bind.
This is the one place where "rename both sides" is not enough: the
old core has to be stopped, not re-adopted.

## Tianyi update badge (same batch, panel side only)

- Backend: `NodeView.agentOs` (from `AgentNode.ProbeOS`), overlaid
  in `annotateAgentTelemetry` ahead of the telemetry early-exit,
  like `ProbeOnly`.
- Frontend: both badge sites in `NodeList.tsx` (list column +
  detail) now gate on `!isWindowsAgentOS(agentOs)`, where the
  helper (in `panel-version.ts`) is a case-insensitive `windows`
  prefix test. Empty OS fails open (badge as before).
- Backend: `requestAgentUpdate` refuses Windows rows up front
  ("not available on Windows … re-running install-agent.ps1")
  instead of recording an intent that would only age out. The
  one-click action button itself is unchanged; clicking it on a
  Windows row now errors clearly.
- Why ProbeOS is reliable: the frozen A2.2.1 Windows agent reports
  `probeFacts.os` = `winOSName()` — registry ProductName
  ("Windows 10", "Windows 11", …) with DisplayVersion appended,
  falling back to bare "Windows" — on register and on heartbeat,
  and the panel persists it to `probe_os` (pinned by
  `TestAgentLegacyWindows221Contract`). No fake version, no
  per-node freeze switch, no Windows agent change, no new win asset.
- Tianyi's machine itself is untouched; its agent stays A2.2.1.

## Intentionally kept (not omissions)

- **Go module path `github.com/mhsanaei/3x-ui/v3`** — the upstream
  import path. Renaming it would break every import and the
  `-ldflags -X` injection paths; it is not user-visible.
- **Upstream mentions** — sentences that name the upstream original
  ("upstream 3x-ui", "stock 3x-ui", "based on upstream 3x-ui",
  `ghcr.io/mhsanaei/3x-ui`, `raw.githubusercontent.com/mhsanaei/3x-ui`)
  stay, because that is the upstream project's actual name.
- **Windows agent, frozen** — `cmd/xui-agent-windows/` untouched:
  service name `x-ui-agent`, `C:\x-ui\agent.json`, display name
  "3x-ui Agent", `x-ui-agent-windows.exe`. The shipped A2.2.1
  binary cannot change without a new win release, which this batch
  explicitly does not ship. Renaming its source would only make
  the source lie about the shipped binary.
- **`install-agent.ps1` untouched** — see Pending.
- **Log filenames `3xui.log`, `3xipl.log`, `3xipl-banned.log` and
  the fail2ban jail name `3x-ipl`** — only their directory moves
  (`/var/log/l-ui/`). Renaming the files would break external
  fail2ban configs beyond the directory move the migration
  already requires.
- **Docker Postgres user/DB `xui`** — renaming them would orphan
  existing `pgdata` volumes (a fresh empty DB would appear and
  the panel would start empty). Service/container names were
  renamed (`l-ui`, `l-ui_app`, `l-ui_postgres`); credentials kept.
- **Windows-only DB copy in `internal/config/config.go` `init()`** —
  its source is now explicitly `/etc/x-ui/x-ui.db` (the only
  pre-rename path left in Go code, as a copy source only). Normal
  operation never reads it; operator migration moves the DB by mv.
- **`install-agent.sh` legacy-process kill** — it now kills both
  `/usr/local/l-ui/l-ui agent` and `/usr/local/x-ui/x-ui agent`.
  The old form is a one-time migration cleanup, not a runtime
  dual-path fallback; it can be deleted once old forms are gone.
- **`frontend/src/generated/schemas.ts`** — generated by
  `tools/openapigen`, marked DO NOT EDIT. Its three "3x-ui panel"
  descriptions come from Go model comments and will refresh on
  the next regeneration; hand-editing a generated file would be
  overwritten anyway.
- **Tracked test binaries `x-ui-agent-test-amd64`,
  `x-ui-master-new-amd64`, `x-ui-with-ui-amd64`** — stale ELF
  artifacts committed earlier, not referenced by any script or by
  `release-build.sh`, not release assets. Left untouched (not
  rebuilt, not renamed); deleting committed binaries is a separate
  cleanup decision, not part of this rename.
- **`docs/release.md` version-table examples (V2.4.0 / A2.3.0)** —
  pre-existing stale examples, not version constants; left as-is
  so this diff stays a rename. The agent-change glob there now
  reads `cmd/lui-agent*`, which correctly excludes the frozen
  Windows dir (Windows-only changes must not move the agent line).

## Pending / must be decided before any release

1. **Gitea repo spelling (BLOCKER).** `rogue/l-ui` is a placeholder.
   The Gitea repo has NOT been renamed in this batch and must not
   be assumed renamed. Before any release: user confirms the exact
   spelling, then update `internal/selfupdate/selfupdate.go`
   (annotated in code), `internal/web/service/panel/panel.go`,
   `scripts/release-build.sh`, `install-agent.sh`,
   `install-master.sh`, `update.sh`, `install.sh`, `docs/release.md`
   and every `rogue/l-ui` URL in the tree to the confirmed spelling.
   Until then, the renamed update check points at a repo that does
   not exist yet — this branch must not be released as-is.
2. **Version bump.** Panel stays V2.6.0, agent stays A2.5.0 in this
   diff. The release step must bump the panel line (and the agent
   line only if agent code changed in the release commit) and
   `install-agent.sh`'s `RELEASE_BASE`.
3. **`install-agent.ps1` (Windows, frozen, TYYUN only).** Untouched
   on purpose: it is pinned to the V2.4.0 release base and
   downloads `x-ui-agent-windows-amd64.exe` into `C:\x-ui`.
   After the Gitea repo is renamed, that download URL
   (`rogue/3x-ui-agent/releases/download/V2.4.0/…`) will 404
   unless one of these is chosen: (a) leave ps1 alone and accept
   that a future Windows reinstall needs a manual exe (the frozen
   line needs no reinstall by design); (b) update only its repo
   segment to the confirmed spelling, keeping the V2.4.0 pin and
   the old asset name (the V2.4.0 release's assets keep their old
   names only if the repo is renamed without re-uploading them —
   verify before choosing); (c) unfreeze Windows and ship a new
   win asset (out of scope for this batch). Do NOT quietly bump
   its pin to a release that has no win asset.
4. **Generated schemas regeneration** — run `tools/openapigen`
   at release time so `frontend/src/generated/schemas.ts`
   descriptions pick up the L-UI wording.
5. **Tracked test binaries** — decide separately whether to delete
   the three stale ELF files from the repo.