安装 | Pingclair

Pingclair 以单个 Linux 二进制形式发布。本页完成安装，说明安装器留下了什么，并验证服务器能响应。当前版本是 v0.2.0-rc.3，属于 release candidate，本网站的每一页描述的都是这个版本。

🧾 需要什么

一台 x86_64 或 aarch64 的 Linux 主机，两种架构都有发布版二进制。
sudo 或 root：安装器会写入 /usr/local/bin、/etc/Pingclair、 /var/lib/pingclair 和 /etc/systemd/system。
走服务方式需要 systemd。没有 systemd 的主机请用 Docker 或前台运行，两者下面都会讲到。
如果要签发公共证书，80 和 443 端口要能从公网访问（HTTPS）。在云主机上，通常还要在服务商的防火墙里一并放行。

macOS 的源码构建只用于开发支持。macOS 不是发布平台。

📦 从发布版二进制安装

curl -fsSL https://pingclair.com/install.sh | sudo bash

脚本先读 releases.pingclair.com 上的发版通道，打印将要安装的 tag，再用通道为该压缩包公布的 SHA-256 校验——对不上就拒绝，不解压。该主机不通时会退回 GitHub 的 release API 与压缩包旁边发布的校验和文件，因此安装不依赖单一提供方。随后它创建服务用户、授予绑定低端口的能力、写入默认配置、安装 unit，并启动服务。完整的一轮会这样结束：

Detected architecture: x86_64
Installing v0.2.0-rc.3 — a release candidate, not a final release.
Downloading https://releases.pingclair.com/pingclair/releases/0.2.0-rc.3/pingclair-linux-x86_64.tar.gz (from releases.pingclair.com)...
✅ sha256 matches the release channel document
Creating system user 'pingclair'...
Setting capabilities...
Configuring directories and assets...
Fetching default landing page...
Creating default Pingclairfile...
Installing Systemd service...
Creating 'pc' symlink...
✅ Installation Complete!
Use pc service status to check the service.
Config: /etc/Pingclair/Pingclairfile

需要尚未发布的修复时，可以安装 main 而不是发布版二进制：

curl -fsSL https://pingclair.com/install.sh | sudo bash -s -- --main

--main 会在主机上克隆并编译。它需要 Rust 1.98 或更新版本，以及 BoringSSL 与 jemalloc 所需的 C 工具链：cmake、clang、libclang-dev、g++ 和 git。在 apt 和 dnf 系统上，这些包都由脚本自行安装。因为 BoringSSL 要从源码编译，首次构建需要几分钟。

🗂️ 安装器留下了什么

路径	内容
`/usr/local/bin/pingclair`	服务器二进制。
`/usr/local/bin/pc`	指向同一二进制的软链接，用于短命令。
`/etc/Pingclair/Pingclairfile`	服务实际运行的配置。
`/etc/Pingclair/Pingclairfile.example`	带注释的示例，升级时不会被覆盖。
`/var/lib/pingclair/.local/share/pingclair`	证书存储：服务账号的数据目录，二进制的默认位置。
`/var/lib/pingclair/html`	在 80 端口提供的占位站点。
`/var/log/pingclair`	配置了 `log` 之后日志写入的位置。
`/etc/systemd/system/pingclair.service`	已启用并正在运行的 unit。

脚本结束时服务已经在提供服务。它运行的配置就是这份占位配置，一屏就能读完：

# 🦀 Pingclair default configuration file
# Management commands: pc service <start|stop|reload|status>

:80 {
    # Welcome page
    file_server /var/lib/pingclair/html
}

服务用户和证书存储只在缺失时创建，已存在的 /etc/Pingclair/Pingclairfile 永远不会被替换。正因如此，重复运行安装器是升级而不是重置（升级与卸载）。

✅ 验证安装

先问二进制自己的版本：

pingclair version

v0.2.0-rc.3

pc 是同一个二进制，所以 pc version 输出同样的字符串。再问 systemd：

pc service status

