文档

安装与更新

Orbitra 为快速上手而优化,无需复杂的环境配置。它构建在轻量的 PHP + SQLite + Nginx 技术栈上 — 不需要独立的数据库服务器(没有 ClickHouse、Redis 或 MySQL)。

系统要求

Orbitra 把所有数据存在单个 SQLite 文件里,因此内存需求远低于基于 ClickHouse 的追踪器,最便宜的 VPS 套餐也能运行。

基础配置(必需):

按流量规模选型(参考值):

每日点击量内存CPU磁盘
最高约 100,0001–2 GB1–2 vCPU20 GB SSD
约 100,000 – 500,0002–4 GB2 vCPU40 GB SSD
约 500,000 – 1,000,0004–8 GB4 vCPU80 GB SSD

✅ 实测验证: Orbitra 在 2 vCPU / 2 GB 内存 / 20 GB SSD 的 VPS(Ubuntu 24.04)上小流量稳定运行 — 这是个方便又便宜的起点。表格中更高的配置是应对更大流量的余量,并非硬性要求。

💡 为什么比 Keitaro 要求低? Keitaro 把点击存进 ClickHouse + Redis + MySQL,因此在每天数百万点击的量级下内存需求会涨到 64 GB。而在 Orbitra 里,一切都住在单个 SQLite 文件中 — 瓶颈不是内存,而是磁盘 I/O 和 SQLite 的单线程写入。对小到中等流量(WAL 模式下)这就足够了;如果要在重度分析场景下持续承受每天数百万点击,列式数据库的追踪器(如 Keitaro)在架构上是更合适的选择。

💡 在 1 GB 内存的服务器上安装时,请额外加 1–2 GB swap:构建前端(Vite)是最吃内存的一步。追踪器本身在 1 GB 内存上运行良好。

快速自动安装(生产环境)

在服务器上部署项目最快、最正规的方式是使用内置安装器。

  1. 确认你有一台"干净"的 Linux 服务器(Ubuntu 22.04+ 或 Debian 12+)。
  2. 以 root/sudo 运行命令:
   wget -O orbitra-install.sh https://raw.githubusercontent.com/fenjo26/Orbitra.link/main/install.sh && bash orbitra-install.sh

下载单独成一步是有意为之:用 wget -qO- … | bash 时,下载失败会把空内容静默地灌进 bash,安装会"一声不吭地完成",一行输出都没有。这样写它会在 && 处停下,wget 会报告失败原因。

  1. 脚本会安装 Nginx、新版 PHP(优先 8.5,其次来自 Ondřej Surý 仓库的 8.4;如果也没有 — 用发行版自带的)、SQLite,下载前端代码并配置 HTTPS 证书。

首次登录: 没有"默认"账号。安装完成后打开 http://<your-domain>/admin.php — 首次运行时 Orbitra 会启动初始设置向导,你在那里创建自己的管理员(登录名 ≥ 3 个字符,密码 ≥ 8 位,以及时区和语言)。

通过 IP 访问后台

无论你绑定了多少域名、之后删掉其中哪些,后台始终可以通过服务器地址访问 — http://<ip>/admin.php。这由 Orbitra 放在 Nginx 配置最前面的 catch-all 块实现;证书通过 certbot certonly --webroot 签发,因此 Certbot 不会改写配置。

https://<ip>/admin.php 也能用,但浏览器会警告:Let's Encrypt 不给裸 IP 签发证书,所以使用的是自签名证书。

如果后台仍然无法访问 — 例如 Nginx 配置被手动改过 — 可以从数据库重建它:

sudo php /var/www/orbitra/cli/nginx_sync.php

该命令还会修复旧签发方式遗留的 Certbot 续期配置,并生成自签名证书。从 0.9.6.4 以下版本更新后,请运行一次。

安装器会做哪些事

不会自动安装的:按保留期清理(cli/cleanup_cron.php,见 管理)、postback 监控器和来源 URL 检查。

在运行中的服务器上重复执行安装器是安全的:它会更新 PHP、配置和 cron 任务,但不会碰数据。

安装后的后台安全设置 — 自定义后台路径、按 IP 限制访问、两步验证登录 — 见管理。

更新 PHP

安全公告:CVE-2026-109618 / CVE-2026-109619(2026 年 10 月)

