Kibitzr 8.0.0 安装与首个监控任务

目标：在 Ubuntu 22.04 服务器上从零安装 Kibitzr 8.0.0，规划配置与状态目录，跑通「URL 内容变化 → 控制台通知」的完整闭环，并用 systemd 托管为常驻监控。文中命令与回显均来自 2026-10-27 的真实服务器实测。

一、环境信息

项目	实测值
操作系统	Ubuntu 22.04.5 LTS（Jammy Jellyfish）
内核架构	x86_64
系统 Python	Python 3.10.12
系统 pip	22.0.2（`python3-pip` 包）
虚拟环境 pip	26.2.2（安装时升级）
Kibitzr 版本	8.0.0
安装目录	`/opt/kibitzr`
虚拟环境	`/opt/kibitzr/venv`
配置文件	`/opt/kibitzr/kibitzr.yml`
凭据文件	`/opt/kibitzr/kibitzr-creds.yml`（权限 600）
运行用户	`kibitzr`（系统用户，uid 999）
工作目录	`/opt/kibitzr`（`pages/`、`stash.db` 均落在此目录）
测试目标站点	`http://127.0.0.1:8131/index.html`（本机临时 HTTP 服务）
服务单元	`/etc/systemd/system/kibitzr.service`

💡 说明：Kibitzr 的配置、变更历史和键值存储都是「相对当前工作目录」的，因此本文从一开始就把工作目录固定为 /opt/kibitzr，避免后续 CLI 手工执行与 systemd 托管出现两份状态。

二、前置条件

2.1 系统依赖

Kibitzr 的核心依赖是纯 Python，但 changes 转换依赖系统 git，浏览器抓取依赖 Firefox（可选），jq 转换依赖系统 jq（可选）。最低安装只需要 Python 虚拟环境：

apt-get update
apt-get install -y python3-venv python3-pip

实测回显（本机已预装，因此显示为最新版本）：

Hit:2 http://archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:3 http://archive.ubuntu.com/ubuntu jammy-backports InRelease
Hit:4 http://security.ubuntu.com/ubuntu jammy-security InRelease
Reading package lists...
Reading package lists...
Building dependency tree...
Reading state information...
python3-pip is already the newest version (22.0.2+dfsg-1ubuntu0.7).
python3-venv is already the newest version (3.10.6-1~22.04.1).
0 upgraded, 0 newly installed, 0 to remove and 2 not upgraded.

确认虚拟环境模块可用：

python3 -V
dpkg -l python3-venv python3-pip | tail -2

Python 3.10.12
ii  python3-pip    22.0.2+dfsg-1ubuntu0.7 all          Python package installer
ii  python3-venv   3.10.6-1~22.04.1       amd64        venv module for python3 (default python3 version)

2.2 可选依赖

依赖	触发条件	安装命令	不装的后果
`git`	使用 `changes` 转换	`apt-get install -y git`	运行时报 `sh.CommandNotFound: git`
`jq`	使用 `jq` 转换	`apt-get install -y jq`	运行时报 `sh.CommandNotFound: jq`
Firefox + geckodriver	使用 `delay`/`form`/`scenario`	见官方 Firefox 指南	检查会卡在驱动获取阶段
编译头文件	从源码编译 `lxml` 时	`apt-get install -y python3-dev libxml2-dev libxslt1-dev`	`pip install` 编译失败

⚠️ 注意：git 和 jq 不在 pip 依赖里，必须在操作系统层安装。本文后续会用到 changes，因此下面会先装 git。本次实测 git --version 为 git version 2.34.1。

三、版本选型说明

截至 2026-10-27，PyPI 上的最新稳定版是 8.0.0（2025-05-05 发布），Python 要求 >=3.9，分类器覆盖 3.9–3.13。生产环境建议：

