changedetection.io 0.60.9 配置参数详解

目标：系统梳理 changedetection.io 0.60.9 的全部配置入口——命令行参数、环境变量、Web 设置页、数据目录结构，并给出生产环境推荐配置模板。所有参数说明均在 0.60.9 实测环境验证。

一、环境信息

项目	实测值
版本	changedetection.io 0.60.9
参考系统	Ubuntu 22.04（pip 安装）与 Docker 部署两种形态
主配置文件	数据目录下 `changedetection.json`
命令行帮助	`changedetection.io --help`（实测全文见第四节）

二、前置条件

服务已安装并能启动（安装见《changedetection.io 0.60.9 Ubuntu 22.04 安装指南》或《changedetection.io 0.60.9 Docker Compose 部署指南》）；
能查看服务日志（pip 版 journalctl -u changedetection -f；Compose 版 docker compose logs -f changedetection）——环境变量是否生效以日志为准。

三、配置体系总览

changedetection.io 的配置分三层，作用范围与优先级如下：

层级	载体	生效范围	修改后生效方式	适用场景
命令行参数	启动命令 `-d -p -h -l` 等	仅该进程实例	重启服务	端口、数据目录、日志级别等启动属性
环境变量	systemd `Environment=` 或 Compose `environment:`	仅该实例	重建/重启服务	部署形态相关：抓取后端、代理、限额、AI
界面设置	数据目录 `changedetection.json`	全部实例共享（随数据迁移）	界面保存即生效	业务策略：默认检查频率、通知、过滤、RSS
单监控设置	每个 watch 的配置（界面编辑页）	单个监控	保存即生效	个别监控覆盖全局默认

💡 说明：三层配置不是简单的覆盖关系——命令行与环境变量控制进程行为，界面设置控制监控业务行为，二者互不冲突。例如 -p 5000 决定监听端口（进程行为），而界面里的 "Time Between Check" 决定检查频率（业务行为）。单监控设置可覆盖界面全局默认（如检查频率、通知渠道），界面全局默认则是新建监控的初始值。

四、命令行参数详解

实测 changedetection.io --help 全文（0.60.9 原文）：

Usage: changedetection.py [options]

Standard options:
  -s                SSL enable
  -h HOST           Listen host (default: 0.0.0.0)
  -p PORT           Listen port (default: 5000)
  -d PATH           Datastore path
  -l LEVEL          Log level (TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL)
  -c                Cleanup unused snapshots
  -C                Create datastore directory if it doesn't exist
  -P true/false     Set all watches paused (true) or active (false)

Add URLs on startup:
  -u URL            Add URL to watch (can be used multiple times)
  -u0 'JSON'        Set options for first -u URL (e.g. '{"processor":"text_json_diff"}')
  -u1 'JSON'        Set options for second -u URL (0-indexed)
  -u2 'JSON'        Set options for third -u URL, etc.
                    Available options: processor, fetch_backend, headers, method, etc.
                    See model/Watch.py for all available options

Recheck on startup:
  -r all            Queue all watches for recheck on startup
  -r UUID,...       Queue specific watches (comma-separated UUIDs)
  -r all N          Queue all watches, wait for completion, repeat N times
  -r UUID,... N     Queue specific watches, wait for completion, repeat N times

Batch mode:
  -b                Run in batch mode (process queue then exit)
                    Useful for CI/CD, cron jobs, or one-time checks
                    NOTE: Batch mode checks if Flask is running and aborts if port is in use
                    Use -p PORT to specify a different port if needed

逐项实测说明：

参数	实测说明
`-s`	启用 HTTPS，需配合环境变量 `SSL_CERT_FILE` / `SSL_PRIVKEY_FILE` 提供证书
`-h HOST`	监听地址。默认 `0.0.0.0`（全网卡）；放反向代理后建议 `-h 127.0.0.1` 只监听回环
`-p PORT`	监听端口，默认 5000。与环境变量 `PORT` 等效，命令行优先
`-d PATH`	数据目录，最重要参数，决定全部数据位置，必配
`-l LEVEL`	日志级别，默认 DEBUG（日志量大），生产建议 `-l INFO`
`-c`	启动时清理无引用的历史快照文件
`-C`	数据目录不存在时自动创建（实测首启日志 `No datastore found, creating new datastore`）
`-P true/false`	启动时把全部监控置为暂停/活跃，用于批量运维
`-u URL` / `-u0 'JSON'`	启动即添加监控，`-u0` 起的 JSON 参数可为对应 URL 指定 processor、fetch_backend 等
`-r all` / `-r UUID,...`	启动即入队重检；`-r all N` 形式可"检查完成后再来 N 轮"，适合迁移后快速补齐快照
`-b`	批处理模式：处理完队列即退出（配合定时任务做单次检查）；端口被占用会拒绝启动

