docs: RENAMING.md + l-ui migration runbook
RENAMING.md: exact mapping, LUI_ inventory, sing-box orphan-scan re-verification, Tianyi badge mechanism, intentionally-kept items (module path, upstream mentions, frozen Windows, ps1, log filenames, Postgres creds, generated schemas, stale test binaries), and pending items (repo spelling BLOCKER, version bump, ps1 URL after repo rename, schema regeneration). docs/migration-l-ui.md: operator-only mv table, DB file rename, unit-env translation, backup-then-delete, old-core stop rule, rollback before acceptance only, per-machine acceptance checklist, pilot order (probe node, master, rest one by one, TYYUN untouched). docs/release.md: placeholder-repo warning.
This commit is contained in:
Muse
+195
@@ -0,0 +1,195 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user