chore: quickstart startup flow

Author: h3zh1

docs/getting-started.md

@@ -35,19 +35,25 @@ Release 中的主要二进制如下：
 
 ### 直接启动
 
-已从 `server/config.example.yaml` 复制出本地 `config.yaml` 后，可直接启动：
+已有 `config.yaml`，或者让程序自动生成默认配置后，可直接启动：
 
 ```bash
 ./malice-network_linux_amd64 -i <public-ip>
 ```
 
+默认启动时的初始化行为：
+
+- 如果配置文件不存在，且当前是交互终端，程序会先询问是否进入 quickstart 向导
+- 如果配置文件不存在，且当前不是交互终端，程序会直接写入默认 `config.yaml` 并继续正常启动
+- 如果显式传入 `--quickstart`，则直接进入向导模式，而不是等默认启动时再判断
+
 常用参数：
 
 - `-c, --config`: 指定配置文件路径，默认是 `config.yaml`
 - `-i, --ip`: 覆盖配置里的外网 IP
 - `--server-only`: 只启动 server
 - `--listener-only`: 只启动 listener
-- `--quickstart`: 仅在配置文件不存在时运行初始化向导
+- `--quickstart`: 显式进入交互式初始化向导
 - `--debug`: 打开 debug 日志
 
 ### 首次启动生成的文件

docs/server/index.md

@@ -32,7 +32,7 @@ Server 是 malice-network 的控制核心，职责包括：
 | `./malice-network --server-only` | 仅启动 Server，不启动 Listener |
 | `./malice-network --listener-only` | 仅启动 Listener，独立部署时使用 |
 | `./malice-network --daemon` | 以守护进程模式运行 |
-| `./malice-network --quickstart` | 交互式配置向导，引导完成初始配置 |
+| `./malice-network --quickstart` | 显式进入交互式配置向导，引导完成初始配置 |
 
 | 参数 | 说明 |
 |------|------|
@@ -41,6 +41,12 @@ Server 是 malice-network 的控制核心，职责包括：
 | `--debug` | 开启 debug 日志 |
 | `--opsec` | 启用 OPSEC 模式 |
 
+当默认启动时，如果配置文件不存在：
+
+- 交互终端会先提示是否进入 quickstart
+- 非交互环境会直接生成默认配置并继续启动
+- 只有显式传入 `--quickstart` 时，才会强制进入向导
+
 !!! tip "部署指南"
     完整的部署流程见 [部署操作指南](../operations/deployment.md)。
 

docs/server/quickstart.md

@@ -30,6 +30,12 @@
 !!! important "IP 设置"
     `-i` 参数需要设置为 Client 可访问到的 IP 地址。公网服务器设置为公网 IP，内网环境设置为内网 IP。
 
+如果当前还没有配置文件，默认启动会按下面的规则处理：
+
+- **交互终端**：先提示你是否进入 quickstart 向导
+- **非交互环境**（比如 systemd、无 PTY 的脚本环境）：直接生成默认 `config.yaml`，然后继续正常启动
+- **显式传入 `--quickstart`**：直接进入向导模式
+
 首次启动后，Server 会自动完成：
 
 1. 生成默认配置文件 `config.yaml`
@@ -53,6 +59,12 @@
 
 向导会引导完成 IP、端口、构建源等基础配置。
 
+注意：
+
+- `--quickstart` 是显式入口，不依赖“配置文件是否存在”来触发
+- quickstart 基于 TUI，适合交互式终端，不适合 systemd 这类无 PTY 环境
+- 如果目标配置文件已经存在，quickstart 不会覆盖原文件
+
 ## 使用安装脚本（Linux）
 
 !!! info "安装脚本会自动完成 Docker 安装、Server/Client 下载、malefic.zip 解压，并可选配置 systemd"
@@ -66,7 +78,7 @@ curl -L "https://raw.githubusercontent.com/chainreactors/malice-network/master/i
 - **安装路径**：默认 `/opt/iom`
 - **IP 地址**：自动检测，可手动修改
 
-安装完成后，脚本会询问是否安装并启动 systemd 服务；如果跳过，会直接输出手动启动命令。
+安装完成后，脚本会询问是否安装并启动 systemd 服务；如果跳过，会直接输出手动启动命令。使用 systemd 时，服务端会走默认启动路径，不会自动进入 quickstart 向导。
 
 ## 防火墙配置
 

server/cmd/server/options.go

