changedetection.io 0.60.9 Docker Compose 部署指南

目标：使用 Docker Compose 在 Ubuntu 22.04 上部署 changedetection.io 0.60.9，并启用 sockpuppetbrowser 实现基于 Chrome 的浏览器渲染监控。全部命令已在 Docker Engine 29.8.1 + Docker Compose v5.5.1 环境实测通过，服务启动后访问正常（HTTP 200）。

本篇是 Compose 部署专题，命令以 docker compose 为主体。若希望直接在裸机以 pip 方式安装，见《changedetection.io 0.60.9 Ubuntu 22.04 安装指南》。

一、环境信息

二、镜像选型说明

2.1 主服务镜像

changedetection.io 官方只维护一个主镜像，发布在 GitHub Container Registry：

• ghcr.io/dgtlmoon/changedetection.io（未带 tag 时默认 latest，当前对应 0.60.9）
• 也可锁定版本：ghcr.io/dgtlmoon/changedetection.io:0.60.9

⚠️ 注意：Docker Hub 上存在同名镜像 dgtlmoon/changedetection.io，但官方 compose 与文档统一使用 ghcr.io 源，生产环境请以 ghcr.io 为准。锁定具体版本号可以避免 latest 更新带来的不可预期升级。

2.2 浏览器渲染方案对比

需要监控 JavaScript 动态渲染的页面时，官方 compose 提供了两种浏览器后端，选型对比如下（对比要点摘自官方 compose.yml 注释原文）：

💡 技术拓展：changedetection.io 支持的三种抓取后端——

• html_requests（默认）：纯 HTTP 客户端抓取，不执行 JS，资源占用最低，适合静态页；
• html_webdriver：通过 Playwright 协议驱动远端 Chrome 渲染，可执行 JS、支持视觉差异与 Visual Selector；
• restock_diff（补货监控处理器）：基于前两者之一抓取，用 AI/规则识别价格与库存状态。 每个监控可独立选择后端（监控编辑页 Fetching 标签页里的 "Fetch backend" 下拉框），全局后端在 Settings → Fetching 中设置。

三、前置条件

确认 Docker 与 Compose 插件可用：

docker --version && docker compose version

实测回显：

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

⚠️ 注意：docker compose（空格）是 Compose v2+ 插件写法。如果你的环境只有旧版 docker-compose（连字符），本篇所有 docker compose 命令需要相应替换，yaml 语法无需改动。

如未安装 Docker，Ubuntu 22.04 可使用官方一键脚本安装：

curl -fsSL https://get.docker.com | sh

安装完成后把当前用户加入 docker 组（免 sudo，重新登录生效）：

usermod -aG docker $USER

四、部署步骤

4.1 创建部署目录

mkdir -p /opt/changedetection && cd /opt/changedetection

实测回显：无输出（目录已存在时静默）。

4.2 编写 docker-compose.yml

创建 docker-compose.yml（主服务 + sockpuppetbrowser 浏览器渲染，双服务形态）：

cat > docker-compose.yml <<'EOF'
services:
    changedetection:
      image: ghcr.io/dgtlmoon/changedetection.io
      container_name: changedetection
      hostname: changedetection
      volumes:
        - changedetection-data:/datastore
      environment:
        # 启用 Chrome 渲染：指向 sockpuppetbrowser 的 WebSocket 地址
        - PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000
        # 默认出于安全禁止监控私有/保留网段，内网监控场景需要打开
        - ALLOW_IANA_RESTRICTED_ADDRESSES=true
      ports:
        - 5000:5000
      restart: unless-stopped

    browser-sockpuppet-chrome:
        hostname: browser-sockpuppet-chrome
        image: dgtlmoon/sockpuppetbrowser:latest
        cap_add:
            - SYS_ADMIN
        restart: unless-stopped
        environment:
            - SCREEN_WIDTH=1920
            - SCREEN_HEIGHT=1024
            - SCREEN_DEPTH=16
            - MAX_CONCURRENT_CHROME_PROCESSES=10

volumes:
  changedetection-data:
EOF

实测回显：无输出（写入成功）。

配置要点：