生产服务常用组合（systemd ExecStart 实测值）：

/opt/changedetection/venv/bin/changedetection.io -d /opt/changedetection/data -p 5000 -C

五、环境变量详解

以下变量清单摘自 0.60.9 官方 compose.yml 注释原文，逐项给出取值与用法。pip（裸机）方式在 systemd 单元 [Service] 段用 Environment=KEY=value 配置；Compose 方式写在 environment: 段。

5.1 服务与监听

变量	默认	说明
`PORT`	5000	容器内监听端口，与 `-p` 等效（Compose 里别与 ports 映射混淆）
`LISTEN_HOST`	0.0.0.0	监听地址，与 `-h` 等效，IPv6 写 `::`
`LOGGER_LEVEL`	DEBUG	日志级别 TRACE/DEBUG/INFO/SUCCESS/WARNING/ERROR/CRITICAL，生产建议 INFO
`BASE_URL`	未设置	实例对外地址（如 `https://mon.example.com`），会拼进通知消息的差异链接
`USE_X_SETTINGS`	未设置	反代场景设 `1`，尊重 `proxy_set_header Host` 与 `X-Forwarded-Prefix`
`HIDE_REFERER`	未设置	设 `true` 隐藏 Referer，被监控站看不到来源地址
`SSL_CERT_FILE` / `SSL_PRIVKEY_FILE`	未设置	以 HTTPS 直接对外时的证书/私钥文件名，配合 `-s` 使用（证书文件挂载进容器）
`TZ`	未设置	重检调度时区，如 `Asia/Shanghai`（时区全表见 tz database）
`LC_ALL`	en_US.UTF-8	文本处理 locale，UTF-8 覆盖绝大多数场景
`DISABLE_VERSION_CHECK`	未设置	设 `true` 关闭版本检查与遥测上报（隐私场景）

5.2 抓取与网络

变量	默认	说明
`FETCH_WORKERS`	10	并行抓取 worker 数，监控量大时调大（受 CPU/内存约束）
`MINIMUM_SECONDS_RECHECK_TIME`	3	全局最小重检间隔（秒），覆盖所有监控设置的下限，设 0 禁用兜底
`PAGE_WATCH_LIMIT`	未设置	实例最多容纳监控数量，超出后 UI/API/导入均拒绝新增
`HTTP_PROXY` / `HTTPS_PROXY`	未设置	纯 requests 抓取的代理，如 `socks5h://10.10.1.10:1080`
`NO_PROXY`	未设置	代理排除列表，如 `localhost,192.168.0.0/24`
`PLAYWRIGHT_DRIVER_URL`	未设置	Playwright 渲染服务地址（`ws://browser-sockpuppet-chrome:3000`），设置后启用 Chrome 渲染后端
`PLAYWRIGHT_BYPASS_CSP`	true	对不支持 `Page.setBypassCSP` 的浏览器（如 Obscura）设为 `false`
`WEBDRIVER_URL`	未设置	旧版 Selenium WebDriver 地址；官方注释已标注弃用（不支持整页截图与自定义头），不建议新用
`ALLOW_FILE_URI`	False	设 true 允许监控 `file:///` 本地文件（有安全风险，慎开）
`ALLOW_IANA_RESTRICTED_ADDRESSES`	false	设 true 允许监控私有/保留网段（内网监控必开），实测验证见下
`SCREENSHOT_MAX_HEIGHT`	16000	整页截图最大高度（px），截图超高被裁剪；调大增加内存

环境变量生效性实测（ALLOW_IANA_RESTRICTED_ADDRESSES，systemd 方式）：单元文件加 Environment=ALLOW_IANA_RESTRICTED_ADDRESSES=true 后重启，确认注入：

systemctl show changedetection -p Environment

实测回显：

Environment=ALLOW_IANA_RESTRICTED_ADDRESSES=true

Compose 方式修改 environment: 后执行 docker compose up -d，出现 Recreate/Recreated 输出即已重建生效。

5.3 数据与扩展

变量	默认	说明
`EXTRA_PACKAGES`	未设置	启动时额外安装的 Python 插件包，空格分隔，如 `changedetection.io-osint-processor another-plugin`（插件生态见 changedetection.io/plugins）

5.4 AI / 补货监控

变量	默认	说明
`LLM_FEATURES_DISABLED`	未设置	设 `true` 关闭全部 LLM/AI 功能与提示
`LLM_RESTOCK_MAX_CONTENT_CHARS`	15000	AI 识别价格/库存时读取的页面文本上限，价格在页面深处可调大；本地模型（Ollama）建议同步把 `num_ctx` 提到 8192 以上
`LITELLM_FETCH_PRICING_FROM_GITHUB`	false	是否从 GitHub 拉取最新模型计价表（用于费用估算），默认 false 不出网