固定小版本安装：pip install kibitzr==8.0.0，避免 pip install kibitzr 在某次重建虚拟环境时升级到未验证版本。
固定 Python 3.9–3.13 之间的系统 Python；Ubuntu 22.04 自带的 3.10 可用。
如果目标服务器不能访问公网，使用本文第五节的离线 wheel 方案。

版本对照：

版本	发布状态	建议
8.0.0	最新稳定版	本文实测版本，生产首选
7.x	历史稳定版	仅在已有配置兼容性验证时使用
5.3.x / 6.x	历史版本	不建议新部署

四、在线安装方案（A：venv + pip）

4.1 创建安装目录与虚拟环境

mkdir -p /opt/kibitzr
python3 -m venv /opt/kibitzr/venv

venv 成功时没有输出。验证虚拟环境已生成：

ls /opt/kibitzr/venv/bin | head -8
/opt/kibitzr/venv/bin/pip -V

Activate.ps1
activate
activate.csh
activate.fish
doesitcache
httpx
idna
kibitzr
pip 26.2.2 from /opt/kibitzr/venv/lib/python3.10/site-packages/pip (python 3.10)

💡 说明：此时 bin 下还没有 kibitzr，上面列表中的 kibitzr 是开始安装后新生成的。pip -V 显示的 26.2.2 是本次安装时执行 pip install --upgrade pip 后的结果；系统 pip 仍是 22.0.2。

4.2 安装 Kibitzr

/opt/kibitzr/venv/bin/pip install --upgrade pip
/opt/kibitzr/venv/bin/pip install kibitzr==8.0.0

⚠️ 网络说明：本次实测先尝试官方 PyPI 源，依赖下载阶段长时间无进展，随后改用清华 TUNA 源 https://pypi.tuna.tsinghua.edu.cn/simple 完成安装。若你的服务器访问官方源正常，可省略 -i 参数；受限网络环境可改用国内 PyPI 源。安装过程实际下载了 40 余个依赖包。

安装输出节选（实测尾段）：

  Stored in directory: /root/.cache/pip/wheels/f0/d6/08/c646f4ead7b1fecf0f5d3d9f6203775acf0d80df435a176e0e
Successfully built sh
Installing collected packages: sortedcontainers, sh, pytimeparse, websocket-client, urllib3, typing-extensions, soupsieve, sniffio, six, schedule, pyyaml, pysocks, psutil, propcache, msgpack, MarkupSafe, lxml, lazy-object-proxy, idna, h11, frozenlist, entrypoints, defusedxml, click, charset_normalizer, certifi, attrs, async-timeout, aiohappyeyeballs, wsproto, requests, PyJWT, outcome, multidict, Jinja2, httpcore, exceptiongroup, beautifulsoup4, aiosignal, yarl, trio, cachecontrol, bs4, anyio, trio-websocket, httpx, aiohttp, selenium, python-telegram-bot, aiohttp-retry, twilio, kibitzr

Successfully installed Jinja2-3.1.6 MarkupSafe-3.0.4 PyJWT-2.15.1 aiohappyeyeballs-2.7.1 aiohttp-3.14.5 aiohttp-retry-2.9.1 aiosignal-1.4.0 anyio-4.15.1 async-timeout-5.0.1 attrs-26.1.0 beautifulsoup4-4.15.0 bs4-0.0.2 cachecontrol-0.14.4 certifi-2026.10.23 charset_normalizer-3.5.2 click-8.5.0 defusedxml-0.7.1 entrypoints-0.4.2 exceptiongroup-1.3.1 frozenlist-1.8.0 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 idna-3.20 kibitzr-8.0.0 lazy-object-proxy-1.12.0 lxml-6.1.3 msgpack-1.2.4 multidict-7.1.0 outcome-1.3.0.post0 propcache-0.5.4 psutil-7.2.2 pysocks-1.7.1 python-telegram-bot-22.8 pytimeparse-1.1.8 pyyaml-6.0.3 requests-2.34.2 schedule-1.2.2 selenium-4.51.0 sh-1.14.3 six-1.17.0 sniffio-1.3.1 sortedcontainers-2.4.0 soupsieve-2.10 trio-0.34.0 trio-websocket-0.12.2 twilio-9.12.0 typing-extensions-4.16.0 urllib3-2.8.0 websocket-client-1.9.2 wsproto-1.3.2 yarl-1.25.1

依赖解读：

click 提供 CLI 框架；pyyaml 解析配置；jinja2 提供模板转换；beautifulsoup4/lxml 处理 HTML。
schedule/pytimeparse 负责周期与日历调度。
selenium 与 python-telegram-bot、twilio 属于「装了但不一定用」的可选能力依赖，因此首次安装体积偏大（约数十 MB），这属正常现象。

4.3 版本验证

kibitzr 没有 --version 选项，版本用 version 子命令查看：

/opt/kibitzr/venv/bin/kibitzr version

8.0.0

如果误用 kibitzr --version，会得到明确报错（实测）：

Usage: kibitzr [OPTIONS] COMMAND [ARGS]...
Try 'kibitzr --help' for help.

Error: No such option '--version'.

4.4 安装系统依赖 git

apt-get install -y git
git --version

git version 2.34.1

五、离线安装方案（B：wheel 包 + 断网安装）

适用于生产服务器不能直连公网、但有一台可联网机器可以中转的场景。思路是在联网机器上把全部依赖下载为 wheel，复制到目标服务器后 --no-index 安装。

5.1 在联网机器下载 wheel

mkdir -p /opt/kibitzr/wheels
/opt/kibitzr/venv/bin/pip download -i https://pypi.tuna.tsinghua.edu.cn/simple \
  -d /opt/kibitzr/wheels kibitzr==8.0.0

输出节选（实测尾段）：

Saved ./opt/kibitzr/wheels/propcache-0.5.4-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Successfully downloaded kibitzr sh bs4 beautifulsoup4 soupsieve typing-extensions cachecontrol msgpack requests charset_normalizer idna urllib3 certifi click defusedxml entrypoints Jinja2 MarkupSafe lazy-object-proxy lxml psutil python-telegram-bot httpx httpcore h11 anyio exceptiongroup pytimeparse pyyaml schedule selenium trio trio-websocket pysocks websocket-client attrs outcome sniffio wsproto six sortedcontainers twilio PyJWT aiohttp async-timeout multidict yarl aiohappyeyeballs aiohttp-retry aiosignal frozenlist propcache

核对文件数量与体积：

ls /opt/kibitzr/wheels | wc -l
du -sh /opt/kibitzr/wheels

52
27M	/opt/kibitzr/wheels

5.2 目标服务器断网安装

把 wheels/ 目录整体复制到目标服务器（本文仍放在 /opt/kibitzr/wheels），创建独立虚拟环境后执行：

python3 -m venv /opt/kibitzr/venv-offline
/opt/kibitzr/venv-offline/bin/pip install --no-index \
  --find-links=/opt/kibitzr/wheels kibitzr==8.0.0

实测输出节选（尾段）：

Processing /opt/kibitzr/wheels/soupsieve-2.10-py3-none-any.whl
Using legacy 'setup.py install' for sh, since package 'wheel' is not installed.
Installing collected packages: sortedcontainers, sh, pytimeparse, websocket-client, urllib3, typing_extensions, soupsieve, sniffio, six, schedule, pyyaml, pysocks, psutil, propcache, msgpack, MarkupSafe, lxml, lazy-object-proxy, idna, h11, frozenlist, entrypoints, defusedxml, click, charset_normalizer, certifi, attrs, async-timeout, aiohappyeyeballs, wsproto, requests, PyJWT, outcome, multidict, Jinja2, httpcore, exceptiongroup, beautifulsoup4, aiosignal, yarl, trio, cachecontrol, bs4, anyio, trio-websocket, httpx, aiohttp, selenium, python-telegram-bot, aiohttp-retry, twilio, kibitzr
  Running setup.py install for sh: started
  Running setup.py install for sh: finished with status 'done'