• changedetection-data:/datastore：所有配置与快照数据存于 named volume，升级/重建容器不丢数据；
• PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000：服务名即 DNS 名，Compose 内部网络互通；
• cap_add: SYS_ADMIN：Chrome 沙箱需要，官方 compose 原文注释 "SYS_ADMIN might be too much, but it can be needed on your platform"；
• ports: 5000:5000：生产建议改为 127.0.0.1:5000:5000 只绑定本机回环，配合反向代理对外；
• 只监控静态页、不需要浏览器渲染时，可删掉 browser-sockpuppet-chrome 整个服务与 PLAYWRIGHT_DRIVER_URL 环境变量，只留主服务。

4.3 校验 Compose 文件语法

docker compose config --quiet && echo CONFIG_OK

实测回显：

CONFIG_OK

4.4 拉取镜像并启动

docker compose up -d

实测回显（首次启动时还会先出现两行 Pulling changedetection... / Pulling browser-sockpuppet-chrome...，输出节选）：

 Container root-browser-sockpuppet-chrome-1 Created
 Container changedetection Created
 Container root-browser-sockpuppet-chrome-1 Starting
 Container changedetection Starting
 Container changedetection Started
 Container root-browser-sockpuppet-chrome-1 Started

⚠️ 注意：sockpuppetbrowser 镜像约 1 GB（内含完整 Chrome），首次拉取耗时取决于带宽。国内环境拉取 ghcr.io 与 docker.io 缓慢时，给 Docker 配置镜像加速或代理（/etc/docker/daemon.json 的 proxies 段或 systemd 的 HTTPS_PROXY 环境变量）后再 pull。

4.5 验证部署

查看两个服务的运行状态：

docker compose ps --format "table {{.Name}}\t{{.Image}}\t{{.Status}}"

实测回显：

NAME                               IMAGE                                 STATUS
changedetection                    ghcr.io/dgtlmoon/changedetection.io   Up 15 seconds
root-browser-sockpuppet-chrome-1   dgtlmoon/sockpuppetbrowser:latest     Up 15 seconds

查看主服务日志，确认版本与渲染后端：

docker logs changedetection 2>&1 | grep -E "version 0.60.9|Playwright"

实测回显：

2026-10-17 02:48:55.410 | DEBUG    | changedetectionio.content_fetchers:<module>:184 - Using Playwright library as fetcher
2026-10-17 02:48:55.672 | SUCCESS  | changedetectionio:main:347 - changedetection.io version 0.60.9 starting.

两行日志的含义：

• Using Playwright library as fetcher：PLAYWRIGHT_DRIVER_URL 已生效，Playwright 渲染后端就绪（未配置该变量时会显示 Falling back to selenium as fetcher，即纯 HTTP 抓取模式）；
• version 0.60.9 starting.：镜像实际版本确认。

最后做 HTTP 验证：

curl -sI http://127.0.0.1:5000/ | head -2

实测回显（示例）：

HTTP/1.1 200 OK
Server: Werkzeug/3.1.9 Python/3.11.17

浏览器访问 http://<服务器IP>:5000 即可使用。

五、浏览器渲染方案验证

部署 sockpuppetbrowser 后，用同一页面对比两种抓取后端的实际差异，验证渲染链路真实可用。

5.1 双后端对比实测

准备一个包含 JavaScript 动态写入内容的测试页面，分别创建 html_requests（纯 HTTP）与 html_webdriver（Chrome 渲染）两个监控，触发检查后读取快照。

通过 REST API 创建监控（API key 在 Settings → API 页查看，本例为 fe8460996ec089722789f97a6673b118）：

curl -s -H "x-api-key: fe8460996ec089722789f97a6673b118" -X POST -H "Content-Type: application/json" -d '{"url": "http://172.17.0.35:8000/js-test.html", "fetch_backend": "html_requests"}' http://127.0.0.1:5000/api/v1/watch

实测回显：

{"uuid": "9a8f0345-d733-49e0-bf95-246f9307d8a6"}

curl -s -H "x-api-key: fe8460996ec089722789f97a6673b118" -X POST -H "Content-Type: application/json" -d '{"url": "http://172.17.0.35:8000/js-test.html", "fetch_backend": "html_webdriver"}' http://127.0.0.1:5000/api/v1/watch

实测回显：

{"uuid": "c363a081-67f9-4388-9f66-22273f0b6742"}

检查完成后读取两个监控的最新快照对比（读取方式见《changedetection.io 0.60.9 进阶实战与运维》）：

== html_requests（纯 HTTP 客户端） 最新快照 ==
Dynamic Render Monitor