PHP 自身存在两个严重的未授权 RCE 漏洞("php2shell",CVSS v4.0 评分 9.2,已有公开利用代码),上游已于 2026-10-21 修复。已修复版本:8.5.12、8.4.27、8.3.36、8.2.35。追踪器是暴露在公网上的 PHP 应用,每一个面向 Web 的解释器都必须打上补丁。在当前运行的 PHP 报告为上述版本(或更高)之前,仪表盘会一直显示红色横幅。

常规升级

Ubuntu 22.04 / Debian 12 / Ubuntu 24.04 自带的是 PHP 8.1 / 8.2 / 8.3 — 这些版本不再接收安全更新(8.1 和 8.2 已 EOL;8.3 在 2027 年底之前只收安全修复)。Orbitra v1.5.10 在它们上面都能运行,但全新安装或升级服务器时应从 PHP 8.4+ 起步。

最简单的办法是重新运行安装器(它是幂等的,支持在现有安装上升级):

sudo bash /var/www/orbitra/install.sh

安装器会添加当前的 PHP 构建仓库(Ubuntu 上是 ondrej/php,Debian 上是 packages.sury.org),与旧版本并行安装 PHP 8.5(失败则退回 8.4),切换 php 命令行的 alternative(cron 任务和 Composer 使用),把 Nginx 配置改写到新的 FPM socket,应用进程池设置并重启服务。旧版 PHP 保留在系统里但不再承接流量;检查无误后可以自行卸载。

手动升级(Ubuntu):

sudo add-apt-repository -y ppa:ondrej/php && sudo apt-get update
sudo apt-get install -y php8.5-fpm php8.5-cli php8.5-sqlite3 php8.5-curl php8.5-mbstring php8.5-xml php8.5-zip php8.5-intl php8.5-bcmath
sudo update-alternatives --set php /usr/bin/php8.5
sudo bash /var/www/orbitra/install.sh   # switches nginx/FPM/crons to the new version

手动升级(Debian):

. /etc/os-release
curl -fsSL https://packages.sury.org/php/apt.gpg | sudo gpg --dearmor --yes -o /usr/share/keyrings/deb.sury.org-php.gpg
echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ ${VERSION_CODENAME} main" | sudo tee /etc/apt/sources.list.d/php-sury.list
sudo apt-get update
sudo apt-get install -y php8.5-fpm php8.5-cli php8.5-sqlite3 php8.5-curl php8.5-mbstring php8.5-xml php8.5-zip php8.5-intl php8.5-bcmath
sudo update-alternatives --set php /usr/bin/php8.5
sudo bash /var/www/orbitra/install.sh

更新完成后检查:php -v 显示 8.4/8.5,后台能打开,Logs → System log(日志 → 系统日志)里没有 postback.php database error 条目,postback 队列设置里 worker 的 ping 时间是新鲜的。通过按钮更新时,如果服务器仍停留在 PHP < 8.4,面板会自行发出警告。

更新后的一次性服务器操作(1.6.0+)

面板里的"Update"按钮以 Web 用户身份运行,无法修改 sudoers。1.6.0 之前安装的服务器在更新后需要以 root 身份运行一次 cli/server_setup.sh — 面板会用横幅显示这条命令:

curl -fsSL https://raw.githubusercontent.com/fenjo26/Orbitra.link/v1.6.0/cli/server_setup.sh | sudo ORBITRA_REF=v1.6.0 bash

脚本从 release 标签下载,而不是从 /var/www/orbitra(该目录属于 Web 用户,root 不应执行 Web 用户可改写的文件)。它用带参数校验的辅助脚本替换了旧的 sudo 规则(任意参数的 certbot,以及向 sites-available 的 cp — 两者都可能让 Web 用户获得 root),安装点击队列 cron,并把版本写入 /etc/orbitra/server-setup-version。重复运行是安全的。install.sh 调用的是同一个脚本,因此全新安装也会得到同样的处理。

更新到 1.8.4 之后:nginx 加固(2026 年 10 月安全公告)

服务器上无需执行任何操作:更新本身就会重新生成不带 alias 指令的 nginx vhost 并重载 nginx(走的是与保存域名相同的校验路径)。剩下的 操作系统 部分属于 2026 年 10 月公告的另一半 — nginx 软件包本身(CVSS 最高 9.2)、内核和 CA 信任库 — 只有运维人员自己能更新:

