feat(auth): 完善英文初始化与裸机安装

在登录和首个管理员创建前提供中英文切换，并在初始化状态不可达时展示可重试错误，避免误入登录页。对齐源码构建产物与安装脚本路径，增加 systemd/API 就绪检查、失败诊断及中英文裸机文档。 Closes #104
2026-08-29 20:16:59 +08:00 · 2026-08-07 05:55:56 +08:00
parent cc50637b4b
commit f8deafcb00
17 changed files with 526 additions and 152 deletions
@@ -10,20 +10,21 @@ description: systemd + Nginx deployment from the prebuilt release tarball or sou

 ```bash
 # Download the matching tarball
-curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-v1.6.0-linux-amd64.tar.gz
+curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-linux-amd64.tar.gz

 # Extract and install
-tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
+tar xzf backupx-linux-amd64.tar.gz && cd backupx-*-linux-amd64
 sudo ./install.sh
 ```

 The installer performs these steps automatically:

 1. Creates a system user `backupx`
-2. Copies the binary to `/opt/backupx/`
-3. Generates a default `config.yaml` with safe JWT/encryption secrets
+2. Copies the binary to `/opt/backupx/bin/backupx` and the web console to `/opt/backupx/web`
+3. Installs the default configuration at `/etc/backupx/config.yaml`
 4. Installs `backupx.service` (systemd), enabled at boot
 5. (Optional) installs an Nginx site file — see [Nginx Reverse Proxy](./nginx)
+6. Verifies the first-setup API before reporting success

 For multi-node clusters, edit `/etc/backupx/config.yaml` after installation and set the Master URL that remote Agents can reach:

@@ -63,11 +64,13 @@ After=network.target
 [Service]
 Type=simple
 User=backupx
+Group=backupx
 WorkingDirectory=/opt/backupx
-ExecStart=/opt/backupx/backupx --config /opt/backupx/config.yaml
+ExecStart=/opt/backupx/bin/backupx -config /etc/backupx/config.yaml
 Restart=on-failure
-RestartSec=5s
-LimitNOFILE=65536
+RestartSec=5
+NoNewPrivileges=true
+LimitNOFILE=65535

 [Install]
 WantedBy=multi-user.target
@@ -79,17 +82,20 @@ Typical operations:
 sudo systemctl status backupx
 sudo journalctl -u backupx -f    # live logs
 sudo systemctl restart backupx
+curl -fsS http://127.0.0.1:8340/api/auth/setup/status
 ```

+Open `http://your-server:8340`, switch to English if desired, and create the first administrator on the **System setup** screen. For a custom listen port, run the installer with a matching `HEALTH_URL`.
+
 ## Password reset

 If the admin password is lost:

 ```bash
-/opt/backupx/backupx reset-password \
+/opt/backupx/bin/backupx reset-password \
  --username admin \
  --password 'newpass123' \
-  --config /opt/backupx/config.yaml
+  --config /etc/backupx/config.yaml
 ```

 Docker equivalent:
@@ -55,10 +55,11 @@ sudo ./install.sh        # creates system user, installs to /opt/backupx, sets u
 The installer:

 1. Creates a `backupx` system user
-2. Installs binary to `/opt/backupx/backupx`
-3. Creates `/opt/backupx/config.yaml` with safe defaults
+2. Installs the binary to `/opt/backupx/bin/backupx` and the web console to `/opt/backupx/web`
+3. Creates `/etc/backupx/config.yaml` with safe defaults
 4. Installs and enables the `backupx.service` systemd unit
 5. (Optional) Configures an Nginx reverse proxy
+6. Waits for `/api/auth/setup/status`; if startup fails, prints systemd diagnostics and exits non-zero

 ## From source

@@ -67,16 +68,17 @@ Requires Go ≥ 1.25 and Node.js ≥ 20.
 ```bash
 git clone https://github.com/Awuqing/BackupX.git && cd BackupX
 make build
-# or, for builds behind the great firewall
-make docker-cn
+sudo ./deploy/install.sh
 ```

 After `make build`, the binary is at `server/bin/backupx` and the built web UI is at `web/dist/`.
+The installer consumes those exact paths, so no Docker runtime is required. If an existing configuration uses a non-default port, set `HEALTH_URL` for the readiness check, for example `sudo HEALTH_URL=http://127.0.0.1:9000/api/auth/setup/status ./deploy/install.sh`.

 ## Verify the install

 ```bash
-backupx --version           # e.g. v1.6.0
+/opt/backupx/bin/backupx --version
+curl -fsS http://127.0.0.1:8340/api/auth/setup/status
 ```

