xrayproc

package
v0.1.15 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 21, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

Documentation

Overview

Package xrayproc 托管 xray-core 子进程:启动/停止/配置校验重启/看门狗拉起。 结论依据《知识状态清单》A 类实测:SIGTERM 优雅退出(exit 0)、SIGKILL(137)、 `-test` 配置错误 exit 23、启动失败 exit 255、watchdog 2s 拉起。

「启动成功」的判据(2026-09-21 实机修正):xray 的致命错误分两段——`-test` (= core.LoadConfig + core.New,只做配置解析)与 server.Start()(真正绑定端口、构建路由)。 端口被占这类问题 -test 完全看不见(实测 `-test` 打印 Configuration OK. 而 run 秒死 `Failed to start: ... failed to listen TCP on 443 ... bind: ...`),进程 exec 成功后 立刻退出。因此 Start() 必须等一个就绪窗口确认进程没退出才算"已启动",并把退出码与 stderr 摘要留档(Health)供心跳回传主控;看门狗按连续失败退避,达上限后停止自动拉起 但保留低频「慢探底」(环境类故障修好后无需人工介入即可自愈)。

另一处配套约束(2026-09-21):主控每 2 分钟重推一次待推送配置,而"过了 -test 却起不来" 的配置每次应用都要先停掉正在服务的 xray 再回滚——同一份内容失败后进入冷却期, 冷却内的重复推送直接拒绝且不碰运行中的进程(见 RestartWithConfig)。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnsureBootstrapConfig

func EnsureBootstrapConfig(configPath string) (bool, error)

EnsureBootstrapConfig 配置缺失时落盘自举最小模板,返回是否实际写入。 只在文件不存在时写入,绝不覆盖已有配置;首个 push_config 到达后 RestartWithConfig 原子替换,本模板天然充当"上一份好配置"的回滚兜底(-test 失败时回滚到的就是它, xray 至少保持最小配置运行、gRPC 可连,而不是裸死)。

Types

type Health added in v0.1.15

type Health struct {
	State     string    // running / restarting / failed / stopped
	LastError string    // 最近一次启动失败原因(含已恢复的历史原因,UI 自行决定是否淡显)
	ErrorAt   time.Time // 该原因的观测时刻
	Failures  int       // 连续启动失败次数(启动成功后归零)
	GaveUp    bool      // 是否已停止自动拉起
}

Health xray 健康快照(心跳上报主控,面板据此显示状态与失败原因)。

type Proc

type Proc struct {
	Bin        string
	ConfigPath string
	LogPath    string
	PidFile    string

	OnRestart func() // 崩溃后被 Watchdog 成功拉起时的回调
	// OnGiveUp 连续启动失败达上限、停止自动拉起时的告警回调(agent 用它立刻推一帧心跳,
	// 让主控/面板马上看到原因,而不是干等下一个心跳周期)。
	OnGiveUp func(reason string)
	// contains filtered or unexported fields
}

Proc 管理单个 xray 实例。

func New

func New(bin, configPath, logPath, pidFile string) *Proc

New 构造托管器。

func (*Proc) CleanupStale

func (p *Proc) CleanupStale()

CleanupStale 停止同配置路径的残留 xray 实例(agent 异常退出遗留的孤儿进程)。

func (*Proc) EnsureUsableConfig added in v0.1.15

func (p *Proc) EnsureUsableConfig() string

EnsureUsableConfig 开机配置体检:配置缺失时写自举最小模板;-test 不通过时回退到 上一份可用配置副本(.good)。返回一句"发生了什么"的说明(空 = 无需说明); 除"已写入自举最小配置"这条正常路径外,说明同时记入 Health.LastError, 让面板能看到"这次开机为什么不是当前配置在跑"。

func (*Proc) Health added in v0.1.15

func (p *Proc) Health() Health

Health 返回 xray 健康快照(心跳上报主控)。

func (*Proc) IsRunning

func (p *Proc) IsRunning() bool

IsRunning 通过 pid 文件 + isProcessAlive 判断进程存活;僵尸(Z)视为不在运行。

func (*Proc) Logs

func (p *Proc) Logs(n int) (string, error)

Logs 读取最近 n 行日志。

func (*Proc) ResetFailures added in v0.1.15

func (p *Proc) ResetFailures()

ResetFailures 清零连续失败、放弃态与同内容冷却(面板「重启 Xray」/ 新配置下发时调用, 重新给机会——包括立刻重试此前被冷却拒绝的那份配置,这正是管理员修好环境后的动作)。

func (*Proc) RestartWithConfig

func (p *Proc) RestartWithConfig(configJSON string) error

RestartWithConfig 写配置 → 校验 → 重启。新配置"spawn 成功但秒死"也算启动失败并回滚 到上一份配置(旧实现只看 spawn,坏配置会永久顶掉好配置、节点静默宕机)。

同一份内容在冷却期内被重复推送时直接拒绝、不碰运行中的进程:主控每 2 分钟补推一次待推送 配置,而每次应用都要先停掉正在服务的 xray 再回滚(回滚成功也要重启一次),会退化成 "每 2 分钟断一次用户"。冷却过后自动放行重试,环境类故障修好即可自愈。

func (*Proc) Start

func (p *Proc) Start() error

Start 启动 xray 子进程(配置已存在时使用)。 返回 nil 表示"确实起来了":spawn 成功且进程活过了就绪窗口;秒死则返回带退出码与 stderr 摘要的错误(并计入连续失败计数)。

func (*Proc) Status

func (p *Proc) Status() (running bool, pid int, startedAt time.Time, uptimeSec int64)

Status 返回运行状态。与 Health() 同口径:pid 文件指向活着的 xray 即算运行 (含上一轮 agent 遗留、本轮未托管的实例),否则同一帧心跳里 xray_running 与 xray_state 会互相打架。未托管时 startedAt 为零值,运行时长报 0。

func (*Proc) Stop

func (p *Proc) Stop() error

Stop 停止 xray(SIGTERM 优雅退出,超时后 SIGKILL)。

func (*Proc) TestConfig

func (p *Proc) TestConfig(path string) error

TestConfig 用 `xray -test` 校验配置(exit 0 = 通过)。

func (*Proc) Watchdog

func (p *Proc) Watchdog(stop <-chan struct{})

Watchdog 崩溃自动拉起(每 watchdogInterval 检测一次)。 连续启动失败按 backoffFor 退避,达 maxStartFailures 后停止自动拉起(不再永无止境地 拉起 xray),此后按 probeInterval 慢探底;状态与原因留给心跳上报主控。 只有真正拉起来的那次(含探底成功)才触发 OnRestart。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL