README.md

Rama main · réplica de lectura del repositorio original.

# Vastora

Current route lifecycle: [startup-only readiness](docs/startup-readiness.md).
This supersedes the historical periodic-health lease behavior described below.

Vastora is a self-hosted desired-state control plane for applications
across multiple Sites and Nodes. The Center stores intent and orchestration
state; one Agent binary is the only node-side executor for Docker workloads,
verified native probes, and an optional local Caddy Gateway. Existing applications and applied routes continue
when the Center is unavailable.

> **Pre-alpha.** The repository is intentionally published only with working,
> tested building blocks. Do not use it to manage production workloads yet.

## What is implemented now

- A Go `vastora` CLI with a Center HTTP API, one-time Agent enrollment,
  authenticated Agent heartbeats and Agent-local encrypted credentials.
- Schema 4 catalog consumption from the pinned independent
  [petauron/catalog](https://github.com/petauron/catalog) module, with generic
  Docker/systemd execution contracts. Catalog signing/publishing tools belong
  to that repository, not the Vastora CLI. Production cutover remains gated by
  the [maintenance and adoption checklist](docs/catalog-release-guide.md).
- Browser-based first-administrator setup with a username, Argon2id password
  hashing, and authenticated sessions.
- AES-256-GCM encrypted secrets in SQLite, multi-source catalog persistence,
  Ed25519 signed catalog verification, and a bilingual React catalog console.
- Organization → Site → Node topology, typed Network Candidate/Profile state,
  private application Services, and independent multi-entry Publications.
- Leased, retryable, attempt-fenced Agent tasks with append-only audit events.
- LAN, Headscale, direct-public, shared-443, and Cloudflare Tunnel publication
  paths; each host uses one Agent-managed Caddy with a private Unix socket,
  while optional HAProxy provides TLS SNI passthrough only when Web HTTPS and
  raw TCP must share `443`.
- Signed Vastora Proxy, CPA, and Keeper runtimes pinned by digest, plus a native
  Komari Agent binary pinned by platform and SHA-256. Vastora Proxy workers run
  the official Xray image directly; only the temporary global controller keeps
  the pinned 3x-ui migration adapter.
- Separate CPA management and public client API entries: the public hostname
  routes only `/v1` through Cloudflare Tunnel and keeps CPA key authentication,
  while the management page remains on its protected entry.
- One global Vastora-owned subscription authority with cross-Site Xray-only
  workers, encrypted controller/worker journals, and sequential Alpha
  convergence from legacy per-Site 3x-ui controllers.
- An Ubuntu 24.04 Center installation path and an OS-aware Agent installer for
  Debian 12/13 and Ubuntu 22.04/24.04/26.04 on x86_64 and ARM64, including
  mixed-architecture Sites and architecture-aware Agent updates. The one-line
  Agent installer installs Docker from its official repository when missing.

## Development

Frontend work follows the [Vastora design language](docs/design-language.md), including
shared macOS-style components, application icons, and responsive behavior.

Requirements: Go 1.26.10, Node.js 24.19, and npm.

```sh
make bootstrap
make check
make security-check
```

Start a local control plane after the checks pass:

```sh
GOTOOLCHAIN=go1.26.10 go run ./cmd/vastora center serve --data-dir .vastora/center --listen 127.0.0.1:8080 --agent-connect-url http://127.0.0.1:8080
```

To connect Headscale, authorize its exact HTTPS origin when Center starts by
adding `--headscale-allowed-url https://headscale.example.com`. Repeat the flag
to permit additional operator-approved control planes; browser users cannot
make Center send authenticated requests to any other host.

In another terminal, start the web development server with `cd web && npm run
dev`. On the first visit, create the administrator, then follow the required
wizard to create a real location and confirm how Agents reach Center. The
configured Agent address is reused automatically when adding nodes.

When a Cloudflare zone such as `example.com` is selected, the wizard keeps that
root zone separate and defaults Vastora to the `vastora.example.com` namespace.
Center and bundled Headscale use `center.vastora.example.com` and
`headscale.vastora.example.com`; only Headscale receives a public DNS record.
Center receives a browser-trusted DNS-01 certificate and a Headscale DNS record,
so its console is reachable only after joining the private network by default. The
wizard can optionally add a Cloudflare Tunnel fallback protected by Access. That
fallback accepts either one exact administrator email or one email domain and
still requires the Center administrator login. Agent APIs remain on their
separate private path. A Cloudflare connection created by an older Center must
be reauthorized once before enabling the fallback so its OAuth grant includes
Access management. App hostnames use a visible hierarchy such as
`manager.cpa.home.vastora.example.com`, and node-specific raw entries use names
such as `reality.edge-1.home.vastora.example.com`. Existing DNS records outside this
namespace are not overwritten.

Create an encrypted control-plane backup with a password stored in a local
`0600` file, then restore only into a new empty state directory:

```sh
GOTOOLCHAIN=go1.26.10 go run ./cmd/vastora center backup --data-dir .vastora/center --output center.vastora --password-file ./backup-password
GOTOOLCHAIN=go1.26.10 go run ./cmd/vastora center restore --input center.vastora --data-dir .vastora/restored-center --password-file ./backup-password
```

Restore uses an equivalent Vastora version and recreates the Center directory
with restrictive permissions. The archive contains SQLite, the Center root key,
and therefore the encrypted ACME account and certificate state stored in SQLite;
it does not contain Headscale, Agent, gateway, or application runtime volumes.

The Dockerfiles build an unprivileged Center image with the compiled web UI and
a separate Agent image. They intentionally do not provide an insecure default
command: a network-reachable Center must be started with its TLS certificate
and key.

Released versions use one public Center bootstrap command:

```sh
curl -LsSf https://vastora.petauron.com/install.sh | sudo sh -s -- center
```

It downloads a verified release bundle and starts Center only on the server's
loopback interface. The installer prints an SSH tunnel command; opening its
local URL starts the administrator, location, and network wizard without
claiming public port 443. Users do not clone this repository or enter a
container image digest. Each Center then generates its own short-lived,
one-line Agent install command. See [`deploy/center`](deploy/center/README.md)
for the complete bootstrap flow and local release packaging. Center checks the
official complete release selected by that endpoint and offers a confirmed
in-place update in Settings. The first release with this capability may still
be installed by running the same command again; later updates preserve the
configuration and use the built-in updater.

Center uses schema **123** as the compact alpha baseline. New installations
create the current schema directly. A completed schema-122 database is backed
up, checked, and converted in place by replacing only its migration journal;
business tables and encrypted values are not copied or rewritten. Historical
migrations 4–122 are no longer shipped. See [database baseline conversion](docs/database-baseline.md)
for older databases and recovery. Later changes remain forward-only; integrity
and foreign-key failures prevent startup.

## Security model

- The Center never mounts a Docker socket.
- Agent enrollment uses a short-lived, one-time token; the Agent exchanges it
  for a unique credential encrypted in its own local state.
- Catalog source content is accepted only after Ed25519 signature verification.
- Registry credentials and catalog Bearer tokens are separate from catalogs and
  stored encrypted.
- Application runtime data is Agent-local and never uploaded as configuration.
- The Center deployment stack can run a fixed-version Headscale service with a
  separate data volume; an existing Headscale control plane is also supported.
  Bundled Headscale is the public Caddy HTTPS entry. Center stays private, while
  only its public Docker installer, token-protected Agent bootstrap and binary
  download, and task-bound uninstall completion paths are reachable through the
  Headscale hostname.
- Management pages remain private by default. Public publication requires an
  explicit high-risk confirmation and application-level authentication.

Read [the architecture](docs/architecture.md), [catalog format](docs/catalog.md),
and [threat model](docs/threat-model.md) before contributing.
For backup-bound native replacements and retained public service identity, see
[installation handover](docs/native-lifecycle-handover.md).
For verified retirement of old Glivela proxy execution records while retaining
their services and history, see [execution retirement](docs/glivela-execution-retirement.md).
For controller-plus-pilot upgrades, configure the persistent
[Agent update scope](docs/agent-update-scope.md) before upgrading Center.
For IPv6-only Agent onboarding, see the explicitly configured
[Headscale control IPv6 address](docs/tailscale-compatibility.md#ipv6-only-control-connectivity-1206).

## License

Apache-2.0. See [LICENSE](LICENSE).

### Center login lifetime

Authenticated Center requests renew a session when at most 12 hours remain,
extending it to 24 hours from the request, capped at seven days from login.
Background authenticated polling counts as activity; there is no separate
keepalive or refresh credential. After expiry, sign in again. Logout and
password-change revocation remain authoritative: renewal never recreates a
removed session (password change retains the current session, as before).
Existing sessions retain their original expiry when migrating to schema 119;
new logins receive the seven-day maximum. The normal pre-migration database
backup applies. No Agent or managed application upgrade is needed for this
Center-only change.

Existing Glivela business installations require the [final data handover](docs/GLIVELA-BUSINESS-HANDOVER.md) before serving the replacement Center.

离线节点在 Glivela 完成独立接管后，平台移除保留冻结业务历史及外键引用，
完成状态从正常节点和安装列表移除；业务订阅须先由 Glivela 停用。参见
[永久移除离线节点](docs/offline-node-removal.md)。

节点管理的“SSH 保护策略”按需读取 Glivela 当前状态，显示代理出口对宿主 SSH
地址的保护配置、运行修订与最后上报。该只读快照不代表 SSH 登录验证；宿主登录
安全基线仍单独管理。读取失败或缺少节点映射时显示未知，可手动刷新。

Node-local Daylight certificates and shared Caddy ownership: [configuration, handover and recovery](docs/node-site-certificates.md) (#1128).
Alpine/OpenRC 的原生套件契约和隔离验收边界见 [Alpine/OpenRC MVP](docs/alpine-openrc.md)（#1182；无 TUN 用户态管理接续 #1214，源码验收不代表生产发布）。

Vastora 自动管理的运行目录、开机准备和共享资源卸载边界见 [运行目录生命周期](docs/runtime-directories.md)（#356）。
Linux Agent 和共址 Center 的开机引导依赖系统 iproute2（`ip`）；安装器会检查，不自动下载或更改已有网络身份。
新购 KVM VPS 的网页重装条件、网络恢复边界与操作步骤见 [KVM Debian 13 网页重装](docs/os-reinstall.md)。系统盘将被清空，生产重装仍须单独确认。