跳到主要内容
快速入门

快速部署 STX

在 Linux 上安装 STX、接入主机,并在本机或另一台机器上使用 STX CLI。

在一台 Linux 机器上安装 STX 后,你会得到 Web UI、STX Server 和 Agent 所需的 gRPC 服务。本文介绍如何用安装脚本安装 STX。

安装前检查​

检查项要求
系统Linux,glibc ≥ 2.17;支持 Ubuntu / Debian、Rocky / Alma / RHEL 8+、CentOS 7 等。推荐带 systemd;容器 / CI 等无 systemd 环境加 --no-systemd
架构amd64 或 arm64;CentOS 7 仅支持 amd64
网络浏览器能访问 STX 安装机的 17880;被纳管主机能访问 STX 安装机的 17800 和 17890
磁盘安装目录所在分区约 700 MB;带本地监控组件约 2.2 GB
命令bash、curl、tar、gzip、sha256sum;不需要 Node.js 和 python3(离线包自带 Node)
权限root(用 sudo 执行安装脚本)
备注

一键安装面向 Linux。macOS 和 Windows 可用于本地开发,不是这套安装脚本的目标系统。

1. 一键安装​

在准备作为 STX 安装机 的 Linux 机器上执行一条命令。安装目录默认为 /opt/stx。

# 中国网络(推荐)
curl -fsSL https://v4.gh-proxy.org/https://github.com/LeonYoah/stx/releases/latest/download/install-online.sh | sudo bash

# 直接访问 GitHub
curl -fsSL https://github.com/LeonYoah/stx/releases/latest/download/install-online.sh | sudo bash

脚本按 CPU 架构和 glibc 版本下载对应的离线包,校验 sha256 后安装;CentOS 7 等 glibc < 2.28 的系统自动使用 CentOS 7 专用包。不加 -y 时会提问端口、对外访问 IP、数据库和管理员密码,直接回车即使用默认值。

无 systemd 时(例如部分容器或 CI 环境)加 --no-systemd;非 root 还需同时指定当前用户可写的 --install-dir。

选择下载线路​

脚本默认测速后使用最快的线路,失败时自动换下一条。可用 --mirror 固定线路(编号或名称,也可以是自己的代理前缀):

编号名称地址
1gh-proxyhttps://gh-proxy.org(Cloudflare 主站加速)
2v4https://v4.gh-proxy.org(Cloudflare 优选,推荐,仅 IPv4)
3v6https://v6.gh-proxy.org(Cloudflare 优选,支持 IPv6)
4cdnhttps://cdn.gh-proxy.org(Fastly CDN)
5axisnowhttps://axisnow.gh-proxy.org(AxisNow 三网优选)
6githubGitHub 直连
curl -fsSL https://v4.gh-proxy.org/https://github.com/LeonYoah/stx/releases/latest/download/install-online.sh | sudo bash -s -- --mirror v4

常用参数​

参数加在命令后,例如 curl -fsSL ... | sudo bash -s -- -y --install-dir /data/stx:

参数作用
-y不提问,全部使用默认值 / 参数值
--install-dir /opt/stx安装目录,默认 /opt/stx
--admin-password xxxadmin 初始密码
--frontend-port / --http-port / --grpc-portWeb UI / HTTP API / gRPC 端口,默认 17880 / 17800 / 17890
--external-ip 10.0.0.10对外访问 IP 或域名
--db-type sqlite|mysql|postgres数据库,默认 sqlite;postgres 也可写 pg
--db-host / --db-port / --db-user / --db-password / --db-nameMySQL / PostgreSQL 连接参数;密码也可用环境变量 STX_DB_PASSWORD
--without-observability不安装本地监控组件(Prometheus / Alertmanager / Grafana)
--prometheus-port / --alertmanager-port / --grafana-port本地监控组件端口,默认 9090 / 9093 / 3000
--mirror v4固定下载线路(仅一键安装 / download-bundle.sh)
--variant amd64|arm64|centos7 / --version <tag>指定离线包类型 / 版本(仅一键安装 / download-bundle.sh)
--without-node不用包内 Node,改用本机 Node ≥ 18.18
--service-user stx用指定用户运行服务(默认 root)
--no-autostart / --no-systemd / --no-start不开机自启 / 不创建 systemd 服务 / 安装后不启动

使用外部数据库的示例:

