Ubuntu 22.04 安装 Apprise API 2.0 指南

在 Ubuntu 22.04 从零安装 Apprise API v2.0.2：deadsnakes 装 Python 3.12、GitHub 源码 + venv 在线安装与 36 个 wheel 离线安装两方案，systemd 托管 gunicorn + nginx 反代 8000，含端到端发送验证与卸载清理（全量实测）。

Apprise通知自托管Ubuntu2026/10/25

Ubuntu 22.04 安装 Apprise API 2.0 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Apprise API v2.0.2（自托管通知网关，对应 Apprise 库 v2.1.0），给出在线源码安装与离线 wheel 包安装两种方案，含 systemd 托管、nginx 反向代理与发送验证。本文所有命令与回显均已在 Ubuntu 22.04.5 LTS（x86_64）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（jammy），x86_64
  • 系统自带 Python：3.10.12；实际运行用 Python：3.12.15（deadsnakes PPA）
  • 软件版本：Apprise API v2.0.2（git tag）、Apprise 库 2.1.0、Django 6.0.9、gunicorn 26.2.0、gevent 26.9.0、nginx 1.18.0、pip 26.2.2
  • 安装路径：源码 /opt/apprise-api、虚拟环境 /opt/apprise-api/venv
  • 数据目录：/var/lib/apprise/{config,attach,plugin}；环境文件 /etc/apprise-api.env
  • 服务形态：systemd 托管 gunicorn（127.0.0.1:8001）+ nginx 反代对外（0.0.0.0:8000）
  • 运行账号：专用系统用户 apprise

💡 说明：Apprise 生态有「Python 库」与「HTTP API 服务」两个仓库，本文安装的是后者（caronc/apprise-api），即独立部署的通知网关服务；只想在 Python 代码里发通知的读者直接用 pip install apprise 即可，无需本文。生态定位与选型见《Apprise 介绍与选型指南》。

二、前置条件

开始安装前确认以下条件满足：

  1. 一台 Ubuntu 22.04 服务器，有 sudo 权限与 systemd（systemctl is-system-running 返回 running）。
  2. 磁盘剩余空间 ≥ 1GB（源码 + 依赖约 300MB，离线方案另需 23MB wheel 包）。
  3. 在线方案要求能访问 PyPI 与 github.com（访问受限时按 8.2 走代理，或直接选用第五章离线方案）。
  4. 8000 端口未被占用（对外服务端口，可用 ss -ltn | grep :8000 预查）。

查看系统版本确认目标系统：

lsb_release -a

Distributor ID:	Ubuntu
Description:	Ubuntu 22.04.5 LTS
Release:	22.04
Codename:	jammy

三、版本选型说明

Apprise API 以 git tag 发布（无 deb 包、无 PyPI 包），版本与 Apprise 库版本相互独立。实测关键版本事实（2026-10-25 实查）：

组件版本说明
Apprise API（服务端）v2.0.2当前最新稳定 tag（2026-09-30 发布），本文安装目标
Apprise 库（依赖）2.1.0由服务端 requirements.txt 锁定 apprise == 2.1.0
Python≥ 3.11依赖 slixmpp ≥ 1.16.0 要求 Python ≥ 3.11，Ubuntu 22.04 自带 3.10 不可用
Django6.0.9由 requirements 中 django < 7 自动取最新 6.x

⚠️ 注意：Ubuntu 22.04 自带的 Python 3.10.12 不能直接运行 Apprise API 2.0——其依赖 slixmpp >= 1.16.0 要求 Python ≥ 3.11，强行用 3.10 创建虚拟环境安装会在解析依赖时报错退出。正确做法是按下文 4.2 通过 deadsnakes PPA 安装 Python 3.12。

四、在线源码安装方案（A：官方 GitHub + PyPI）

4.1 方案说明

官方推荐的裸机形态：从 GitHub 克隆 release tag 源码，用 Python 虚拟环境安装 requirements.txt 锁定的依赖，gunicorn 以 gevent 异步 worker 运行 Django 应用，nginx 前置反代。适合可联网服务器，升级方便（git checkout 新 tag + 重装依赖）。

