功能: 一键部署 Agent 向导 (#44)

server/internal/installscript/renderer.go

@@ -0,0 +1,170 @@
+// Package installscript 负责把一次性安装令牌 + 节点配置渲染为可执行 shell 脚本或 docker-compose YAML。
+//
+// 模板文件通过 go:embed 嵌入二进制，避免运行时依赖外部资源。
+package installscript
+
+import (
+	"bytes"
+	_ "embed"
+	"fmt"
+	"net/url"
+	"strings"
+	"text/template"
+
+	"backupx/server/internal/model"
+)
+
+//go:embed templates/agent-install.sh.tmpl
+var installScriptTmpl string
+
+//go:embed templates/agent-compose.yml.tmpl
+var composeYamlTmpl string
+
+// Context 是模板渲染输入。
+type Context struct {
+	MasterURL     string
+	AgentToken    string
+	AgentVersion  string
+	Mode          string // systemd|docker|foreground
+	Arch          string // amd64|arm64|auto
+	DownloadBase  string
+	InstallPrefix string
+	NodeID        uint
+}
+
+// DownloadBaseFor 将下载源枚举转换为具体 URL 前缀。
+func DownloadBaseFor(src string) string {
+	switch src {
+	case model.InstallSourceGhproxy:
+		return "https://ghproxy.com/https://github.com/Awuqing/BackupX/releases/download"
+	default:
+		return "https://github.com/Awuqing/BackupX/releases/download"
+	}
+}
+
+// RenderScript 渲染目标机安装脚本。
+func RenderScript(ctx Context) (string, error) {
+	ctx = withDefaults(ctx)
+	if err := validateContext(ctx); err != nil {
+		return "", err
+	}
+	tmpl, err := template.New("install").Parse(installScriptTmpl)
+	if err != nil {
+		return "", fmt.Errorf("parse template: %w", err)
+	}
+	var buf bytes.Buffer
+	if err := tmpl.Execute(&buf, ctx); err != nil {
+		return "", fmt.Errorf("execute template: %w", err)
+	}
+	return buf.String(), nil
+}
+
+// RenderComposeYaml 渲染 docker-compose.yml 片段。
+func RenderComposeYaml(ctx Context) (string, error) {
+	ctx = withDefaults(ctx)
+	if err := validateContext(ctx); err != nil {
+		return "", err
+	}
+	tmpl, err := template.New("compose").Parse(composeYamlTmpl)
+	if err != nil {
+		return "", fmt.Errorf("parse template: %w", err)
+	}
+	var buf bytes.Buffer
+	if err := tmpl.Execute(&buf, ctx); err != nil {
+		return "", fmt.Errorf("execute template: %w", err)
+	}
+	return buf.String(), nil
+}
+
+// validateContext 对模板变量做安全校验，防止 YAML/shell 注入。
+//   - MasterURL：必须是合法 http(s) URL，无控制字符
+//   - AgentToken：仅允许 hex 字符，最长 128
+//   - AgentVersion：仅允许 tag 常见字符（字母数字、点、连字符、下划线、加号）
+//
+// 这些字段被直接写入 shell 双引号字符串和 YAML 双引号值；不做校验会带来
+// 注入风险（如 MasterURL 含 `"\nCOMMAND:` 可逃逸 YAML 结构）。
+func validateContext(ctx Context) error {
+	if err := validateMasterURL(ctx.MasterURL); err != nil {
+		return err
+	}
+	if err := validateAgentToken(ctx.AgentToken); err != nil {
+		return err
+	}
+	if err := validateAgentVersion(ctx.AgentVersion); err != nil {
+		return err
+	}
+	return nil
+}
+
+func validateMasterURL(raw string) error {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return fmt.Errorf("master URL empty")
+	}
+	if strings.ContainsAny(raw, " \t\r\n\"'`$\\") {
+		return fmt.Errorf("master URL contains illegal characters")
+	}
+	u, err := url.Parse(raw)
+	if err != nil {
+		return fmt.Errorf("invalid master URL: %w", err)
+	}
+	if u.Scheme != "http" && u.Scheme != "https" {
+		return fmt.Errorf("master URL scheme must be http or https, got %q", u.Scheme)
+	}
+	if u.Host == "" {
+		return fmt.Errorf("master URL missing host")
+	}
+	return nil
+}
+
+// validateAgentToken 允许占位符 <AGENT_TOKEN>（PreviewScript 使用），
+// 或 32 字节 hex（64 字符）+ 小幅兼容（16-128 hex 字符）
+func validateAgentToken(tok string) error {
+	if tok == "<AGENT_TOKEN>" {
+		return nil
+	}
+	if len(tok) < 8 || len(tok) > 128 {
+		return fmt.Errorf("agent token length out of range")
+	}
+	for _, c := range tok {
+		switch {
+		case c >= '0' && c <= '9':
+		case c >= 'a' && c <= 'f':
+		case c >= 'A' && c <= 'F':
+		default:
+			return fmt.Errorf("agent token must be hex")
+		}
+	}
+	return nil
+}
+
+func validateAgentVersion(v string) error {
+	v = strings.TrimSpace(v)
+	if v == "" {
+		return fmt.Errorf("agent version empty")
+	}
+	if len(v) > 64 {
+		return fmt.Errorf("agent version too long")
+	}
+	for _, c := range v {
+		switch {
+		case c >= '0' && c <= '9':
+		case c >= 'a' && c <= 'z':
+		case c >= 'A' && c <= 'Z':
+		case c == '.' || c == '-' || c == '_' || c == '+':
+		default:
+			return fmt.Errorf("agent version contains illegal char %q", c)
+		}
+	}
+	return nil
+}
+
+func withDefaults(ctx Context) Context {
+	if ctx.InstallPrefix == "" {
+		ctx.InstallPrefix = "/opt/backupx-agent"
+	}
+	if ctx.DownloadBase == "" {
+		ctx.DownloadBase = DownloadBaseFor(model.InstallSourceGitHub)
+	}
+	return ctx
+}