● pingclair.service - Pingclair High-Performance Web Server
     Loaded: loaded (/etc/systemd/system/pingclair.service; enabled; preset: enabled)
     Active: active (running) since Tue 2026-09-22 03:21:55 UTC; 42s ago
       Docs: https://github.com/dorianverlaine/pingclair
   Main PID: 1808 (pingclair)
     Status: "Serving"
      Tasks: 12 (limit: 627)
     Memory: 8.2M (peak: 8.5M)

Status: "Serving" 不是 systemd 看到进程还活着而猜出来的，而是服务器自己上报的：unit 的类型是 notify，只有所有监听器都绑定完成之后，服务器才宣告就绪。

最后问服务器本身：

curl -i http://localhost/

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 18747
Last-Modified: Tue, 22 Sep 2026 03:21:54 GMT
ETag: "493b-6ab1f452"
Vary: Accept-Encoding
Accept-Ranges: bytes
server: Pingclair

带 ETag 和 Last-Modified 的 200 说明文件服务器应答了，正文就是 /var/lib/pingclair/html 里的占位页面。

🐳 Docker

已发布的镜像以配置文件模式运行：entrypoint 是 pingclair，默认命令是 run /etc/pingclair/Pingclairfile。镜像把 /etc/pingclair 和 /var/lib/pingclair 声明为卷，并暴露 80 和 443 端口。

services:
  pingclair:
    image: ghcr.io/dorianverlaine/pingclair:v0.2.0-rc.3
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp" # HTTP/3
    volumes:
      - ./conf:/etc/pingclair:ro
      - ./site:/srv:ro
      - pingclair_tls:/var/lib/pingclair

volumes:
  pingclair_tls:

mkdir -p conf site
printf ':80 {\n    file_server /srv\n}\n' > conf/Pingclairfile
echo '<h1>hello from the container</h1>' > site/index.html
docker compose up -d
curl -i http://localhost/

有三个容易搞错的地方：

不要加 command:。 镜像默认值已经是 run /etc/pingclair/Pingclairfile，覆盖它会替换掉那条命令。
不要只挂 /var/lib/pingclair/.local/share/pingclair。 存储除了证书目录之外还保存其他状态，容器只挂 certs 重建时会丢掉这些状态。请挂 /var/lib/pingclair。
固定发布 tag。 latest 会跟随最新发布，生产环境应写明版本，如上面的例子。已发布的 tag 列在软件包页面。

在用户不属于 docker 组的主机上，给命令加上 sudo，或者用 sudo usermod -aG docker "$USER" 加入一次并重新登录。在 Ubuntu 上， docker compose 插件来自 docker-compose-v2 包。

🛠️ 从源码构建

git clone https://github.com/dorianverlaine/pingclair
cd pingclair
cargo build --release

要求：Rust 1.98.1（CI 固定的版本）、cmake、clang、libclang-dev、g++ 和 git。构建过程会从源码编译 BoringSSL，因此首次构建需要几分钟。

⚠️ 安装失败时

This script must be run as root。 脚本会写到主目录之外并安装 unit，请加上 sudo 重新执行。
Fedora 上 setcap: command not found。 那是 libcap 包。安装器会装它，但手工搭建的主机可能缺失，而没有这个能力服务就无法绑定 80 和 443。
安装后立刻 Job for pingclair.service failed。 读 journalctl -u pingclair -n 20。常见原因是配置未通过校验，或者已经有别的进程占着 80 端口。
服务在跑，但从外面没有任何响应。 监听器已绑定，数据包没有到达。先检查服务商的防火墙或安全组，再检查主机自身的规则。
主机没有 systemd。 二进制装好可以运行，但安装器的服务步骤无法执行。请使用 Docker，或 pingclair run。

🧹 卸载

升级与卸载给出了拆除步骤，并指出哪些目录值得保留。

🧭 下一步

快速开始：把占位页面换成你自己的配置，提供真实站点。
HTTPS：为公开域名签发证书。
以服务方式运行：unit 做了什么，以及如何安全地重载。

📦安装