Skip to content

docs: leaner READMEs with a real run image #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BlueBirdBack merged 1 commit into from
Oct 11, 2026
Merged

docs: leaner READMEs with a real run image #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 33 additions & 106 deletions README.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,126 +2,71 @@

[简体中文](README.md)

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 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. When it finishes you get a score plus one verdict: **KEEP / MAYBE / AVOID / INCOMPLETE**.

<p align="center"><img src="assets/abs-to6427-3vcpu-keep.jpg" width="720" alt="A real ABS run: host info → per-metric results → final score and verdict"></p>

The image above is a real run: host details first, then the measured CPU/memory/disk/fsync numbers, then the final score and a `KEEP` verdict.

## Run

```bash
curl -fsSL https://askclaw.top/abs.sh | bash
```

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`.
Terminal output defaults to Chinese; a typical run finishes in about 3 minutes once dependencies are installed. ABS may install `sysbench`, `fio`, `python3`, and `curl` via `sudo`.

```bash
# English output
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --lang en

# Do not install missing tools
curl -fsSL https://askclaw.top/abs.sh | bash -s -- -n
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --lang en # English output
curl -fsSL https://askclaw.top/abs.sh | bash -s -- -n # don't install missing tools
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --quick # quick ~60s
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --full # full 5–8 min
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --json-file result.json
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --lang en --help # every option
```

> `curl | bash` executes downloaded code directly. To inspect the script first:
> `curl | bash` executes downloaded code. To inspect the script first:
>
> ```bash
> curl -fsSLo abs.sh https://askclaw.top/abs.sh
> less abs.sh
> bash abs.sh --lang en
> curl -fsSLo abs.sh https://askclaw.top/abs.sh && less abs.sh && bash abs.sh --lang en
> ```

## Reading the result

English mode keeps the stable machine codes:

```text
==================== ABS RESULT ====================
SCORE : FULL 1568 (local only; network reference 136)
VERDICT : MAYBE - disk component is weak (component score 306); weak durable-write/fsync
LOCAL : FULL 1568 (local only: cpu,mem,disk,fsync; network excluded)
NETWORK : SANITY 136 (Cloudflare HTTP; reference only, not in score)
====================================================
VERDICT : MAYBE - disk component is weak (component score 306)
```

- **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** = every core test ran (doesn't mean fast)
- **PARTIAL — not comparable** = some test failed; don't compare this score to other machines
- **Verdict** = decided by local score + a weakest-component floor: any component below 250 forces `AVOID`; below 500 caps at `MAYBE`

## What it measures
## What it measures & how it scores

- **CPU**: single-thread and all-thread throughput
- **Memory**: sequential read and write
- **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**
- **CPU** single-thread + all-thread throughput
- **Memory** sequential read + write
- **Disk** sequential, 4K random at QD1 (queue depth 1 — typical scattered small I/O), and multi-job pressure
- **fsync** durable 4K writes (what actually reaches disk, not just the memory cache)
- **Network** Cloudflare sanity (10 MB down, 5 MB up of zero data; **not scored**)

```text
score = 40% CPU + 15% memory + 30% 4K QD1 disk + 15% fsync
```

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.

Formulas, reference constants, applicability limits, and known caveats live in [docs/scoring.md](docs/scoring.md).

## Common commands

```bash
# Quick check, about 60 seconds
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 the network check (local score stays valid)
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --no-network

# Write the result to JSON
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --json-file result.json

# Broader network picture: Cloudflare + 3 public iperf3 regions
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --network-full
```

Every option: `bash abs.sh --lang en --help`
Formulas, reference constants, and known caveats live in [docs/scoring.md](docs/scoring.md).

## Comparing two VPSes
## Comparing two VPSes — hard requirements

Two scores are only directly comparable when **all** of these match:
Two scores are directly comparable **only when all of these match**: ABS version, profile, `-t` threads, `-z` fio size, and `DIRECT` (default `1` = bypass the filesystem cache and measure real disk; `0` = through the cache, inflates numbers). Both runs must be `FULL`.

- 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
## Behavior notes

## 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

## If dependency installation fails

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.

## What the network check does

The default is a Cloudflare sanity check only:

- 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`
- **Install fails**: prints a reason + repair hint + log path, then keeps going and produces `INCOMPLETE` instead of silently dying. On interactive terminals `sudo` attaches to `/dev/tty`, so `curl | bash` can still prompt for a password; headless runs use non-interactive sudo and fail fast. ABS never runs `dpkg --configure -a` on its own.
- **Files**: logs land in a private `/tmp/abs.*` dir; the fio test file lives in its own temp dir and is removed after; existing `abs.test*` and `abs-dd.test` files are **never** deleted.
- **No fio**: falls back to a rough `dd` check, not scored.
- **Alpine minimal**: install bash first — `apk add bash`.
- **Language**: terminal output defaults to Chinese, `--lang en` or `ABS_LANG=en` switches; `results.tsv` and `result.json` stay in English for scripts.