curl -fsSL https://v4.gh-proxy.org/https://github.com/LeonYoah/stx/releases/latest/download/install-online.sh \
| sudo bash -s -- --db-type postgres --db-host 10.0.0.5 --db-user stx --db-name stx
sudo

安装需要 root。不用 sudo 执行时,脚本会在任何检查和提问之前退出,并打印带 sudo 的完整命令。只有同时指定当前用户可写的 --install-dir 和 --no-systemd 时才可以不用 root。

安装完成后检查状态:

/opt/stx/bin/status.sh
# 使用 systemd 安装时也可查看
systemctl status stx

2. 打开 Web UI​

假设 STX 安装机的 IP 是 10.0.0.10,在浏览器中打开 http://10.0.0.10:17880,用 admin 和安装时设置的密码登录(直接回车的为 admin123,登录后请尽快修改)。

服务默认端口谁需要访问
Web UI17880使用浏览器的人
STX Server HTTP API17800Web UI、CLI 和被纳管主机上的安装脚本
stx-agent gRPC17890被纳管主机上的 stx-agent

安装结果末尾会打印后续步骤;接入主机和创建集群见 主机管理 和 集群管理。

安装 STX CLI​

STX 客户端和服务端用的是同一个二进制文件:运行 stx server 时启动 STX Server;运行 stx login、stx cluster list 等命令时,它就是客户端。可以把它理解成 Hadoop 部署后的 hadoop 命令。

客户端和服务端在同一台机器​

整套 STX 安装完成后,直接使用安装目录中的文件,不需要再安装 CLI:

/opt/stx/stx login --server http://127.0.0.1:17800
/opt/stx/stx cluster list --output table

如果安装时改了 --install-dir,将 /opt/stx 换成自己的目录。登录会提示输入用户名和密码;本机登录信息保存在执行命令的用户目录中。

客户端与服务端分离​

假设 STX 安装机是 10.0.0.10,另一台 Linux 机器只需通过 CLI 远程操作。两台机器 CPU 架构相同时,直接复制安装机上的 /opt/stx/stx 即可。在客户端机器执行:

scp [email protected]:/opt/stx/stx ./stx
chmod +x ./stx
./stx login --server http://10.0.0.10:17800
./stx cluster list --output table

把 user 换成能读取该文件的 SSH 用户名。客户端不需要安装 Web UI、Node.js 或 stx-agent。复制这个文件不会在客户端启动 STX Server;客户端只需能访问安装机的 17800 端口。

不能使用 SSH 时,也可以通过 U 盘或内网文件传输复制同一个文件,放到客户端后从 chmod +x ./stx 继续。客户端安装时可以不连外网,但运行远程命令时仍要连通 STX Server。

架构不同怎么办

先在两台机器分别运行 uname -m。如果一台是 x86_64,另一台是 aarch64,不能直接复制安装机上的文件。请在能联网的机器上下载与客户端架构及 STX Server 版本相符的 Release 文件(stx-linux-amd64 或 stx-linux-arm64),再复制到客户端并命名为 stx。只复制二进制文件是为了使用 CLI,不会安装完整服务。

下一步看 STX CLI 用法。给 AI Agent 用时执行 stx skill install(见 安装 Skill)。

其他安装方式​

离线安装​

每个 Release 附带三个完整离线包,包含 STX Server、Web UI、stx-agent、Node、本地监控组件,各带一个 .sha256 校验文件。按 STX 安装机选择:

离线包适用系统怎么判断
stx-offline-linux-amd64.tar.gzx86_64,glibc ≥ 2.28:Ubuntu 20.04+、Debian 10+、Rocky / Alma / RHEL 8+ 等uname -m 输出 x86_64,ldd --version 首行 ≥ 2.28
stx-offline-linux-arm64.tar.gzaarch64,glibc ≥ 2.28uname -m 输出 aarch64
stx-offline-linux-amd64-centos7.tar.gzx86_64,glibc < 2.28:CentOS 7、RHEL 7ldd --version 首行是 2.17 等

上表是最新 Release 的固定文件名。指定版本时,文件名形如 stx-vX.Y.Z-linux-amd64-offline.tar.gz,下载地址把 latest/download 换成 download/vX.Y.Z。

在能联网的机器上下载,6 条线路任选一条(哪条快用哪条)。以 CentOS 7 为例:

