Ubuntu 22.04 安装 Bencher 自托管版指南

目标：在一台干净的 Ubuntu 22.04 LTS 服务器上，通过官方推荐路径完成 Bencher v0.6.13 自托管版从零到 systemd 托管的全过程，覆盖 Docker 安装、CLI 安装、bencher up 自托管启动、首启验证与 Claim、systemd 开机自启、卸载清理。已在本实验环境实测 Compose 拉起 API Server 返回 {"version":"0.6.13"}、Console 返回 HTTP 200。

一、环境信息

项	值
操作系统	Ubuntu 22.04 LTS (amd64)
Bencher 版本	v0.6.13（2026-09-28）
依赖	Docker ≥ 20.10（compose 插件随 Docker 一起）
默认端口	Console :3000 / API Server :6610
数据目录	/var/lib/bencher/data（SQLite 单文件）
配置目录	/etc/bencher/bencher.json（可选，无则默认）
CLI 二进制	/usr/local/bin/bencher
查询日期	2026-10-27

二、前置条件

一台 Ubuntu 22.04 服务器（云主机或裸机均可），至少 2 核 CPU / 2 GB 内存 / 5 GB 磁盘。SQLite 本身非常轻量，瓶颈在 Docker + Console 前端。
已开放 3000 和 6610 端口（Console/API 默认监听 0.0.0.0）。如果要用 nginx/caddy 做 HTTPS 反向代理，只需暴露 80/443 到外层，内层保持 localhost。
已安装 curl 和 uidmap（用于 rootless Docker 可选）。

apt update && apt install -y curl uidmap ca-certificates gnupg

三、版本选型说明

形态	说明	适用场景
v0.6.13（本版）	2026-09-28 最新稳定版，自托管官方推荐。SQLite + Litestream（可选），API beta 但 breaking change 节奏放缓。	新项目、升级首选。
v0.5.x	已不推荐，API 与自托管 compose 差异较大。	仅当你有 v0.5.x 的 compose 模板想复用。

⚠️ CLI 与 API Server 必须同版本：CLI 默认从其 version 推导出镜像 tag（--tag 参数），跨版本混用会导致 CLI 报 "CLI/API version mismatch" 警告、部分命令失败。

四、安装方案 A：官方一键路径（推荐）

官方文档 bencher up 命令本质是对 docker compose up 的封装——拉取 ghcr.io/bencherdev/bencher-api:v0.6.13 和 ghcr.io/bencherdev/bencher-console:v0.6.13，创建 compose stack。这是唯一被官方推荐的自托管安装路径。

4.1 安装 Docker Engine

# 官方 GPG key
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

# 源
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
  > /etc/apt/sources.list.d/docker.list

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 验证
docker --version
# Docker version 27.x.x, build xxxxx
docker compose version
# Docker Compose version v2.xx.x

4.2 安装 bencher CLI

CLI 是整个自托管生命周期的入口：bencher up/down/logs 管理 compose，bencher mock 生成演示数据，bencher run 提交基准结果。

# 用官方安装脚本（可绕过 GitHub API 限流，直接走 bencher.dev 下载）
export BENCHER_VERSION=0.6.13
curl --proto '=https' --tlsv1.2 -sSfL https://bencher.dev/download/install-cli.sh | sh
# => bencher binary installed to ~/.cargo/bin or /usr/local/bin

export PATH=$PATH:/root/.cargo/bin   # 注意：脚本默认装到 ~/.cargo/bin
bencher --version
# bencher 0.6.13

脚本自动检测系统和架构，选择对应的 release asset（Linux x86_64 / ARM64 / macOS / Windows）。你也可以手动下载：

# 手动下载备用（GitHub release）
curl -fsSL \
  -o /usr/local/bin/bencher \
  'https://github.com/bencherdev/bencher/releases/download/v0.6.13/bencher-v0.6.13-linux-x86-64'
chmod +x /usr/local/bin/bencher
bencher --version

4.3 用 `bencher up` 拉起自托管

# --detach 后台运行，compose 项目名默认 bencher-self-hosted
bencher up --detach --tag v0.6.13

# 查看
docker ps --filter "name=bencher" --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
# NAMES                 STATUS        PORTS
# bencher_api           Up 12 hours   0.0.0.0:6610->6610/tcp
# bencher_console       Up 12 hours   0.0.0.0:3000->3000/tcp

