Apprise API 2.0 配置参数详解

Apprise API v2.0.2 全部环境变量参数详解：默认值实提自 settings 源码（标注行号），按服务基础/存储/附件/通知行为/安全认证/性能/Web 七组逐项解释，附生产配置模板与 FAQ（实测验证）。

Apprise通知自托管API2026/10/25

Apprise API 2.0 配置参数详解

目标：讲清 Apprise API v2.0.2 服务端的全部配置入口与参数语义——所有配置经环境变量注入，本文逐组解释每个参数的含义、默认值（标注源码行号）、取值约定与生产建议，并给出可直接套用的生产配置模板。所有默认值均实提自 v2.0.2 源码 apprise_api/core/settings/__init__.py 与 gunicorn.conf.py，命令与回显在 Ubuntu 22.04 裸机安装形态（见《Ubuntu 22.04 安装 Apprise API 2.0 指南》）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（jammy），x86_64
  • 软件版本：Apprise API v2.0.2（Apprise 库 2.1.0、Django 6.0.9、gunicorn 26.2.0）
  • 部署形态：裸机源码安装（《Ubuntu 22.04 安装 Apprise API 2.0 指南》），环境文件 /etc/apprise-api.env，systemd 托管
  • 参数定义源码：/opt/apprise-api/apprise_api/core/settings/__init__.py（下文行号均指该文件）、/opt/apprise-api/apprise_api/gunicorn.conf.py
  • 数据目录：/var/lib/apprise/{config,attach,plugin}

二、前置条件

  1. 已按安装篇完成部署并能访问服务：curl -s http://127.0.0.1:8000/status 返回 OK。
  2. 有 sudo 权限，可编辑 /etc/apprise-api.env 并 systemctl restart apprise-api。
  3. 了解两个基本事实：Apprise API 没有传统配置文件，全部服务端行为由环境变量决定；通知通道本身的配置（Apprise URL 列表）是另一层数据，存于 APPRISE_CONFIG_DIR 下的 {key}.cfg，不在本文范围。

三、参数查看与修改方式

3.1 修改方式：环境变量文件 + 重启

裸机安装形态下，所有参数集中在 /etc/apprise-api.env（systemd 经 EnvironmentFile= 注入），修改后重启生效：

sudo vi /etc/apprise-api.env        # 编辑变量
sudo systemctl restart apprise-api  # 重启生效

env 文件语法要点：每行一个 KEY=VALUE；值不需要引号（写了会成为值的一部分）；不支持行内注释与 export 前缀；修改必须重启服务，没有热加载。

3.2 查看运行中进程的生效值

配置是否真正注入，以运行进程的环境变量为准。查 gunicorn 主进程的实际生效值：

PID=$(pgrep -f "gunicorn core.wsgi" | head -1)
sudo tr '\0' '\n' < /proc/$PID/environ | grep -E "^(APPRISE_|ALLOWED_HOSTS|TZ)" | sort

ALLOWED_HOSTS=*
APPRISE_ATTACH_DIR=/var/lib/apprise/attach
APPRISE_CONFIG_DIR=/var/lib/apprise/config
APPRISE_DEFAULT_FORMAT=text
APPRISE_PLUGIN_PATHS=/var/lib/apprise/plugin
APPRISE_STATEFUL_MODE=simple
APPRISE_WORKER_COUNT=3
TZ=Asia/Shanghai

若这里看不到刚改的变量，说明 env 文件未生效（多半是忘了重启，或改错了文件路径）。

3.3 取值类型约定

源码中参数按三类解析，写值时遵守对应约定：

类型解析函数合法取值示例参数
布尔env_boolyes/no、true/false、1/0（源码注释明确支持这三种写法）APPRISE_AUTH_REQUIRED、APPRISE_ADMIN
枚举env_choice限定列表，只需写首字母（first_character=True，大小写不敏感）APPRISE_STATEFUL_MODE（h/s/d）、APPRISE_STORAGE_MODE（a/f/m）、APPRISE_DEFAULT_THEME（l/d）
整数env_int纯数字，部分带上下界钳制APPRISE_ATTACH_SIZE、APPRISE_WORKER_COUNT

