upgrade

package
v0.3.1 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

Documentation

Overview

Package upgrade 提供 agent 自升级:版本查询/比较/下载/校验/替换(CLI 与 WS 推送共用)。

下载源:XPanel-Node 仓库的 GitHub Releases。版本查询优先 /releases.atom (含 prerelease,不调 REST API,规避匿名速率限制且兼容镜像站),必要时回退 /releases/latest 的重定向 Location;二进制与 checksums.txt 从 /releases/download/<tag>/ 拉取,sha256 必检。

镜像候选链:配置的 update.mirror 置顶,其后自动落回内置候选(与 install-agent.sh 的 DEFAULT_MIRRORS 同源)。逐个尝试,网络/HTTP 级失败切下一个;checksums.txt 拿到了但内容不对(缺条目)视为 release 本身损坏,换镜像无意义,立即报错。 资产与 checksums.txt 始终取自同一镜像,保证校验可信。

Index

Constants

View Source
const DefaultGeoDir = "/usr/local/share/xray"

DefaultGeoDir xray 在 Linux 上的标准资产目录(搜索顺序中的 /usr/local/share/xray)。

View Source
const DefaultRepo = "acdc-awa/XPanel-Node"

DefaultRepo 默认发布仓库(XPanel-Node on GitHub)。

View Source
const XrayRepo = "XTLS/Xray-core"

XrayRepo Xray 内核的默认发布仓库。

Variables

View Source
var ErrUpToDate = errors.New("已是最新版本")

ErrUpToDate 已是最新版本。

View Source
var GeoFileNames = []string{"geoip.dat", "geosite.dat"}

GeoFileNames 面板目前用到的两个规则库文件名。

View Source
var TagPattern = regexp.MustCompile(`^v?\d+(\.\d+)+(-[0-9A-Za-z.-]+)?$`)

TagPattern 严格限制版本标签格式,防路径穿越与 URL 注入。

View Source
var Version = "dev"

Version 当前 agent 版本(构建期 -ldflags -X 注入;"dev" 为默认开发值)。

Functions

func Apply

func Apply(f *Fetcher, exePath string, restart func() error, out io.Writer) error

Apply 完整升级流程:查版本 → 比较 → 下载 → sha256 强制校验 → 原子替换 → 重启。 exePath 为目标二进制路径(通常 os.Executable());restart 由调用方注入(systemd 重启或手动提示)。

func ApplyTarget added in v0.1.17

func ApplyTarget(f *Fetcher, target string, force bool, exePath string, restart func() error, out io.Writer) error

ApplyTarget 带目标版本与强制选项的升级/回滚流程: target 为空时查最新 release;force 为 false 时若当前已 >= 目标版本则拒绝(返回 ErrUpToDate); force 为 true 时只要版本不完全相同即允许降级回滚。

func AssetName

func AssetName() string

AssetName 当前平台的发布资产名(agent 运行于 Linux 节点,恒 linux-<arch>)。

func Compare

func Compare(a, b string) int

Compare 语义化比较版本:-1 a<b / 0 相等 / 1 a>b。非法版本归一为 "0"。

func CurrentVersion

func CurrentVersion() string

CurrentVersion 返回当前 agent 版本。

func IsProbeError added in v0.2.0

func IsProbeError(err error) bool

IsProbeError 判断是否为二进制探测失败。

func ReplaceBinary

func ReplaceBinary(exePath string, data []byte) error

ReplaceBinary 原子替换二进制文件:写入同目录 .tmp → chmod 0755 → rename 覆盖。 失败时清理 .tmp。CLI 升级与 WS 触发升级共用。

func ReplaceGeoFile added in v0.2.0

func ReplaceGeoFile(dir, name string, data []byte) (changed bool, prevPath string, err error)

ReplaceGeoFile 原子替换 geo 数据文件。 返回 changed=false 表示内容与现有文件逐字节相同(不备份、不重写)。 返回的 prevPath 是替换前的备份路径(无旧文件时为空)。

func ReplaceXrayBinary added in v0.2.0

func ReplaceXrayBinary(binPath string, data []byte) (prevPath string, err error)

ReplaceXrayBinary 原子替换 xray 可执行文件,并保留一份 .prev 供失败回滚。 与 ReplaceBinary 的差异:xray 正在运行时其可执行文件在 Linux 上仍可替换(inode 无关), 但调用方仍应先 Stop,避免新进程与旧进程混跑。

func RollbackXrayBinary added in v0.2.0

func RollbackXrayBinary(binPath, prevPath string) error

RollbackXrayBinary 用 .prev 覆盖回 binPath(替换后自检失败时使用)。

func Sha256Hex

