文档目录
在 Linux 上安装 Velotrak
更新于 2026年11月17日
在 Linux 服务器上以 root 运行 curl -fsSL https://velotrak.app/install.sh | sudo bash。脚本会在需要时安装 Docker,在本机启动 PostgreSQL 和 ClickHouse,并用 systemd 运行 Velotrak。
运行安装器
公开脚本是 velotrak.app/install.sh。发布的二进制在 GitHub。
curl -fsSL https://velotrak.app/install.sh | sudo bash
不是 root、不是 Linux,或缺少 systemd、curl 时,脚本拒绝运行。它接受 x86_64(amd64)和 aarch64(arm64)。全新安装时,内存低于 3500 MB 会警告,并把 2 vCPU / 4 GB 称为最低配置。警告不会中止脚本,脚本也不检查 CPU 数量。官网推荐 4 vCPU / 8 GB。
全新安装做三件事:
- 如果没有 Docker,就从 get.docker.com 安装,然后用 Docker Compose 在
/opt/velotrak/stack启动 PostgreSQL 和 ClickHouse。Postgres 监听127.0.0.1:15432。ClickHouse 监听127.0.0.1:19000。密码写在该目录的.env里。 - 从公开仓库
velotrak/velotrak下载本机架构的发布二进制,并按checksums.txt校验 SHA-256。 - 写入
/opt/velotrak/velotrak.env,安装 systemd 服务velotrak,以用户velotrak运行/opt/velotrak/velotrak,并等待http://127.0.0.1:8080/healthz有响应。默认 HTTP 端口是 8080。数据目录是/var/lib/velotrak。
二进制还会尝试把 DB-IP city lite 数据库下载到 /var/lib/velotrak/geoip。下载失败时,脚本警告:在放上数据库之前,国家、地区和城市保持为空。
指定版本或自备数据库
钉住发布页上存在的标签:
curl -fsSL https://velotrak.app/install.sh | sudo VELOTRAK_VERSION=v1.2.3 bash
把 v1.2.3 换成真实标签。跳过 Docker、使用已有数据库:
curl -fsSL https://velotrak.app/install.sh | sudo VELOTRAK_EXTERNAL_DB=1 bash
脚本会让你在 /opt/velotrak/velotrak.env 里设置 VELOTRAK_PG_DSN 和 VELOTRAK_CH_DSN,然后 systemctl start velotrak。迁移编译在二进制里。velotrak migrate 只迁移、不启动服务。安装本机已有的二进制:sudo ./install.sh ./velotrak。
打开设置向导
在第一个管理员出现之前,进程把一次性令牌写到 /var/lib/velotrak/setup.token(权限 0600),安装器打印形如 http://<主机>:8080/admin/#setup=<令牌> 的地址。没有令牌的 POST /api/setup 返回 403。你可以在首次启动前自己设置 VELOTRAK_SETUP_TOKEN(至少 16 个字符)。管理员创建后该文件会被删除。
向导顺序是:欢迎、环境检查、管理员账号、常规设置、授权(可跳过)、完成。环境检查报告程序、PostgreSQL、ClickHouse、GeoIP、资源和端口。常规设置保存时区,以及 USD、CNY、EUR、GBP、JPY 之一。密码为 8 个字符到 72 字节。授权可以以后再激活,见套餐。
后台路径默认是 /admin/。如果后台不应在追踪域名上响应,设置 VELOTRAK_ADMIN_HOST(可填多个主机名)。运维说明写明:能上传落地页的操作员,或第三方落地页,不应与后台同源。
域名和 TLS
在「域名」页登记每一个投放主机名。设置 VELOTRAK_TLS_DOMAIN 后,该主机被视为追踪域名,并启用内置 ACME:绑定 443,为该名字以及后台里添加的域名签发证书。把 DNS 指到这台机器,然后在域名上点「检查」。检查是一次外部探测。
已有证书时,设置 VELOTRAK_TLS_CERT_FILE 和 VELOTRAK_TLS_KEY_FILE。生成的 env 文件里有注释示例。Cloudflare 以外的 CDN 放在前面时,把它们的地址段写入 VELOTRAK_TRUSTED_PROXIES,这样记下的才是访客 IP。Cloudflare 自己的地址段已经编进程序。橙色云的 TLS、缓存,以及必须保持原样的路径见 Cloudflare。未登记的主机不会按正常落地页源站返回:服务器会把响应放进沙箱,该主机上的像素读不到追踪 cookie。
升级
再运行同一条命令。旧二进制保留为 /opt/velotrak/velotrak.old。env 文件、生成的密码和数据目录不动。如果服务没有响应,安装器让你看 journalctl -u velotrak -n 50 --no-pager。
停止或删除
仓库里没有卸载脚本。systemctl disable --now velotrak 会停止安装在 /etc/systemd/system/velotrak.service 的服务。安装器创建了 /opt/velotrak(二进制、env 和 Compose 栈)和 /var/lib/velotrak(数据、master.key、证书、备份)。删除这些目录会删掉本地数据库的 Docker 文件和追踪数据,包括备份。如果还要解密已保存的集成凭据,先复制 master.key。见备份。
安装之后的套餐上限在定价页。