六、界面设置项详解（Settings 十大标签页）

Settings 页（右上角齿轮 → Settings）共 10 个标签页，以下锚点名与控件文案均为 0.60.9 实测原文。

6.1 General（general）

Time Between Check：全局默认检查间隔，Weeks/Days/Hours/Minutes/Seconds 五框组合（新建监控默认继承此值）；
Number of history items per watch to keep：每个监控保留的历史快照条数上限，超限后最旧的被清理（配合 -c 启动参数回收磁盘）；
Password：设置访问密码（设置后所有访问需登录；忘记密码时删除数据目录 changedetection.json 中的 password 字段可恢复匿名）。

6.2 Fetching（fetching）

Fetch Method：全局默认抓取后端——Basic fast Plaintext/HTTP Client（纯 HTTP，默认）或 WebDriver Chrome/Javascript（Chrome 渲染）；
Wait seconds before extracting text：抓取后等待秒数（等 JS 渲染完成），渲染监控常用 2~5 秒；
Number of fetch workers：与 FETCH_WORKERS 环境变量同源的并行抓取数；
Random jitter seconds ± check：检查时间随机抖动秒数（避免固定节奏被目标站识别）；
Requests timeout in seconds：单次抓取超时；
Default User-Agent overrides：默认 UA 与分后端 UA 覆盖（Plaintext requests 与浏览器后端分别设置）。

6.3 Notifications

全局默认通知配置：Notification URL List（一行一个 Apprise URL）、Notification Title / Body（Jinja2 模板，变量如 {{watch_url}}、{{diff}}）、Notification format（文本/HTML）、触发条件（Failures/Changed 等）。详见《changedetection.io 0.60.9 快速入门（添加监控到差异告警）》第七节。

6.4 API（api）

API token 展示与重置区：REST API 凭证，请求头 x-api-key 认证；
API access token security check enabled：启用 token 安全校验开关；
区块说明原文："Drive your changedetection.io via API"（链接官方 API 文档）；Restrict API access limit by using x-api-key header - required for the Chrome Extension to work（Chrome 扩展也依赖此 token）。

6.5 RSS（rss）

Hide muted watches from RSS feed：静音的监控不进 feed；
Number of changes to show in watch RSS feed：feed 内条数上限；
Enable RSS reader mode：阅读器模式（正文直接内嵌差异内容）；
RSS Content format 与 RSS "System default" template override：feed 正文格式与模板覆盖。

RSS 地址（实测）：http://127.0.0.1:5000/rss?token=<rss_access_token>，token 见数据目录 changedetection.json 的 settings.application.rss_access_token 字段（本实例实测值 80dadc72cf602324fd276e496cd91cac）。实测输出片段：

<?xml version='1.0' encoding='UTF-8'?>
<rss ... version="2.0"><channel><title>changedetection.io</title>...
<item><title>http://127.0.0.1:8000/status.json</title><link>http://127.0.0.1:5000/diff/909d2621-04cc-4604-8bef-878e5391d628</link>
<description><![CDATA[<pre>http://127.0.0.1:8000/status.json had a change.

(changed) 99.0
(into) 88.0
</pre>]]></description>

6.6 Global Filters（filters）

全局过滤器默认值（全局忽略文本/正则等），作用于所有监控；单监控可在编辑页覆盖。

6.7 CAPTCHA（proxies）

CAPTCHA/验证码应对与代理池配置：配置 Tor/Squid 等代理列表，给抓取分配出口；配合 proxies.json 数据文件使用。

6.8 Time（timedate）

时区与时间显示相关设置，影响界面展示与调度基准。

6.9 UI Options（ui-options）

界面行为：主题、每页显示条数、列表列展示开关等外观项。

6.10 AI（ai）

LLM 服务商选择（实测下拉选项原文）：anthropic / Google (Gemini) / Ollama / openai / OpenAI-compatible (vLLM, LM Studio, llama.cpp) / OpenRouter (200+ models)；配置 API Key 与（Ollama/自建端点才需要的）API Base URL。页面说明原文："The AI sees only a unified diff of what changed — never full page HTML. Low-cost models like gpt-4o-mini or Gemini Flash handle this well, typically fractions of a cent per check."（AI 只看差异文本，不看全页 HTML，成本极低）。

6.11 Info（info）

实例信息页：版本号、数据目录、schema 版本、监控统计等只读信息，排障时先看这里。

七、数据目录与主配置文件结构

7.1 目录结构（实测）