apt update && NEEDRESTART_MODE=a apt upgrade -y   # Debian/Ubuntu; dnf upgrade on the RHEL family
systemctl reload nginx
reboot                                             # loads the fixed kernel
nginx -v                                           # fixed: 1.31.7+ mainline / 1.30.6+ stable

发行版构建可能在不提升版本号的情况下回移植修复 — 用 apt changelog nginx 检查。在当前运行的 nginx 报告为已修复版本之前(前提是有 shell 可供读取),仪表盘会显示一条可关闭的横幅。追踪器不受同一份公告里 PostgreSQL / Redis / Node.js 条目的影响:它运行 PHP + SQLite,服务器上也不附带 Node.js。

更新到 1.8.3 之后:整站会话录制

服务器上无需执行任何操作。本次更新加入了广告系列级的会话录制、One click per visit(每次访问合并为一次点击)的访问归并以及同意模式,全部默认关闭 — 只有你自己开启的地方,点击统计和录制才会变化。无需新增 cron:清理仍然搭在传入的录制上完成。

更新到 1.8.2 之后:浏览器检查

服务器上无需执行任何操作。本次更新加入了浏览器检查,但在已有安装上保持关闭,路由不会自行改变。管理员会在仪表盘上看到一次性横幅:Turn on soft mode(开启温和模式)将其开启,Learn more 打开 Settings → Bots,Not now 隐藏横幅(模式之后随时可在 Settings → Bots 里更改)。全新安装则默认以温和模式启动。

更新的完整性

本地开发(React 与 PHP 服务器)

如果你打算修改前端源码(React)和追踪器的界面部分,需要一套本地 PHP + Vite 环境。

第 1 部分:启动后端 API

打开第一个终端,用路由器脚本启动内置 PHP 服务器:

cd Orbitra
php -S localhost:8080 router.php

这个服务器负责处理 API 请求和跳转。

第 2 部分:启动前端(Vite)

打开第二个终端,安装 npm 依赖并启动开发服务器:

cd Orbitra/frontend
npm install
npm run dev

然后在浏览器里打开 http://localhost:5173。前端发出的所有 API 请求都会(通过 vite.config.js 的 proxy)自动代理到 http://localhost:8080/api.php,从而避免开发模式下的 CORS 和会话问题。

构建后台

只有在你修改后台代码时才需要:

cd Orbitra/frontend
npm run build

构建产物位于 frontend/dist/,并提交进仓库 — 服务器通过 git pull 或面板更新直接获取现成的后台,自己不做任何构建。

Telegram 机器人

连接方式与运行模式 — Telegram 机器人。

← 上一篇
快速上手
下一篇 →
从 Keitaro 迁移
在 GitHub 上查看源码: github.com/fenjo26/Orbitra.link/wiki
全部教程
文档

快速上手

从裸机服务器到第一条转化的九个步骤:安装、首次登录、域名、联盟与 offer、流量来源、广告系列、验证、消耗与统计。

阅读教程 →
文档

安装与更新

系统要求、一条命令的安装器、PHP 更新与安全公告、按 IP 访问后台、更新完整性校验,以及本地开发环境。

阅读教程 →
文档

从 Keitaro 迁移

通过 SQL dump 把设置从 Keitaro 迁到 Orbitra:迁移内容清单、导出脚本、导入步骤,以及导入后要检查的事项。

阅读教程 →
文档

从 Binom 迁移

通过 Binom v2 Public API 直接导入广告系列、offer、流等设置 — 无需 dump 文件,附字段映射说明。

阅读教程 →
文档

功能总览

所有功能一览:流量与方案、postback 与消耗、数据分析、基础设施与管理 — 每项都链接到详细页面,并附各版本的新增内容。

阅读教程 →
文档

广告系列与流

广告系列编辑器详解:设置标签页、计费模式、流类型与全部过滤器、方案、自动优化轮询、测试链接与重复点击防护。

阅读教程 →
文档

斗篷(参考文档)

斗篷完整参考:流设置、检测层、灵敏度、定向过滤器、JavaScript 验证、全局设置、判定结果与原因代码及诊断方法。

