安装与更新
Orbitra 为快速上手而优化,无需复杂的环境配置。它构建在轻量的 PHP + SQLite + Nginx 技术栈上 — 不需要独立的数据库服务器(没有 ClickHouse、Redis 或 MySQL)。
系统要求
Orbitra 把所有数据存在单个 SQLite 文件里,因此内存需求远低于基于 ClickHouse 的追踪器,最便宜的 VPS 套餐也能运行。
基础配置(必需):
- CPU: 1 vCPU(x86_64)
- 内存: 1 GB(建议 2 GB)
- 磁盘: 20 GB SSD
- 操作系统: Ubuntu 22.04 至 26.04,或 Debian 12 / 13
- 一台没有控制面板的干净服务器;需要 root/sudo 权限
按流量规模选型(参考值):
| 每日点击量 | 内存 | CPU | 磁盘 |
|---|---|---|---|
| 最高约 100,000 | 1–2 GB | 1–2 vCPU | 20 GB SSD |
| 约 100,000 – 500,000 | 2–4 GB | 2 vCPU | 40 GB SSD |
| 约 500,000 – 1,000,000 | 4–8 GB | 4 vCPU | 80 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 内存上运行良好。
快速自动安装(生产环境)
在服务器上部署项目最快、最正规的方式是使用内置安装器。
- 确认你有一台"干净"的 Linux 服务器(Ubuntu 22.04+ 或 Debian 12+)。
- 以 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 会报告失败原因。
- 脚本会安装 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 以下版本更新后,请运行一次。
安装器会做哪些事
- Nginx、PHP-FPM(进程池按内存大小设定,
fastcgi_read_timeout 180s)、SQLite,以及带 SHA-256 校验的 Composer。 - 代码位于
/var/www/orbitra,属主为www-data。 - 独立的 postback 密钥。
- Sypex Geo City 数据库(免费、无需密钥)。如果服务器连不上 sypexgeo.net,安装仍会完成,数据库之后可以在 ⚙ → Geo Databases 里添加。
- 带参数校验的 SSL 和 nginx 辅助脚本(
cli/server_setup.sh)。 - Cron 任务:点击落盘队列、postback 队列、Web Push、轮询自动优化、Telegram 轮询、SSL 签发、消耗导入、IP 段、geo 数据库。完整表格见 Architecture(架构文档)。
- MCP 服务器依赖(如果服务器上有 npm)。
- 如果 ufw 已启用,会开放 80/443 端口。
不会自动安装的:按保留期清理(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 报告为上述版本(或更高)之前,仪表盘会一直显示红色横幅。
- PHP 8.2–8.5,未打补丁: 运行
NEEDRESTART_MODE=a apt install -y --only-upgrade 'php8.X-'(把 X 换成你的分支),然后重启 PHP-FPM 和 Web 服务器(systemctl restart php8.X-fpm nginx)。这条命令按可整段粘贴设计:-y免除了Continue? [Y/n]确认(整段粘贴多行命令块时,下一行会被当作答案读入 — apt 随即中止),而NEEDRESTART_MODE=a会自动应答 Ubuntu 22.04+ 的"重启哪些服务"对话框。不要直接用apt upgrade 'php':apt 会把这个通配符展开成仓库里所有名字带 php 的包,并在升级任何东西之前因冲突而中止。发行版构建可能在版本号未变的情况下回移植了修复 — 在断定自己受影响之前,先用apt changelog php8.X-fpm | grep 109618检查。 - PHP 8.1 或更老: 该分支已 EOL,永远不会收到修复。请通过下文的安装器路径升级(
sudo bash install.sh会并行安装 PHP 8.5 并把所有服务切换过去)。 - 如果 PHP 是由主机控制面板(ispmanager 等)安装的,请在该面板里更新。
常规升级
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 里更改)。全新安装则默认以温和模式启动。
更新的完整性
composer.phar不进仓库:安装器下载install.sh里固定的版本(COMPOSER_VER)并校验COMPOSER_SHA256;不匹配则中止安装。已存在的/var/www/orbitra/composer.phar会原样使用。- 后台(
frontend/dist)在发布机上构建并提交入库:服务器从不运行npm install/npm run build,安装完成后工作副本保持干净。 - Release 标签应当签名(
git tag -s),这样从面板更新拉取的代码才是可验证的。
本地开发(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 机器人。
快速上手
从裸机服务器到第一条转化的九个步骤:安装、首次登录、域名、联盟与 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 密钥安全。
阅读教程 →