-Then open `http://your-server:8340` to see the initial admin setup screen.
+Then open `http://your-server:8340`. Choose **English** or **中文** in the upper-right corner. A fresh database shows **System setup**, where you create the first administrator username and password. If that form does not appear, retry the status request above before attempting to sign in.
@@ -10,20 +10,21 @@ description: 从预编译包或源码部署 BackupX（systemd + Nginx）。

 ```bash
 # 下载对应平台的压缩包
-curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-v1.6.0-linux-amd64.tar.gz
+curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-linux-amd64.tar.gz

 # 解压并安装
-tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
+tar xzf backupx-linux-amd64.tar.gz && cd backupx-*-linux-amd64
 sudo ./install.sh
 ```

 安装脚本自动完成以下步骤：

 1. 创建系统用户 `backupx`
-2. 复制二进制到 `/opt/backupx/`
-3. 生成默认 `config.yaml`（含安全的 JWT/加密密钥）
+2. 复制二进制到 `/opt/backupx/bin/backupx`，并把 Web 控制台复制到 `/opt/backupx/web`
+3. 把默认配置安装到 `/etc/backupx/config.yaml`
 4. 安装并启用 `backupx.service` systemd 单元
 5. （可选）生成 Nginx 站点配置 — 参见 [Nginx 反向代理](./nginx)
+6. 验证首次初始化接口就绪后才报告安装成功

 如果要部署多节点集群，安装后请编辑 `/etc/backupx/config.yaml`，设置远程 Agent 可访问到的 Master URL：

@@ -63,11 +64,13 @@ After=network.target
 [Service]
 Type=simple
 User=backupx
+Group=backupx
 WorkingDirectory=/opt/backupx
-ExecStart=/opt/backupx/backupx --config /opt/backupx/config.yaml
+ExecStart=/opt/backupx/bin/backupx -config /etc/backupx/config.yaml
 Restart=on-failure
-RestartSec=5s
-LimitNOFILE=65536
+RestartSec=5
+NoNewPrivileges=true
+LimitNOFILE=65535

 [Install]
 WantedBy=multi-user.target
@@ -79,17 +82,20 @@ WantedBy=multi-user.target
 sudo systemctl status backupx
 sudo journalctl -u backupx -f    # 实时日志
 sudo systemctl restart backupx
+curl -fsS http://127.0.0.1:8340/api/auth/setup/status
 ```

+访问 `http://your-server:8340`，可按需切换到 English，然后在“系统初始化 / System setup”页面创建首个管理员。若监听端口不是默认值，请为安装脚本传入对应的 `HEALTH_URL`。
+
 ## 密码重置

 忘记管理员密码时：

 ```bash
-/opt/backupx/backupx reset-password \
+/opt/backupx/bin/backupx reset-password \
  --username admin \
  --password 'newpass123' \
-  --config /opt/backupx/config.yaml
+  --config /etc/backupx/config.yaml
 ```

 Docker 等效命令：
@@ -55,10 +55,11 @@ sudo ./install.sh        # 创建系统用户、安装到 /opt/backupx、配置
 安装脚本会自动：

 1. 创建 `backupx` 系统用户
-2. 安装二进制到 `/opt/backupx/backupx`
-3. 生成 `/opt/backupx/config.yaml`（含安全默认值）
+2. 安装二进制到 `/opt/backupx/bin/backupx`，并把 Web 控制台安装到 `/opt/backupx/web`
+3. 生成 `/etc/backupx/config.yaml`（含安全默认值）
 4. 注册并启用 `backupx.service` systemd 单元
 5. （可选）配置 Nginx 反向代理
+6. 等待 `/api/auth/setup/status` 就绪；启动失败时输出 systemd 诊断并返回非零状态

 ## 从源码构建

@@ -67,16 +68,17 @@ sudo ./install.sh        # 创建系统用户、安装到 /opt/backupx、配置
 ```bash
 git clone https://github.com/Awuqing/BackupX.git && cd BackupX
 make build
-# 或使用国内镜像加速构建 Docker
-make docker-cn
+sudo ./deploy/install.sh
 ```

 `make build` 完成后，二进制位于 `server/bin/backupx`，构建好的 Web UI 位于 `web/dist/`。
+安装脚本会直接使用这两个路径，不需要 Docker 运行时。如果已有配置修改了默认端口，可覆盖就绪检查地址，例如：`sudo HEALTH_URL=http://127.0.0.1:9000/api/auth/setup/status ./deploy/install.sh`。

 ## 验证安装

 ```bash
-backupx --version           # 输出如 v1.6.0
+/opt/backupx/bin/backupx --version
+curl -fsS http://127.0.0.1:8340/api/auth/setup/status
 ```

-打开浏览器访问 `http://your-server:8340`，会进入初始化管理员账户页面。
+打开浏览器访问 `http://your-server:8340`，可在右上角选择 **中文** 或 **English**。全新数据库会显示“系统初始化 / System setup”，在这里创建首个管理员用户名和密码。如果没有出现初始化表单，请先重试上面的状态接口，不要直接尝试登录。