Successfully installed Jinja2-3.1.6 MarkupSafe-3.0.4 PyJWT-2.15.1 aiohappyeyeballs-2.7.1 aiohttp-3.14.5 aiohttp-retry-2.9.1 aiosignal-1.4.0 anyio-4.15.1 async-timeout-5.0.1 attrs-26.1.0 beautifulsoup4-4.15.0 bs4-0.0.2 cachecontrol-0.14.4 certifi-2026.10.23 charset_normalizer-3.5.2 click-8.5.0 defusedxml-0.7.1 entrypoints-0.4.2 exceptiongroup-1.3.1 frozenlist-1.8.0 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 idna-3.20 kibitzr-8.0.0 lazy-object-proxy-1.12.0 lxml-6.1.3 msgpack-1.2.4 multidict-7.1.0 outcome-1.3.0.post0 propcache-0.5.4 psutil-7.2.2 pysocks-1.7.1 python-telegram-bot-22.8 pytimeparse-1.1.8 pyyaml-6.0.3 requests-2.34.2 schedule-1.2.2 selenium-4.51.0 sh-1.14.3 six-1.17.0 sniffio-1.3.1 sortedcontainers-2.4.0 soupsieve-2.10 trio-0.34.0 trio-websocket-0.12.2 twilio-9.12.0 typing-extensions-4.16.0 urllib3-2.8.0 websocket-client-1.9.2 wsproto-1.3.2 yarl-1.25.1

验证：

/opt/kibitzr/venv-offline/bin/kibitzr version

8.0.0

💡 说明：离线环境的 wheel 必须与目标服务器的 Python 版本、CPU 架构匹配。本文 wheel 为 cp310 + manylinux x86_64；如果目标机是 Python 3.11 或 ARM，需要在同版本同架构的联网机器上重新 pip download。

六、安装方案对比与选择建议

维度	方案 A：在线 venv + pip	方案 B：离线 wheel
是否需联网	目标机需能访问 PyPI 或国内 PyPI 源	仅首次中转机需要
安装耗时	依赖下载时间为主	本地解包，通常更快
版本可控性	`==8.0.0` 固定	固定 wheel 集合，可审计
磁盘占用	约数十 MB	额外保留 27 MB wheel
适用场景	云主机、可出网的内网	隔离内网、生产变更窗口
升级方式	`pip install -U kibitzr==<新版本>`	重新下载 wheel 后覆盖安装

选择建议：能出网就用方案 A，最简单；生产隔离网用方案 B，并在中转机保留 wheel 目录以便回滚。两套方案不要混用同一个虚拟环境。

七、目录与配置落地

7.1 创建运行用户与目录

useradd --system --create-home --home-dir /var/lib/kibitzr \
  --shell /usr/sbin/nologin kibitzr
id kibitzr

uid=999(kibitzr) gid=999(kibitzr) groups=999(kibitzr)

把安装目录交给运行用户，并保护凭据文件：

chown -R kibitzr:kibitzr /opt/kibitzr
chmod 600 /opt/kibitzr/kibitzr-creds.yml
ls -la /opt/kibitzr

total 36
drwxr-xr-x 4 kibitzr kibitzr  4096 Oct 27 14:30 .
drwxr-xr-x 1 root    root     4096 Oct 27 14:15 ..
-rw------- 1 kibitzr kibitzr   173 Oct 27 14:30 kibitzr-creds.yml
-rw-r--r-- 1 kibitzr kibitzr   193 Oct 27 14:30 kibitzr.yml
-rw-r--r-- 1 kibitzr kibitzr 10123 Oct 27 14:25 pip.log
drwxr-xr-x 5 kibitzr kibitzr  4096 Oct 27 14:15 venv
drwxr-xr-x 2 kibitzr kibitzr  4096 Oct 27 14:29 work