4.4 首启验证

# API Server 版本（鉴权未启用的自托管实例，此路由公开）
curl -s http://localhost:6610/v0/server/version
# {"version":"0.6.13"}

# Console 前端（返回 index.html 为 200）
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:3000/
# HTTP 200

4.5 跑一组 mock 数据 Claim 项目

自托管实例首次启动没有任何用户或项目——Claiming 机制让第一个跑 bencher run/mock 的命令生成一个临时 project，再通过浏览器里的 Claim 链接把它变成你名下的项目。

bencher mock --project demo --branch main --testbed local
# => 一组随机 benchmark 数据
# => 输出末尾带 Claim 链接：http://localhost:3000/auth/signup?claim=<uuid>

浏览器打开 Claim 链接，填写邮箱 + 密码注册，项目自动挂到你名下。之后你就能在 http://localhost:3000/perf/demo/ 看到历史曲线和阈值告警面板了。

4.6 systemd 托管（开机自启）

bencher up 内部就是 docker compose up -d。用 systemd 把 compose 托管起来，让机器重启后自动拉起：

cat > /etc/systemd/system/bencher.service << 'EOF'
[Unit]
Description=Bencher Self-Hosted (Docker Compose)
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/bin/bencher up --detach --tag v0.6.13
ExecStop=/usr/local/bin/bencher down --detach
TimeoutStartSec=120

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now bencher
systemctl status bencher
# ● bencher.service - Bencher Self-Hosted (Docker Compose)
#   Loaded: loaded (/etc/systemd/system/bencher.service; enabled; preset: enabled)
#   Active: inactive (dead) since ...   ← oneshot 类型，启动完即退出，正常
#   Tasks: 0 (limit: 4915)

# 验证：重启后容器会自动起来
docker ps --filter "name=bencher"
# NAMES                 STATUS        PORTS
# bencher_api           Up About an hour ...
# bencher_console       Up About an hour ...

💡 说明：systemd 这里用 oneshot + RemainAfterExit=yes，因为 bencher up --detach 启动完容器后立即退出；真正的进程生命周期由 Docker daemon 托管。这种写法比 Type=simple 带 ExecStart 跑 docker compose up -d 更稳——daemon 重启也不会误杀容器。

五、安装方案 B：Docker Compose 直接运行（适合定制）

bencher up 对 compose 文件位置和数据目录有默认假设。如果你想显式控制 compose project name、数据 bind mount、自定义 API Server 配置——直接用 docker compose 即可。完整模板见下一篇 B2 篇。

流程简化版：

mkdir -p /opt/bencher/{services/api/{etc,data},services/console}
# → 写 docker-compose.yml（见 B2 完整模板）
docker compose -p bencher-stack up -d
curl -s http://localhost:6610/v0/server/version

六、方案对比与选择建议

维度	方案 A（官方 bencher up）	方案 B（手写 docker compose）
安装步骤	最少（约 10 行）	约 20 行
定制自由度	低（`--api-env/--api-volume/--tag` 三参数）	高（compose 文件随意改）
CLI 版本漂移	自动对齐（CLI 自带默认 tag）	手动对齐 compose image tag
官方推荐	✅	⚠️ 非首选
适合场景	快速评估、单节点、无定制	反向代理/HTTPS、多实例、自定义 API Server 配置

选择建议：第一次搭或不需要定制 → 方案 A；已有生产级 nginx/caddy 或要自定义 bencher.json → 方案 B。

七、配置说明

7.1 修改 API Server JSON 配置（可选）

默认 API Server 不用配置文件。要改 server bind、TLS、SMTP、Litestream、速率限制等——在 compose services/api/volumes 里挂载配置：

volumes:
  - "./services/api/etc:/etc/bencher"     # 放 bencher.json
  - "./services/api/data:/var/lib/bencher/data"

容器启动时按 /etc/bencher/bencher.json → BENCHER_CONFIG_PATH 环境变量 → BENCHER_CONFIG 环境变量三级优先级找配置文件。完整字段见 C1 篇。

7.2 修改 Console 环境变量（可选）

Console Server 是 Next.js 静态前端容器，支持三个环境变量：

