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
- Variables
- func Apply(f *Fetcher, exePath string, restart func() error, out io.Writer) error
- func ApplyTarget(f *Fetcher, target string, force bool, exePath string, restart func() error, ...) error
- func AssetName() string
- func Compare(a, b string) int
- func CurrentVersion() string
- func IsProbeError(err error) bool
- func ReplaceBinary(exePath string, data []byte) error
- func ReplaceGeoFile(dir, name string, data []byte) (changed bool, prevPath string, err error)
- func ReplaceXrayBinary(binPath string, data []byte) (prevPath string, err error)
- func RollbackXrayBinary(binPath, prevPath string) error
- func Sha256Hex(data []byte) string
- func ValidateGeoFileName(name string) error
- func VerifyXrayBinary(data []byte, wanted string) error
- func XrayAssetName() (string, error)
- func XrayBinVersion(bin string) (string, error)
- func XrayVersionOf(output string) string
- type Fetcher
- type XrayBundle
- type XrayFetcher
Constants ¶
const DefaultGeoDir = "/usr/local/share/xray"
DefaultGeoDir xray 在 Linux 上的标准资产目录(搜索顺序中的 /usr/local/share/xray)。
const DefaultRepo = "acdc-awa/XPanel-Node"
DefaultRepo 默认发布仓库(XPanel-Node on GitHub)。
const XrayRepo = "XTLS/Xray-core"
XrayRepo Xray 内核的默认发布仓库。
Variables ¶
var ErrUpToDate = errors.New("已是最新版本")
ErrUpToDate 已是最新版本。
var GeoFileNames = []string{"geoip.dat", "geosite.dat"}
GeoFileNames 面板目前用到的两个规则库文件名。
var TagPattern = regexp.MustCompile(`^v?\d+(\.\d+)+(-[0-9A-Za-z.-]+)?$`)
TagPattern 严格限制版本标签格式,防路径穿越与 URL 注入。
var Version = "dev"
Version 当前 agent 版本(构建期 -ldflags -X 注入;"dev" 为默认开发值)。
Functions ¶
func Apply ¶
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 ReplaceBinary ¶
ReplaceBinary 原子替换二进制文件:写入同目录 .tmp → chmod 0755 → rename 覆盖。 失败时清理 .tmp。CLI 升级与 WS 触发升级共用。
func ReplaceGeoFile ¶ added in v0.2.0
ReplaceGeoFile 原子替换 geo 数据文件。 返回 changed=false 表示内容与现有文件逐字节相同(不备份、不重写)。 返回的 prevPath 是替换前的备份路径(无旧文件时为空)。
func ReplaceXrayBinary ¶ added in v0.2.0
ReplaceXrayBinary 原子替换 xray 可执行文件,并保留一份 .prev 供失败回滚。 与 ReplaceBinary 的差异:xray 正在运行时其可执行文件在 Linux 上仍可替换(inode 无关), 但调用方仍应先 Stop,避免新进程与旧进程混跑。
func RollbackXrayBinary ¶ added in v0.2.0
RollbackXrayBinary 用 .prev 覆盖回 binPath(替换后自检失败时使用)。
func ValidateGeoFileName ¶ added in v0.2.0
ValidateGeoFileName 只允许落盘到 geo 目录下的普通文件名,防路径穿越。
func VerifyXrayBinary ¶ added in v0.2.0
VerifyXrayBinary 校验待替换的二进制可用:写临时文件 → 执行 version → 解析出版本号。 失败时清理临时文件。这是「下载成功」之外的独立一道门:压缩包解出来的可能不是可执行 xray(架构不符 / 内容被替换),只有能跑起来并报出目标版本才算通过。
func XrayAssetName ¶ added in v0.2.0
XrayAssetName 当前平台的 Xray 发布资产名。 命名规则来自 XTLS 的 release 脚本:amd64 用 "64"、arm64 用 "arm64-v8a"。
func XrayBinVersion ¶ added in v0.2.0
XrayBinVersion 运行 `<bin> version` 并解析版本号。 bin 为待探测的可执行文件路径;超时或执行失败返回错误(调用方据此判定该二进制不可用)。
func XrayVersionOf ¶ added in v0.2.0
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 发布资产,按镜像候选链逐个尝试。
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) XrayDownload ¶ added in v0.2.0
func (f *XrayFetcher) XrayDownload(tag string) (bin []byte, sha string, err error)
XrayDownload 按候选链下载指定版本的 Xray 压缩包,校验 sha256 后返回其中 xray 可执行文件的字节。 返回的 expected 摘要仅用于日志/回执展示(校验已在内部完成)。
func (*XrayFetcher) XrayDownloadBundle ¶ added in v0.2.0
func (f *XrayFetcher) XrayDownloadBundle(tag string) (*XrayBundle, error)
XrayDownloadBundle 下载并解包完整发布包(内核 + geo 数据),只走一次下载。 换内核与 geo 回退共用:两者必须来自同一个已校验压缩包,不能各下一份。