F=stx-offline-linux-amd64-centos7.tar.gz # 换成上表中你需要的文件名
U=https://github.com/LeonYoah/stx/releases/latest/download/$F

wget "https://gh-proxy.org/$U" # 1) Cloudflare 主站加速
wget "https://v4.gh-proxy.org/$U" # 2) Cloudflare 优选(推荐,仅 IPv4)
wget "https://v6.gh-proxy.org/$U" # 3) Cloudflare 优选(支持 IPv6)
wget "https://cdn.gh-proxy.org/$U" # 4) Fastly CDN
wget "https://axisnow.gh-proxy.org/$U" # 5) AxisNow 三网优选
wget "$U" # 6) GitHub 直连

# 校验文件用同一条线路下载,例如:
wget "https://v4.gh-proxy.org/$U.sha256"

也可以让脚本测速下载:curl -fsSL https://v4.gh-proxy.org/https://github.com/LeonYoah/stx/releases/latest/download/download-bundle.sh | bash -s -- --variant centos7。

把两个文件复制到 STX 安装机后安装:

sha256sum -c stx-offline-linux-amd64-centos7.tar.gz.sha256
tar -xzf stx-offline-linux-amd64-centos7.tar.gz
cd stx-*-offline/
sudo ./install.sh

常用参数与一键安装相同(如 sudo ./install.sh -y --db-type postgres ...,无 systemd 时加 --no-systemd);下载相关的 --mirror、--variant、--version、--bundle-file 不适用于 install.sh,它安装的就是当前目录这个离线包。离线包默认按包内组件安装,一般不必再加 --offline。

这只装好 STX 控制面。无网环境还要装 SeaTunnel 集群时,须另备 SeaTunnel 离线资产包(安装包 ± 插件),在有网侧的 STX 里导出后拷过来导入。

Docker Compose​

mkdir -p stx-docker && cd stx-docker
# 中国
curl -fsSL https://v4.gh-proxy.org/https://github.com/LeonYoah/stx/releases/latest/download/stx-docker-compose.tar.gz | tar -xz
# GitHub 直连:去掉 https://v4.gh-proxy.org/
cd docker
# SeaTunnel 不在本机时,改 config.yaml 的 app.external_url / app.console_url 为其他机器能访问的安装机 IP(默认 127.0.0.1)
mkdir -p data
docker compose up -d

中国拉镜像再执行 cp .env.cn.example .env 后 docker compose up -d。SQLite:docker compose -f docker-compose.sqlite.yml up -d。

打开 Web UI http://127.0.0.1:17880。宿主机只暴露 17880 / 17800 / 17890。

单容器体验(不含监控)​

# GHCR
docker run -d -p 17800:17800 -p 17880:17880 -p 17890:17890 ghcr.io/leonyoah/stx-all-in-one:latest

# 华为云 SWR
docker run -d -p 17800:17800 -p 17880:17880 -p 17890:17890 swr.cn-east-3.myhuaweicloud.com/stx/stx-all-in-one:latest

启停服务​

/opt/stx/bin/start.sh
/opt/stx/bin/stop.sh
/opt/stx/bin/status.sh
# 使用 systemd 安装时也可执行 systemctl restart stx

start.sh 默认按 observability.enabled 和本地监控组件的安装情况决定是否启动监控。要明确关闭,执行 /opt/stx/bin/start.sh --observability off。

安装遇到问题​

现象检查方法
安装前检查提示端口被占用交互安装时按提示换一个端口;用 -y 时加 --http-port 等参数。查看占用:ss -lntp | grep -E '17800|17880|17890'
安装失败按提示查看出错的步骤和日志 /tmp/stx-install-*.log(或 /opt/stx/logs/install.log)
CentOS 7 上提示 glibc 版本过低改用 stx-offline-linux-amd64-centos7.tar.gz;一键安装会自动选择
主机一直不在线从被纳管主机检查能否访问 STX 安装机的 17800 和 17890,再检查防火墙与安全组
下载慢或失败换一条下载线路,或加 --mirror v4 等固定线路
无 systemd / 容器环境安装失败加 --no-systemd;非 root 时再加可写的 --install-dir
打开 17800 看不到登录页Web UI 默认在 17880;17800 是 HTTP API

如果你要在本机开发 STX,而不是安装 Release,请看源码仓库的开发说明。