**When GitHub Raw is unreachable from China**, use the jsDelivr mirror:

Expand All @@ -130,24 +75,6 @@ curl --resolve cdn.jsdelivr.net:443:104.16.175.226 \
-fsSL https://cdn.jsdelivr.net/gh/getaskclaw/abs@main/abs.sh | bash -s -- -n
```

## Glossary

| 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` |

## Development

```bash
python3 -m unittest -v tests/test_abs.py
```

GitHub Actions runs the suite on every push and pull request.

## License

MIT
137 changes: 33 additions & 104 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,150 +2,79 @@

[English](README.en.md)

在租一台 Linux VPS（或续费）之前跑一下，就能知道这机器 CPU 快不快、内存够不够、磁盘写起来稳不稳。ABS 把这些测一遍，给一个分数和一个结论：**保留、谨慎保留、不建议保留**，或者**测试不完整**（某些测试没跑成，别拿这个分数下结论）。
租或续一台 Linux VPS 前跑一下，看 CPU 快不快、内存够不够、磁盘能不能真写。跑完给一个分数和一句结论：**保留 / 谨慎保留 / 不建议保留 / 测试不完整**。

<p align="center"><img src="assets/abs-to6427-3vcpu-keep.jpg" width="720" alt="ABS 实跑示例：主机信息 → 各分项指标 → 最终得分和结论"></p>

上图是一次真实跑分：先列机器配置，再逐项打印 CPU/内存/磁盘/fsync 数据，最后给出总分和「保留」结论。

## 跑一下

```bash
curl -fsSL https://askclaw.top/abs.sh | bash
```

默认输出中文，装完依赖后 3 分钟内出结果。脚本可能用 `sudo` 装 `sysbench`、`fio`、`python3`、`curl`。
默认输出中文，装完依赖后约 3 分钟出结果。脚本可能用 `sudo` 装 `sysbench`、`fio`、`python3`、`curl`。

```bash
# 不安装缺失工具
curl -fsSL https://askclaw.top/abs.sh | bash -s -- -n

# 英文输出
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --lang en
curl -fsSL https://askclaw.top/abs.sh | bash -s -- -n # 不安装缺失工具
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --lang en # 英文输出
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --quick # 快速版 ~60 秒
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --full # 完整版 5–8 分钟
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --json-file result.json
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --help # 全部选项
```

> `curl | bash` 会直接执行下载内容。想先看看脚本内容：
> `curl | bash` 直接执行下载内容。想先看脚本：
>
> ```bash
> curl -fsSLo abs.sh https://askclaw.top/abs.sh
> less abs.sh
> bash abs.sh
> curl -fsSLo abs.sh https://askclaw.top/abs.sh && less abs.sh && bash abs.sh
> ```

## 读结果

```text
===================== ABS 结果 =====================
得分：完整，得分 1568（仅本地；网络参考分 136）
结论：谨慎保留 — 磁盘性能偏弱
本地：完整，得分 1568（仅本地；网络不计分）
网络：参考分 136（Cloudflare HTTP，仅供参考，不计分）
====================================================
```

- **完整** = 所有核心测试都跑完了（不代表快）
- **不完整，不能比较** = 有测试没跑成，分数不能和其他机器直接比
- **保留 / 谨慎保留 / 不建议保留** = 按本地分数和一个“最弱分项”红线给出的建议
- **测试不完整** = CPU、内存、磁盘或 fsync 有缺项
- **完整** = 所有核心测试都跑完（不代表快）
- **不完整，不能比较** = 有测试没跑成，分数不能和其他机器比
- **结论** = 按本地分数 + 最弱分项红线给的：分项 <250 直接「不建议保留」，<500 最多「谨慎保留」

## 测了什么
## 测了什么、怎么算分

- **CPU**：单线程、全线程吞吐
- **内存**：顺序读写
- **磁盘**：顺序读写、4K 随机小 IO（QD1=队列深度 1，接近日常零散读写）、多线程压力
- **fsync**：4K 强制落盘写入（数据库/文件真正写完的指标，比“看起来写完了”更接近真实持久化）
- **网络**：Cloudflare 简单测速，仅供参考，**不计分**
- **CPU** 单线程 + 全线程吞吐
- **内存** 顺序读写
- **磁盘** 顺序读写、4K 随机小 IO（QD1=队列深度 1，接近日常零散读写）、多线程压力
- **fsync** 4K 强制落盘写入（真正写进磁盘的指标，不是只到内存缓存）
- **网络** Cloudflare 简测（下载 10 MB、上传 5 MB 全零数据；仅供参考，**不计分**）