⚠️ 注意：pip.log 与 work/ 是本次实验的临时产物，生产环境不应留在安装目录。正式的目录结构只保留 venv/、kibitzr.yml、kibitzr-creds.yml，运行后自动生成 pages/ 与 stash.db。

7.2 生成骨架配置

cd /opt/kibitzr
/opt/kibitzr/venv/bin/kibitzr init

2026-10-27 14:29:03,276 [INFO] kibitzr.bootstrap: Saving sample check in kibitzr.yml
2026-10-27 14:29:03,276 [INFO] kibitzr.bootstrap: Creating kibitzr-creds.yml

total 16
drwxr-xr-x 2 kibitzr kibitzr 4096 Oct 27 14:29 .
drwxr-xr-x 4 kibitzr kibitzr 4096 Oct 27 14:15 ..
-rw------- 1 kibitzr kibitzr  173 Oct 27 14:29 kibitzr-creds.yml
-rw-r--r-- 1 kibitzr kibitzr  308 Oct 27 14:29 kibitzr.yml

生成的 kibitzr.yml（实测原文）：

# Format: http://kibitzr.readthedocs.io/en/latest/configuration.html
checks:
  - name: Kibitzr release
    url: https://pypi.python.org/pypi/kibitzr/json
    transform:
      - jinja: |
          {{ json["info"]["version"] }}
      - changes: verbose
    notify:
      - python: print(content)
    period: 5

生成的 kibitzr-creds.yml（实测原文，示例值需替换）：

# Plain text credentials configuration
# Documentation and other options: http://kibitzr.readthedocs.io/en/latest/credentials.html
service:
  username: john
  password: doe

逐项说明：name 是检查唯一标识，会出现在日志与通知里；url 是数据源；jinja 从 JSON 中取 info.version；changes: verbose 负责与上一版比较；notify 用 Python 打印；period: 5 是 5 秒周期。kibitzr-creds.yml 默认 600 权限，适合放 API Token 一类凭据。

八、跑通第一个 URL 变更监控

8.1 准备一个可变更的目标页面

在服务器本机启动一个临时 HTTP 站点，模拟「版本发布页」：

mkdir -p /srv/www
cat > /srv/www/index.html <<'EOF'
<html><head><title>Demo Site</title></head><body><div id="status">BUILD-2026-10-27-01</div><p>hello kibitzr</p></body></html>
EOF
cd /srv/www
nohup python3 -m http.server 8131 --bind 0.0.0.0 >/var/log/http.log 2>&1 &
sleep 2
curl -s http://127.0.0.1:8131/index.html

<html><head><title>Demo Site</title></head><body><div id="status">BUILD-2026-10-27-01</div><p>hello kibitzr</p></body></html>

💡 说明：这里用 Python 自带的 http.server 只是为了让实验可复现；真实场景把 url 换成你的业务页面即可。端口 8131 需确认未被占用（可用 ss -ltn 查看）。

8.2 编写第一个检查

在 /opt/kibitzr/kibitzr.yml 中写入以下配置（本文实测使用的配置）：

checks:
  - name: Demo build
    url: http://127.0.0.1:8131/index.html
    transform:
      - css: "#status"
      - text
      - changes: verbose
    notify:
      - python: print(content)
    period: 60

逐项说明：

css: "#status" 只保留 id=status 的元素，避免页头、页脚等噪声造成误报。
text 去掉 HTML 标签，只留 BUILD-2026-10-27-01 这样的纯文本。
changes: verbose 与 pages/Demo_build/ 中的上一版比较，输出「New value / Old value」。
python: print(content) 是最简单的控制台通知器，内容非空才会执行。
period: 60 表示每 60 秒检查一次。

8.3 首次运行

cd /opt/kibitzr
/opt/kibitzr/venv/bin/kibitzr once