/opt/changedetection/data/
├── changedetection.json          # 全局主配置（界面设置、监控索引、通知、token）
├── changedetection-0-60-9.json   # 版本标记文件（当前 schema 对应版本）
├── secret.txt                    # 实例密钥
├── changedetection-backup-*.zip  # 内置备份功能的产物（如生成过）
├── 909d2621-04cc-4604-8bef-878e5391d628/   # 每个监控一个 UUID 目录
│   ├── watch.json                # 该监控的全部配置
│   ├── <sha1>.txt                # 历史快照（文件名为内容特征值）
│   └── last-checksum.txt         # 最近一次内容校验值
└── ed3d8844-.../tag.json         # 分组（tag）目录

7.2 changedetection.json 关键字段（实测）

{
  "app_guid": "111b8718-d54f-4a30-a694-99c557c09f18",
  "settings": {
    "application": {
      "api_access_token": "5521439027a85d13458e92c9c11b0cda",
      "api_access_token_enabled": true,
      "rss_access_token": "80dadc72cf602324fd276e496cd91cac"
    }
  }
}

api_access_token：REST API 凭证（首次安装自动生成，Settings → API 页可见）；
rss_access_token：RSS feed 的访问 token；
设置访问密码后此处出现 password 字段。

⚠️ 注意：changedetection.json 含 API token 等敏感信息，备份与传输时注意权限（数据目录默认 700 更安全）。

八、生产环境推荐配置模板

8.1 systemd（pip 安装）模板

[Unit]
Description=changedetection.io website change monitoring
After=network-online.target
Wants=network-online.target

[Service]
WorkingDirectory=/opt/changedetection
Environment=LOGGER_LEVEL=INFO
Environment=TZ=Asia/Shanghai
Environment=ALLOW_IANA_RESTRICTED_ADDRESSES=true
Environment=DISABLE_VERSION_CHECK=true
ExecStart=/opt/changedetection/venv/bin/changedetection.io -d /opt/changedetection/data -p 5000 -C
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

要点：-l 换成 LOGGER_LEVEL=INFO 降日志量；TZ 保证重检调度按本地时间；仅内网监控时保留 ALLOW_IANA_RESTRICTED_ADDRESSES=true。

8.2 Compose environment 模板

      environment:
        - LOGGER_LEVEL=INFO
        - TZ=Asia/Shanghai
        - PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000
        - ALLOW_IANA_RESTRICTED_ADDRESSES=true
        - BASE_URL=https://mon.example.com
        - FETCH_WORKERS=10
        - MINIMUM_SECONDS_RECHECK_TIME=3
        - DISABLE_VERSION_CHECK=true

要点：BASE_URL 一定要设成对外域名，通知里的差异链接才可点击；其余项按需增删。

九、常见问题（FAQ）

Q1：改了环境变量不生效？ 三个原因按序排查：① systemd 方式改后漏了 systemctl daemon-reload；② Compose 方式只 restart 未 up -d（environment 变更需要重建容器）；③ 同名参数同时存在时命令行 > 环境变量 > 默认值（如 -p 与 PORT）。

Q2：日志刷屏（DEBUG 量太大）？ -l INFO（或 LOGGER_LEVEL=INFO）后重启。实测 DEBUG 级别下每次抓取会输出完整队列与抓取细节，长期运行建议 INFO。

Q3：API key 忘了/泄露了怎么办？ Settings → API 页可重置（重置后旧 key 立即失效）；或直接编辑数据目录 changedetection.json 的 settings.application.api_access_token 字段后重启服务。

Q4：数据目录能放哪里？ 任意本地路径（-d 指定即可）；放 NFS/CIFS 等网络存储不推荐（快照写入频繁，锁与延迟易出问题）。磁盘规划按"监控数 × 历史条数 × 单页大小"估算，配合 General 页的历史条数上限与 -c 清理参数控制增长。

Q5：PORT 改了页面还是 5000？ PORT 是监听端口，客户端访问还要看端口映射（Compose ports:）与防火墙（ufw allow）。分层排查：容器内 curl -sI http://127.0.0.1:<PORT> → 宿主机映射 → 防火墙。

十、参考链接

官方 compose.yml（环境变量全集出处）：https://github.com/dgtlmoon/changedetection.io/blob/master/docker-compose.yml
REST API 文档：https://changedetection.io/docs/api_v1/index.html
反向代理 Wiki：https://github.com/dgtlmoon/changedetection.io/wiki/Running-changedetection.io-behind-a-reverse-proxy
配套文档：《changedetection.io 0.60.9 Ubuntu 22.04 安装指南》《changedetection.io 0.60.9 Docker Compose 部署指南》《changedetection.io 0.60.9 快速入门（添加监控到差异告警）》《changedetection.io 0.60.9 进阶实战与运维》