Documentation
¶
Index ¶
- Variables
- func CheckDockerAvailable(ctx context.Context) (string, error)
- func ComposeEnv(base []string, spec CommandSpec) []string
- func PullDockerImage(ctx context.Context, ref string) error
- func RemoveDockerImage(ctx context.Context, ref string, force bool) error
- type CommandSpec
- type CrashInfo
- type IProcessCommand
- type ImageSummary
- type Instance
- type InstanceSnapshot
- type InstanceState
- type Manager
- func (m *Manager) Create(uuid, name, startCommand, stopCommand, workDir string, ...) error
- func (m *Manager) GetAllInstanceStates() []InstanceSnapshot
- func (m *Manager) GetInstance(uuid string) (*Instance, bool)
- func (m *Manager) GetInstanceDockerStats(ctx context.Context, uuid string) (cpuPercent float64, memBytes int64, memLimitBytes int64, ok bool)
- func (m *Manager) GetInstancePID(uuid string) int
- func (m *Manager) GetRCONConfig(uuid string) (port int, password string, err error)
- func (m *Manager) GetState(uuid string) (InstanceState, error)
- func (m *Manager) Kill(uuid string) error
- func (m *Manager) ListInstances() []string
- func (m *Manager) PreflightStart(uuid string) ([]PreflightCheckResult, error)
- func (m *Manager) ReapDaemonForDelete(uuid string)
- func (m *Manager) RecoverDaemonInstances() (int, error)
- func (m *Manager) Remove(uuid string) error
- func (m *Manager) Restart(uuid string) error
- func (m *Manager) SendCommand(uuid, command string) error
- func (m *Manager) SetCrashHandler(handler func(instanceID string, info CrashInfo))
- func (m *Manager) SetDockerConfig(uuid, image string, mappings []PortMapping, cpuLimit float64, ...)
- func (m *Manager) SetGracefulStopTimeout(uuid string, seconds int)
- func (m *Manager) SetLaunchConfig(uuid, startCommand, jdkPath, jdkBinPath string, envVars map[string]string, ...)
- func (m *Manager) SetMemGuard(cfg MemGuardConfig)
- func (m *Manager) SetMemReader(r readSysMem)
- func (m *Manager) SetOutputHandler(handler func(instanceID string, stream string, data []byte))
- func (m *Manager) SetRCONConfig(uuid string, port int, password string) error
- func (m *Manager) SetStateChangeHandler(handler func(instanceUUID string, oldState, newState InstanceState))
- func (m *Manager) Start(uuid string) error
- func (m *Manager) Stop(uuid string) error
- func (m *Manager) StopAll()
- type MemGuardConfig
- type PortMapping
- type PreflightCheckResult
- type ProcessType
Constants ¶
This section is empty.
Variables ¶
var ErrNotImplemented = errors.New("该启动方式尚未实现")
ErrNotImplemented 表示该启动方式尚未实现。 docker/rcon 等未落地的策略统一返回此错误，避免误用。
Functions ¶
func CheckDockerAvailable ¶
CheckDockerAvailable 探测本机 Docker 守护进程可用性（FR-237）：连客户端 + ServerVersion。 返回 Engine 版本；守护进程未装 / 未起 / 不可达时返回 error。供创建向导选 docker 模式前先测。
func ComposeEnv ¶
func ComposeEnv(base []string, spec CommandSpec) []string
ComposeEnv 合成进程最终环境： 1) Worker 自身环境（os.Environ）作为基线，保留系统 PATH/编码等； 2) 注入 JAVA_HOME（如果提供）和对应 PATH 前缀； 3) 叠加实例自定义 EnvVars（覆盖基线同名键）。 始终不修改调用方的 map。
func PullDockerImage ¶
PullDockerImage 从 registry 拉取镜像到 Worker 本机。 拉取流必须读尽，否则 Docker 守护进程可能中断拉取。
Types ¶
type CommandSpec ¶
type CommandSpec struct {
UUID string
Name string
StartCommand string
// StopCommand 优雅停止时写入进程 stdin 的命令（按实例角色派生：MC 后端 stop / 代理 end）。
// 空时由策略回退到默认 "stop"。仅 daemon 策略经 stdin 优雅关服时使用。
StopCommand string
WorkDir string
EnvVars map[string]string
// JavaHome 显式指定 JAVA_HOME（来自实例绑定的 JDK），非空时 Worker 会
// 把它注入到进程环境并把 JavaHome/bin 接入 PATH。
JavaHome string
// JDKBinPath 显式指定要前置到 PATH 的目录；空时由 JavaHome 派生。
JDKBinPath string
AutoRestart bool
ProcessType ProcessType
// ProbePort 是实例 ServerProbe /metrics 端口（CP 分配后下发）。daemon 策略透传到
// wrapper→PID 记录，供 Worker 重启恢复后心跳继续自采（FR-060）；0=未部署探针。
ProbePort int
// GracefulStopTimeoutSeconds 是优雅停止超时（秒，CP 从平台设置下发，FR-063）。daemon 策略
// 透传到 wrapper 做超时强杀兜底；0=未指定，wrapper 回退 env/默认。值在启动时定型。
GracefulStopTimeoutSeconds int
// Image 是 docker 模式的容器镜像引用（如 itzg/minecraft-server:latest）。
// 仅 docker 策略使用；缺失时 docker 启动报错（ADR-019）。
Image string
// PortMappings 是 docker 模式的容器端口↔宿主端口映射（宿主端口来自 FR-032 端口池）。
// 仅 docker 策略使用，发布容器内端口到宿主（ADR-019）。
PortMappings []PortMapping
// CPULimit 是 docker 模式的 CPU 核数上限（如 1.5 表示 1.5 核），注入 HostConfig.NanoCPUs。
// 仅 docker 策略使用；0=不限制（FR-079，见 ADR-019）。
CPULimit float64
// MemLimitMB 是 docker 模式的内存上限（MiB），注入 HostConfig.Memory。
// 仅 docker 策略使用；0=不限制（FR-079，见 ADR-019）。
MemLimitMB int64
// DiskLimitMB 是 docker 模式的磁盘上限（MiB），仅持久化与展示，v1 不注入 HostConfig。
// bind-mount 工作目录无法用 HostConfig 简单施加磁盘配额（依赖存储驱动），留作前向兼容（FR-079）。
DiskLimitMB int64
}
CommandSpec 是启动一个实例所需的全部配置。 各策略实现（direct/daemon/docker）从同一份配置派生各自所需参数。
type CrashInfo ¶
type CrashInfo struct {
// ExitCode 进程退出码；无法获知（Wait 出错无退出状态 / 容器 Wait 错误）时为 -1。
ExitCode int
// Signal 终止信号名（Unix，如 killed）；Windows / 非信号退出为空。
Signal string
// DurationMs 本次运行时长（毫秒）。
DurationMs int64
// OccurredAt 崩溃发生时刻。
OccurredAt time.Time
}
CrashInfo 进程非正常退出的现场信息（FR-313）：退出码 ≠ 0，或 RUNNING/STARTING 态 意外退出时由策略捕获，经 Manager 崩溃回调扇出、组装崩溃快照上报 CP。
type IProcessCommand ¶
type IProcessCommand interface {
// Start 启动实例进程。ctx 用于取消启动阶段（如连接 wrapper 超时）。
Start(ctx context.Context) error
// Stop 优雅停止实例。
Stop() error
// Kill 强制终止实例。
Kill() error
// SendCommand 向实例 stdin 发送一行命令。
SendCommand(command string) error
// State 返回策略当前记录的实例状态。
State() InstanceState
// Close 释放策略持有的资源（socket 连接、goroutine 等），
// 不影响被管理的游戏服进程本身（daemon 模式下 wrapper 继续运行）。
Close() error
// GetPID 返回实例进程的 PID，用于从 OS 层采集进程内存等指标。
// 未启动或已退出时返回 0。
GetPID() int
}
IProcessCommand 进程启动策略接口。 Manager 按 instance.ProcessType 选择具体实现（direct/daemon/docker）， 把「如何启动/停止/发送命令」的差异收敛到策略内部，Manager 只负责路由和生命周期记账。 参见 ADR-003: 守护进程 Wrapper 模式。
type ImageSummary ¶
ImageSummary 是 Worker 本机一个 Docker 镜像的精简描述（FR-078，ADR-019）。
func ListDockerImages ¶
func ListDockerImages(ctx context.Context) ([]ImageSummary, error)
ListDockerImages 列出 Worker 本机 Docker 镜像。 Docker 不可用时返回错误，调用方据此回报 docker_available=false（FR-078）。
type Instance ¶
type Instance struct {
UUID string
Name string
StartCommand string
// StopCommand 优雅停止命令（按角色派生：MC 后端 stop / 代理 end）；空时回退默认 stop。
StopCommand string
WorkDir string
EnvVars map[string]string
JDKPath string
JDKBinPath string
RCONPort int
RCONPassword string
// ProbePort 是实例 ServerProbe /metrics 端口（CP 分配后随 Create 下发）。
// 心跳采集器据此自采每实例富指标（FR-060）；0=未部署探针，心跳跳过该实例。
ProbePort int
// GracefulStopTimeoutSeconds 是优雅停止超时（秒，CP 从平台设置下发，FR-063）。daemon 启动时
// 透传到 wrapper 做超时强杀兜底；0=未指定，wrapper 回退 env/默认。值在启动时随 spec 定型。
GracefulStopTimeoutSeconds int
// Image 是 docker 模式的容器镜像引用（ADR-019）；仅 docker 实例使用。
Image string
// PortMappings 是 docker 模式的容器端口↔宿主端口映射（ADR-019）；仅 docker 实例使用。
PortMappings []PortMapping
// CPULimit / MemLimitMB / DiskLimitMB 是 docker 模式的资源限额（FR-079，见 ADR-019）；
// 仅 docker 实例使用，值在 Start 时随 spec 定型。0=不限制；DiskLimitMB v1 仅记账不注入。
CPULimit float64
MemLimitMB int64
DiskLimitMB int64
State InstanceState
AutoRestart bool
CrashCount int
// contains filtered or unexported fields
}
Instance 运行中的实例记账信息。 策略实现（direct/daemon）持有进程/socket 句柄，这里只保留 Manager 路由与查询所需字段。
type InstanceSnapshot ¶
type InstanceSnapshot struct {
UUID string
State string // STOPPED, STARTING, RUNNING, STOPPING, CRASHED
ProbePort int // ServerProbe /metrics 端口；>0 且 RUNNING 时心跳采集器自采富指标（FR-060）
PID int // 受管实例根进程 PID；>0 时心跳可采集进程 TOPN（FR-170）
}
InstanceSnapshot 表示单个实例的状态快照（用于心跳上报）。
type InstanceState ¶
type InstanceState string
InstanceState 实例运行状态。
const ( StateStopped InstanceState = "STOPPED" StateStarting InstanceState = "STARTING" StateRunning InstanceState = "RUNNING" StateStopping InstanceState = "STOPPING" StateCrashed InstanceState = "CRASHED" )
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager 进程管理器。 它通过 IProcessCommand 策略接口支持多种启动方式（direct/daemon/docker）， 参见 ADR-003: 守护进程 Wrapper 模式。
func (*Manager) Create ¶
func (m *Manager) Create(uuid, name, startCommand, stopCommand, workDir string, envVars map[string]string, autoRestart bool, processType ProcessType, jdkPath, jdkBinPath string, probePort, gracefulStopTimeoutSeconds int) error
Create 创建实例（但不启动）。processType 决定启动方式（direct/daemon/docker/rcon）。 jdkPath / jdkBinPath 非空时会被注入到实例启动时的环境。 stopCommand 为优雅停止命令（按角色派生：MC 后端 stop / 代理 end），空时回退默认 stop。 probePort 为实例 ServerProbe /metrics 端口（CP 分配），供心跳采集器自采富指标（FR-060）；0=未部署。 gracefulStopTimeoutSeconds 为优雅停止超时（秒，CP 从平台设置下发，FR-063）；0=未指定，wrapper 回退默认。
func (*Manager) GetAllInstanceStates ¶
func (m *Manager) GetAllInstanceStates() []InstanceSnapshot
GetAllInstanceStates 返回所有实例的状态快照（用于心跳上报）。
func (*Manager) GetInstance ¶
GetInstance 获取实例信息。
func (*Manager) GetInstanceDockerStats ¶
func (m *Manager) GetInstanceDockerStats(ctx context.Context, uuid string) (cpuPercent float64, memBytes int64, memLimitBytes int64, ok bool)
GetInstanceDockerStats 采集 docker 实例的容器资源指标（CPU%/内存/内存上限，字节）。 非 docker 实例、未运行或采集失败返回 ok=false，调用方据此回退 OS 进程内存路径。
func (*Manager) GetInstancePID ¶
GetInstancePID 获取实例进程的 PID。 策略未启动或已退出时返回 0。
func (*Manager) GetRCONConfig ¶
GetRCONConfig 获取实例的 RCON 配置。
func (*Manager) GetState ¶
func (m *Manager) GetState(uuid string) (InstanceState, error)
GetState 获取实例状态。
func (*Manager) ListInstances ¶
ListInstances 返回所有实例的 UUID 列表。
func (*Manager) PreflightStart ¶
func (m *Manager) PreflightStart(uuid string) ([]PreflightCheckResult, error)
PreflightStart 对已注册实例做启动前同步预检（FR-314）：校验 java 运行时、工作目录、启动目标 jar， 供 CP 在转 STARTING 前同步拦截配置错误，终结「配置错误也要启动中→崩溃兜一圈」。 docker 实例整体放行（本地 JDK/文件语义不适用）。实例未注册返回 error。 与 Start 内嵌的 preflightJavaVersion 同源复用、并存不冲突（纵深防御，防 CP 绕过与竞态窗口）。
func (*Manager) ReapDaemonForDelete ¶
ReapDaemonForDelete 在删除实例前强杀该实例的 daemon 进程树并清理遗留的 PID 文件 / socket（FR-310）。
背景（真机缺陷）：删除运行中 daemon 实例时，删除流程只杀 wrapper 组随即 RemoveAll 工作目录。 Unix 上被托管的 Java 经 wrapper 的 applyProcAttr 自成进程组（见 daemon.applyProcAttr），杀 wrapper 组够不到它；未死透的 Java 在 RemoveAll 之后继续写 world region 文件，把工作目录重建出来——于是 worker 日志打印「已清理工作目录」（RemoveAll 返回 nil），盘上却残留 world/plugins。此外 wrapper 被 强杀时其 defer cleanupPIDFile 不执行，遗留 <uuid>.pid 与 <uuid>.sock（本机 var/servers 下）。
处置：按 PID 记录强杀 wrapper 与 Java 两棵进程树——Unix 各杀其组，故两棵都要杀；Windows taskkill /T 已覆盖子树，补杀已死 PID 无害——轮询确认死透后再由调用方 RemoveAll，杜绝存活进程回写；确认死透即 清理遗留的 PID 文件与 socket。与 FR-325 接管兜底 reapOrphanWrapper 同源（复用 killTree / waitPIDsGone / pidAlive 桩，便于确定性单测）。
无 PID 文件（非 daemon 实例，或 wrapper 已优雅退出自清理）时为空操作。强杀后仍有存活（权限不足等） 则保留 PID 文件，让后续 Worker 重启的接管扫描 RecoverDaemonInstances 仍能发现并再次兜底，杜绝孤儿 永久失联——此时工作目录可能残留，由调用方 removeInstanceWorkDir 的校验重试如实反映。
func (*Manager) RecoverDaemonInstances ¶
RecoverDaemonInstances 在 Worker 重启后扫描 PID 目录，恢复仍存活的 daemon wrapper 连接。 对每个 PID 文件：wrapper pid 存活且 socket 可达则 reconnect 并登记实例为 RUNNING； 否则删除 PID 文件与残留 socket（清理）。返回成功恢复的实例数。 参见 ADR-003: 平台重启后通过 PID 文件重新连接已有 daemon。
func (*Manager) Restart ¶
Restart 优雅重启实例：运行中先发停止命令让游戏服正常关服（保存世界、释放 world/session.lock、 输出关服日志），等旧进程完全退出后再启动；已停止/崩溃则直接启动。整个过程持有同一实例生命周期锁。
此前用强杀（killLocked）+ 立即启动：daemon 模式强杀 wrapper 进程树时，Unix 上自成进程组的 Java 可能未被杀到而沦为孤儿、仍占 world 锁，新进程随即启动即撞 Paper `SessionLock$ExceptionWorldConflict` （真机复现）；且强杀无关服日志、跳过世界保存。改走优雅停止——stopLocked 下发 stop 控制帧由 wrapper 优雅关服（自带超时强杀兜底、复用同一策略）；startLocked 内 strategy.Start() 的 daemon.WaitForPriorExit 依 PID 文件等旧 wrapper/Java 全退出（best-effort 上限）再拉起新进程， reapWrapper 的 `d.wrapperCmd != cmd` 陈旧守卫保证旧 reaper 不误改新实例状态。
func (*Manager) SendCommand ¶
SendCommand 向实例发送命令（通过 stdin）。
func (*Manager) SetCrashHandler ¶
SetCrashHandler 设置进程非正常退出回调（FR-313）。 各策略在崩溃判定路径（direct/docker waitLoop、daemon 经 wrapper 退出事件）捕获现场后 经此扇出；回调须快速返回（上报本身应异步），不得阻塞策略的崩溃处理。
func (*Manager) SetDockerConfig ¶
func (m *Manager) SetDockerConfig(uuid, image string, mappings []PortMapping, cpuLimit float64, memLimitMB, diskLimitMB int64)
SetDockerConfig 设置已登记实例的 docker 镜像、端口映射与资源限额（ADR-019 / FR-079）。 由 CP 在创建/重注册 docker 实例时下发，使镜像/端口/限额对下一次启动生效（值在 Start 时随 spec 定型）。 实例不存在则忽略（与 SetGracefulStopTimeout 容错风格一致，不阻塞启动路径）。
func (*Manager) SetGracefulStopTimeout ¶
SetGracefulStopTimeout 更新已登记实例的优雅停止超时（秒）。 供 CP 在「重新注册已存在实例」时刷新该值，使设置变更对下一次启动生效（值在 Start 时随 spec 定型）。 实例不存在则忽略（与 SetRCONConfig 的容错风格一致，但此处不报错以免阻塞启动路径）。
func (*Manager) SetLaunchConfig ¶
func (m *Manager) SetLaunchConfig(uuid, startCommand, jdkPath, jdkBinPath string, envVars map[string]string, autoRestart bool)
SetLaunchConfig 刷新已存在实例的启动配置，供 CP 幂等重注册时下发（FR-233）。 运行中的策略继续服务且仅标记过期；停止/崩溃态则立即丢弃旧策略，确保下一次启动采用新规格。
func (*Manager) SetMemGuard ¶
func (m *Manager) SetMemGuard(cfg MemGuardConfig)
SetMemGuard 注入内存闸配置（main 从 worker.yml 接线）。
func (*Manager) SetMemReader ¶
func (m *Manager) SetMemReader(r readSysMem)
SetMemReader 注入系统内存读数器（仅测试）。
func (*Manager) SetOutputHandler ¶
SetOutputHandler 设置进程输出回调。 输出会路由到此处（用于桥接 WebSocket 终端）。
func (*Manager) SetRCONConfig ¶
SetRCONConfig 设置实例的 RCON 配置。
func (*Manager) SetStateChangeHandler ¶
func (m *Manager) SetStateChangeHandler(handler func(instanceUUID string, oldState, newState InstanceState))
SetStateChangeHandler 设置实例状态变更回调。 每次实例状态发生转换时调用，用于 StreamInstanceEvents 推送。
type MemGuardConfig ¶
type MemGuardConfig struct {
// ReserveMB 保留水位（MB）；0 = 默认策略 max(512MB, 总内存 10%)。
ReserveMB int64
// Disabled 显式关闭守卫（应急逃生口，如误判阻塞关键启动时）。
Disabled bool
}
MemGuardConfig Worker 实时内存闸配置（FR-317，worker.yml memory_guard 段）。
type PortMapping ¶
type PortMapping struct {
// ContainerPort 容器内监听端口（由镜像约定，如 MC 容器内 25565）。
ContainerPort int
// HostPort 宿主发布端口（来自 FR-032 端口池分配）。
HostPort int
// Protocol 端口协议，tcp（默认）或 udp（如 MC query）。
Protocol string
}
PortMapping 描述一条容器端口到宿主端口的发布关系（docker 模式，ADR-019）。
type PreflightCheckResult ¶
PreflightCheckResult 单项启动预检结果（FR-314）。
type ProcessType ¶
type ProcessType string
ProcessType 启动方式，与 model.ProcessType 对齐。 这里独立定义为字符串以避免 process 包反向依赖 controlplane/model。
const ( ProcessTypeDirect ProcessType = "direct" ProcessTypeDaemon ProcessType = "daemon" ProcessTypeDocker ProcessType = "docker" ProcessTypeRCON ProcessType = "rcon" )
Source Files