4.2 基础环境安装

安装 git、nginx 与 Python 3.12（deadsnakes PPA 是 Ubuntu 上安装新版 Python 的标准渠道）：

sudo apt update
sudo apt install -y software-properties-common git nginx
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.12 python3.12-venv

验证两个 Python 版本并存（系统 3.10 保持不动，运行时用 3.12）：

python3 --version
python3.12 --version

Python 3.10.12
Python 3.12.15

4.3 创建服务用户与数据目录

创建专用系统用户与数据目录，避免以 root 运行服务：

sudo useradd --system --home /var/lib/apprise --shell /usr/sbin/nologin apprise
sudo mkdir -p /var/lib/apprise/config /var/lib/apprise/attach /var/lib/apprise/plugin
sudo chown -R apprise:apprise /var/lib/apprise

三个目录的用途：config 存有状态通知通道配置（每个配置键一个 .cfg 文件）；attach 存通知附件上传；plugin 放自定义通知插件。

4.4 获取 v2.0.2 源码

从 GitHub 克隆 v2.0.2 tag（浅克隆即可）：

cd /opt
sudo git clone --branch v2.0.2 --depth 1 https://github.com/caronc/apprise-api.git

⚠️ 网络说明：本次实测时服务器直连 github.com 443 端口被拒绝（连接重置），已改用代理完成克隆：sudo git -c http.proxy=http://192.168.1.62:7897 clone --branch v2.0.2 --depth 1 https://github.com/caronc/apprise-api.git。国内服务器访问 GitHub 不稳定属常见情况，遇到超时可换镜像站或代理后重试。

确认版本落点：

cd /opt/apprise-api
sudo git describe --tags
sudo git log -1 --format="%H %cs %s"

v2.0.2
308498f6f00389420c998c12019cceed315909f1 2026-10-24 bumped version to v2.0.2 to support Apprise v2.1.0

4.5 创建虚拟环境并安装依赖

用 Python 3.12 建 venv，按官方 requirements.txt 安装（锁定 apprise==2.1.0、django<7、gunicorn[gevent]、gevent、requests 及各通知服务依赖）：

cd /opt/apprise-api
sudo python3.12 -m venv venv
sudo ./venv/bin/pip install --upgrade pip
sudo ./venv/bin/pip install -r requirements.txt

验证核心组件版本：

sudo /opt/apprise-api/venv/bin/pip list | grep -iE "^(apprise|Django|gunicorn|gevent) "

apprise            2.1.0
Django             6.0.9
gevent             26.9.0
gunicorn           26.2.0

💡 技术拓展：Python 应用的依赖隔离方案对比——

方案特点适用
venv（本文）标准库自带、轻量、与系统 Python 完全隔离单机服务部署
conda带跨语言包管理与多环境数据科学栈
pipx面向「命令行应用」的隔离安装CLI 工具
系统直装零隔离，易污染系统 Python不推荐

本文用 venv：官方文档推荐路径，无额外组件依赖。

4.6 环境变量配置

创建环境文件 /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=3
ALLOWED_HOSTS=*
TZ=Asia/Shanghai
EOF

逐项说明：

变量本文取值说明
APPRISE_CONFIG_DIR/var/lib/apprise/config有状态配置目录（每键一个 .cfg）
APPRISE_ATTACH_DIR/var/lib/apprise/attach附件上传目录
APPRISE_PLUGIN_PATHS/var/lib/apprise/plugin自定义通知插件扫描路径
APPRISE_STATEFUL_MODEsimple配置键直接对应 {key}.cfg 文件，可读可手工编辑；另有 hash（键名哈希落盘，默认）/disabled（关闭有状态）
APPRISE_DEFAULT_FORMATtext通知正文默认按纯文本处理（可选 text/markdown/html）
APPRISE_WORKER_COUNT3gunicorn worker 数；默认 CPU×2+1，小规格机器建议显式调小
ALLOWED_HOSTS*Django 允许的 Host 头；生产环境应改为实际域名（空格分隔）
TZAsia/Shanghai服务时区