⚠️ 注意：APPRISE_CONFIG_MAX_LENGTH 单位是 KB（源码 L375-376：env_int(..., 512) * 1024），而 APPRISE_ATTACH_SIZE 单位是 MB（L304），单位不统一是易错点。

四、参数总览

全部参数按职能分七组（默认值均为 v2.0.2 源码实提值）：

分组参数（默认值）
服务基础TZ（Etc/UTC）、ALLOWED_HOSTS（*）、APPRISE_BASE_URL（空）、APPRISE_DEFAULT_CONFIG_ID（apprise）、APPRISE_WEBHOOK_URL（空）
存储与持久化APPRISE_CONFIG_DIR（BASE_DIR/var/config）、APPRISE_STORAGE_DIR（CONFIG_DIR/store）、APPRISE_STORAGE_PRUNE_DAYS（30）、APPRISE_STORAGE_UID_LENGTH（8）、APPRISE_STORAGE_MODE（auto）、APPRISE_STATEFUL_MODE（hash）、APPRISE_AUTH_PRUNE_SECONDS（2592000）
附件APPRISE_ATTACH_DIR（BASE_DIR/var/attach）、APPRISE_ATTACH_SIZE（200MB）、APPRISE_ATTACH_ALLOW_URL（）、APPRISE_ATTACH_REJECT_URL（127.0. localhost*）、APPRISE_MAX_ATTACHMENTS（6）、APPRISE_UPLOAD_MAX_MEMORY_SIZE（3MB）、APPRISE_STREAM_*（见 5.3）
通知行为APPRISE_DEFAULT_FORMAT（空）、APPRISE_STATELESS_MODE（enabled）、APPRISE_DENY_SERVICES（windows,dbus,gnome,macosx,syslog）、APPRISE_ALLOW_SERVICES（空）、APPRISE_RECURSION_MAX（1）、APPRISE_ALLOW_TEMPLATES（yes）、APPRISE_PLUGIN_PATHS（BASE_DIR/var/plugin）、APPRISE_INTERPRET_EMOJIS（自动）、APPRISE_HTTP_REDIRECTS（yes）
安全与认证APPRISE_AUTH_REQUIRED（no）、APPRISE_USER/APPRISE_PASSWORD（空）、APPRISE_BASIC_AUTH_REALM（Apprise API）、APPRISE_WEB_AUTH_MAX_AGE（24h）、APPRISE_CONFIG_LOCK（no）、APPRISE_CONFIG_MAX_LENGTH（512KB）
性能APPRISE_WORKER_COUNT（CPU×2+1）、APPRISE_WORKER_TIMEOUT（300）、APPRISE_WORKER_MAX_REQUESTS（1000）、APPRISE_WORKER_MAX_REQUESTS_JITTER（50）
Web 管理器APPRISE_ADMIN（yes）、APPRISE_API_ONLY（no）、APPRISE_DEFAULT_THEME（light）

五、核心参数分类详解

5.1 服务基础参数

TZ（L56，默认 Etc/UTC）：服务时区，影响日志时间与通知模板中的时间戳。国内服务器设 Asia/Shanghai。

ALLOWED_HOSTS（L83，默认 *，空格分隔多个）：Django 允许的 HTTP Host 头。默认 * 放行一切，方便但宽松；生产环境应改为实际域名，如 alert.example.com 192.168.1.10。配错时 Django 返回 400 DisallowedHost（见常见问题 Q3）。

APPRISE_BASE_URL（默认空）：服务部署在子路径时的前缀（如 /apprise），配合反代使用；根路径部署保持为空。

APPRISE_DEFAULT_CONFIG_ID（L235，默认 apprise）：Web 管理器与部分端点的默认配置键名。

APPRISE_WEBHOOK_URL（L259，默认空）：设置后，每次通知执行结果会再 POST 一份到该 URL，适合接审计/日志系统。