@@ -210,12 +210,16 @@ func (opt *Options) Save() error {
 func (opt *Options) PrepareConfig(defaultConfig []byte) error {
 	filename := configs.FindConfig(opt.Config)
 	if filename == "" {
-		err := os.WriteFile(configs.ServerConfigFileName, defaultConfig, 0644)
+		target := opt.Config
+		if target == "" {
+			target = configs.ServerConfigFileName
+		}
+		err := os.WriteFile(target, defaultConfig, 0644)
 		if err != nil {
 			return err
 		}
-		logs.Log.Warnf("config file not found, created default config %s", configs.ServerConfigFileName)
-		filename = configs.ServerConfigFileName
+		logs.Log.Warnf("config file not found, created default config %s", target)
+		filename = target
 	}
 
 	config.WithOptions(config.WithHookFunc(func(event string, c *config.Config) {

server/cmd/server/quickstart.go

@@ -6,7 +6,6 @@ import (
 	"fmt"
 	"net"
 	"net/url"
-	"os"
 	"strconv"
 	"strings"
 
@@ -19,9 +18,19 @@ import (
 // RunQuickstart runs the interactive quickstart wizard using a single-page
 // tabbed form so that users can review/edit all configuration at once.
 func RunQuickstart(opt *Options) error {
+	if opt == nil {
+		return fmt.Errorf("options is required")
+	}
+
+	configPath := opt.Config
+	if configPath == "" {
+		configPath = configs.ServerConfigFileName
+		opt.Config = configPath
+	}
+
 	// skip if config already exists
-	if _, err := os.Stat(opt.Config); err == nil {
-		logs.Log.Warnf("config %s already exists, skipping quickstart", opt.Config)
+	if existing := configs.FindConfig(configPath); existing != "" {
+		logs.Log.Warnf("config %s already exists, skipping quickstart", existing)
 		return nil
 	}
 
@@ -85,7 +94,7 @@ func RunQuickstart(opt *Options) error {
 					Name: "encryption_key", Title: "Encryption Key",
 					Kind: wizard.KindInput, InputValue: encryptionKey,
 					Required: true,
-					Value: &encryptionKey,
+					Value:    &encryptionKey,
 				},
 			},
 		},
@@ -120,21 +129,21 @@ func RunQuickstart(opt *Options) error {
 				{
 					Name: "tcp_port", Title: "TCP Port",
 					Description: "ignored if tcp not selected",
-					Kind: wizard.KindInput, InputValue: tcpPort,
+					Kind:        wizard.KindInput, InputValue: tcpPort,
 					Validate: validatePort,
 					Value:    &tcpPort,
 				},
 				{
 					Name: "http_port", Title: "HTTP Port",
 					Description: "ignored if http not selected",
-					Kind: wizard.KindInput, InputValue: httpPort,
+					Kind:        wizard.KindInput, InputValue: httpPort,
 					Validate: validatePort,
 					Value:    &httpPort,
 				},
 				{
 					Name: "rem_name", Title: "REM Pipeline Name",
 					Description: "ignored if rem not selected",
-					Kind: wizard.KindInput, InputValue: remName,
+					Kind:        wizard.KindInput, InputValue: remName,
 					Value: &remName,
 				},
 			},
@@ -201,14 +210,14 @@ func RunQuickstart(opt *Options) error {
 				{
 					Name: "notify_param1", Title: "Webhook/Token/APIKey",
 					Description: "main credential for the service",
-					Kind: wizard.KindInput, InputValue: notifyParam1,
+					Kind:        wizard.KindInput, InputValue: notifyParam1,
 					Required: true,
 					Value:    &notifyParam1,
 				},
 				{
 					Name: "notify_param2", Title: "Secret/ChatID (optional)",
 					Description: "dingtalk secret or telegram chat ID",
-					Kind: wizard.KindInput, InputValue: notifyParam2,
+					Kind:        wizard.KindInput, InputValue: notifyParam2,
 					Value: &notifyParam2,
 				},
 			},
@@ -326,7 +335,7 @@ func RunQuickstart(opt *Options) error {
 		return fmt.Errorf("failed to save config: %w", err)
 	}
 
-	logs.Log.Importantf("quickstart config saved to %s", opt.Config)
+	logs.Log.Importantf("quickstart config saved to %s", configPath)
 	return nil
 }
 

server/cmd/server/quickstart_test.go

@@ -86,6 +86,99 @@ func TestValidateNotEmpty(t *testing.T) {
 	}
 }
 
+func TestShouldOfferQuickstart(t *testing.T) {
+	tests := []struct {
+		name             string
+		opt              *Options
+		configMissing    bool
+		interactive      bool
+		hasActiveCommand bool
+		want             bool
+	}{
+		{
+			name:             "default startup offers quickstart on interactive terminal",
+			opt:              &Options{},
+			configMissing:    true,
+			interactive:      true,
+			hasActiveCommand: false,
+			want:             true,
+		},
+		{
+			name:             "nil options never offer quickstart",
+			opt:              nil,
+			configMissing:    true,
+			interactive:      true,
+			hasActiveCommand: false,
+			want:             false,
+		},
+		{
+			name:             "explicit quickstart skips prompt",
+			opt:              &Options{Quickstart: true},
+			configMissing:    true,
+			interactive:      true,
+			hasActiveCommand: false,
+			want:             false,
+		},
+		{
+			name:             "existing config skips prompt",
+			opt:              &Options{},
+			configMissing:    false,
+			interactive:      true,
+			hasActiveCommand: false,
+			want:             false,
+		},
+		{
+			name:             "non interactive terminal skips prompt",
+			opt:              &Options{},
+			configMissing:    true,
+			interactive:      false,
+			hasActiveCommand: false,
+			want:             false,
+		},
+		{
+			name:             "active subcommand skips prompt",
+			opt:              &Options{},
+			configMissing:    true,
+			interactive:      true,
+			hasActiveCommand: true,
+			want:             false,
+		},
+		{
+			name:             "daemon mode skips prompt",
+			opt:              &Options{Daemon: true},
+			configMissing:    true,
+			interactive:      true,
+			hasActiveCommand: false,
+			want:             false,
+		},
+		{
+			name:             "server only skips prompt",
+			opt:              &Options{ServerOnly: true},
+			configMissing:    true,
+			interactive:      true,
+			hasActiveCommand: false,
+			want:             false,
+		},
+		{
+			name:             "listener only skips prompt",
+			opt:              &Options{ListenerOnly: true},
+			configMissing:    true,
+			interactive:      true,
+			hasActiveCommand: false,
+			want:             false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := shouldOfferQuickstart(tt.opt, tt.configMissing, tt.interactive, tt.hasActiveCommand)
+			if got != tt.want {
+				t.Fatalf("shouldOfferQuickstart() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
 func TestRandomHex(t *testing.T) {
 	h := randomHex(16)
 	if len(h) != 32 {

server/cmd/server/server.go

@@ -1,8 +1,11 @@
 package server
 
 import (
+	"bufio"
 	"fmt"
+	"io"
 	"os"
+	"strings"
 
 	"github.com/chainreactors/logs"
 	"github.com/chainreactors/malice-network/helper/codenames"
@@ -28,6 +31,47 @@ func init() {
 	assets.SetupGithubFile()
 }
 
+func isInteractiveTerminal() bool {
+	stdinInfo, err := os.Stdin.Stat()
+	if err != nil {
+		return false
+	}
+	stdoutInfo, err := os.Stdout.Stat()
+	if err != nil {
+		return false
+	}
+	return stdinInfo.Mode()&os.ModeCharDevice != 0 && stdoutInfo.Mode()&os.ModeCharDevice != 0
+}
+
+func shouldOfferQuickstart(opt *Options, configMissing bool, interactive bool, hasActiveCommand bool) bool {
+	if opt == nil {
+		return false
+	}
+	if opt.Quickstart || !configMissing || !interactive || hasActiveCommand {
+		return false
+	}
+	if opt.ServerOnly || opt.ListenerOnly || opt.Daemon {
+		return false
+	}
+	return true
+}
+
+func promptQuickstart(configPath string) (bool, error) {
+	if configPath == "" {
+		configPath = configs.ServerConfigFileName
+	}
+
+	fmt.Printf("config %s not found. Run quickstart wizard now? [y/N] ", configPath)
+	reader := bufio.NewReader(os.Stdin)
+	line, err := reader.ReadString('\n')
+	if err != nil && err != io.EOF {
+		return false, err
+	}
+
+	answer := strings.ToLower(strings.TrimSpace(line))
+	return answer == "y" || answer == "yes", nil
+}
+
 func Start(defaultConfig []byte) error {
 	var opt Options
 	var err error
@@ -40,10 +84,22 @@ func Start(defaultConfig []byte) error {
 		}
 		return nil
 	}
-	if _, statErr := os.Stat(opt.Config); opt.Quickstart || os.IsNotExist(statErr) {
+
+	configMissing := configs.FindConfig(opt.Config) == ""
+	if opt.Quickstart {
 		if err := RunQuickstart(&opt); err != nil {
 			return fmt.Errorf("quickstart failed: %w", err)
 		}
+	} else if shouldOfferQuickstart(&opt, configMissing, isInteractiveTerminal(), parser.Active != nil) {
+		runWizard, promptErr := promptQuickstart(opt.Config)
+		if promptErr != nil {
+			return fmt.Errorf("prompt quickstart: %w", promptErr)
+		}
+		if runWizard {
+			if err := RunQuickstart(&opt); err != nil {
+				return fmt.Errorf("quickstart failed: %w", err)
+			}
+		}
 	}
 
 	err = opt.PrepareConfig(defaultConfig)