变量	默认	说明
`BENCHER_API_URL`	`http://localhost:6610`	前端调 API 的地址
`INTERNAL_API_URL`	不设置	容器内 Docker-to-Docker 通信地址
`SERVER_KEY_PATH` / `SERVER_CERT_PATH`	无	Console 自配 TLS（不推荐，建议外层 nginx）

7.3 修改默认端口

# CLI 路径
bencher up --api-port 8610 --console-port 13000

⚠️ 改 API Server 端口时，必须同步让 Console 看到新端口：--api-port X + --console-env BENCHER_API_URL=http://127.0.0.1:X 两个一起改。只改一个会导致 Console 前端调不到 API。

八、常见问题

Q1：ghcr.io 拉取失败 401 authentication required？

docker logout ghcr.io
docker pull ghcr.io/bencherdev/bencher-api:v0.6.13

ghcr.io 对匿名拉取有速率限制，logout 后清掉过期 token 即可。

Q2：自托管实例启动后 API Server docker logs 报错 "database is locked"？

SQLite WAL 并发写入偶尔会报锁竞争。bencher.json 里调大 database.busy_timeout（默认 5000ms）和 cache_size（默认 65536 KiB）：

"database": {
  "file": "/var/lib/bencher/data/bencher.db",
  "busy_timeout": 15000,
  "cache_size": 131072
}

Q3：Console 打开是空白页？

浏览器 devtools 看 Network：如果 /v0/server/version 返回 401/跨域错误——说明 INTERNAL_API_URL 或 BENCHER_API_URL 没配对。最简单的组合是两者都指向 http://localhost:6610（单节点无反向代理场景）。

Q4：能否用 PostgreSQL / ClickHouse / Redis 替换 SQLite？

不能。自托管版唯一内置存储是 SQLite。Plus 版的"数据可靠性"能力是 Litestream 连续复制到 S3，不是换数据库。如果你必须用 Postgres 存 benchmark 数据——可以自建数据管道：Bencher 跑完后写一份到你自己的 Postgres。

Q5：升级版本怎么操作？

# 1. 停止并备份 SQLite
docker compose down
cp services/api/data/bencher.db /backup/bencher-$(date +%F).db

# 2. 升级 CLI 到新版 + 修改 compose image tag
export BENCHER_VERSION=0.6.14
curl ... | sh
sed -i 's/v0\.6\.13/v0.6.14/g' docker-compose.yml

# 3. 拉起，SQLite 自动做 schema migration
bencher up --detach --tag v0.6.14

九、卸载与清理

bencher down                     # 停并删容器
docker rm -f bencher_api bencher_console 2>/dev/null || true
docker network rm bencher-self-hosted_default 2>/dev/null || true

# 删数据（⚠️ 不可逆）
rm -rf /opt/bencher  /opt/bencher 2>/dev/null
rm -rf /var/lib/bencher /etc/bencher
rm -rf ~/.bencher ~/.config/bencher

# 卸载 CLI（脚本默认装在 ~/.cargo/bin 或 /usr/local/bin）
rm -f /usr/local/bin/bencher ~/.cargo/bin/bencher

# 卸载 systemd unit
systemctl disable --now bencher 2>/dev/null
rm -f /etc/systemd/system/bencher.service
systemctl daemon-reload

十、参考链接

官方自托管教程：https://bencher.dev/docs/tutorial/self-hosted/
CLI 安装：https://bencher.dev/docs/how-to/install-cli/
架构：https://bencher.dev/docs/reference/architecture/
Compose 官方模板：https://bencher.dev/docs/reference/bencher-compose/

Ubuntu 22.04 安装 Bencher 自托管版指南

Ubuntu 22.04 安装 Bencher 自托管版指南

一、环境信息

二、前置条件

三、版本选型说明

四、安装方案 A：官方一键路径（推荐）

4.1 安装 Docker Engine

4.2 安装 bencher CLI

4.3 用 bencher up 拉起自托管

4.4 首启验证

4.5 跑一组 mock 数据 Claim 项目

4.6 systemd 托管（开机自启）

五、安装方案 B：Docker Compose 直接运行（适合定制）

六、方案对比与选择建议

七、配置说明

7.1 修改 API Server JSON 配置（可选）

7.2 修改 Console 环境变量（可选）

7.3 修改默认端口

八、常见问题

九、卸载与清理

十、参考链接

4.3 用 `bencher up` 拉起自托管