5.2 存储与持久化参数

APPRISE_CONFIG_DIR（L262，默认 BASE_DIR/var/config）：有状态配置目录。裸机部署应显式指向 /var/lib/apprise/config 这类数据分区路径。

APPRISE_STORAGE_DIR（L265，默认 CONFIG_DIR/store）：持久化存储区，保存通知执行状态与附件引用。

APPRISE_STORAGE_PRUNE_DAYS（L268，默认 30）：持久化存储保留天数，超期自动清理。

APPRISE_STORAGE_UID_LENGTH（L275-280，默认 8，合法区间 2-64）：存储键 ID 长度。

APPRISE_STORAGE_MODE（L293，默认 auto，可选 auto/flush/memory）：持久化写入策略——auto 每次通知执行后写盘；flush 尽可能频繁写盘（IO 高，但并发调用同一配置键时状态更同步）；memory 关闭持久化。枚举只需首字母（a/f/m）。

APPRISE_STATEFUL_MODE（L534，默认 hash，可选 hash/simple/disabled）：有状态配置的落盘策略，是部署期最重要的决策之一。

💡 技术拓展：三档策略对比——

模式键名与文件映射适用
hash（默认）键名哈希后映射文件，目录不暴露键名键名含敏感信息的多租户场景
simple键名直接对应 {key}.cfg，纯文本可读小团队，要手工编辑/直接备份
disabled关闭有状态，仅无状态 /notify纯转发，零存储

本专栏部署篇均选 simple：配置文件可读、可打包备份。

APPRISE_AUTH_PRUNE_SECONDS（L272，默认 2592000 即 30 天）：清理闲置认证锁的周期；有配置在用的锁永远保留。

5.3 附件参数

APPRISE_ATTACH_DIR（L301，默认 BASE_DIR/var/attach）：附件上传目录。

APPRISE_ATTACH_SIZE（L304，默认 200，单位 MB）：单请求附件总大小上限。调大时前置 nginx 的 client_max_body_size 必须同步调大，否则先被 nginx 以 413 拦截。

APPRISE_ATTACH_ALLOW_URL / APPRISE_ATTACH_REJECT_URL（L342/L339，默认 * 与 127.0.* localhost*）：附件若以 URL 形式引用（而非上传文件），允许/拒绝抓取的地址模式。默认拒绝本机地址，防 SSRF 打内网；生产环境建议按需收紧 ALLOW 到对象存储域名。

APPRISE_MAX_ATTACHMENTS（L578，默认 6）：单请求附件个数上限。

APPRISE_UPLOAD_MAX_MEMORY_SIZE（L347，默认 3MB）：小于该体积的上传直接放内存处理。

APPRISE_STREAM_*（L354-370）：大请求体流式处理系列——APPRISE_STREAM_MEMORY_SIZE（2MB，内存缓冲）、APPRISE_STREAM_DISK_SIZE（256MB，磁盘缓冲上限）、APPRISE_STREAM_WORKER_COUNT（4）、APPRISE_STREAM_QUEUE_SIZE（8）、APPRISE_STREAM_RETRY_AFTER（15s）、APPRISE_STREAM_HEARTBEAT（15s）。一般保持默认，仅超大附件场景需要调整。

生效值可从健康检查端点直接印证（attach_size 单位字节，209715200 = 200MB）：

curl -s -H "Accept: application/json" http://127.0.0.1:8000/status

{"config_lock": false, "attach_lock": false, "stateful_enabled": true, "stateless_enabled": true, "degraded": false, "max_attachments": 6, "attach_size": 209715200, "status": {"persistent_storage": true, "can_write_config": true, "can_write_attach": true, "details": ["OK"]}, "privilege": "admin"}

5.4 通知行为参数

APPRISE_DEFAULT_FORMAT（L608，默认空）：通知正文的默认格式声明（text/markdown/html）。设 text 后调用方不传 format 时按纯文本处理，行为最可预期。

