文档目录

在 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。

全新安装做三件事:

  1. 如果没有 Docker,就从 get.docker.com 安装,然后用 Docker Compose 在 /opt/velotrak/stack 启动 PostgreSQL 和 ClickHouse。Postgres 监听 127.0.0.1:15432。ClickHouse 监听 127.0.0.1:19000。密码写在该目录的 .env 里。
  2. 从公开仓库 velotrak/velotrak 下载本机架构的发布二进制,并按 checksums.txt 校验 SHA-256。
  3. 写入 /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。见备份。

安装之后的套餐上限在定价页。