安装与使用

两个项目各自独立部署，选一个开始就行。只关心某块文字是否变了，用 WebMonitor；要按“降价 10%”“缺货变有货”“列表新增”这类条件通知，用 Agent。已经拿到别人的实例地址和账号时，直接登录即可，不用安装 Docker。

需要一台能运行 Docker 的电脑或服务器，以及用于下载部署文件的 curl。普通安装不用克隆仓库，也不用登录镜像仓库。公开镜像同时支持 Intel/AMD 与 Apple Silicon，Docker 会自动选择。

镜像默认跟随最新稳定版 latest。想固定版本，把 .env 里的 WEBMONITOR_IMAGE 改成 1.0.0 这样的发布版本。两个项目最后都用 docker compose up -d --wait 启动，命令会等到健康检查通过才返回。

WebMonitor 用一个容器同时提供网页界面和数据接口，自带 SQLite 与 Chromium。不需要模型密钥，邮件在登录后配置。

mkdir -p webmonitor
cd webmonitor
curl -fsSLo compose.yaml https://raw.githubusercontent.com/webmonitor/WebMonitor/main/compose.yaml

WEBMONITOR_IMAGE=ghcr.io/webmonitor/webmonitor:latest
SECRET_KEY=
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=

docker compose up -d --wait
# 打开 http://localhost:8000

登录后看到仪表板，就说明安装完成。左侧可以进入「监控任务」「监控日志」「邮件配置」和「公开任务」。如果 --wait 报错或迟迟不返回，先执行 docker compose ps 和 docker compose logs --tail=100 查看原因。

WebMonitor 仓库与完整说明

Agent 需要兼容 OpenAI Chat Completions 的模型服务，用来理解你的描述并整理监控设置。安装会启动应用、数据库、页面存档和出站代理等一组容器；应用镜像直接拉取公开版本，另外两个辅助镜像会在首次启动时用下载的文件在本地构建。

mkdir -p webmonitor-agent
cd webmonitor-agent
(
  set -e
  for file in compose.yaml .dockerignore deploy/browser-seccomp.json deploy/minio.Dockerfile deploy/minio-artifacts.json deploy/egress.Dockerfile deploy/egress/squid.conf deploy/egress/unbound.conf deploy/egress/entrypoint.sh deploy/proxy/nginx.conf; do
    curl -fsSL --create-dirs "https://raw.githubusercontent.com/webmonitor/WebMonitor-Agent/main/$file" -o "$file"
  done
)

WEBMONITOR_IMAGE=ghcr.io/webmonitor/webmonitor-agent:latest
WEBMONITOR_HTTP_PORT=8080
APP_ORIGIN=http://localhost:8080
DEVELOPMENT_MODE=true
POSTGRES_PASSWORD=
SECRET_KEY=
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=
SMTP_HOST=
SMTP_PORT=465
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_USE_SSL=true
SMTP_STARTTLS=false
MAIL_FROM=

docker compose up -d --wait
# 打开 http://localhost:8080

打开页面后，用 .env 里的 ADMIN_EMAIL 和 ADMIN_PASSWORD 登录，会看到对话工作台。如果还没有管理员账户，或需要邀请成员，看下面的「遇到问题」。

WebMonitor-Agent 仓库与完整说明

1. 登录后打开「监控任务」，点「创建新任务」。
2. 填写任务名称、监控 URL、XPath 选择器和检查间隔（秒，最小 10，默认 300）。不确定 XPath 时先点「测试监控」，看到提取到的文字再继续；测试不会发邮件。
3. 决定是否公开任务、是否「启用监控」，然后点「创建任务」。
4. 到「监控日志」查看每次检查的时间、结果和新内容；仪表板会汇总任务数、最近变化和执行成功率。

首次成功的定时检查可能先发一封初始通知，之后只在文字变化时通知。任务不绑定邮件配置也会照常采集和记录日志，只是不发邮件。把任务设为公开后，同一实例的其他用户可以在「公开任务」里订阅，并用自己的邮件配置接收通知。

1. 登录后在左侧点「新对话」。
2. 把网址和要求一起说清楚：看什么、多久检查一次、什么条件下通知。例如：「监控这个页面的价格，降价 10% 时邮件提醒我。」
3. 助手会打开页面试采集一次，稍等它读取页面并整理监控设置。
4. 在「创建监控」卡片里核对采集到的内容、通知条件、收件人和邮件预览；不满意可以点「重新预览」。
5. 点「创建监控」，开始定时检查。

创建后，监控会出现在左侧「监控」列表。打开后可以看当前内容、最近检查、事件，以及浏览器采集留下的截图和页面存档；右上角有「暂停」「恢复」「立即检查」和「修改设置」。要改监控的内容或条件，回到对话里说明，重新核对预览后保存。