APPRISE_STATELESS_MODE（L546，默认 enabled）：置 no/disabled 后拒绝无状态 /notify（不带配置键的直发），强制所有流量走预存配置键，便于管控出口。

APPRISE_DENY_SERVICES（L553，默认 windows,dbus,gnome,macosx,syslog）：禁用的通知通道列表（逗号分隔 schema）。默认禁掉的都是「本机桌面/系统总线」类通道（在服务器上无意义）。写一个 schema 即连带其变体（如 xml 同时禁 xmls）。

APPRISE_ALLOW_SERVICES（L561，默认空）：白名单，优先级高于 DENY。一旦设置，未列出的通道全部被拒——金融/政企环境出口管控的利器，如 APPRISE_ALLOW_SERVICES=mailto,json,dingtalk。

APPRISE_RECURSION_MAX（L567，默认 1）：apprise:// 自引用通知的递归深度上限，防循环调用打爆自己。

APPRISE_ALLOW_TEMPLATES（L571，默认 yes）：允许在配置中使用模板语法。

APPRISE_PLUGIN_PATHS（默认 BASE_DIR/var/plugin，逗号分隔多路径）：自定义通知插件（Python 文件）扫描路径。

APPRISE_INTERPRET_EMOJIS（L597，默认自动）：是否把 :smile: 这类短码转成 emoji；默认按通道能力自动决定。

APPRISE_HTTP_REDIRECTS（L604，默认 yes）：通知请求遇到 301/302 时是否跟随。

5.5 安全与认证参数

APPRISE_AUTH_REQUIRED / APPRISE_USER / APPRISE_PASSWORD（L400-407，默认 no/空/空）：全局 Basic Auth 开关与管理员凭据。AUTH_REQUIRED=yes 后所有 API 与 Web 管理器都要求认证。生产环境必须开启——默认无认证意味着任何能访问 8000 端口的人都能借你的通道发通知。开启示例（演示账号 admin / q1w2e3r4）：

sudo tee -a /etc/apprise-api.env <<'EOF'
APPRISE_AUTH_REQUIRED=yes
APPRISE_USER=admin
APPRISE_PASSWORD=q1w2e3r4
EOF
sudo systemctl restart apprise-api
curl -s http://127.0.0.1:8000/status
curl -s -u admin:q1w2e3r4 http://127.0.0.1:8000/status

Access Denied
OK

APPRISE_BASIC_AUTH_REALM（默认 Apprise API）：Basic Auth 弹窗显示的域名字符串。

APPRISE_WEB_AUTH_MAX_AGE（L509，默认 24 小时）：Web 管理器登录会话有效期。

APPRISE_CONFIG_LOCK（L396，默认 no）：置 yes 后冻结配置变更（/add、/del 等被拒），/status 中 config_lock 变 true，适合冻结期防误改。

APPRISE_CONFIG_MAX_LENGTH（L375，默认 512，单位 KB）：单个配置键内容长度上限。

5.6 性能参数（gunicorn worker）

来自 gunicorn.conf.py，经环境变量覆盖：

参数默认值说明
APPRISE_WORKER_COUNTCPU×2+1gevent worker 进程数
APPRISE_WORKER_TIMEOUT300worker 静默超时秒数，超时被杀重启
APPRISE_WORKER_MAX_REQUESTS1000单 worker 处理满该请求数后重启（防内存泄漏累积）
APPRISE_WORKER_MAX_REQUESTS_JITTER50上一条的随机抖动，防所有 worker 同时重启

默认 worker 数按 CPU×2+1 计算，16 核机器会拉起 33 个 worker、闲时也有数百 MB 常驻内存。告警网关属低频流量，小规格机器建议显式调小到 1～3。调整后确认进程数：

pgrep -fc "gunicorn core.wsgi"

4

（1 主进程 + 3 worker，与 APPRISE_WORKER_COUNT=3 一致。）

5.7 Web 管理器参数

