Notifo v1.3.0 配置参数详解

目标：把 Notifo 1.3.0 的全部配置项讲透——配置加载体系与优先级、appsettings.json 逐组参数的默认值与取值约束、环境变量转换规则，以及按场景（最小单机/生产 SMTP/多实例集群）的推荐组合。参数默认值取自官方 1.3.0 源码中的 appsettings.json，行为描述均在本地容器实测验证（2026-10-30）。

一、环境信息

二、配置体系总览

Notifo 没有独立的配置 Web 界面，全部配置走三条通道，优先级从高到低：

1. 环境变量：双下划线 __ 表示层级，例如 IDENTITY__USERS__0__EMAIL 对应 JSON 键 identity:users[0]:email（0 为数组下标）。这是容器部署的主通道；
2. appsettings.Production.json：挂载到 /app/appsettings.Production.json 即可覆盖镜像内置默认值，适合固化不常改动的大块配置；
3. appsettings.json（镜像内置）：所有参数的默认值来源，本文以它为基准逐组讲解。

💡 实测技巧：想确认容器「最终看到」的某个配置，可以直接 docker inspect <容器名> --format '{{json .Config.Env}}' 比对环境变量，或 docker exec <容器名> cat /app/appsettings.json 查看内置默认。运行态验证手段见第六节。

三、核心参数组详解

3.1 urls —— 对外地址（必配）

3.2 storage —— 存储后端（必配，仅 MongoDB）

3.3 messaging —— 消息队列与调度

💡 实测印证：默认 Scheduler 模式下，Mongo 的 Queue_events（事件队列）与 Scheduler_email/webpush/webhook/...（每渠道调度集合）在发布通知后会短暂出现记录，处理完成即消费，这就是内置调度的实现位置。

3.4 clustering —— 多实例协调

3.5 assetStore —— 资产存储

3.6 identity —— 认证与初始账号（部署必看）

⚠️ 安全提醒：镜像内置的 GitHub/Google 演示凭据是公开信息，部署后请一律置空或更换；初始管理员密码 Q1w2e3r4! 也应在首登后修改或改用随机值环境变量。

3.7 webPush —— 浏览器推送（Web Push 渠道必配）

3.8 sms / email —— 渠道级凭据

💡 注意分层：这组是「全局/服务商级」凭据；而 App 内的 Email 发件服务器（如自建 SMTP、Mailhog）在 Dashboard 的 Integrations 里按 App 配置，两者不冲突——实测同一实例里 App 级 SMTP 指向 Mailhog 正常收信，无需动这组全局参数。

3.9 web —— 实时通道（SignalR）

3.10 diagnostics —— 诊断与自愈

3.11 logging —— 日志

3.12 其他

四、环境变量转换规则与部署全量对照

转换规则只有一条：JSON 路径用双下划线拼接，数组用数字下标。部署篇 compose 里的全部环境变量与语义对照如下（均为实测生效值）：

五、按场景推荐配置

场景 A：最小单机（测试/演示） —— 部署篇 compose 原样即可：内置 Scheduler + Folder 资产 + Mailhog 收信验证，零外部依赖。

场景 B：生产单机（真实发信） —— 在 A 基础上：URLS__BASEURL 换正式域名；App 内配置真实 SMTP 或启用全局 email:amazonSES；webPush:vapid* 换自有密钥对；初始管理员密码改强随机值；IDENTITY__GITHUB/GOOGLE/MICROSOFT* 置空；数据目录纳入备份（见部署篇第五节）。

场景 C：多实例高可用 —— clustering:type=Redis + messaging:type=RabbitMq（或 Kafka，注意 groupId 一致形成竞争消费）+ web:signalR:sticky=true（负载均衡开粘滞会话）+ assetStore 换共享后端（S3/GridFS，不能用本地 Folder）+ Mongo 副本集。四项缺一都会出现通知偶发丢失或 Web 通道断连。

六、参数校验与生效验证方法

配置改完如何确认「真的生效」？以下命令全部实测可用：

# 1) 健康与内存阈值：status=Healthy 且 gc 描述包含 threshold 对应文字
curl -s http://localhost:8151/healthz | python3 -m json.tool

# 2) 轻量探活
curl -s http://localhost:8151/ping

# 3) 库名验证：列出实际使用的库与集合
docker exec notifo-1-3-0-stack-notifo-mongo-1 mongosh --quiet \
  --eval 'db.getSiblingDB("Notifications").getCollectionNames().join(",")'

# 4) client_credentials 验证（identity:adminClient* 配置正确即返回 token）
curl -s -X POST http://localhost:8151/connect/token \
  -d "grant_type=client_credentials&client_id=notifo-admin&client_secret=q1w2e3r4&scope=NotifoAPI"

# 5) 链接前缀验证：发布一条通知后，检查返回里的 trackSeenUrl 是否以 BASEURL 开头
curl -s -H "X-ApiKey: <AppKey>" "http://localhost:8151/api/apps/{appId}/notifications?take=1"

环境变量改动需 docker compose up -d（重建容器）生效；appsettings.Production.json 改动同样需要重启容器进程。

七、常见问题（FAQ）

Q1：环境变量写了却不生效？ 三个高频原因：① 双下划线写成了单下划线；② 数组下标越界（USERS__1__EMAIL 但只初始化到 0 位不会自动扩位）；③ 改完没有重建容器（docker compose restart 不重读 env，需 up -d）。

Q2：URLS__BASEURL 能否填 localhost？ 仅当所有用户都在本机访问时可以。邮件里的链接由服务端拼好发给收件人，收件人机器上的 localhost 不是服务器——必须用外部可达的 IP/域名（实测邮件偏好链接、跟踪链接均直接拼 BASEURL）。

Q3：Web Push 通知发不出去？ 检查 webPush:vapid* 是否还是官方演示密钥；浏览器端授权站点与 VAPID subject 需匹配，且 baseUrl 必须是 HTTPS（浏览器 Push API 的硬性要求）。

Q4：想换端口怎么办？ 只改宿主映射即可（ports: "8151:5000" 左侧），容器内 5000 与 healthcheck 不用动；同时把 URLS__BASEURL 的端口同步成宿主端口。

Q5：内存阈值可以调吗？ 可以，diagnostics:gc:threshold 单位 MB。小内存机器下调到如 1024，内存超限时 healthz 会转不健康，便于被编排系统感知重启。

八、参考链接

• 官方配置文档：https://docs.notifo.io/configuration
• 官方 appsettings.json（tag 1.3.0）：https://github.com/notifo-io/notifo/blob/main/backend/src/Notifo/appsettings.json
• 官方部署文档：https://docs.notifo.io/self-hosting
• 本系列文档：《Notifo 介绍与选型指南》、《Notifo v1.3.0 Docker Compose 部署指南》、《Notifo v1.3.0 API 使用详解》