From 9f67473fad516427c80122bc41a709a701f07565 Mon Sep 17 00:00:00 2001 From: Rac Date: Sun, 11 Oct 2026 19:12:05 +0800 Subject: [PATCH] docs: rewrite READMEs for zero-background readers Apply the blank-reader-30s-test: lead with who it's for and what it does, expand fsync/QD1/DIRECT/p95/OpenVZ on first use, add a dedicated comparability section, surface the jsDelivr note with context, add a glossary table. --- README.en.md | 110 +++++++++++++++++++++++++++++++------------------ README.md | 114 +++++++++++++++++++++++++++++---------------------- 2 files changed, 135 insertions(+), 89 deletions(-) diff --git a/README.en.md b/README.en.md index ef2ba11..2680b1a 100644 --- a/README.en.md +++ b/README.en.md @@ -2,7 +2,7 @@ [简体中文](README.md) -ABS benchmarks CPU, memory, disk, and fsync on a Linux VPS, then gives one simple verdict: **keep, keep with caution, avoid, or incomplete**. +Run it on a Linux VPS before you rent or renew — it tells you whether the CPU is fast, the memory is adequate, and the disk can actually write. ABS measures all of that, produces a score, and gives one verdict: **KEEP**, **MAYBE**, **AVOID**, or **INCOMPLETE** (some test didn't run, so don't judge by that score). ## Run @@ -10,7 +10,7 @@ ABS benchmarks CPU, memory, disk, and fsync on a Linux VPS, then gives one simpl curl -fsSL https://askclaw.top/abs.sh | bash ``` -Terminal output is Chinese by default. A normal run usually finishes within three minutes after dependencies are installed. ABS may install `sysbench`, `fio`, `python3`, and `curl`. +Terminal output defaults to Chinese. A typical run finishes within three minutes after dependencies are installed. ABS may install `sysbench`, `fio`, `python3`, and `curl` via `sudo`. ```bash # English output @@ -20,7 +20,7 @@ curl -fsSL https://askclaw.top/abs.sh | bash -s -- --lang en curl -fsSL https://askclaw.top/abs.sh | bash -s -- -n ``` -> `curl | bash` executes downloaded code directly. To inspect it first: +> `curl | bash` executes downloaded code directly. To inspect the script first: > > ```bash > curl -fsSLo abs.sh https://askclaw.top/abs.sh @@ -28,9 +28,9 @@ curl -fsSL https://askclaw.top/abs.sh | bash -s -- -n > bash abs.sh --lang en > ``` -## Result +## Reading the result -English mode keeps the stable result codes: +English mode keeps the stable machine codes: ```text ==================== ABS RESULT ==================== @@ -41,30 +41,26 @@ NETWORK : SANITY 136 (Cloudflare HTTP; reference only, not in score) ==================================================== ``` -- **KEEP**: local performance is healthy -- **MAYBE**: usable, but has a clear weakness -- **AVOID**: weak local performance or a critical bottleneck -- **INCOMPLETE**: CPU, memory, disk, or fsync data is missing +- **FULL** = every core test ran (does not mean fast) +- **PARTIAL - not comparable** = some tests failed; don't compare this score to other machines +- **KEEP / MAYBE / AVOID** = the recommendation, based on the local score plus a weakest-component floor +- **INCOMPLETE** = CPU, memory, disk, or fsync data is missing -`FULL` means all core tests completed; it does not mean the VPS is fast. Do not compare a `PARTIAL - not comparable` result with a full result. - -## Tests and score +## What it measures - **CPU**: single-thread and all-thread throughput - **Memory**: sequential read and write -- **Disk**: sequential, 4K QD1, and pressure tests -- **fsync**: durable 4K writes -- **Network**: a short Cloudflare reference check +- **Disk**: sequential, 4K random at QD1 (queue depth 1 — close to typical scattered small I/O), and multi-job pressure +- **fsync**: durable 4K writes — what actually reaches persistent storage, not what merely looks written +- **Network**: a short Cloudflare reference check, **never counted in the score** ```text -40% CPU + 15% memory + 30% 4K QD1 disk + 15% fsync +score = 40% CPU + 15% memory + 30% 4K QD1 disk + 15% fsync ``` -Network never changes the headline score. ABS also applies a component floor: below 250 forces `AVOID`; below 500 prevents `KEEP`. - -Compare results only when ABS version, profile, thread count, fio size, and `DIRECT` setting match. Only a full local result with `DIRECT=1` is directly comparable. +There's also a floor rule: any component score below 250 forces `AVOID`; below 500 caps the verdict at `MAYBE`. One bad weak spot drags the whole result. -Scoring formulas, reference constants, applicability limits, and calibration caveats are documented in [docs/scoring.md](docs/scoring.md). +Formulas, reference constants, applicability limits, and known caveats live in [docs/scoring.md](docs/scoring.md). ## Common commands @@ -75,40 +71,76 @@ curl -fsSL https://askclaw.top/abs.sh | bash -s -- --quick # Full test, about 5–8 minutes curl -fsSL https://askclaw.top/abs.sh | bash -s -- --full -# Skip network; the local score remains valid +# Skip the network check (local score stays valid) curl -fsSL https://askclaw.top/abs.sh | bash -s -- --no-network -# Save JSON +# Write the result to JSON curl -fsSL https://askclaw.top/abs.sh | bash -s -- --json-file result.json -# Cloudflare plus three public iperf3 regions +# Broader network picture: Cloudflare + 3 public iperf3 regions curl -fsSL https://askclaw.top/abs.sh | bash -s -- --network-full ``` -Run `bash abs.sh --lang en --help` for every option. +Every option: `bash abs.sh --lang en --help` + +## Comparing two VPSes + +Two scores are only directly comparable when **all** of these match: + +- Same ABS version +- Same profile (`--quick` / default / `--full`) +- Same thread count (`-t`) +- Same fio test size (`-z`) +- Same `DIRECT` setting — `DIRECT=1` (default) bypasses the filesystem cache and measures the real disk; `DIRECT=0` goes through the cache, inflates numbers, and **cannot be compared against DIRECT=1** +- Both runs are `FULL`; if either is `PARTIAL`, don't compare + +## Terminal language vs. machine output + +- Terminal display defaults to Chinese; use `--lang en` or `ABS_LANG=en` for English +- `results.tsv` metric names and `result.json` fields and values stay in English for scripting +- Switching language never changes the score or the file formats -## Language and machine output +## If dependency installation fails -- Terminal output defaults to Chinese; use `--lang en` or `ABS_LANG=en` for English -- `results.tsv` metric names and `result.json` fields and values remain stable English -- Language selection does not change scoring or machine output +ABS prints a short reason, a repair hint when known, and the log path, then keeps going and produces an `INCOMPLETE` result instead of silently dying. On an interactive terminal it attaches `sudo` to `/dev/tty`, so `curl | bash` can still prompt for a password; headless runs use non-interactive sudo and fail fast. ABS does not run system-repair commands such as `dpkg --configure -a` on its own. -## Installation and network behavior +## What the network check does -If dependency installation fails, ABS prints a short cause, a repair hint when known, and the log path, then continues with an incomplete result. In an interactive terminal, ABS attaches `sudo` to `/dev/tty`, so `curl | bash` can still prompt for the sudo password; headless runs use non-interactive sudo and fail quickly. ABS does not run system repair commands such as `dpkg --configure -a` automatically. +The default is a Cloudflare sanity check only: -The default Cloudflare check downloads 10 MB and uploads 5 MB of zero data. Each attempt has a 45-second timeout and one retry. Use `--network-full` or `--network-yabs` for broader network checks. +- Downloads 10 MB from Cloudflare +- Uploads 5 MB of all-zero data (synthetic, not a real file) +- 45-second timeout per attempt, one automatic retry + +For a broader network picture, use `--network-full` or `--network-yabs` to add public iperf3 nodes. + +## Safety and file locations + +- ABS **never uploads results** +- Logs live in a private random `/tmp/abs.*` directory +- Disk test files go to a separate temporary directory and are removed afterward +- Pre-existing `abs.test*` and `abs-dd.test` files are **not** deleted +- If `fio` is missing, a rough `dd` check runs as a fallback but **is not scored** +- Minimal Alpine images need bash first: `apk add bash` + +**When GitHub Raw is unreachable from China**, use the jsDelivr mirror: + +```bash +curl --resolve cdn.jsdelivr.net:443:104.16.175.226 \ + -fsSL https://cdn.jsdelivr.net/gh/getaskclaw/abs@main/abs.sh | bash -s -- -n +``` -## Safety and files +## Glossary -- ABS uploads no benchmark result -- Logs use a private random `/tmp/abs.*` directory -- Disk test files use a separate temporary directory and are removed afterward -- Existing `abs.test*` and `abs-dd.test` files are preserved -- A `dd` fallback may run when fio is missing, but it is not scored -- Minimal Alpine systems need Bash first: `apk add bash` +| Term | Plain meaning | +|---|---| +| `fsync` | Forces data to actually hit the disk, not just the memory cache. It's what a database commit or file save really needs | +| `QD1` | Queue depth 1 — one I/O request at a time, matching typical scattered small reads/writes | +| `p95` | 95th-percentile latency — 95% of requests finish faster than this; shows the worst-tail speed | +| `DIRECT` | fio's direct mode: 1 = bypass OS cache and measure real disk; 0 = through the cache (numbers get inflated) | +| `OpenVZ` | A virtualization type; its disk numbers can be cache-inflated, verify with `--full` | -## Tests +## Development ```bash python3 -m unittest -v tests/test_abs.py diff --git a/README.md b/README.md index d33cf0c..0f74d2a 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,15 @@ [English](README.en.md) -ABS 测试 Linux VPS 的 CPU、内存、磁盘和 fsync，并给出一个简单结论：**保留、谨慎保留、不建议保留或测试不完整**。 +在租一台 Linux VPS（或续费）之前跑一下，就能知道这机器 CPU 快不快、内存够不够、磁盘写起来稳不稳。ABS 把这些测一遍，给一个分数和一个结论：**保留、谨慎保留、不建议保留**，或者**测试不完整**（某些测试没跑成，别拿这个分数下结论）。 -## 运行 +## 跑一下 ```bash curl -fsSL https://askclaw.top/abs.sh | bash ``` -默认输出中文，通常在安装依赖后 3 分钟内完成。脚本可能安装 `sysbench`、`fio`、`python3` 和 `curl`。 +默认输出中文，装完依赖后 3 分钟内出结果。脚本可能用 `sudo` 装 `sysbench`、`fio`、`python3`、`curl`。 ```bash # 不安装缺失工具 @@ -20,7 +20,7 @@ curl -fsSL https://askclaw.top/abs.sh | bash -s -- -n curl -fsSL https://askclaw.top/abs.sh | bash -s -- --lang en ``` -> `curl | bash` 会直接执行下载内容。需要先检查时： +> `curl | bash` 会直接执行下载内容。想先看看脚本内容： > > ```bash > curl -fsSLo abs.sh https://askclaw.top/abs.sh @@ -28,7 +28,7 @@ curl -fsSL https://askclaw.top/abs.sh | bash -s -- --lang en > bash abs.sh > ``` -## 结果 +## 读结果 ```text ===================== ABS 结果 ===================== @@ -39,30 +39,26 @@ curl -fsSL https://askclaw.top/abs.sh | bash -s -- --lang en ==================================================== ``` -- **保留**：本地性能整体良好 -- **谨慎保留**：可以使用，但有明显短板 -- **不建议保留**：本地性能较弱或存在严重瓶颈 -- **测试不完整**：CPU、内存、磁盘或 fsync 测试缺失 +- **完整** = 所有核心测试都跑完了（不代表快） +- **不完整，不能比较** = 有测试没跑成，分数不能和其他机器直接比 +- **保留 / 谨慎保留 / 不建议保留** = 按本地分数和一个“最弱分项”红线给出的建议 +- **测试不完整** = CPU、内存、磁盘或 fsync 有缺项 -`完整` 只表示核心测试全部完成，不表示机器一定很快。`不完整，不能比较` 不应与完整结果直接比较。 +## 测了什么 -## 测试内容和评分 - -- **CPU**：单线程和全线程吞吐 -- **内存**：顺序读取和写入 -- **磁盘**：顺序读写、4K QD1 和压力测试 -- **fsync**：4K 持久化写入 -- **网络**：Cloudflare 简测，仅供参考 +- **CPU**：单线程、全线程吞吐 +- **内存**：顺序读写 +- **磁盘**：顺序读写、4K 随机小 IO（QD1=队列深度 1，接近日常零散读写）、多线程压力 +- **fsync**：4K 强制落盘写入（数据库/文件真正写完的指标，比“看起来写完了”更接近真实持久化） +- **网络**：Cloudflare 简单测速，仅供参考，**不计分** ```text -40% CPU + 15% 内存 + 30% 4K QD1 磁盘 + 15% fsync +总分 = 40% CPU + 15% 内存 + 30% 4K QD1 磁盘 + 15% fsync ``` -网络不计入总分。ABS 还检查最弱分项：分项低于 250 时“不建议保留”，低于 500 时最多“谨慎保留”。 - -比较机器时，应使用相同的 ABS 版本、测试模式、线程数、fio 大小和 `DIRECT` 设置。只有 `DIRECT=1` 的完整本地结果可直接比较。 +另外有一条底线规则：任一分项分数低于 250 直接「不建议保留」；低于 500 时最多只能到「谨慎保留」。也就是说，一个很弱的短板会拖累整体评价。 -评分公式、参考常数、适用边界和校准局限见 [docs/scoring.md](docs/scoring.md)。 +评分公式、参考常数、适用边界和已知局限见 [docs/scoring.md](docs/scoring.md)。 ## 常用命令 @@ -73,64 +69,82 @@ curl -fsSL https://askclaw.top/abs.sh | bash -s -- --quick # 完整测试，约 5–8 分钟 curl -fsSL https://askclaw.top/abs.sh | bash -s -- --full -# 跳过网络；本地得分仍有效 +# 跳过网络测速（本地分数仍有效） curl -fsSL https://askclaw.top/abs.sh | bash -s -- --no-network -# 保存 JSON +# 结果存成 JSON curl -fsSL https://askclaw.top/abs.sh | bash -s -- --json-file result.json -# Cloudflare + 3 个公共 iperf3 区域 +# 网络测试加强版：Cloudflare + 3 个公共 iperf3 节点 curl -fsSL https://askclaw.top/abs.sh | bash -s -- --network-full ``` -完整选项见： +全部选项：`bash abs.sh --help` -```bash -bash abs.sh --help -``` +## 比较两台 VPS + +两台机器**只有在以下条件全部一致时，分数才能直接比**： -## 语言和机器输出 +- ABS 版本相同 +- 用的测试模式相同（`--quick` / 默认 / `--full`） +- 线程数 `-t` 相同 +- fio 测试文件大小 `-z` 相同 +- `DIRECT` 设置相同——`DIRECT=1`（默认）跳过文件系统缓存，直接测磁盘；`DIRECT=0` 走缓存，结果会虚高且**不能和 DIRECT=1 的结果比** +- 两边都是「完整」结果；任意一边是「不完整，不能比较」就不要比 -- 终端默认中文；使用 `--lang en` 或 `ABS_LANG=en` 切换英文 -- `results.tsv` 的指标名、`result.json` 的字段和值保持英文，便于程序读取 -- 切换终端语言不会改变评分或机器输出格式 +## 终端语言 vs. 机器输出 -## 安装和网络 +- 终端显示默认中文，`--lang en` 或 `ABS_LANG=en` 切英文 +- `results.tsv` 的指标名、`result.json` 的字段和值始终是英文，方便脚本读取 +- 切语言不会改变分数和文件格式 -依赖安装失败时，ABS 会显示简短原因、修复提示和日志路径，然后继续生成不完整结果。交互式终端中，ABS 会把 `sudo` 连接到 `/dev/tty`，因此 `curl | bash` 也可以正常询问 sudo 密码；无终端运行则使用非交互 sudo 并快速失败。ABS 不会自行运行 `dpkg --configure -a` 等系统修复命令。 +## 依赖安装失败怎么办 -默认网络简测： +ABS 会打印一个简短原因、一条修复建议和日志路径，然后继续跑出一个「不完整」结果，而不是无声退出。在交互式终端里，它把 `sudo` 接到 `/dev/tty`，所以 `curl | bash` 也能正常输密码；无人值守环境用非交互 sudo、失败就跳过。ABS 不会自动执行 `dpkg --configure -a` 这种系统级修复命令。 + +## 网络检查做了什么 + +默认只做 Cloudflare 简测： - 从 Cloudflare 下载 10 MB -- 上传 5 MB 零数据 -- 单次超时 45 秒 -- 失败后重试一次 +- 上传 5 MB 全零数据（测速用，不传真实文件） +- 单次超时 45 秒，失败自动重试一次 -更完整的网络测试使用 `--network-full` 或 `--network-yabs`。 +想要更完整的网络画像，用 `--network-full` 或 `--network-yabs` 加公共 iperf3 节点。 -## 安全和文件 +## 安全和文件位置 -- ABS 不上传跑分结果 -- 日志保存在私有随机目录 `/tmp/abs.*` -- 磁盘测试文件放在独立临时目录，结束后删除 -- 原有 `abs.test*` 和 `abs-dd.test` 文件不会被删除 -- `fio` 缺失时使用 `dd` 粗略检查，但不计分 -- Alpine 最小系统需要先安装 Bash：`apk add bash` +- ABS **不会上传跑分结果** +- 日志写在 `/tmp/abs.*` 随机私有目录 +- 磁盘测试文件放在一个单独的临时目录，跑完删掉 +- 已存在的 `abs.test*`、`abs-dd.test` 文件**不会**被删除 +- 没有 `fio` 时退而用 `dd` 粗略测一下，但**不计入总分** +- Alpine 最小镜像要先装 bash：`apk add bash` -中国网络无法访问 GitHub Raw 时： +**中国网络拉不到 GitHub Raw 时**，用 jsDelivr 镜像： ```bash curl --resolve cdn.jsdelivr.net:443:104.16.175.226 \ -fsSL https://cdn.jsdelivr.net/gh/getaskclaw/abs@main/abs.sh | bash -s -- -n ``` -## 开发测试 +## 术语速查 + +| 词 | 通俗意思 | +|---|---| +| `fsync` | 强制把数据真正写入磁盘（不是只写到内存缓存）。数据库、文件保存靠它才算写完 | +| `QD1` | 队列深度 1：一次只发一个 IO 请求，接近日常零散小读写 | +| `p95` | 95 分位延迟：95% 的请求比这个数快，反映“最坏那一批”的速度 | +| `DIRECT` | fio 的直连模式：1=跳过系统缓存测真实磁盘，0=走缓存（数值会虚高） | +| `OpenVZ` | 一种虚拟化方式；它的磁盘结果可能被缓存影响，建议再用 `--full` 验证 | + +## 开发 ```bash python3 -m unittest -v tests/test_abs.py ``` -GitHub Actions 会在 push 和 pull request 时运行测试。 +push 和 PR 都会触发 GitHub Actions 跑这套测试。 ## License