== html_webdriver（Playwright/Chrome） 最新快照 ==
Dynamic Render Monitor

  JS-RENDERED-2026

结论一目了然：页面中由 JavaScript 写入的 JS-RENDERED-2026 内容，只有走 Chrome 渲染的监控才能抓到——这就是浏览器渲染方案的价值，也是价格监控、补货监控必须启用它的原因。

5.2 Chrome 进程并发控制

sockpuppetbrowser 的 MAX_CONCURRENT_CHROME_PROCESSES=10 限制并发 Chrome 实例数，需要与主服务的 FETCH_WORKERS（默认 10）联动：worker 数量超过 Chrome 进程上限时，多余任务会排队等待。监控量大（数百个）且大量启用浏览器渲染时，建议同步调大两者，并留意内存占用（每个 Chrome 实例约 200~400 MB）。

六、数据持久化说明

6.1 数据卷与数据目录

全部数据存于 named volume changedetection-data，对应容器内 /datastore：

docker exec changedetection ls /datastore

实测回显（结构示例，UUID 目录对应各监控与分组）：

09f5d214-cdf1-43bf-9d59-5e274b1d6dd3
2007bef2-11a3-4df7-afe6-ae4eb3bd8016
531391a0-1695-4d97-baa6-d5e55625b8d3
69a732a6-f53a-420f-a54e-603cb54c42f9
98d51a16-8b56-4eae-bbf9-348e179a18bc
9a8f0345-d733-49e0-bf95-246f9307d8a6
c363a081-67f9-4388-9f66-22273f0b6742
changedetection-0-60-9.json
changedetection.json
secret.txt

• changedetection.json：全局配置（设置项、watch 索引、通知配置等）；
• changedetection-0-60-9.json：当前版本标记文件；
• secret.txt：实例密钥；
• UUID 目录：每个监控一个目录，内含 watch.json（监控配置）与 <hash>.txt（历史快照）。

6.2 直接查看与备份数据卷

查看 volume 在宿主机的实际位置（named volume 名称会带 Compose 项目名前缀，项目目录为 /root 时前缀是 root_，先用 docker volume ls 确认）：

docker volume inspect root_changedetection-data --format '{{.Mountpoint}}'

实测回显：

/var/lib/docker/volumes/root_changedetection-data/_data

停机热备份（打包 volume 内容）：

docker run --rm -v root_changedetection-data:/data -v /opt/backup:/backup ubuntu tar czf /backup/changedetection-data.tar.gz -C /data .

实测产物：

-rw-r--r-- 1 root root 122K Oct 17 03:06 /opt/backup/changedetection-data.tar.gz

恢复时反向解包即可。changedetection.io 还内置了 Web 备份功能（生成 zip），详见《changedetection.io 0.60.9 进阶实战与运维》。

七、环境变量参考

以下变量均配置在主服务 changedetection 的 environment: 段，出处为官方 compose.yml 注释，按用途分组：

7.1 服务与监听

7.2 抓取与网络

7.3 AI/补货监控相关

环境变量修改后需要重建服务生效：

docker compose up -d

实测回显（environment 有变化时会重建对应容器）：

 Container changedetection Recreate
 Container changedetection Recreated
 Container changedetection Started

八、配置文件挂载

changedetection.io 支持通过数据目录内的 JSON 文件扩展配置，官方 compose 注释给出的挂载示例是代理列表：

      volumes:
        - changedetection-data:/datastore
        - ./proxies.json:/datastore/proxies.json

proxies.json 用于"代理列表"功能（给不同监控分配不同出口代理），配置格式见官方 Wiki 的 Proxy-configuration 页面。挂载后重启服务生效。

💡 提示：也可以不挂载文件，而是先 docker compose up -d 启动，再把 proxies.json 直接复制进数据卷：docker cp proxies.json changedetection:/datastore/，然后 docker compose restart changedetection。

九、等价启动命令

不用 Compose 时，等价的 docker run 命令如下（先起浏览器渲染服务，再起主服务；注意两者需要位于同一自定义网络内）：

docker network create changedetection-net

docker run -d --name browser-sockpuppet-chrome --hostname browser-sockpuppet-chrome --cap-add SYS_ADMIN --network changedetection-net --restart unless-stopped -e SCREEN_WIDTH=1920 -e SCREEN_HEIGHT=1024 -e SCREEN_DEPTH=16 -e MAX_CONCURRENT_CHROME_PROCESSES=10 dgtlmoon/sockpuppetbrowser:latest