func Sha256Hex(data []byte) string

Sha256Hex 计算数据 sha256 的 hex 串。

func ValidateGeoFileName added in v0.2.0

func ValidateGeoFileName(name string) error

ValidateGeoFileName 只允许落盘到 geo 目录下的普通文件名,防路径穿越。

func VerifyXrayBinary added in v0.2.0

func VerifyXrayBinary(data []byte, wanted string) error

VerifyXrayBinary 校验待替换的二进制可用:写临时文件 → 执行 version → 解析出版本号。 失败时清理临时文件。这是「下载成功」之外的独立一道门:压缩包解出来的可能不是可执行 xray(架构不符 / 内容被替换),只有能跑起来并报出目标版本才算通过。

func XrayAssetName added in v0.2.0

func XrayAssetName() (string, error)

XrayAssetName 当前平台的 Xray 发布资产名。 命名规则来自 XTLS 的 release 脚本:amd64 用 "64"、arm64 用 "arm64-v8a"。

func XrayBinVersion added in v0.2.0

func XrayBinVersion(bin string) (string, error)

XrayBinVersion 运行 `<bin> version` 并解析版本号。 bin 为待探测的可执行文件路径;超时或执行失败返回错误(调用方据此判定该二进制不可用)。

func XrayVersionOf added in v0.2.0

func XrayVersionOf(output string) string

XrayVersionOf 解析 `xray version` 输出的版本号(第二列,如 "26.10.21")。

Types

type Fetcher

type Fetcher struct {
	Repo   string // owner/repo,空 = DefaultRepo
	Mirror string // 可选:首选镜像/代理前缀(如 https://ghproxy.net/https://github.com),置顶尝试
	// Mirrors 显式完整候选列表(测试注入用);非空时忽略 Mirror 与内置列表。
	Mirrors []string
	// DownloadTimeout 单镜像单次资产下载超时,0 = defaultDownloadTimeout。
	DownloadTimeout time.Duration
	// Client 测试注入用;非空时两个角色共用(注入方自管重定向策略)。
	Client *http.Client
	// RequireAtom 只认 releases.atom(包含 prerelease),不回退 /releases/latest。
	// XTLS 自 26.4 起所有发布都标了 prerelease,/releases/latest 会退回 v26.3.27;
	// 内核查询必须置 true,否则“最新版”会解析成很旧的正式版。
	RequireAtom bool
	// contains filtered or unexported fields
}

Fetcher 从 GitHub Releases 查询版本并下载 agent 发布资产,按镜像候选链逐个尝试。

func (*Fetcher) Download

func (f *Fetcher) Download(tag string) ([]byte, string, error)

Download 按候选链下载指定 tag 的资产与 checksums.txt(同一镜像取齐),返回数据与期望 sha256(hex)。

func (*Fetcher) Latest

func (f *Fetcher) Latest() (string, error)

Latest 按候选链解析最新 release tag。

优先 releases.atom:它包含 prerelease,且不受 REST API 匿名限流影响。 /releases/latest 只认非 prerelease,仅在 RequireAtom=false 时作为兜底 (agent 自身仓库的发布是正式版,可兜底;Xray 内核仓库全是 prerelease,必须禁用)。

type XrayBundle added in v0.2.0

type XrayBundle struct {
	Bin      []byte            // xray / xray.exe
	Geo      map[string][]byte // geoip.dat / geosite.dat(发布包里没有则为空)
	SHA256   string            // 压缩包摘要(hex)
	Asset    string            // 压缩包资产名(用于日志)
	Tag      string            // 发布版本标签
	Official bool              // 固定 true,便于调用方区分数据来源
}

XrayBundle 一个已校验的 Xray 发布包解出的内容。

type XrayFetcher added in v0.2.0

type XrayFetcher struct {
	Fetcher
}

XrayFetcher 下载 Xray 内核压缩包。复用 Fetcher 的镜像候选链与 HTTP 客户端。

func NewXrayFetcher added in v0.2.0

func NewXrayFetcher(mirror string, timeout time.Duration) *XrayFetcher

NewXrayFetcher 供 main 装配:repo 恒为 XTLS/Xray-core(内核来源不随 agent 的 update.repo 变化), 但镜像候选链与下载超时沿用节点 update 段的配置。

func (*XrayFetcher) XrayDownloadBundle added in v0.2.0

func (f *XrayFetcher) XrayDownloadBundle(tag string) (*XrayBundle, error)

XrayDownloadBundle 下载并解包完整发布包(内核 + geo 数据),只走一次下载。 换内核与 geo 回退共用:两者必须来自同一个已校验压缩包,不能各下一份。

Jump to

Keyboard shortcuts

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