server/internal/installscript/renderer_test.go

@@ -0,0 +1,176 @@
+package installscript
+
+import (
+	"strings"
+	"testing"
+
+	"backupx/server/internal/model"
+)
+
+// 使用合法 hex token（32 字节 = 64 字符）以通过 validateAgentToken 校验
+var testCtx = Context{
+	MasterURL:     "https://master.example.com",
+	AgentToken:    "deadbeefcafebabe0123456789abcdef0123456789abcdef0123456789abcdef",
+	AgentVersion:  "v1.7.0",
+	Mode:          model.InstallModeSystemd,
+	Arch:          model.InstallArchAuto,
+	DownloadBase:  "https://github.com/Awuqing/BackupX/releases/download",
+	InstallPrefix: "/opt/backupx-agent",
+	NodeID:        42,
+}
+
+func TestRenderScriptSystemd(t *testing.T) {
+	got, err := RenderScript(testCtx)
+	if err != nil {
+		t.Fatalf("render err: %v", err)
+	}
+	mustContain := []string{
+		"BACKUPX_AGENT_MASTER=${MASTER_URL}",
+		`Environment="BACKUPX_AGENT_TOKEN=${AGENT_TOKEN}"`,
+		"systemctl daemon-reload",
+		"systemctl enable --now backupx-agent",
+		"X-Agent-Token: ${AGENT_TOKEN}",
+		"MASTER_URL=\"https://master.example.com\"",
+		"AGENT_TOKEN=\"deadbeefcafebabe0123456789abcdef0123456789abcdef0123456789abcdef\"",
+	}
+	for _, s := range mustContain {
+		if !strings.Contains(got, s) {
+			t.Errorf("systemd script missing %q", s)
+		}
+	}
+	mustNotContain := []string{"docker run", `exec "${INSTALL_PREFIX}/backupx" agent --temp-dir`}
+	for _, s := range mustNotContain {
+		if strings.Contains(got, s) {
+			t.Errorf("systemd script unexpectedly contains %q", s)
+		}
+	}
+}
+
+func TestRenderScriptForeground(t *testing.T) {
+	ctx := testCtx
+	ctx.Mode = model.InstallModeForeground
+	got, err := RenderScript(ctx)
+	if err != nil {
+		t.Fatalf("render err: %v", err)
+	}
+	if !strings.Contains(got, `exec "${INSTALL_PREFIX}/backupx" agent`) {
+		t.Errorf("foreground script missing exec line:\n%s", got)
+	}
+	if strings.Contains(got, "systemctl daemon-reload") {
+		t.Errorf("foreground script should not reference systemctl:\n%s", got)
+	}
+	if strings.Contains(got, "docker run") {
+		t.Errorf("foreground script should not reference docker:\n%s", got)
+	}
+}
+
+func TestRenderScriptDocker(t *testing.T) {
+	ctx := testCtx
+	ctx.Mode = model.InstallModeDocker
+	got, err := RenderScript(ctx)
+	if err != nil {
+		t.Fatalf("render err: %v", err)
+	}
+	if !strings.Contains(got, "docker run") {
+		t.Errorf("docker script missing `docker run`:\n%s", got)
+	}
+	if !strings.Contains(got, "awuqing/backupx:${AGENT_VERSION}") {
+		t.Errorf("docker script missing image tag reference:\n%s", got)
+	}
+	if strings.Contains(got, "systemctl daemon-reload") {
+		t.Errorf("docker script should not reference systemctl:\n%s", got)
+	}
+}
+
+func TestRenderComposeYaml(t *testing.T) {
+	ctx := testCtx
+	ctx.Mode = model.InstallModeDocker
+	got, err := RenderComposeYaml(ctx)
+	if err != nil {
+		t.Fatalf("render err: %v", err)
+	}
+	if !strings.Contains(got, "image: awuqing/backupx:v1.7.0") {
+		t.Errorf("compose missing image:\n%s", got)
+	}
+	if !strings.Contains(got, `BACKUPX_AGENT_TOKEN: "deadbeefcafebabe0123456789abcdef0123456789abcdef0123456789abcdef"`) {
+		t.Errorf("compose missing token env:\n%s", got)
+	}
+}
+
+func TestRenderScriptRejectsInjectedMasterURL(t *testing.T) {
+	bad := []string{
+		"https://example.com\" other: inject", // 含引号和空格
+		"javascript:alert(1)",                  // scheme 非法
+		"https://example.com\n- privileged",    // 含换行，YAML 注入经典 payload
+		"",                                     // 空
+	}
+	for _, u := range bad {
+		ctx := testCtx
+		ctx.MasterURL = u
+		if _, err := RenderScript(ctx); err == nil {
+			t.Errorf("RenderScript should reject MasterURL %q", u)
+		}
+	}
+}
+
+func TestRenderComposeYamlRejectsInjectedMasterURL(t *testing.T) {
+	ctx := testCtx
+	ctx.Mode = model.InstallModeDocker
+	ctx.MasterURL = "https://example.com\n- privileged: true"
+	if _, err := RenderComposeYaml(ctx); err == nil {
+		t.Errorf("RenderComposeYaml should reject injected MasterURL")
+	}
+}
+
+func TestRenderScriptRejectsBadToken(t *testing.T) {
+	ctx := testCtx
+	ctx.AgentToken = "not-hex-token" // 非 hex
+	if _, err := RenderScript(ctx); err == nil {
+		t.Errorf("should reject non-hex agent token")
+	}
+}
+
+func TestRenderScriptAcceptsPlaceholderToken(t *testing.T) {
+	ctx := testCtx
+	ctx.AgentToken = "<AGENT_TOKEN>" // Preview 占位符
+	if _, err := RenderScript(ctx); err != nil {
+		t.Errorf("should accept placeholder token: %v", err)
+	}
+}
+
+func TestRenderScriptRejectsBadVersion(t *testing.T) {
+	ctx := testCtx
+	ctx.AgentVersion = "v1.7 && rm -rf /" // 含非法字符
+	if _, err := RenderScript(ctx); err == nil {
+		t.Errorf("should reject version with shell metacharacters")
+	}
+}
+
+func TestDownloadBaseMapping(t *testing.T) {
+	cases := map[string]string{
+		model.InstallSourceGitHub:  "https://github.com/Awuqing/BackupX/releases/download",
+		model.InstallSourceGhproxy: "https://ghproxy.com/https://github.com/Awuqing/BackupX/releases/download",
+	}
+	for src, want := range cases {
+		got := DownloadBaseFor(src)
+		if got != want {
+			t.Errorf("src=%s want=%s got=%s", src, want, got)
+		}
+	}
+}
+
+func TestRenderScriptDefaultsApplied(t *testing.T) {
+	ctx := testCtx
+	ctx.InstallPrefix = ""   // 应被默认为 /opt/backupx-agent
+	ctx.DownloadBase = ""    // 应被默认为 github
+	got, err := RenderScript(ctx)
+	if err != nil {
+		t.Fatalf("render err: %v", err)
+	}
+	if !strings.Contains(got, "INSTALL_PREFIX=\"/opt/backupx-agent\"") {
+		t.Errorf("default InstallPrefix not applied:\n%s", got)
+	}
+	if !strings.Contains(got, "DOWNLOAD_BASE=\"https://github.com/Awuqing/BackupX/releases/download\"") {
+		t.Errorf("default DownloadBase not applied:\n%s", got)
+	}
+}