docker run -d --name changedetection --hostname changedetection --network changedetection-net -p 5000:5000 -v changedetection-data:/datastore -e PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000 -e ALLOW_IANA_RESTRICTED_ADDRESSES=true --restart unless-stopped ghcr.io/dgtlmoon/changedetection.io

日常使用更推荐 Compose：配置即代码、依赖关系清晰、一条命令升降级。

十、常用运维命令

以下命令均在部署目录（含 docker-compose.yml）内执行。

查看服务状态：

docker compose ps

跟踪主服务日志：

docker compose logs -f changedetection

查看浏览器渲染服务日志：

docker compose logs -f browser-sockpuppet-chrome

重启主服务（改配置后）：

docker compose restart changedetection

停止全部服务（保留数据卷）：

docker compose down

实测回显：

 Container changedetection Removing
 Container changedetection Removed
 Network root_default Removing
 Network root_default Removed

💡 说明：docker compose down 不删除 named volume，数据安全；如确认要连同数据一起清掉，加 -v 参数（高危操作，先备份）。

升级到新版本（官方发新镜像后）：

docker compose pull changedetection

docker compose up -d

pull 拉取新镜像，up -d 检测到镜像变化会自动重建主服务，数据卷保留。升级前建议先用第六节的命令备份数据卷。如需回滚，把 image: 锁回具体版本号（如 ghcr.io/dgtlmoon/changedetection.io:0.60.9）再 up -d。

十一、常见问题（FAQ）

Q1：监控内网地址时提示 Fetch blocked？ 默认禁止抓取私有/保留网段。解决：主服务 environment 增加 ALLOW_IANA_RESTRICTED_ADDRESSES=true 后 docker compose up -d 重建。实测报错原文与裸机安装一致：

Exception: Fetch blocked: 'http://127.0.0.1:8000/monitor-test.html' resolves to a private/reserved IP address or contains a parser-differential payload. Set ALLOW_IANA_RESTRICTED_ADDRESSES=true to allow.

Q2：动态页面抓不到 JS 渲染的内容？ 该监控的 Fetch backend 仍是 html_requests（纯 HTTP）。到监控编辑页 Fetching 标签页把后端改为 html_webdriver，或通过 API 直接改：PUT /api/v1/watch/<uuid> 提交 {"fetch_backend": "html_webdriver"}。前提是已按本篇启用 sockpuppetbrowser（日志中有 Using Playwright library as fetcher）。

Q3：5000 端口被占用或与 AirPlay 冲突？ 改 ports 映射即可，如 "5050:5000"。官方 compose 注释特别提示 Mac 用户使用 127.0.0.1:5050:5000（端口 5050）避免与本机 AirPlay 冲突（引用官方 issue #3401）。

Q4：sockpuppetbrowser 一直重启？ 多为内核限制导致 Chrome 沙箱崩溃。确认 Compose 里保留了 cap_add: SYS_ADMIN；宿主机 /proc/sys/kernel/unprivileged_userns_clone 为 0 时设为 1；仍不行可在 sockpuppetbrowser 环境加 DEFAULT_CHROME_FLAGS（传入 --no-sandbox 等参数，代价是降低浏览器隔离）。

Q5：内存占用高？ 主要来自 Chrome 渲染。优化顺序：降低 MAX_CONCURRENT_CHROME_PROCESSES、减少启用浏览器渲染的监控数量、给静态页改回 html_requests 后端、调低 FETCH_WORKERS。

十二、参考链接

• 官方 compose.yml：https://github.com/dgtlmoon/changedetection.io/blob/master/docker-compose.yml
• 官方镜像：https://ghcr.io/dgtlmoon/changedetection.io
• sockpuppetbrowser：https://github.com/dgtlmoon/sockpuppetbrowser
• 反向代理部署 Wiki：https://github.com/dgtlmoon/changedetection.io/wiki/Running-changedetection.io-behind-a-reverse-proxy
• 代理配置 Wiki：https://github.com/dgtlmoon/changedetection.io/wiki/Proxy-configuration
• 配套文档：《changedetection.io 0.60.9 Ubuntu 22.04 安装指南》《changedetection.io 0.60.9 快速入门（添加监控到差异告警）》《changedetection.io 0.60.9 配置参数详解》《changedetection.io 0.60.9 进阶实战与运维》