```text
总分 = 40% CPU + 15% 内存 + 30% 4K QD1 磁盘 + 15% fsync
```

另外有一条底线规则：任一分项分数低于 250 直接「不建议保留」；低于 500 时最多只能到「谨慎保留」。也就是说，一个很弱的短板会拖累整体评价。

评分公式、参考常数、适用边界和已知局限见 [docs/scoring.md](docs/scoring.md)。

## 常用命令

```bash
# 快速检查，约 60 秒
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
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --json-file result.json

# 网络测试加强版：Cloudflare + 3 个公共 iperf3 节点
curl -fsSL https://askclaw.top/abs.sh | bash -s -- --network-full
```

全部选项：`bash abs.sh --help`

## 比较两台 VPS
公式细节、参考常数和已知局限见 [docs/scoring.md](docs/scoring.md)。

两台机器**只有在以下条件全部一致时，分数才能直接比**：
## 比较两台 VPS 的硬条件

- ABS 版本相同
- 用的测试模式相同（`--quick` / 默认 / `--full`）
- 线程数 `-t` 相同
- fio 测试文件大小 `-z` 相同
- `DIRECT` 设置相同——`DIRECT=1`（默认）跳过文件系统缓存，直接测磁盘；`DIRECT=0` 走缓存，结果会虚高且**不能和 DIRECT=1 的结果比**
- 两边都是「完整」结果；任意一边是「不完整，不能比较」就不要比
两台机器分数**只在以下条件全部一致时可直接比**：ABS 版本、测试模式、`-t` 线程数、`-z` 测试文件大小、`DIRECT` 设置（默认 `1`=跳过系统缓存测真磁盘；`0`=走缓存，数值虚高）。两边都必须是「完整」结果。

## 终端语言 vs. 机器输出
## 行为说明

- 终端显示默认中文，`--lang en` 或 `ABS_LANG=en` 切英文
- `results.tsv` 的指标名、`result.json` 的字段和值始终是英文，方便脚本读取
- 切语言不会改变分数和文件格式
- **依赖装失败**：打印原因 + 修复建议 + 日志路径，继续跑出「不完整」结果，不无声退出。交互式终端里 `sudo` 接 `/dev/tty`，`curl | bash` 也能输密码；无终端用非交互 sudo、失败就跳过。不会自动跑 `dpkg --configure -a`。
- **文件**：日志写 `/tmp/abs.*` 私有目录；磁盘测试文件用独立临时目录、跑完删掉；已有 `abs.test*`、`abs-dd.test` **不会**被删。
- **没有 fio** 时退用 `dd` 粗测，不计入总分。
- **Alpine 最小镜像**：先 `apk add bash`。
- **终端默认中文**，`--lang en` 或 `ABS_LANG=en` 切英文；`results.tsv` / `result.json` 始终英文，方便脚本读。

## 依赖安装失败怎么办

ABS 会打印一个简短原因、一条修复建议和日志路径，然后继续跑出一个「不完整」结果，而不是无声退出。在交互式终端里，它把 `sudo` 接到 `/dev/tty`，所以 `curl | bash` 也能正常输密码；无人值守环境用非交互 sudo、失败就跳过。ABS 不会自动执行 `dpkg --configure -a` 这种系统级修复命令。

## 网络检查做了什么

默认只做 Cloudflare 简测：

- 从 Cloudflare 下载 10 MB
- 上传 5 MB 全零数据（测速用，不传真实文件）
- 单次超时 45 秒，失败自动重试一次

想要更完整的网络画像，用 `--network-full` 或 `--network-yabs` 加公共 iperf3 节点。

## 安全和文件位置

- ABS **不会上传跑分结果**
- 日志写在 `/tmp/abs.*` 随机私有目录
- 磁盘测试文件放在一个单独的临时目录，跑完删掉
- 已存在的 `abs.test*`、`abs-dd.test` 文件**不会**被删除
- 没有 `fio` 时退而用 `dd` 粗略测一下，但**不计入总分**
- Alpine 最小镜像要先装 bash：`apk add bash`

**中国网络拉不到 GitHub Raw 时**，用 jsDelivr 镜像：
**国内拉不到 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
```

push 和 PR 都会触发 GitHub Actions 跑这套测试。

## License

MIT
Loading