APPRISE_ADMIN（L594，默认 yes）：置 no 关闭 Web 配置管理器（浏览器首页不可用，API 不受影响）。

APPRISE_API_ONLY（L591，默认 no）：置 yes 后服务只保留 API 端点，比 ADMIN=no 更彻底（连静态资源也不服务），纯后端嵌入场景使用。

APPRISE_DEFAULT_THEME（L249，默认 light，可选 light/dark）：Web 管理器默认主题，用户可在页面自行切换。

六、生产配置模板

适用场景：2C4G 虚拟机、告警类低频通知流量、启用认证、simple 落盘。在 /etc/apprise-api.env 写入：

sudo tee /etc/apprise-api.env <<'EOF'
# 路径
APPRISE_CONFIG_DIR=/var/lib/apprise/config
APPRISE_ATTACH_DIR=/var/lib/apprise/attach
APPRISE_PLUGIN_PATHS=/var/lib/apprise/plugin
# 行为
APPRISE_STATEFUL_MODE=simple
APPRISE_DEFAULT_FORMAT=text
APPRISE_WORKER_COUNT=2
ALLOWED_HOSTS=alert.example.com
TZ=Asia/Shanghai
# 安全
APPRISE_AUTH_REQUIRED=yes
APPRISE_USER=admin
APPRISE_PASSWORD=q1w2e3r4
APPRISE_ATTACH_REJECT_URL=127.0.* localhost* 10.* 192.168.*
EOF
sudo systemctl restart apprise-api

模板解读：worker 固定 2 匹配 2C4G 小规格；ALLOWED_HOSTS 收紧到实际域名；附件 URL 抓取额外拒掉内网网段（防 SSRF）；认证必开。重启后逐项验证：

curl -s -u admin:q1w2e3r4 -H "Accept: application/json" http://127.0.0.1:8000/status

{"config_lock": false, "attach_lock": false, "stateful_enabled": true, "stateless_enabled": true, "degraded": false, "max_attachments": 6, "attach_size": 209715200, "status": {"persistent_storage": true, "can_write_config": true, "can_write_attach": true, "details": ["OK"]}, "privilege": "admin"}

details: ["OK"] 且 privilege: admin，模板生效。

七、常见问题

Q1：改了 /etc/apprise-api.env 不生效？ A：两个高频原因：忘了 systemctl restart apprise-api（env 无热加载）；或在值两侧加了引号（env 文件语法里引号会成为值的一部分）。用 3.2 的 /proc/<pid>/environ 方法核对进程实际拿到的值。

Q2：APPRISE_STATEFUL_MODE=disabled 后 /add 报错？ A：属预期行为——disabled 关闭了全部有状态端点，/add、/del、/notify/{key} 均不可用，只剩无状态 /notify。同样 STATELESS_MODE 关闭后无状态 /notify 返回拒绝。两路至少留一路，否则服务没有可用发送入口。

Q3：浏览器访问报 400 Bad Request（DisallowedHost）？ A：ALLOWED_HOSTS 不含当前访问用的主机名/IP。把访问地址加进去（空格分隔多个），或临时改回 * 验证，确认后再收紧。

Q4：大附件通知返回 413？ A：两层限制要同时看——应用侧 APPRISE_ATTACH_SIZE（默认 200MB）与前置 nginx 的 client_max_body_size。谁小谁先生效；调大附件上限时两边同步调整。

Q5：想只放通邮件和 Webhook，禁掉其他所有通道？ A：用白名单 APPRISE_ALLOW_SERVICES=mailto,json（优先级高于 DENY 列表），未列出的 schema 一律拒绝。DENY 适合黑名单式补充，如追加 APPRISE_DENY_SERVICES=windows,dbus,gnome,macosx,syslog,sms。

Q6：闲置时内存占用偏高？ A：基本是 worker 过多。默认 CPU×2+1 在多核机器上很夸张，把 APPRISE_WORKER_COUNT 调到 1～3，重启后用 5.6 的 pgrep -fc 确认进程数符合预期。

八、参考链接