2026-10-27 14:49:04,136 [INFO] kibitzr.fetcher.loader: Fetching Demo build at http://127.0.0.1:8131/index.html
2026-10-27 14:49:04,187 [INFO] kibitzr.notifier.custom: Executing Python notifier
Demo build at http://127.0.0.1:8131/index.html
BUILD-2026-10-27-01

首次运行没有历史，changes: verbose 输出「检查名 + 当前值」。由于 /opt/kibitzr/kibitzr-creds.yml 已存在，这次运行没有出现 No credentials file found 提示。

8.4 修改页面并观察变更通知

sed -i 's/BUILD-2026-10-27-01/BUILD-2026-10-27-02/' /srv/www/index.html
/opt/kibitzr/venv/bin/kibitzr once

2026-10-27 14:49:04,325 [INFO] kibitzr.fetcher.loader: Fetching Demo build at http://127.0.0.1:8131/index.html
2026-10-27 14:49:04,377 [INFO] kibitzr.notifier.custom: Executing Python notifier
Demo build at http://127.0.0.1:8131/index.html
New value:
BUILD-2026-10-27-02
Old value:
BUILD-2026-10-27-01

再运行一次，内容未变化：

/opt/kibitzr/venv/bin/kibitzr once

2026-10-27 14:49:04,533 [INFO] kibitzr.fetcher.loader: Fetching Demo build at http://127.0.0.1:8131/index.html

第二次没有 Executing Python notifier，也没有输出内容——这正是「只在变化时通知」的效果。验证历史已落盘：

find /opt/kibitzr/pages -maxdepth 2

/opt/kibitzr/pages
/opt/kibitzr/pages/Demo_build
/opt/kibitzr/pages/Demo_build/content
/opt/kibitzr/pages/Demo_build/.git

💡 技术拓展：内容差分有三种常见策略——逐字节比较、行级 unified diff、词级 diff。逐字节最简单但无法阅读；行级 diff 适合结构化文本（版本号、表格行）；词级 diff 适合长句新闻。Kibitzr 的 changes 默认行级 diff，changes: verbose 输出「新旧值」两段，changes: word 输出词级高亮。本文使用 verbose，因为版本号场景只需要知道新旧值。

九、systemd 托管

Kibitzr 官方没有 daemon 模式，推荐用外部进程管理器拉起。systemd 是最通用的选择。

9.1 编写服务单元

创建 /etc/systemd/system/kibitzr.service：

[Unit]
Description=Kibitzr web change monitor
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=kibitzr
Group=kibitzr
WorkingDirectory=/opt/kibitzr
ExecStart=/opt/kibitzr/venv/bin/kibitzr run
Restart=on-failure
RestartSec=10
TimeoutStopSec=30
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

逐项说明：

WorkingDirectory=/opt/kibitzr 必须与配置文件、pages/、stash.db 所在目录一致，否则历史会写到别处。
ExecStart 使用绝对路径，避免 systemd 环境变量 PATH 不含虚拟环境。
Restart=on-failure 在进程异常退出时自动拉起；手工 systemctl stop 不会触发重启。
TimeoutStopSec=30 给正在执行的抓取留出退出时间。

9.2 启动并验证

systemctl daemon-reload
systemctl enable --now kibitzr
sleep 6
systemctl status kibitzr --no-pager -l

输出节选（实测首部）：