阅读教程 →
文档

浏览器检查

通过浏览器自报矛盾识别机器人、审核员虚拟机、模拟器和反检测浏览器:四种模式、特征清单、结果查看与安全启用步骤。

阅读教程 →
文档

落地页(参考文档)

落地页完整参考:本地、跳转、Preload 与 Action 四种类型,{offer} 宏、subid 传递、停留时长、JS adapter、PHP 落地页与故障排查。

阅读教程 →
文档

PWA 与 Web Push

PWA 落地页与自建 Web Push:构建器、域名绑定、VAPID 密钥、订阅者、消息与发送 cron、转化归因和故障排查。

阅读教程 →
文档

PWA 漏斗

PWA 落地页内的可配置漏斗:store/screen/instructions/push 步骤类型、逐屏追踪、统计维度与编辑器用法。

阅读教程 →
文档

转化弹窗(Conversion Popups)

在落地页上展示带 offer 按钮的弹窗:适用场景、Popup 标签页设置、触发条件与统计指标。

阅读教程 →
文档

会话录制与热力图

像视频一样回放真实访问,配合点击热力图与滚动图;含整站录制、Cookie 同意、存储上限与隐私说明。

阅读教程 →
文档

素材库完整参考

Gallery 页面、上传与软删除、MediaPicker 的尺寸契约(sizeContract)、格式与大小限制,以及视频支持。

阅读教程 →
文档

创意库

平台同步的创意与手动上传的草稿统一存放,自动绑定花费/收入/ROI,找出真正赚钱的创意。

阅读教程 →
文档

外部 PWA 与 Telegram 频道

把第三方 PWA 构建器接入流做 A/B,并把 Telegram 频道当作可归因的 offer 目的地。

阅读教程 →
文档

Postback 与转化

入站 postback 参数与状态映射、转化类型、出站 S2S postback、投递队列与测试器、转化导入和 Conversions API。

阅读教程 →
文档

花费(Costs)

从 Facebook、TikTok、Google Ads 和 push/pop 联盟导入花费并分摊到点击;含收入聚合器、代理佣金与排错。

阅读教程 →
文档

Push 与 Pop 联盟

接入 push/pop 联盟的花费导入与 zone 级优化:支持联盟列表、匹配规则与 Zone Killer 屏蔽烧钱 zone。

阅读教程 →
文档

Facebook / Meta

两套独立集成:从 Meta 导入广告花费,以及用 Conversions API 服务端发送转化事件,含浏览器匹配与排错。

阅读教程 →
文档

Dolphin / Fbtool

通过 Dolphin(Fbtool)API 实时接收 Facebook 消耗:兼容 Keitaro 的入站端点、API 密钥与活动参数配置、消耗分摊与验证。

阅读教程 →
文档

FB 评论清理器

按计划批量审核 Facebook 广告贴下的评论:停用词、正则、链接与联系方式规则,默认 dry-run、默认隐藏、操作可恢复。

阅读教程 →
文档

流量来源与联盟

配置漏斗两端的两个目录:约 200 个流量来源模板与约 440 个联盟模板,参数三元组、postback URL 与 offer 参数宏。

阅读教程 →
文档

报表、日志与指标

仪表盘、报表生成器、趋势与群组、流量日志与点击卡片,以及每个指标的计算方式。

阅读教程 →
文档

域名与 SSL

添加域名、把 DNS 指向服务器、自动签发 Let's Encrypt 证书,以及 Domains 页面上每个开关的作用。

阅读教程 →
文档

Cloudflare

通过 API 接入 Cloudflare:域名自动停放 A 记录、多账号、代理(橙色云朵)与 Flexible / Full / Strict SSL 模式。

阅读教程 →
文档

管理

用户、角色与按资源授权、两步验证、API 密钥、安全设置、geo 数据库、面板更新与系统状态。

阅读教程 →
文档

Telegram 机器人

在 Telegram 里管理追踪器:转化通知、每日摘要、统计命令,以及发到频道/群组的转化提醒。

阅读教程 →
文档

MCP:追踪器里的 AI 助手

把 Claude 或任何 MCP 客户端连上 Orbitra,用大白话管理广告系列:41 个工具、远程与本地两种连接方式、API 密钥安全。

阅读教程 →