完整参数清单与默认值见本专栏《Apprise API 2.0 配置参数详解》。

4.7 systemd 托管

创建服务单元 /etc/systemd/system/apprise-api.service：

sudo tee /etc/systemd/system/apprise-api.service <<'EOF'
[Unit]
Description=Apprise API Notification Gateway
After=network.target

[Service]
Type=simple
User=apprise
Group=apprise
EnvironmentFile=/etc/apprise-api.env
WorkingDirectory=/opt/apprise-api/apprise_api
ExecStart=/opt/apprise-api/venv/bin/gunicorn core.wsgi:application --bind 127.0.0.1:8001 --workers 3 --worker-class gevent
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

源码属 root、运行属 apprise，把数据目录权限再确认一次后启动并设开机自启：

sudo chown -R apprise:apprise /var/lib/apprise
sudo systemctl daemon-reload
sudo systemctl enable apprise-api
sudo systemctl start apprise-api

查看服务状态：

systemctl status apprise-api --no-pager | head -6

● apprise-api.service - Apprise API Notification Gateway
     Loaded: loaded (/etc/systemd/system/apprise-api.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-25 03:27:28 UTC; 1min 12s ago
   Main PID: 7125 (gunicorn)
      Tasks: 5 (limit: 3612)
     Memory: 136.9M

此时 gunicorn 只监听 127.0.0.1:8001，尚不能从外部访问，下一节用 nginx 反代对外。

4.8 nginx 反向代理

创建站点配置 /etc/nginx/sites-available/apprise-api：静态资源 /s/ 直接由 nginx 服务，其余请求转发给 gunicorn：

sudo tee /etc/nginx/sites-available/apprise-api <<'EOF'
server {
    listen 8000;
    server_name _;

    client_max_body_size 210m;

    # 静态资源（Web 配置管理器）
    location /s/ {
        alias /opt/apprise-api/apprise_api/static/;
        expires 7d;
    }

    # 其余请求全部反代给 gunicorn
    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}
EOF
sudo ln -s /etc/nginx/sites-available/apprise-api /etc/nginx/sites-enabled/apprise-api

⚠️ 注意：client_max_body_size 210m 必须不小于附件上限（默认 200MB），否则大附件通知会被 nginx 以 413 拦截。静态资源 alias 路径末尾的 / 不可省略。

校验配置并启动：

sudo nginx -t
sudo systemctl enable nginx
sudo systemctl start nginx

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

确认端口监听符合预期（8001 仅回环、8000 对外）：

ss -ltnp | grep -E ":8000|:8001"

LISTEN 0 2048 127.0.0.1:8001 0.0.0.0:* users:(("gunicorn",...))
LISTEN 0  511   0.0.0.0:8000 0.0.0.0:* users:(("nginx",...))

4.9 验证运行

健康检查（JSON 与纯文本两种形式）：

curl -s -H "Accept: application/json" http://127.0.0.1:8000/status
curl -s 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"}
OK

stateful_enabled/stateless_enabled 均为 true，说明两种通知模式都可用。

浏览器访问 http://<服务器IP>:8000/ 可打开 Web 配置管理器。也可以先做一次端到端发送验证：在本机 8433 端口起一个临时 HTTP 接收器模拟通知目标（把下面脚本存为 /root/webhook_receiver.py 后用 nohup python3 /root/webhook_receiver.py > /var/log/webhook-receiver.log 2>&1 & 后台运行）：

from http.server import BaseHTTPRequestHandler, HTTPServer

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        l = int(self.headers.get("Content-Length", 0))
        body = self.rfile.read(l)
        print("RECEIVED path=%s body=%s" % (self.path, body.decode()), flush=True)
        self.send_response(200)
        self.end_headers()
        self.wfile.write(b"{}")
    def log_message(self, *a):
        pass

HTTPServer(("0.0.0.0", 8433), H).serve_forever()

通过无状态接口发一条测试通知（json:// 是通用 JSON Webhook 通道，把通知以 JSON POST 到目标地址）：

curl -s -X POST -d "urls=json://127.0.0.1:8433/hook&title=Test Title&body=hello apprise&type=success" http://127.0.0.1:8000/notify

2026-10-25 03:24:24,324 - INFO - Notifying 1 service(s).
2026-10-25 03:24:24,328 - INFO - Sent JSON POST notification.

接收器日志确认投递内容：

tail -1 /var/log/webhook-receiver.log

RECEIVED path=/hook body={"version": "1.0", "title": "Test Title", "message": "hello apprise", "attachments": [], "type": "success"}

至此方案 A 安装完成：8000 端口对外提供 API 与 Web 管理器，通知可正常投递。各 HTTP 端点（有状态配置管理、标签路由、附件上传、认证等）的完整用法见本专栏《Apprise API 2.0 API 使用详解》。

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

5.1 方案说明

内网/断网服务器无法访问 PyPI 时，先在一台可联网的同版本机器（同为 Ubuntu 22.04 + Python 3.12）上用 pip download 拉齐全部 wheel 包，拷贝到离线机后用 --no-index 本地安装。Apprise API 全量依赖仅 36 个 wheel 共 23MB，离线化成本很低。

5.2 联网机下载依赖包

在可联网机器上准备 Python 3.12 环境后（同 4.2），下载源码与全部 wheel：

cd /opt
sudo git clone --branch v2.0.2 --depth 1 https://github.com/caronc/apprise-api.git
cd apprise-api
sudo python3.12 -m pip download -r requirements.txt -d /opt/apprise-offline --only-binary=:all:

实测得到 36 个 wheel 包、合计 23MB：

ls /opt/apprise-offline/ | head -5
ls /opt/apprise-offline/ | wc -l
du -sh /opt/apprise-offline/

PGPy-0.5.4-py2.py3-none-any.whl
aiodns-4.0.4-py3-none-any.whl
apprise-2.1.0-py3-none-any.whl
asgiref-3.13.0-py3-none-any.whl
certifi-2026.10.23-py2.py3-none-any.whl
36
23M	/opt/apprise-offline/

⚠️ 注意：--only-binary=:all: 强制只用预编译 wheel，避免离线机编译失败。离线机的 Python 次版本号（3.12）与操作系统发行版必须与下载机一致，否则含 C 扩展的包（如 cffi、cryptography）会因 ABI 不匹配无法安装。

5.3 离线机安装

把 /opt/apprise-api（源码）与 /opt/apprise-offline（wheel 包）整体拷贝到离线机后，在离线机上执行：

cd /opt/apprise-api
sudo python3.12 -m venv venv
sudo ./venv/bin/pip install --no-index --find-links /opt/apprise-offline -r requirements.txt

--no-index 表示完全不访问 PyPI，全部从本地目录解析。实测安装过程数秒内完成，验证方式与 4.5 相同（pip list 应看到 apprise 2.1.0 / Django 6.0.9）。

5.4 后续步骤

离线方案与在线方案仅在「依赖获取」环节不同，用户与目录创建（4.3）、环境文件（4.6）、systemd 托管（4.7）、nginx 反代（4.8）与验证（4.9）完全相同，照第四章对应小节执行即可。

六、方案对比与选择建议

维度方案 A：在线源码安装方案 B：离线 wheel 包安装
是否需要联网安装时需要（GitHub + PyPI）目标机完全不需要
依赖获取pip 在线解析联网机预下载 36 个 wheel（23MB）
安装耗时依赖下载约 1–2 分钟本地安装数秒
升级方式git checkout 新 tag + pip 重装重新走一遍打包/拷贝流程
适用场景可联网的生产/测试服务器内网隔离、安全域服务器

选择建议：能联网选方案 A，链路最短、升级最方便；目标机断网但有同版本联网中转机时选方案 B。若倾向容器化部署（官方镜像一份 compose 文件拉起，免装 Python 环境），另见本专栏《Apprise API Docker Compose 部署指南》。

七、配置说明

  1. 配置载体：Apprise API 服务端全部由环境变量配置（见 4.6 表格），B1 安装形态经 /etc/apprise-api.env 注入，改动后 sudo systemctl restart apprise-api 生效。
  2. 通知通道配置：有状态模式下每个配置键对应 /var/lib/apprise/config/<key>.cfg 纯文本文件（每行一条 Apprise URL，可手工编辑，权限 600 属 apprise 用户），也可通过 API 或 Web 管理器维护；实测落盘形态：
ls -la /var/lib/apprise/config/
cat /var/lib/apprise/config/myalerts.cfg

-rw------- 1 apprise apprise 85 Oct 25 02:51 myalerts.cfg
drwxr-xr-x 3 apprise apprise 4096 Oct 25 02:40 store
json://127.0.0.1:8433/hook?method=POST&overflow=upstream&retry=0&wait=0.5&optional=no
  1. 升级方法：cd /opt/apprise-api && sudo git fetch --tags && sudo git checkout <新tag>，然后 sudo ./venv/bin/pip install -U -r requirements.txt，最后 sudo systemctl restart apprise-api。降级同理 checkout 旧 tag。多版本管理可用多个 /opt/apprise-api-<版本> 目录 + 独立 venv 并存，切换 systemd 的 WorkingDirectory/ExecStart 路径即可。
  2. 命令行工具：依赖安装后 venv 内自带 apprise CLI（来自 apprise 库），可独立验证 URL 拼写，如 sudo /opt/apprise-api/venv/bin/apprise --version 输出 Apprise v2.1.0。

八、常见问题

Q1：用系统自带 Python 3.10 建 venv，pip install 报依赖解析失败？ A：requirements.txt 中 slixmpp >= 1.16.0 要求 Python ≥ 3.11，Ubuntu 22.04 自带 3.10.12 不满足。按 4.2 安装 Python 3.12 并重新创建 venv 即可，不要试图降级 slixmpp（会带出一连串兼容问题）。

Q2：git clone github.com 超时或连接被拒绝？ A：国内网络访问 GitHub 不稳定。可换代理：git -c http.proxy=http://<代理地址>:<端口> clone ...；或用 GitHub 镜像站。本文实测时直连被拒、走代理成功。同理 pip 慢可加 -i https://pypi.tuna.tsinghua.edu.cn/simple 走国内镜像。

Q3：浏览器访问 8000 报 502 Bad Gateway？ A：先查后端是否存活 systemctl status apprise-api，再查 ss -ltn | grep 8001 确认 gunicorn 在监听；nginx 错误日志在 /var/log/nginx/error.log。常见原因是 apprise-api 服务未启动或 /etc/apprise-api.env 中路径写错导致启动失败（journalctl -u apprise-api -n 50 --no-pager 看报错）。

Q4：Web 管理器静态资源 404（页面无样式）？ A：检查 nginx 配置中 location /s/ 的 alias 路径是否指向 /opt/apprise-api/apprise_api/static/（末尾带斜杠），并确认 nginx -t 通过后已 reload。

Q5：发送带附件的通知返回 413？ A：nginx 的 client_max_body_size 小于附件体积。本文配置为 210m，略大于默认附件上限 200MB（APPRISE_ATTACH_SIZE）；若调大了附件上限，nginx 侧要同步调大。

九、卸载与清理

按安装逆序清理。停止并摘除 systemd 服务：

sudo systemctl stop apprise-api
sudo systemctl disable apprise-api
sudo rm /etc/systemd/system/apprise-api.service
sudo systemctl daemon-reload

摘除 nginx 站点（nginx 本体如有其他用途可保留）：

sudo rm /etc/nginx/sites-enabled/apprise-api
sudo rm /etc/nginx/sites-available/apprise-api
sudo systemctl reload nginx

删除源码、数据、环境文件与服务用户：

sudo rm -rf /opt/apprise-api /var/lib/apprise /etc/apprise-api.env
sudo userdel apprise

离线方案的 wheel 包目录（/opt/apprise-offline）与临时接收器（/root/webhook_receiver.py）按需一并删除。

十、参考链接