Initial commit: TaskPool React panel

- React frontend with route-level code splitting - Backend rebranded from Baihu to TaskPool - DB brand migration script and local compatibility
2026-07-26 08:43:52 +08:00
commit e6956aa001
397 changed files with 73621 additions and 0 deletions
@@ -0,0 +1,239 @@
+package executor
+
+import (
+	"fmt"
+	"math/rand"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/engigu/taskpool/internal/systime"
+
+	"github.com/robfig/cron/v3"
+)
+
+// 东八区时区（默认）
+var defaultLocation = systime.CST
+
+// CronManager 统一的任务调度管理器
+type CronManager struct {
+	cron      *cron.Cron
+	scheduler *Scheduler
+	entryMap  map[string]cron.EntryID // task ID -> cron entry ID
+	mu        sync.RWMutex
+	logger    SchedulerLogger
+	OnTrigger func(task CronTask) *ExecutionRequest // 任务触发时的请求构造工厂
+}
+
+// NewCronManager 创建一个新的计划任务管理器
+func NewCronManager(scheduler *Scheduler) *CronManager {
+	// 使用秒级精度的 cron parser
+	c := cron.New(cron.WithSeconds(), cron.WithLocation(defaultLocation))
+
+	m := &CronManager{
+		cron:      c,
+		scheduler: scheduler,
+		entryMap:  make(map[string]cron.EntryID),
+		logger:    &DefaultLogger{},
+	}
+
+	if scheduler != nil && scheduler.logger != nil {
+		m.logger = scheduler.logger
+	}
+
+	return m
+}
+
+// SetLogger 设置自定义日志实现
+func (m *CronManager) SetLogger(logger SchedulerLogger) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.logger = logger
+}
+
+// SetScheduler 更新关联的调度器实例
+func (m *CronManager) SetScheduler(scheduler *Scheduler) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.scheduler = scheduler
+}
+
+// Start 启动调度器
+func (m *CronManager) Start() {
+	m.cron.Start()
+	m.logger.Infof("[CronManager] 调度管理服务已启动")
+}
+
+// Stop 停止调度器
+func (m *CronManager) Stop() {
+	ctx := m.cron.Stop()
+	<-ctx.Done()
+	m.logger.Infof("[CronManager] 调度管理服务已停止")
+}
+
+// AddTask 添加或更新计划任务
+func (m *CronManager) AddTask(task CronTask) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	taskID := task.GetID()
+
+	// 如果已存在，先移除旧的
+	if entryID, exists := m.entryMap[taskID]; exists {
+		m.cron.Remove(entryID)
+		delete(m.entryMap, taskID)
+	}
+
+	// 准备任务执行函数
+	cmd := task.GetCommand()
+	name := task.GetName()
+	timeout := task.GetTimeout()
+	workDir := task.GetWorkDir()
+	envs := task.GetEnvs()
+	languages := task.GetLanguages()
+	useMise := task.UseMise()
+	secrets := task.GetSecrets()
+
+	schedule := strings.TrimSpace(task.GetSchedule())
+	entryID, err := m.cron.AddFunc(schedule, func() {
+		defer func() {
+			if r := recover(); r != nil {
+				m.logger.Errorf("[CronManager] 任务 #%s 执行过程中发生 Panic: %v", taskID, r)
+			}
+		}()
+
+		// 构造执行请求的 Builder
+		reqBuilder := func() *ExecutionRequest {
+			if m.OnTrigger != nil {
+				return m.OnTrigger(task)
+			}
+			return &ExecutionRequest{
+				TaskID:      taskID,
+				Name:        name,
+				Command:     cmd,
+				PreCommand:  task.GetPreCommand(),
+				PostCommand: task.GetPostCommand(),
+				Type:        TaskTypeCron,
+				Timeout:     timeout,
+				WorkDir:     workDir,
+				Envs: func() []string {
+					if vars := task.GetEnvVars(); len(vars) > 0 {
+						return vars
+					}
+					return ParseEnvVars(envs)
+				}(),
+				Secrets:   secrets,
+				Languages: languages,
+				UseMise:   useMise,
+			}
+		}
+
+		randomRange := task.GetRandomRange()
+		if randomRange > 0 && m.scheduler != nil {
+			// 生成 0 到 randomRange 之间的随机秒数
+			delaySeconds := rand.Intn(randomRange)
+			delay := time.Duration(delaySeconds) * time.Second
+			m.logger.Infof("[CronManager] 任务 %s (#%s) 将随机延迟 %v (范围: %ds) 后入队", name, taskID, delay, randomRange)
+
+			// 使用调度器的延时投递功能，不阻塞当前 Cron 协程
+			m.scheduler.EnqueueDelayed(delay, reqBuilder)
+		} else {
+			m.logger.Infof("[CronManager] 触发计划任务: %s (#%s)", name, taskID)
+			if m.scheduler != nil {
+				m.scheduler.EnqueueOrExecute(reqBuilder())
+			}
+		}
+
+		// 触发下次运行时间更新事件
+		m.triggerNextRunEvent(taskID, &ExecutionRequest{TaskID: taskID})
+	})
+
+	if err != nil {
+		m.logger.Errorf("[CronManager] 添加任务失败 #%s: %v", taskID, err)
+		return err
+	}
+
+	m.entryMap[taskID] = entryID
+	m.logger.Infof("[CronManager] 已添加调度: %s (#%s) [%s]", name, taskID, task.GetSchedule())
+
+	// 初始触发一次下次运行时间通知
+	go func() {
+		req := &ExecutionRequest{
+			TaskID:  taskID,
+			Name:    name,
+			Type:    TaskTypeCron,
+			UseMise: task.UseMise(),
+		}
+		m.triggerNextRunEvent(taskID, req)
+	}()
+
+	return nil
+}
+
+// RemoveTask 移除计划任务
+func (m *CronManager) RemoveTask(taskID string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if entryID, exists := m.entryMap[taskID]; exists {
+		m.cron.Remove(entryID)
+		delete(m.entryMap, taskID)
+		m.logger.Infof("[CronManager] 任务已移除 #%s", taskID)
+	}
+}
+
+// triggerNextRunEvent 触发下次运行时间更新事件
+func (m *CronManager) triggerNextRunEvent(taskID string, req *ExecutionRequest) {
+	m.mu.RLock()
+	entryID, exists := m.entryMap[taskID]
+	m.mu.RUnlock()
+
+	if !exists {
+		return
+	}
+
+	entry := m.cron.Entry(entryID)
+	if !entry.Next.IsZero() && m.scheduler != nil && m.scheduler.handler != nil {
+		m.scheduler.handler.OnCronNextRun(req, entry.Next)
+	}
+}
+
+// ValidateCron 校验 Cron 表达式
+func (m *CronManager) ValidateCron(expression string) error {
+	expression = strings.TrimSpace(expression)
+	if expression == "" {
+		return fmt.Errorf("cron 表达式不能为空")
+	}
+
+	// 如果不是以 @ 开头的描述符，检查位数
+	if !strings.HasPrefix(expression, "@") {
+		fields := strings.Fields(expression)
+		if len(fields) != 6 {
+			return fmt.Errorf("cron 表达式必须为 6 位 (秒 分 时 日 月 周)")
+		}
+	}
+
+	parser := cron.NewParser(cron.Second | cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor)
+	_, err := parser.Parse(expression)
+	return err
+}
+
+// GetEntry 获取任务详情
+func (m *CronManager) GetEntry(taskID string) (cron.Entry, bool) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	entryID, exists := m.entryMap[taskID]
+	if !exists {
+		return cron.Entry{}, false
+	}
+
+	return m.cron.Entry(entryID), true
+}
+
+// GetScheduledCount 获取已调度任务总数
+func (m *CronManager) GetScheduledCount() int {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	return len(m.entryMap)
+}
@@ -0,0 +1,388 @@
+package executor
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"runtime"
+	"strings"
+	"time"
+
+	"github.com/creack/pty"
+	"github.com/engigu/taskpool/internal/constant"
+	"github.com/engigu/taskpool/internal/logger"
+	"github.com/engigu/taskpool/internal/utils"
+)
+
+// Task 任务基础接口
+type Task interface {
+	GetID() string
+	GetName() string
+	GetCommand() string
+	GetPreCommand() string
+	GetPostCommand() string
+	GetTimeout() int
+	GetWorkDir() string
+	GetEnvs() string
+	GetEnvVars() []string
+	GetLanguages() []map[string]string
+	GetUseMise() bool
+}
+
+// CronTask 计划任务接口
+type CronTask interface {
+	Task
+	GetSchedule() string
+	UseMise() bool
+	GetSecrets() []string
+	GetRandomRange() int
+}
+
+// Request 任务执行请求
+type Request struct {
+	Command     string
+	PreCommand  string
+	PostCommand string
+	WorkDir     string
+	Envs        []string
+	Timeout     int // 任务超时时间（分钟）
+	Languages   []map[string]string
+	UseMise     bool
+}
+
+// Result 任务执行结果
+type Result struct {
+	Output    string
+	Error     string
+	Status    string // 状态: success, failed
+	Duration  int64  // 毫秒
+	ExitCode  int
+	StartTime time.Time
+	EndTime   time.Time
+}
+
+// Hooks 执行钩子接口
+type Hooks interface {
+	// PreExecute 执行前钩子，返回日志ID和错误
+	PreExecute(ctx context.Context, req Request) (logID string, err error)
+
+	// PostExecute 执行后钩子，处理日志压缩和记录更新
+	PostExecute(ctx context.Context, logID string, result *Result) error
+
+	// OnHeartbeat 执行中心跳钩子，用于更新实时状态
+	OnHeartbeat(ctx context.Context, logID string, duration int64) error
+}
+
+// Execute 执行命令（基础版本，不带钩子）
+func Execute(ctx context.Context, req Request, stdout, stderr io.Writer) (*Result, error) {
+	return ExecuteWithHooks(ctx, req, stdout, stderr, nil)
+}
+
+// ExecuteWithHooks 执行命令（带钩子支持）
+func ExecuteWithHooks(ctx context.Context, req Request, stdout, stderr io.Writer, hooks Hooks) (*Result, error) {
+	start := time.Now()
+
+	// 演示模式拦截
+	if constant.DemoMode {
+		logger.Warnf("[Executor] 演示模式下已拦截命令执行: %s", req.Command)
+		if stdout != nil {
+			stdout.Write([]byte("\r\n\033[1;33m[演示模式] 命令执行已跳过\033[0m\r\n"))
+		}
+
+		// 仍然触发 PreExecute 以便流程完整
+		var logID string
+		if hooks != nil {
+			logID, _ = hooks.PreExecute(ctx, req)
+		}
+
+		result := &Result{
+			Status:    constant.TaskStatusFailed,
+			Output:    "[演示模式] 该任务在演示模式下被禁用执行",
+			StartTime: start,
+			EndTime:   time.Now(),
+		}
+
+		if hooks != nil {
+			hooks.PostExecute(ctx, logID, result)
+		}
+		return result, nil
+	}
+
+	// 2. 执行命令
+	timeout := req.Timeout
+	var execCtx context.Context
+	var cancel context.CancelFunc
+
+	if timeout > 0 {
+		execCtx, cancel = context.WithTimeout(ctx, time.Duration(timeout)*time.Minute)
+	} else {
+		execCtx, cancel = context.WithCancel(ctx)
+	}
+	defer cancel()
+
+	// 如果指定使用 mise，则预先构建好带 mise 的命令，这样 PreExecute 记录的就是完整命令
+	if req.UseMise {
+		utils.InjectNodePath(&req.Envs, req.Languages)
+		req.Command = utils.BuildMiseCommand(req.Command, req.Languages)
+		req.UseMise = false
+	}
+
+	// 组合指令（如果存在前置或后置指令）
+	if req.PreCommand != "" || req.PostCommand != "" {
+		finalCmd := ""
+		if req.PreCommand != "" {
+			finalCmd += req.PreCommand + "\n"
+		}
+		finalCmd += req.Command
+		if req.PostCommand != "" {
+			finalCmd += "\n" + req.PostCommand
+		}
+		req.Command = finalCmd
+	}
+
+	// 1. 执行前钩子
+	var logID string
+	if hooks != nil {
+		id, err := hooks.PreExecute(ctx, req)
+		if err != nil {
+			return &Result{
+				Status:    constant.TaskStatusFailed,
+				Duration:  0,
+				ExitCode:  1,
+				StartTime: start,
+				EndTime:   time.Now(),
+			}, err
+		}
+		logID = id
+	}
+
+	shell, args := utils.GetShellCommand(req.Command)
+	cmd := exec.CommandContext(execCtx, shell, args...)
+
+	usePty := runtime.GOOS != "windows" && stdout != nil && (stdout == stderr || stdout == io.Discard)
+	SetProcessGroupAndCancel(cmd, usePty)
+
+	// 设置工作目录
+	// 设置工作目录
+	workDir := strings.TrimSpace(req.WorkDir)
+	if workDir != "" {
+		cmd.Dir = workDir
+	}
+
+	// 设置环境变量（始终继承系统环境变量）
+	cmd.Env = os.Environ()
+	if len(req.Envs) > 0 {
+		cmd.Env = append(cmd.Env, req.Envs...)
+	}
+	// 强制注入终端环境标识及禁用输出缓冲的标志
+	cmd.Env = append(cmd.Env,
+		"TERM=xterm",
+		"PYTHONUNBUFFERED=1",
+		"NODE_NO_WARNINGS=1",
+	)
+
+	var pipeWriter *os.File
+	var ptyFile *os.File
+	var copyDone chan struct{}
+	var err error
+
+	var started bool
+	// 尝试开启 PTY 模式（Unix/macOS 且输出合并时）
+	if runtime.GOOS != "windows" && stdout != nil && (stdout == stderr || stdout == io.Discard) {
+		// 强制注入终端环境标识及禁用输出缓冲的标志，确保 PTY 模式下最佳实时性能
+		cmd.Env = append(cmd.Env,
+			"TERM=xterm",
+			"PYTHONUNBUFFERED=1",
+			"NODE_NO_WARNINGS=1",
+		)
+		f, ptyErr := pty.Start(cmd)
+		if ptyErr == nil {
+			logger.Infof("[Executor] #%s 启动于 PTY 模式", logID)
+			ptyFile = f
+			started = true
+			copyDone = make(chan struct{})
+			go func() {
+				defer close(copyDone)
+				// io.Copy 对于 PTY 来说是最稳健且即时的流式拷贝
+				io.Copy(stdout, f)
+				f.Close()
+			}()
+		} else {
+			logger.Errorf("[Executor] 任务 #%s PTY 启动失败: %v", logID, ptyErr)
+		}
+	}
+
+	if !started {
+		// 如果 stdout 和 stderr 指针不一致，但在逻辑上我们知道它们是同一个 MultiWriter，
+		// 这里会显示为 Pipe 模式。
+		if stdout != stderr && stdout != io.Discard {
+			logger.Debugf("[Executor] 任务 #%d stdout (%p) 和 stderr (%p) 不同，回退到 Pipe 模式。", logID, stdout, stderr)
+		}
+		logger.Infof("[Executor] #%s 启动于 Pipe 模式", logID)
+		if stdout != nil && stdout == stderr {
+			pr, pw, err := os.Pipe()
+			if err == nil {
+				cmd.Stdout = pw
+				cmd.Stderr = pw
+				pipeWriter = pw
+				copyDone = make(chan struct{})
+				go func() {
+					io.Copy(stdout, pr)
+					pr.Close()
+					close(copyDone)
+				}()
+			} else {
+				cmd.Stdout = stdout
+				cmd.Stderr = stderr
+			}
+		} else {
+			cmd.Stdout = stdout
+			cmd.Stderr = stderr
+		}
+
+		// 使用 cmd.Start() + Wait() 以便在后台处理心跳
+		err = cmd.Start()
+		if err != nil {
+			if pipeWriter != nil {
+				pipeWriter.Close()
+			}
+			// 启动失败的处理
+			end := time.Now()
+			result := &Result{
+				Status:    constant.TaskStatusFailed,
+				Duration:  end.Sub(start).Milliseconds(),
+				ExitCode:  1,
+				StartTime: start, // 记录开始时间
+				EndTime:   end,
+			}
+			// 执行后钩子
+			if hooks != nil {
+				result.Output += "\n[系统错误] " + err.Error()
+				hooks.PostExecute(ctx, logID, result)
+			}
+			return result, err
+		}
+
+		// 在父进程中关闭写端，这样子进程退出后 pr 才会收到 EOF
+		if pipeWriter != nil {
+			pipeWriter.Close()
+		}
+	} else {
+		// PTY 模式下 cmd.Start() 已经在 pty.Start(cmd) 中调用过了
+	}
+
+	// 启动心跳协程
+	done := make(chan struct{})
+	go func() {
+		// 每3秒一次心跳
+		ticker := time.NewTicker(3 * time.Second)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-done:
+				return
+			case <-ticker.C:
+				if hooks != nil {
+					hooks.OnHeartbeat(ctx, logID, time.Since(start).Milliseconds())
+				}
+			}
+		}
+	}()
+
+	// 等待命令完成
+	err = cmd.Wait()
+	close(done) // 停止心跳
+
+	// PTY 模式下需要显式关闭
+	if ptyFile != nil {
+		ptyFile.Close()
+	}
+
+	// 等待日志复制完成
+	if copyDone != nil {
+		<-copyDone
+	}
+
+	end := time.Now()
+
+	result := &Result{
+		StartTime: start,
+		EndTime:   end,
+		Duration:  end.Sub(start).Milliseconds(),
+	}
+
+	if err != nil {
+		result.Status = constant.TaskStatusFailed
+		result.Error = err.Error()
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			result.ExitCode = exitErr.ExitCode()
+		} else {
+			result.ExitCode = 1
+		}
+	} else {
+		result.Status = constant.TaskStatusSuccess
+		result.ExitCode = 0
+	}
+
+	// 3. 执行后钩子
+	if hooks != nil {
+		if hookErr := hooks.PostExecute(ctx, logID, result); hookErr != nil {
+			// 记录钩子错误但不影响执行结果
+			result.Output += "\n[钩子错误] " + hookErr.Error()
+		}
+	}
+
+	return result, err
+}
+
+// ParseEnvVars 解析环境变量字符串 "KEY1=VALUE1,KEY2=VALUE2"
+func ParseEnvVars(envStr string) []string {
+	if envStr == "" {
+		return nil
+	}
+
+	pairs := strings.Split(envStr, ",")
+	result := make([]string, 0, len(pairs))
+
+	for _, pair := range pairs {
+		if pair == "" {
+			continue
+		}
+		// 解码特殊字符
+		pair = strings.ReplaceAll(pair, "{{COMMA}}", ",")
+		pair = strings.ReplaceAll(pair, "{{EQUAL}}", "=")
+		pair = strings.ReplaceAll(pair, "{{NL}}", "\n")
+		result = append(result, pair)
+	}
+
+	return result
+}
+
+// FormatEnvVars 将环境变量列表格式化为逗号分隔的字符串 "KEY1=VALUE1,KEY2=VALUE2"
+// 会对 , 和 = 以及换行符进行转义
+func FormatEnvVars(envs []string) string {
+	if len(envs) == 0 {
+		return ""
+	}
+
+	pairs := make([]string, 0, len(envs))
+	for _, pair := range envs {
+		// 寻找第一个等号
+		idx := strings.Index(pair, "=")
+		if idx == -1 {
+			continue
+		}
+		name := pair[:idx]
+		value := pair[idx+1:]
+
+		// 转义特殊字符
+		encodedValue := strings.ReplaceAll(value, ",", "{{COMMA}}")
+		encodedValue = strings.ReplaceAll(encodedValue, "=", "{{EQUAL}}")
+		encodedValue = strings.ReplaceAll(encodedValue, "\n", "{{NL}}")
+		pairs = append(pairs, fmt.Sprintf("%s=%s", name, encodedValue))
+	}
+
+	return strings.Join(pairs, ",")
+}
@@ -0,0 +1,21 @@
+//go:build !windows
+
+package executor
+
+import (
+	"os/exec"
+	"syscall"
+)
+
+func SetProcessGroupAndCancel(cmd *exec.Cmd, usePty bool) {
+	if !usePty {
+		cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	}
+	cmd.Cancel = func() error {
+		if cmd.Process != nil {
+			// Kill the entire process group by sending SIGKILL to negative PID
+			return syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		}
+		return nil
+	}
+}
@@ -0,0 +1,18 @@
+//go:build windows
+
+package executor
+
+import (
+	"fmt"
+	"os/exec"
+)
+
+func SetProcessGroupAndCancel(cmd *exec.Cmd, usePty bool) {
+	cmd.Cancel = func() error {
+		if cmd.Process != nil {
+			killCmd := exec.Command("taskkill", "/F", "/T", "/PID", fmt.Sprintf("%d", cmd.Process.Pid))
+			return killCmd.Run()
+		}
+		return nil
+	}
+}
@@ -0,0 +1,690 @@
+package executor
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"sync"
+	"time"
+
+	"github.com/engigu/taskpool/internal/constant"
+	"github.com/engigu/taskpool/internal/utils"
+)
+
+// safeBuffer 一个线程安全的字节缓冲区，用于合并 stdout 和 stderr
+type safeBuffer struct {
+	mu  sync.Mutex
+	buf bytes.Buffer
+}
+
+func (s *safeBuffer) Write(p []byte) (n int, err error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.buf.Write(p)
+}
+
+func (s *safeBuffer) String() string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.buf.String()
+}
+
+// SchedulerConfig 调度器配置
+type SchedulerConfig struct {
+	WorkerCount  int           // Worker 数量
+	QueueSize    int           // 队列大小
+	RateInterval time.Duration // 速率限制间隔
+	Verbose      bool          // 是否开启详细日志
+	StrictQueue  bool          // 是否开启严格排队（满时拒绝执行，不降级直接执行）
+}
+
+// TaskType 任务类型
+type TaskType string
+
+const (
+	TaskTypeCron   TaskType = "cron"   // 计划任务
+	TaskTypeManual TaskType = "manual" // 手动任务
+	TaskTypeSystem TaskType = "system" // 系统任务
+)
+
+// TaskStatus 任务状态
+type TaskStatus string
+
+const (
+	TaskStatusPending   TaskStatus = TaskStatus(constant.TaskStatusPending)   // 等待中
+	TaskStatusRunning   TaskStatus = TaskStatus(constant.TaskStatusRunning)   // 运行中
+	TaskStatusSuccess   TaskStatus = TaskStatus(constant.TaskStatusSuccess)   // 成功
+	TaskStatusFailed    TaskStatus = TaskStatus(constant.TaskStatusFailed)    // 失败
+	TaskStatusTimeout   TaskStatus = TaskStatus(constant.TaskStatusTimeout)   // 超时
+	TaskStatusCancelled TaskStatus = TaskStatus(constant.TaskStatusCancelled) // 已取消
+)
+
+// ExecutionRequest 执行请求（标准接口）
+type ExecutionRequest struct {
+	TaskID        string              // 任务 ID
+	LogID         string              // 日志 ID
+	Name          string              // 任务名称
+	Type          TaskType            // 任务类型
+	Command       string              // 命令
+	MaskedCommand string              // 脱敏后的命令（用于日志和展示）
+	PreCommand    string              // 前置命令
+	PostCommand   string              // 后置命令
+	WorkDir       string              // 工作目录
+	Envs          []string            // 环境变量
+	Secrets       []string            // 需要脱敏的密码
+	Timeout       int                 // 超时时间（分钟）
+	Languages     []map[string]string // 语言环境配置
+	UseMise       bool                // 是否使用 mise
+	Metadata      ExecutionMetadata   // 额外元数据
+}
+
+// ExecutionMetadata 执行额外元数据
+type ExecutionMetadata struct {
+	GoID       int64 // 关联的 goroutine ID
+	RetryIndex int   // 当前重试索引
+}
+
+// ExecutionResult 执行结果（标准接口）
+type ExecutionResult struct {
+	TaskID    string    // 任务 ID
+	LogID     string    // 日志 ID
+	Success   bool      // 是否成功
+	Output    string    // 输出内容
+	Error     string    // 错误信息
+	Status    string    // 状态: success, failed, timeout, cancelled
+	Duration  int64     // 执行时长（毫秒）
+	ExitCode  int       // 退出码
+	StartTime time.Time // 开始时间
+	EndTime   time.Time // 结束时间
+}
+
+// SchedulerEventHandler 调度器事件处理器（标准接口）
+// 主服务端和 Agent 端通过实现不同的 Handler 来处理事件
+type SchedulerEventHandler interface {
+	// OnTaskScheduled 任务被调度（加入队列）时触发
+	OnTaskScheduled(req *ExecutionRequest)
+
+	// OnTaskExecuting 任务准备开始执行时触发
+	// 返回 stdout/stderr 写入器用于实时日志推送
+	// 主服务端：返回 TinyLog 写入器（写入本地文件）
+	// Agent 端：返回 WebSocket 写入器（实时推送到主服务）
+	OnTaskExecuting(req *ExecutionRequest) (stdout, stderr io.Writer, err error)
+
+	// OnTaskStarted 任务实际开始运行（已经过了队列等待和速率限制）
+	OnTaskStarted(req *ExecutionRequest)
+
+	// OnTaskCompleted 任务执行完成时触发
+	// 主服务端：压缩日志、更新数据库、清理旧日志
+	// Agent 端：通过 WebSocket 发送执行结果到主服务
+	OnTaskCompleted(req *ExecutionRequest, result *ExecutionResult)
+
+	// OnTaskFailed 任务执行失败时触发
+	OnTaskFailed(req *ExecutionRequest, err error)
+
+	// OnCronNextRun 计划任务下次运行时间更新时触发
+	OnCronNextRun(req *ExecutionRequest, nextRun time.Time)
+
+	// OnTaskHeartbeat 任务执行心跳（用于更新实时耗时等）
+	OnTaskHeartbeat(req *ExecutionRequest, duration int64)
+}
+
+// SchedulerLogger 日志接口（允许自定义日志实现）
+type SchedulerLogger interface {
+	Infof(format string, args ...interface{})
+	Warnf(format string, args ...interface{})
+	Errorf(format string, args ...interface{})
+}
+
+// DefaultLogger 默认日志实现（使用 fmt）
+type DefaultLogger struct{}
+
+func (l *DefaultLogger) Infof(format string, args ...interface{}) {
+	fmt.Printf("[INFO] "+format+"\n", args...)
+}
+func (l *DefaultLogger) Warnf(format string, args ...interface{}) {
+	fmt.Printf("[WARN] "+format+"\n", args...)
+}
+func (l *DefaultLogger) Errorf(format string, args ...interface{}) {
+	fmt.Printf("[ERROR] "+format+"\n", args...)
+}
+
+// schedulerHooksAdapter 适配器：将 executor.Hooks 映射到 SchedulerEventHandler
+type schedulerHooksAdapter struct {
+	handler SchedulerEventHandler
+	req     *ExecutionRequest
+}
+
+func (h *schedulerHooksAdapter) PreExecute(ctx context.Context, req Request) (string, error) {
+	return h.req.LogID, nil
+}
+
+func (h *schedulerHooksAdapter) PostExecute(ctx context.Context, logID string, result *Result) error {
+	return nil
+}
+
+func (h *schedulerHooksAdapter) OnHeartbeat(ctx context.Context, logID string, duration int64) error {
+	if h.handler != nil {
+		h.handler.OnTaskHeartbeat(h.req, duration)
+	}
+	return nil
+}
+
+// TaskExecutor 定义任务执行函数签名
+type TaskExecutor func(ctx context.Context, req *ExecutionRequest, stdout, stderr io.Writer) (*Result, error)
+
+// WorkerStatus 定义并发池中单个 Worker 的状态
+type WorkerStatus struct {
+	ID        int    `json:"id"`
+	Status    string `json:"status"` // 状态: "idle" 或 "running"
+	TaskID    string `json:"task_id,omitempty"`
+	TaskName  string `json:"task_name,omitempty"`
+	StartTime int64  `json:"start_time,omitempty"` // 开始时间戳 (秒)
+	Duration  int64  `json:"duration,omitempty"`   // 已运行时长 (秒)
+}
+
+// Scheduler 统一调度器（独立组件，可在主服务和 Agent 中复用）
+// 调度器本身只负责队列管理和任务调度，具体的执行逻辑和事件处理由 Handler 实现
+type Scheduler struct {
+	config       SchedulerConfig
+	handler      SchedulerEventHandler
+	executor     TaskExecutor
+	taskQueue    chan *ExecutionRequest
+	rateLimiter  <-chan time.Time
+	stopCh       chan struct{}
+	wg           sync.WaitGroup
+	mu           sync.RWMutex
+	logger       SchedulerLogger
+	runningTasks map[string]context.CancelFunc // 记录运行中的任务，用于停止 (TaskID -> CancelFunc)
+	runningExecs map[string]context.CancelFunc // 记录运行中的执行，用于停止 (LogID -> CancelFunc)
+
+	workers      []WorkerStatus
+	workerMu     sync.RWMutex
+}
+
+// NewScheduler 创建调度器
+func NewScheduler(config SchedulerConfig, handler SchedulerEventHandler) *Scheduler {
+	if config.WorkerCount <= 0 {
+		config.WorkerCount = 4
+	}
+	if config.WorkerCount > 1000 {
+		config.WorkerCount = 1000
+	}
+	if config.QueueSize <= 0 {
+		config.QueueSize = 100
+	}
+	if config.QueueSize > 50000 {
+		config.QueueSize = 50000
+	}
+	if config.RateInterval <= 0 {
+		config.RateInterval = 200 * time.Millisecond
+	}
+
+	s := &Scheduler{
+		config:  config,
+		handler: handler,
+		executor: func(ctx context.Context, req *ExecutionRequest, stdout, stderr io.Writer) (*Result, error) {
+			hooks := &schedulerHooksAdapter{handler: handler, req: req}
+			return ExecuteWithHooks(ctx, Request{
+				Command:     req.Command,
+				PreCommand:  req.PreCommand,
+				PostCommand: req.PostCommand,
+				WorkDir:     req.WorkDir,
+				Envs:        req.Envs,
+				Timeout:     req.Timeout,
+				Languages:   req.Languages,
+				UseMise:     req.UseMise,
+			}, stdout, stderr, hooks)
+		},
+		taskQueue:    make(chan *ExecutionRequest, config.QueueSize),
+		rateLimiter:  time.Tick(config.RateInterval),
+		stopCh:       make(chan struct{}),
+		logger:       &DefaultLogger{},
+		runningTasks: make(map[string]context.CancelFunc),
+		runningExecs: make(map[string]context.CancelFunc),
+		workers:      make([]WorkerStatus, config.WorkerCount),
+	}
+
+	for i := 0; i < config.WorkerCount; i++ {
+		s.workers[i] = WorkerStatus{
+			ID:     i,
+			Status: "idle",
+		}
+	}
+
+	return s
+}
+
+// SetLogger 设置自定义日志实现
+func (s *Scheduler) SetLogger(logger SchedulerLogger) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.logger = logger
+}
+
+// SetExecutor 设置任务执行器
+func (s *Scheduler) SetExecutor(executor TaskExecutor) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.executor = executor
+}
+
+// Start 启动调度器
+func (s *Scheduler) Start() {
+	for i := 0; i < s.config.WorkerCount; i++ {
+		s.wg.Add(1)
+		go s.worker(i)
+	}
+	s.logger.Infof("[Scheduler] 已启动")
+}
+
+// Stop 停止调度器
+func (s *Scheduler) Stop() {
+	close(s.stopCh)
+	s.wg.Wait()
+	s.logger.Infof("[Scheduler] 已停止")
+}
+
+// Enqueue 将任务加入队列
+func (s *Scheduler) Enqueue(req *ExecutionRequest) error {
+	select {
+	case s.taskQueue <- req:
+		if s.handler != nil {
+			s.handler.OnTaskScheduled(req)
+		}
+		return nil
+	default:
+		// 队列满，返回错误
+		return fmt.Errorf("任务队列已满")
+	}
+}
+
+// EnqueueOrExecute 将任务加入队列，如果队列满则直接执行
+func (s *Scheduler) EnqueueOrExecute(req *ExecutionRequest) {
+	select {
+	case s.taskQueue <- req:
+		// 成功入队
+		if s.handler != nil {
+			s.handler.OnTaskScheduled(req)
+		}
+	default:
+		if s.config.StrictQueue {
+			s.logger.Errorf("[Scheduler] 任务队列已满，拒绝执行任务 %s", req.TaskID)
+			if s.handler != nil {
+				s.handler.OnTaskFailed(req, fmt.Errorf("任务队列已满，拒绝执行"))
+			}
+		} else {
+			// 队列满，直接执行（降级处理）
+			s.logger.Warnf("[Scheduler] 任务队列已满，直接执行任务 %s", req.TaskID)
+			go s.executeTask(req)
+		}
+	}
+}
+
+// EnqueueDelayed 延迟将任务加入队列执行
+func (s *Scheduler) EnqueueDelayed(delay time.Duration, reqBuilder func() *ExecutionRequest) {
+	go func() {
+		select {
+		case <-time.After(delay):
+			if req := reqBuilder(); req != nil {
+				s.EnqueueOrExecute(req)
+			}
+		case <-s.stopCh:
+			// 调度器停止时取消延迟投递
+			return
+		}
+	}()
+}
+
+// ExecuteSync 同步执行任务（不经过队列）
+func (s *Scheduler) ExecuteSync(req *ExecutionRequest) (*ExecutionResult, error) {
+	return s.executeTask(req)
+}
+
+// worker 工作协程
+func (s *Scheduler) worker(id int) {
+	defer s.wg.Done()
+
+	for {
+		select {
+		case <-s.stopCh:
+			return
+		case req := <-s.taskQueue:
+			func() {
+				defer func() {
+					if r := recover(); r != nil {
+						s.logger.Errorf("[Scheduler] Worker %d panic while processing task %s: %v", id, req.TaskID, r)
+					}
+				}()
+				// 速率限制
+				<-s.rateLimiter
+
+				func() {
+					// 恢复 worker 状态为空闲
+					defer func() {
+						s.workerMu.Lock()
+						if id >= 0 && id < len(s.workers) {
+							s.workers[id].Status = "idle"
+							s.workers[id].TaskID = ""
+							s.workers[id].TaskName = ""
+							s.workers[id].StartTime = 0
+						}
+						s.workerMu.Unlock()
+					}()
+
+					// 更新 worker 状态为运行中
+					s.workerMu.Lock()
+					if id >= 0 && id < len(s.workers) {
+						s.workers[id].Status = "running"
+						s.workers[id].TaskID = req.TaskID
+						s.workers[id].TaskName = req.Name
+						s.workers[id].StartTime = time.Now().Unix()
+					}
+					s.workerMu.Unlock()
+
+					s.executeTask(req)
+				}()
+			}()
+		}
+	}
+}
+
+// executeTask 执行任务（本地执行）
+func (s *Scheduler) executeTask(req *ExecutionRequest) (*ExecutionResult, error) {
+	defer func() {
+		if r := recover(); r != nil {
+			s.logger.Errorf("[Scheduler] 任务 %s 执行过程中发生 Panic: %v", req.TaskID, r)
+		}
+	}()
+	start := time.Now()
+
+	s.logger.Infof("[Scheduler] 开始执行: %s (#%s) [%s]", req.Name, req.TaskID, req.Type)
+
+	// 演示模式拦截
+	if constant.DemoMode {
+		s.logger.Infof("[Scheduler] 演示模式下已跳过任务 %s (%s) 的执行", req.TaskID, req.Name)
+		// 仍然触发 OnTaskExecuting 以便创建初始日志记录（业务层面的 Handler 会处理）
+		var stdout io.Writer
+		if s.handler != nil {
+			stdout, _, _ = s.handler.OnTaskExecuting(req)
+		}
+
+		result := &ExecutionResult{
+			TaskID:    req.TaskID,
+			LogID:     req.LogID,
+			Success:   false,
+			Status:    constant.TaskStatusFailed,
+			Error:     "[演示模式] 该任务在演示模式下被禁用执行",
+			StartTime: start,
+			EndTime:   time.Now(),
+		}
+
+		if stdout != nil {
+			stdout.Write([]byte("\r\n\033[1;33m[演示模式] 定时任务/手动任务执行已跳过\033[0m\r\n"))
+		}
+
+		if s.handler != nil {
+			s.handler.OnTaskCompleted(req, result)
+		}
+		return result, nil
+	}
+
+	// 如果指定使用 mise，则预先构建好带 mise 的命令，这样 OnTaskExecuting 记录的就是完整命令
+	if req.UseMise {
+		// 先注入 NODE_PATH (由于调度器会把 UseMise 置为 false，所以必须在这里提前处理)
+		utils.InjectNodePath(&req.Envs, req.Languages)
+		req.Command = utils.BuildMiseCommand(req.Command, req.Languages)
+		req.UseMise = false
+	}
+	// 确保系统级敏感信息（数据库地址、账号、密码等）始终在脱敏列表中
+	allSecrets := append([]string{}, req.Secrets...)
+	allSecrets = append(allSecrets, utils.GetSystemSecrets()...)
+
+	s.logger.Infof("[Scheduler] 命令: %s", utils.MaskSecrets(req.Command, allSecrets))
+
+	if s.config.Verbose {
+		workDir := req.WorkDir
+		if workDir == "" {
+			workDir, _ = os.Getwd()
+		}
+		s.logger.Infof("[Scheduler] 任务 #%s 进程 UID: %d, GID: %d", req.TaskID, os.Getuid(), os.Getgid())
+		s.logger.Infof("[Scheduler] 任务 #%s 工作目录: %s", req.TaskID, workDir)
+	}
+
+	// 1. 执行前事件：获取 stdout/stderr 写入器
+	var stdout, stderr io.Writer
+	var err error
+	if s.handler != nil {
+		stdout, stderr, err = s.handler.OnTaskExecuting(req)
+		if err != nil {
+			s.logger.Errorf("[Scheduler] 任务 %s 执行前事件失败: %v", req.TaskID, err)
+			if s.handler != nil {
+				s.handler.OnTaskFailed(req, err)
+			}
+			return &ExecutionResult{
+				TaskID:    req.TaskID,
+				Success:   false,
+				Status:    constant.TaskStatusFailed,
+				Error:     err.Error(),
+				Duration:  0,
+				ExitCode:  1,
+				StartTime: start,
+				EndTime:   time.Now(),
+			}, err
+		}
+	}
+
+	// 2. 准备输出缓冲区（使用合并缓冲区保证顺序）
+	var combinedBuf safeBuffer
+	var stdoutWriter, stderrWriter io.Writer
+
+	if stdout != nil && stdout == stderr {
+		// 如果 stdout 和 stderr 是同一个对象，合并成一个 MultiWriter
+		// 这样后面 ExecuteWithHooks 才能识别出它们是同一个，从而开启 PTY 模式
+		mw := io.MultiWriter(&combinedBuf, stdout)
+		stdoutWriter = mw
+		stderrWriter = mw
+	} else {
+		if stdout != nil {
+			stdoutWriter = io.MultiWriter(&combinedBuf, stdout)
+		} else {
+			stdoutWriter = &combinedBuf
+		}
+
+		if stderr != nil {
+			stderrWriter = io.MultiWriter(&combinedBuf, stderr)
+		} else {
+			stderrWriter = &combinedBuf
+		}
+	}
+
+	// 3. 实际开始执行事件 (经过队列和速率限制之后)
+	if s.handler != nil {
+		s.handler.OnTaskStarted(req)
+	}
+
+	// 4. 执行命令（使用 executor.Execute）
+	// 创建带取消功能的上下文
+	ctx, cancel := context.WithCancel(context.Background())
+	if req.Timeout > 0 {
+		ctx, cancel = context.WithTimeout(ctx, time.Duration(req.Timeout)*time.Minute)
+	}
+	defer cancel()
+
+	// 注册到运行中任务
+	s.mu.Lock()
+	s.runningTasks[req.TaskID] = cancel
+	if req.LogID != "" {
+		s.runningExecs[req.LogID] = cancel
+	}
+	s.mu.Unlock()
+
+	defer func() {
+		s.mu.Lock()
+		delete(s.runningTasks, req.TaskID)
+		if req.LogID != "" {
+			delete(s.runningExecs, req.LogID)
+		}
+		s.mu.Unlock()
+	}()
+
+	execResult, execErr := s.executor(ctx, req, stdoutWriter, stderrWriter)
+
+	// 5. 构建结果
+	result := &ExecutionResult{
+		TaskID: req.TaskID,
+		LogID:  req.LogID, // 传递 LogID
+	}
+
+	// 统一获取输出并调用封装的脱敏函数
+	rawStr := utils.MaskSecrets(combinedBuf.String(), req.Secrets)
+
+	if execResult != nil {
+		result.Success = execResult.Status == constant.TaskStatusSuccess
+		result.Output = rawStr
+		result.Status = execResult.Status
+		result.Duration = execResult.Duration
+		result.ExitCode = execResult.ExitCode
+		result.StartTime = execResult.StartTime
+		result.EndTime = execResult.EndTime
+	} else {
+		result.Success = false
+		result.Status = constant.TaskStatusFailed
+		result.StartTime = start
+		result.EndTime = time.Now()
+		result.Duration = result.EndTime.Sub(result.StartTime).Milliseconds()
+		result.Output = rawStr
+	}
+
+	if execErr != nil {
+		result.Error = execErr.Error()
+		if ctx.Err() == context.Canceled {
+			result.Status = constant.TaskStatusCancelled
+		} else if ctx.Err() == context.DeadlineExceeded {
+			result.Status = constant.TaskStatusTimeout
+		}
+	}
+
+	// 6. 执行后事件
+	if s.handler != nil {
+		if execResult != nil {
+			// 只要有执行结果（即使执行失败），都认为是任务完成了（包含输出）
+			s.handler.OnTaskCompleted(req, result)
+		} else if execErr != nil {
+			// 只有在完全没有结果的情况下（如无法启动、Panic等），才认为是任务失败
+			s.handler.OnTaskFailed(req, execErr)
+		}
+	}
+
+	if execErr != nil {
+		s.logger.Errorf("[Scheduler] 任务 %s 执行失败: %v", req.TaskID, execErr)
+	} else {
+		s.logger.Infof("[Scheduler] 执行完成: %s (#%s) [%s] (状态: %s, 耗时: %dms)",
+			req.Name, req.TaskID, req.Type, result.Status, result.Duration)
+	}
+
+	return result, execErr
+}
+
+// StopTask 停止正在运行的任务（通过 TaskID，可能会停止多个并发副本）
+func (s *Scheduler) StopTask(taskID string) bool {
+	s.mu.RLock()
+	cancel, exists := s.runningTasks[taskID]
+	s.mu.RUnlock()
+
+	if exists && cancel != nil {
+		cancel()
+		s.logger.Infof("[Scheduler] 已尝试停止任务 %s", taskID)
+		return true
+	}
+	return false
+}
+
+// StopLog 停止正在运行的任务（通过 LogID，精确停止单个执行副本）
+func (s *Scheduler) StopLog(logID string) bool {
+	s.mu.RLock()
+	cancel, exists := s.runningExecs[logID]
+	s.mu.RUnlock()
+
+	if exists && cancel != nil {
+		cancel()
+		s.logger.Infof("[Scheduler] 已尝试停止任务执行 #%s", logID)
+		return true
+	}
+	return false
+}
+
+// GetRunningTaskCount 获取正在运行的任务数量
+func (s *Scheduler) GetRunningTaskCount() int {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return len(s.runningTasks)
+}
+
+// GetRunningTasks 获取所有正在运行的任务 ID
+func (s *Scheduler) GetRunningTasks() []string {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	ids := make([]string, 0, len(s.runningTasks))
+	for id := range s.runningTasks {
+		ids = append(ids, id)
+	}
+	return ids
+}
+
+// Reload 重新加载配置
+func (s *Scheduler) Reload(config SchedulerConfig) {
+	s.logger.Infof("[Scheduler] 正在重载配置...")
+
+	// 停止现有 workers
+	close(s.stopCh)
+	s.wg.Wait()
+
+	// 更新配置
+	s.mu.Lock()
+	s.config = config
+	s.taskQueue = make(chan *ExecutionRequest, config.QueueSize)
+	s.rateLimiter = time.Tick(config.RateInterval)
+	s.stopCh = make(chan struct{})
+	s.mu.Unlock()
+
+	// 重启 workers
+	s.Start()
+
+	s.logger.Infof("[Scheduler] 配置已重载: workers=%d, queue=%d, rate=%v, strict=%t",
+		config.WorkerCount, config.QueueSize, config.RateInterval, config.StrictQueue)
+}
+
+// GetQueueSize 获取当前队列大小
+func (s *Scheduler) GetQueueSize() int {
+	return len(s.taskQueue)
+}
+
+// GetConfig 获取配置
+func (s *Scheduler) GetConfig() SchedulerConfig {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.config
+}
+
+// GetWorkerStatuses 获取所有 Worker 的状态
+func (s *Scheduler) GetWorkerStatuses() []WorkerStatus {
+	s.workerMu.RLock()
+	defer s.workerMu.RUnlock()
+	// 返回副本防止外部修改
+	statuses := make([]WorkerStatus, len(s.workers))
+	now := time.Now().Unix()
+	for i, w := range s.workers {
+		statuses[i] = w
+		// 在服务端计算运行时间，彻底避免客户端与服务端时钟不一致导致的计算偏差
+		if w.Status == "running" && w.StartTime > 0 {
+			duration := now - w.StartTime
+			if duration < 0 {
+				duration = 0
+			}
+			statuses[i].Duration = duration
+		}
+	}
+	return statuses
+}
@@ -0,0 +1,69 @@
+package executor
+
+import (
+	"sync"
+
+	"github.com/engigu/taskpool/internal/logger"
+	"github.com/engigu/taskpool/internal/systime"
+	"github.com/robfig/cron/v3"
+)
+
+type SysCronManager struct {
+	cron *cron.Cron
+}
+
+var (
+	sysCronInstance *SysCronManager
+	sysCronOnce     sync.Once
+)
+
+
+// InitSysCron 初始化系统的内部定时器
+func InitSysCron(){
+	GetSysCron()
+}
+
+// GetSysCron 获取内部系统定时器服务单例
+func GetSysCron() *SysCronManager {
+	sysCronOnce.Do(func() {
+		// 使用秒级精度，指定为东八区
+		c := cron.New(cron.WithSeconds(), cron.WithLocation(systime.CST))
+		c.Start()
+		sysCronInstance = &SysCronManager{
+			cron: c,
+		}
+		logger.Infof("[SysCron] 内部系统定时管理器已启动")
+	})
+	return sysCronInstance
+}
+
+// AddJob 添加内部系统任务，spec为cron表达式（支持 @every 30s 这种快捷方式）
+func (s *SysCronManager) AddJob(spec string, cmd func()) (cron.EntryID, error) {
+	id, err := s.cron.AddFunc(spec, cmd)
+	if err != nil {
+		logger.Errorf("[SysCron] 无法添加系统任务: %s, err: %v", spec, err)
+		return 0, err
+	}
+	return id, nil
+}
+
+// AddJobWithRun 立即开启一个协程异步执行一次任务，随后将其加入到系统定时任务中
+func (s *SysCronManager) AddJobWithRun(spec string, cmd func()) (cron.EntryID, error) {
+	// 立即异步执行一次
+	go func() {
+		defer func() {
+			if r := recover(); r != nil {
+				logger.Errorf("[SysCron] 立即执行任务时发生 panic: %v", r)
+			}
+		}()
+		cmd()
+	}()
+	
+	// 然后加入定时器
+	return s.AddJob(spec, cmd)
+}
+
+// RemoveJob 动态移除指定的系统定时任务
+func (s *SysCronManager) RemoveJob(id cron.EntryID) {
+	s.cron.Remove(id)
+}