● kibitzr.service - Kibitzr web change monitor
     Loaded: loaded (/etc/systemd/system/kibitzr.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-27 14:49:19 UTC; 6s ago
   Main PID: 5945 (kibitzr)
      Tasks: 1 (limit: 2932)
     Memory: 24.7M
        CPU: 147ms
     CGroup: /system.slice/kibitzr.service
             └─5945 /opt/kibitzr/venv/bin/python3 /opt/kibitzr/venv/bin/kibitzr run

查看启动日志：

journalctl -u kibitzr -n 8 --no-pager

Oct 27 14:49:19 kibitzr-lab systemd[1]: Started Kibitzr web change monitor.
Oct 27 14:49:19 kibitzr-lab kibitzr[5945]: 2026-10-27 14:49:19,544 [INFO] kibitzr.fetcher.loader: Fetching Demo build at http://127.0.0.1:8131/index.html
Oct 27 14:49:19 kibitzr-lab kibitzr[5945]: 2026-10-27 14:49:19,578 [INFO] kibitzr.timeline: Scheduling checks for 'Demo build' every 60 seconds
Oct 27 14:49:19 kibitzr-lab kibitzr[5945]: 2026-10-27 14:49:19,578 [INFO] kibitzr.app: Starting infinite loop

验证要点：

Active: active (running) 说明进程在跑。
Scheduling checks for 'Demo build' every 60 seconds 说明配置里的 period 已被解析。
Starting infinite loop 说明已进入常驻循环。

⚠️ 注意：如果先用 root 手工跑过 kibitzr once，再切换到 User=kibitzr 的 systemd 托管，服务会因 pages/ 属主是 root 而失败，journal 里可见 PermissionError: [Errno 13] Permission denied: 'pages/Demo_build/content'。本次实测就遇到了这个场景，执行 chown -R kibitzr:kibitzr /opt/kibitzr/pages 后重启即恢复。生产上安装后就应一次性 chown -R kibitzr:kibitzr /opt/kibitzr，避免手工调试与托管混用。

⚠️ 注意：systemctl stop kibitzr 后，systemctl is-active kibitzr 会显示 failed 而不是 inactive。原因是 Kibitzr 收到 SIGTERM 后按优雅退出路径返回退出码 1（实测 kibitzr run 前台进程收到 SIGTERM 后 wait 得到 1），systemd 因此把这次停止记为失败。它不影响下次 systemctl start，但监控系统若以 systemd 状态判活，需要把这一情况纳入白名单或改用 ExecStop 包装。

十、常见问题

10.1 `pip install` 卡在 lxml 编译

Q1： 安装时报 error: command 'gcc' failed 或卡在 Building wheel for lxml。

A：安装编译依赖，或改用预编译 wheel：

apt-get install -y python3-dev libxml2-dev libxslt1-dev
/opt/kibitzr/venv/bin/pip install --only-binary=lxml lxml

10.2 运行 `changes` 时报 `sh.CommandNotFound: git`

Q2： 首次使用 changes 就报错退出。

A：这是实测中真实遇到的错误：

sh.CommandNotFound: git

安装系统 git 即可：

apt-get install -y git

10.3 `No credentials file found` 是错误吗

Q3： 每次运行都出现 [INFO] kibitzr.conf: No credentials file found at /opt/kibitzr/kibitzr-creds.yml。

A：不是错误。来源是 logger.info，表示当前目录没有 kibitzr-creds.yml；如果你的检查不需要凭据，可以忽略。需要凭据时在同目录创建该文件并 chmod 600。

10.4 配置找不到

Q4： 报 kibitzr.yml not found in following locations。

A： Kibitzr 只在三个位置查找配置：./kibitzr.yml、~/.config/kibitzr/kibitzr.yml、~/kibitzr.yml。systemd 托管时务必设置 WorkingDirectory，否则 ./ 不是你以为的目录。

10.5 浏览器类检查卡住

Q5： 配置了 delay 后，kibitzr once 长时间无输出。

A：该配置会走 Selenium 抓取路径，首次运行需要由 selenium-manager 获取 Firefox 驱动；离线或网络受限时会卡住。没有浏览器抓取需求时不要配置 delay/form/scenario；确有需求时预装 Firefox 与 geckodriver，并保证驱动获取渠道可用。详见《Kibitzr 8.0.0 配置参数详解》第五章。

10.6 systemd 托管报 `PermissionError: 'pages/Demo_build/content'`

Q6： 手工运行正常，改成 systemd 服务后反复重启，journal 显示 PermissionError: [Errno 13] Permission denied。

A：服务以 User=kibitzr 运行，而 pages/ 目录或文件属主是此前用 root 运行留下的。统一属主后重启：

chown -R kibitzr:kibitzr /opt/kibitzr/pages
systemctl restart kibitzr
systemctl is-active kibitzr

active

更彻底的做法是安装完成后立即 chown -R kibitzr:kibitzr /opt/kibitzr，并坚持用同一用户执行手工命令。

十一、卸载清理

11.1 停止并禁用服务

systemctl disable --now kibitzr
systemctl is-active kibitzr
systemctl is-enabled kibitzr

Removed /etc/systemd/system/multi-user.target.wants/kibitzr.service.
failed
disabled

failed 的成因见第九节说明；disabled 说明开机自启已取消。

11.2 卸载 Python 包

/opt/kibitzr/venv/bin/pip uninstall -y kibitzr
/opt/kibitzr/venv/bin/kibitzr version

Found existing installation: kibitzr 8.0.0
Uninstalling kibitzr-8.0.0:
  Successfully uninstalled kibitzr-8.0.0
bash: /opt/kibitzr/venv/bin/kibitzr: No such file or directory

11.3 删除目录与用户

rm -rf /opt/kibitzr
rm -f /etc/systemd/system/kibitzr.service
systemctl daemon-reload
test ! -d /opt/kibitzr && echo "install dir removed"

install dir removed

如需彻底清理运行用户：

userdel kibitzr

⚠️ 注意：rm -rf /opt/kibitzr 会同时删除 kibitzr.yml、pages/ 历史与 stash.db。卸载前如需保留变更历史，先备份 pages/。

十二、参考链接

官方仓库：https://github.com/kibitzr/kibitzr
PyPI 项目页：https://pypi.org/project/kibitzr/
官方安装文档：https://kibitzr.readthedocs.io/en/latest/installation.html
官方配置文档：https://kibitzr.readthedocs.io/en/latest/configuration.html
清华 TUNA PyPI 源：https://pypi.tuna.tsinghua.edu.cn/simple
本专栏认知篇：《Kibitzr 8.0.0 完整部署与实战指南》

Kibitzr 8.0.0 安装与首个监控任务

Kibitzr 8.0.0 安装与首个监控任务

一、环境信息

二、前置条件

2.1 系统依赖

2.2 可选依赖

三、版本选型说明

四、在线安装方案（A：venv + pip）

4.1 创建安装目录与虚拟环境

4.2 安装 Kibitzr

4.3 版本验证

4.4 安装系统依赖 git

五、离线安装方案（B：wheel 包 + 断网安装）

5.1 在联网机器下载 wheel

5.2 目标服务器断网安装

六、安装方案对比与选择建议

七、目录与配置落地

7.1 创建运行用户与目录

7.2 生成骨架配置

八、跑通第一个 URL 变更监控

8.1 准备一个可变更的目标页面

8.2 编写第一个检查

8.3 首次运行

8.4 修改页面并观察变更通知

九、systemd 托管

9.1 编写服务单元

9.2 启动并验证

十、常见问题

10.1 pip install 卡在 lxml 编译

10.2 运行 changes 时报 sh.CommandNotFound: git

10.3 No credentials file found 是错误吗

10.4 配置找不到

10.5 浏览器类检查卡住

10.6 systemd 托管报 PermissionError: 'pages/Demo_build/content'

十一、卸载清理

11.1 停止并禁用服务

11.2 卸载 Python 包

11.3 删除目录与用户

十二、参考链接

10.1 `pip install` 卡在 lxml 编译

10.2 运行 `changes` 时报 `sh.CommandNotFound: git`

10.3 `No credentials file found` 是错误吗

10.6 systemd 托管报 `PermissionError: 'pages/Demo_build/content'`