两个项目的邮件配置方式不同：WebMonitor 由每位用户在应用里填写 SMTP 和收件人；Agent 的 SMTP 属于整套部署，收件人由管理员在通知组里维护。不配置邮件也能采集和查看变化，只是收不到提醒。

WebMonitor： 打开「邮件配置」，点「添加邮件配置」，填写配置名称、SMTP 服务器、SMTP 端口、发件人邮箱、SMTP 密码和接收者邮箱，按邮件服务商的要求勾选「使用 SSL 加密」。密码通常使用邮箱的应用专用密码。点「测试连接」确认能收到测试邮件，再创建或编辑任务，在「邮件配置」里选择这条配置。选「不发送通知」时任务照常采集，只是不发邮件。

WebMonitor-Agent： 在 .env 里填写 SMTP_HOST、SMTP_PORT、SMTP_USERNAME、SMTP_PASSWORD 和 MAIL_FROM，改完执行 docker compose up -d --wait 让配置生效。然后用管理员登录，打开「通知」→「通知组」，点「新建」，填写名称和收件人（每行一个邮箱，也可以用逗号或空格分隔）。创建或修改监控时，在「收件人」里选择通知组；一个监控可以通知多个邮箱。

WebMonitor 的管理入口都在左侧导航里：

• 「监控任务」可以测试、编辑、暂停或启用、删除任务，列表里能看到检查间隔和绑定的邮件配置。
• 「监控日志」按任务查看每次检查的状态、新内容和错误信息。
• 「公开任务」与「我的订阅」用来分享和订阅实例内的任务；每位用户用自己的邮件配置接收通知。
• 管理员还可以在「用户管理」里调整账户和订阅额度，在「黑名单管理」里限制普通用户可监控的域名。

Agent 在一个工作台里管理对话、监控和通知：

• 「监控」列表打开任一监控，查看当前内容、最近检查和事件；用「暂停」「恢复」「立即检查」「修改设置」控制它。
• 「事件」记录变化、采集失败和恢复，可以只看「未读」，看完点「标为已读」。
• 「通知」里维护通知组，并查看每封邮件的收件人、状态和失败原因。
• 成员由管理员邀请，通过邀请链接注册。

• 启动命令报错或一直不返回： 在部署目录执行 docker compose ps 和 docker compose logs --tail=100。常见原因是 .env 还有空值、端口被占用、模型配置不可用。修好后重新执行启动命令。
• 网页打不开： 确认访问的是 http://localhost:8000（WebMonitor）或 http://localhost:8080（Agent），并确认容器正在运行。
• WebMonitor 登录失败： 使用 .env 里的 ADMIN_USERNAME 登录。初始管理员在首次启动时创建；后续账户信息在应用内管理。
• Agent 登录失败： 用 .env 里的 ADMIN_EMAIL 和 ADMIN_PASSWORD 登录，密码要求 12–128 字符。
• Agent 没有管理员，或新成员注册不了： 在部署目录执行 docker compose exec api webmonitor admin-create --email you@example.com 创建管理员，或执行 docker compose exec api webmonitor invite-create --email member@example.com --ttl-hours 24 生成一次性邀请链接。链接过期或邮箱不匹配都不能用。
• WebMonitor 提取不到内容： 先用「测试监控」检查 XPath 是否选中了真正包含文字的元素；需要登录才能看到的内容无法直接监控。
• Agent 预览失败或提示地址不允许： 目标必须是公网 http/https 地址（80 或 443 端口）。站点打不开、拦爬虫、需要登录，或内容在 iframe / Shadow DOM 里时都可能失败；模型服务不可用也会让对话中断。
• 没有收到邮件： WebMonitor 先在「邮件配置」点「测试连接」；Agent 检查 .env 的 SMTP 设置和通知组收件人。也看看垃圾邮件和投递记录。
• 更新后打不开或数据不对： 两个项目都没有自动数据库迁移。先恢复对应备份，或把 WEBMONITOR_IMAGE 改回原来的版本再启动。

更新前先备份数据，并记下当前使用的镜像版本。把 .env 里的 WEBMONITOR_IMAGE 改成新版本，然后在各自的部署目录执行下面的命令。

docker compose pull
docker compose up -d --wait

docker compose pull api web
docker compose up -d --wait api web

需要回退时，把 WEBMONITOR_IMAGE 改回之前仍可用的版本，再执行对应项目的同样命令。没有数据库降级机制，旧版本不一定能读新版本写过的数据；必要时恢复更新前的备份。

WebMonitor 发布记录

Agent 发布记录

两个项目都没有自动备份或数据迁移工具，数据保存在容器内，需要在容器之外自行留存备份。

docker compose stop
docker cp webmonitor:/app/data/webmonitor.db ./webmonitor-backup.db
docker compose start

监控时的限制：

遇到问题请提交到对应项目，附上复现步骤和去掉敏感信息的页面示例。

WebMonitor GitHub 组织