server/internal/installscript/templates/agent-compose.yml.tmpl

@@ -0,0 +1,13 @@
+# BackupX Agent docker-compose 片段
+# 生成于 {{.MasterURL}} · 节点 ID {{.NodeID}}
+version: "3.8"
+services:
+  backupx-agent:
+    image: awuqing/backupx:{{.AgentVersion}}
+    command: ["agent"]
+    restart: unless-stopped
+    environment:
+      BACKUPX_AGENT_MASTER: "{{.MasterURL}}"
+      BACKUPX_AGENT_TOKEN: "{{.AgentToken}}"
+    volumes:
+      - /var/lib/backupx-agent:/tmp/backupx-agent

server/internal/installscript/templates/agent-install.sh.tmpl

@@ -0,0 +1,108 @@
+#!/bin/sh
+# BackupX Agent 一键安装脚本（由 Master 动态渲染）
+# 模式: {{.Mode}} | 架构: {{.Arch}} | 版本: {{.AgentVersion}}
+set -eu
+
+MASTER_URL="{{.MasterURL}}"
+AGENT_TOKEN="{{.AgentToken}}"
+AGENT_VERSION="{{.AgentVersion}}"
+DOWNLOAD_BASE="{{.DownloadBase}}"
+INSTALL_PREFIX="{{.InstallPrefix}}"
+ARCH="{{.Arch}}"
+
+# 1. 前置检查
+[ "$(id -u)" -eq 0 ] || { echo "请使用 root 或 sudo 执行" >&2; exit 1; }
+command -v curl >/dev/null || command -v wget >/dev/null \
+    || { echo "需要 curl 或 wget" >&2; exit 1; }
+{{if eq .Mode "systemd"}}command -v systemctl >/dev/null || { echo "不支持非 systemd 系统" >&2; exit 1; }
+{{end}}{{if eq .Mode "docker"}}command -v docker >/dev/null || { echo "需要先安装 docker" >&2; exit 1; }
+{{end}}
+# 2. 架构检测
+if [ "$ARCH" = "auto" ]; then
+    case "$(uname -m)" in
+        x86_64|amd64)  ARCH=amd64 ;;
+        aarch64|arm64) ARCH=arm64 ;;
+        *) echo "不支持的架构: $(uname -m)" >&2; exit 1 ;;
+    esac
+fi
+
+{{if ne .Mode "docker"}}
+# 3. 下载二进制（systemd / foreground 模式）
+ARCHIVE="backupx-${AGENT_VERSION}-linux-${ARCH}.tar.gz"
+URL="${DOWNLOAD_BASE}/${AGENT_VERSION}/${ARCHIVE}"
+TMPDIR="$(mktemp -d)"; trap 'rm -rf "$TMPDIR"' EXIT
+echo "[1/4] 下载 ${URL}"
+if command -v curl >/dev/null; then
+    curl -fsSL "$URL" -o "$TMPDIR/pkg.tar.gz"
+else
+    wget -qO "$TMPDIR/pkg.tar.gz" "$URL"
+fi
+tar xzf "$TMPDIR/pkg.tar.gz" -C "$TMPDIR"
+
+# 4. 安装二进制 + 用户
+echo "[2/4] 安装到 ${INSTALL_PREFIX}"
+id backupx >/dev/null 2>&1 || useradd --system --home-dir "$INSTALL_PREFIX" --shell /usr/sbin/nologin backupx
+install -d -o backupx -g backupx "$INSTALL_PREFIX" /var/lib/backupx-agent
+install -m 0755 "$TMPDIR/backupx-${AGENT_VERSION}-linux-${ARCH}/backupx" "$INSTALL_PREFIX/backupx"
+{{end}}
+
+{{if eq .Mode "systemd"}}
+# 5. systemd unit
+echo "[3/4] 配置 systemd"
+cat > /etc/systemd/system/backupx-agent.service <<UNIT
+[Unit]
+Description=BackupX Agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=backupx
+Environment="BACKUPX_AGENT_MASTER=${MASTER_URL}"
+Environment="BACKUPX_AGENT_TOKEN=${AGENT_TOKEN}"
+ExecStart=${INSTALL_PREFIX}/backupx agent --temp-dir /var/lib/backupx-agent
+Restart=on-failure
+RestartSec=10s
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+systemctl daemon-reload
+systemctl enable --now backupx-agent
+
+# 6. 等待上线
+echo "[4/4] 等待节点上线"
+for i in $(seq 1 15); do
+    sleep 2
+    if curl -fsSL -H "X-Agent-Token: ${AGENT_TOKEN}" "${MASTER_URL}/api/v1/agent/self" 2>/dev/null \
+        | grep -q '"status":"online"'; then
+        echo "✓ 节点已上线"
+        exit 0
+    fi
+done
+echo "⚠ 30s 内未收到上线心跳，请检查防火墙或 journalctl -u backupx-agent"
+exit 2
+{{end}}
+
+{{if eq .Mode "foreground"}}
+# 5. 前台运行
+echo "[3/3] 前台启动 agent（Ctrl+C 退出）"
+export BACKUPX_AGENT_MASTER="${MASTER_URL}"
+export BACKUPX_AGENT_TOKEN="${AGENT_TOKEN}"
+exec "${INSTALL_PREFIX}/backupx" agent --temp-dir /var/lib/backupx-agent
+{{end}}
+
+{{if eq .Mode "docker"}}
+# Docker 模式：直接用镜像启动容器
+echo "[1/2] 拉取镜像 awuqing/backupx:${AGENT_VERSION}"
+docker pull "awuqing/backupx:${AGENT_VERSION}"
+echo "[2/2] 启动容器 backupx-agent"
+docker rm -f backupx-agent >/dev/null 2>&1 || true
+docker run -d --name backupx-agent --restart=unless-stopped \
+    -e "BACKUPX_AGENT_MASTER=${MASTER_URL}" \
+    -e "BACKUPX_AGENT_TOKEN=${AGENT_TOKEN}" \
+    -v /var/lib/backupx-agent:/tmp/backupx-agent \
+    "awuqing/backupx:${AGENT_VERSION}" agent
+echo "✓ 容器已启动"
+{{end}}