Gotify 3.1.1 配置参数详解

目标：系统讲清 Gotify 3.1.1 的配置体系——3.x 从 config.yml 全面转向环境变量后的加载机制、全量参数分组详解与默认值，并对监听端口、日志、响应头、默认用户、开放注册、自签 TLS 六组参数完成「改参数 → 重启 → 验证」的实测闭环。本文全部命令与回显在 Ubuntu 22.04（x86_64）实测环境逐条运行，实测端口 8144（8128-8152 槽位约定；Gotify 3.x 标准默认端口为 80）。安装过程见 《Ubuntu 22.04 安装 Gotify 3.1.1 指南》，组件定位与版本演进见 《Gotify 3.1.1 介绍与选型指南》。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（Jammy Jellyfish），x86_64；
• 软件版本：Gotify 3.1.1（安装篇所装版本，服务端 /version 实测回显 {"version":"3.1.1",...}，与本文全部实验同版本）；
• 运行形态：官方发布二进制 /opt/gotify/gotify + systemd 托管（服务名 gotify）；
• 配置文件：/etc/gotify/server.env（systemd EnvironmentFile 加载，并由 GOTIFY_CONFIG_FILE 显式指向）；
• 数据目录：/var/lib/gotify（SQLite 数据库 gotify.db）；
• 初始管理员：admin（仅在首次建库时生效，见 5.7 节实测）；
• 配置文档溯源：gotify.net/docs/config（查询日期 2026-10-21）；
• 参数版本基准：3.1.1 稳定版环境变量全集（以本机 --help 与官方配置页交叉核对）。

二、3.x 配置体系总述

2.1 从 config.yml 到环境变量

Gotify 2.x 用 config.yml 配置（搜索 ./config.yml 与 /etc/gotify/config.yml 两个位置）；3.0.0 起配置文件不再被读取，全部参数转为环境变量，可从 env 文件加载。这一变更与令牌哈希存储、CLI 子命令化同属 3.0.0 的破坏性变更（变更明细见认知篇 4.2 节）。从 2.x 升级的服务器用内置子命令把旧 config.yml 转成环境变量清单：

/opt/gotify/gotify migrate-config /etc/gotify/config.yml > gotify-server.env

实测说明：以官方 2.x 示例配置为输入，该命令把 19 个 GOTIFY_* 变量打印到 stdout（逐行回显见安装篇 8.5 节），复制进 env 文件即可完成迁移；转换不触碰旧配置文件本身。

2.2 配置文件加载机制

Gotify 3.x 按以下规则加载配置（官方 docs/config 语义）：

1. 若设置了 GOTIFY_CONFIG_FILE，只读该文件，跳过全部搜索序；
2. 未设置时按搜索序取第一个存在的文件：
   • ① 工作目录下 gotify-server.env；
   • ② $XDG_CONFIG_HOME/gotify/gotify-server.env（XDG_CONFIG_HOME 未设置时回落 $HOME/.config）；
   • ③ /etc/gotify/server.env；
3. 文件中缺失或注释掉的参数回落到默认值（见第四章各表）；
4. 进程环境中已导出的变量优先于文件（systemd Environment= 行即属此类）。

⚠️ 注意：搜索序会探测 $HOME/.config。配合 systemd ProtectHome=true 加固时，专用用户无家目录导致探测直接 permission denied 并 FTL 退出——这正是安装篇 8.1 节排障实录的根因。生产单元务必像安装篇 4.6 节那样显式声明 Environment=GOTIFY_CONFIG_FILE=/etc/gotify/server.env。

本文实测环境通过 journalctl 确认加载行为（每次重启必现）：

2026-10-21T20:08:52+08:00 INF Loading file /etc/gotify/server.env

2.3 值类型与 _FILE 后缀

env 文件中的参数按五种类型解析：

每个参数都支持 _FILE 后缀——值改为从文件读取（适用于密钥托管）：

GOTIFY_DEFAULTUSER_PASS_FILE=/run/secrets/admin_pass

2.4 修改配置的标准流程

# 1. 编辑 /etc/gotify/server.env（或 GOTIFY_CONFIG_FILE 指向的文件）
vim /etc/gotify/server.env
# 2. 重启生效
systemctl restart gotify
# 3. 验证
systemctl is-active gotify
curl -s http://127.0.0.1:8144/health; echo

环境变量在进程启动时读取，必须重启才生效，不存在热加载。

三、参数总览

3.1.1 稳定版环境变量全集（默认值标注在取值列；来源 gotify.net/docs/config，查询日期 2026-10-21）：

⚠️ 注意：3.1.1 的参数全集里没有消息体大小、上传体积等限额参数，也没有监听 worker 数/超时类参数——这两个方向均不可配置，容量控制依赖反代层（如 Nginx 的 client_max_body_size）。

四、数据库组详解

4.1 方言与连接串

GOTIFY_DATABASE_DIALECT 三选一，连接串格式随方言变化：

• mysql/postgres 要求目标库已存在且账号有足够权限（Gotify 不建库建用户）；
• postgres 不走 SSL 时官方明确要求追加 sslmode=disable（gotify/server#90）；
• 本文实测环境为 SQLite（安装篇 4.5 节配置 GOTIFY_DATABASE_CONNECTION=/var/lib/gotify/gotify.db），单文件、零依赖，与 6.9MB 空载内存匹配（安装篇 8.6 节），中小规模推送场景推荐默认方案；需要多实例共享或高并发写再切 mysql/postgres。

4.2 相对路径陷阱

连接串与两个目录参数的相对路径（如 data/gotify.db）以进程工作目录为基准。本环境单元中 WorkingDirectory=/var/lib/gotify（安装篇 4.6 节），因此官方默认值 data/gotify.db 实际落到 /var/lib/gotify/data/gotify.db 一层。生产建议像本文一样写绝对路径，消除歧义。

五、重点参数实测闭环

本章六组实验均在 8144 端口实测环境完成，每组「改参数 → 重启 → 验证 → 还原」四步齐全，回显逐条照录。

5.1 监听端口 GOTIFY_SERVER_PORT（改 8145 验证）

sed -i 's/GOTIFY_SERVER_PORT=8144/GOTIFY_SERVER_PORT=8145/' /etc/gotify/server.env
systemctl restart gotify
sleep 2
systemctl is-active gotify
curl -s http://127.0.0.1:8145/health; echo
ss -ltn | grep ':8144 ' || echo '8144 already released'

实测回显：

active
{"health":"green","database":"green"}
8144 already released

改回 8144 重启还原。结论：端口切换即改即生效，旧端口随重启立即释放。

5.2 日志级别 GOTIFY_LOGLEVEL

七个级别：trace < debug < info < warn < error < fatal < panic。info 级别（默认）下每个 HTTP 请求打 INF 行、无效凭据打 WRN 行（journalctl 实测样例，安装篇 7.3 节同源）：

10月 21 20:03:56 ops gotify[135211]: 2026-10-21T20:03:56+08:00 INF HTTP duration=41.533097ms ip=127.0.0.1 method=POST path=/auth/local/login status=200
10月 21 20:03:56 ops gotify[135211]: 2026-10-21T20:03:56+08:00 WRN HTTP duration=39.994948ms errors="Error #01: invalid credentials" ip=127.0.0.1 method=POST path=/auth/local/login status=401

info 级别下未观察到 DBG 行（debug 级别实验中请求日志仍为 INF 口径），排障时优先依赖 status 码与 WRN 行。生产保持 info；NOCOLOR=1 适合接入日志采集器时去除 ANSI 颜色码。

5.3 响应头 GOTIFY_SERVER_RESPONSEHEADERS（json-map 类型）

追加一行 json-map 配置后重启：

printf '\nGOTIFY_SERVER_RESPONSEHEADERS={"X-Gotify-Node":"lab-8144"}\n' >> /etc/gotify/server.env
systemctl restart gotify && sleep 2

验证不同路由的响应（curl -D 只看头）：

curl -s -o /dev/null -D - http://127.0.0.1:8144/version
curl -s -o /dev/null -D - http://127.0.0.1:8144/message | head -5
curl -s -o /dev/null -D - http://127.0.0.1:8144/health

实测回显：

HTTP/1.1 200 OK
Content-Type: application/json
X-Gotify-Node: lab-8144
Date: Wed, 21 Oct 2026 12:24:41 GMT
Content-Length: 105

HTTP/1.1 401 Unauthorized
Content-Type: application/json
X-Gotify-Node: lab-8144
Date: Wed, 21 Oct 2026 12:24:41 GMT
Content-Length: 141

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 21 Oct 2026 12:24:41 GMT
Content-Length: 37

实测结论：自定义头作用于 API 路由（/version 200、/message 未认证 401 均带头）；但 /health 与静态首页（/）不带头——这两类响应不经过该中间件。用它加 X-Frame-Options 等安全头时注意这个作用域盲区。

实验后删除该行重启还原。

5.4 初始用户 GOTIFY_DEFAULTUSER_PASS（仅首次建库生效）

把 env 中口令从 q1w2e3r4 改成 changed-pass-123 并重启，分别用新旧口令调 /current/user：

sed -i 's/^GOTIFY_DEFAULTUSER_PASS=q1w2e3r4/GOTIFY_DEFAULTUSER_PASS=changed-pass-123/' /etc/gotify/server.env
systemctl restart gotify && sleep 2
curl -s -o /dev/null -w '%{http_code}\n' -u admin:q1w2e3r4 http://127.0.0.1:8144/current/user
curl -s -o /dev/null -w '%{http_code}\n' -u admin:changed-pass-123 http://127.0.0.1:8144/current/user

实测回显：

200
401

实测结论：改 env 后重启，旧口令仍 200、新口令 401——DEFAULTUSER_* 只在数据库首次创建时生效，之后改口令必须走 WebUI 或 API（PUT /current/user/password，见 API 篇）。改回原值重启还原。

同组的 GOTIFY_PASSSTRENGTH=10 是 bcrypt cost，数值越高登录校验越慢；默认 10 是安全与延迟的常用平衡点，无特殊合规要求不必调。

5.5 会话 Cookie GOTIFY_SERVER_SECURECOOKIE

默认 false 时会话登录响应（POST /auth/local/login，表单提交）：

curl -s -i -u admin:q1w2e3r4 -d 'name=cfg-demo-session' -X POST http://127.0.0.1:8144/auth/local/login | grep -iE '^(HTTP|Set-Cookie)'

实测回显：

HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: gotify-client-token=gtfyc.NIQpsEiY7AVLplP9BzCuFfm-Jay_d1iHcBPRXNTKZNg; Path=/; Max-Age=604800; HttpOnly; SameSite=Strict

Cookie 自带 HttpOnly 与 SameSite=Strict 但没有 Secure 标志（默认 false 的实证）。把 Gotify 置于 HTTPS 之后对外时，应设 GOTIFY_SERVER_SECURECOOKIE=true 补上 Secure，防止会话 Cookie 走明文信道泄漏。

5.6 开放注册 GOTIFY_REGISTRATION

默认 false 时探测注册端点：

curl -s -w '\nHTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' \
  -d '{"name":"labreg","password":"regpass123"}' http://127.0.0.1:8144/register

实测回显：

{"error":"Not Found","errorCode":404,"errorDescription":"page not found"}
HTTP 404

设为 true 重启后用同样请求再测：

{"error":"Not Found","errorCode":404,"errorDescription":"page not found"}
HTTP 404

并对 GET /register、POST /api/register、POST /user/register 等候选路径穷举，全部 404/401。实测结论：3.1.1 的 HTTP API 不存在公开注册端点；GOTIFY_REGISTRATION 的开关状态通过 GET /version 同级的 GotifyInfo 暴露（register 字段），供前端决定是否展示注册入口，即便开关为 true，API 层实测也没有可用的注册提交端点。该参数保持默认 false 即可，勿指望它提供自助注册能力；需要批量开号走管理员 POST /user（见 API 篇）。

5.7 TLS 组：自签证书实测闭环

生成自签证书（生产应使用 CA 签发或 Let's Encrypt，此处仅验证机制），放到 /etc/gotify/tls/ 并加配置：

mkdir -p /etc/gotify/tls
openssl req -x509 -newkey rsa:2048 -keyout /etc/gotify/tls/server.key \
  -out /etc/gotify/tls/server.crt -days 3650 -nodes -subj '/CN=lab-8144'
chown -R root:gotify /etc/gotify/tls && chmod 640 /etc/gotify/tls/*
cat >> /etc/gotify/server.env <<'EOF'
GOTIFY_SERVER_SSL_ENABLED=true
GOTIFY_SERVER_SSL_PORT=8145
GOTIFY_SERVER_SSL_CERTFILE=/etc/gotify/tls/server.crt
GOTIFY_SERVER_SSL_CERTKEY=/etc/gotify/tls/server.key
EOF
systemctl restart gotify && sleep 2

journalctl 实测（双监听同时出现）：

2026-10-21T20:26:58+08:00 INF Listen address=[::]:8144 connection_type="plain connection" network=tcp
2026-10-21T20:26:58+08:00 INF Listen address=[::]:8145 connection_type="TLS connection" network=tcp

验证一：HTTPS 健康检查与证书：

curl -sk https://127.0.0.1:8145/health; echo
echo | openssl s_client -connect 127.0.0.1:8145 2>/dev/null | openssl x509 -noout -subject -dates

实测回显：

{"health":"green","database":"green"}
subject=CN = lab-8144
notBefore=Oct 21 12:26:35 2026 GMT
notAfter=Oct 18 12:26:35 2036 GMT

验证二：REDIRECTTOHTTPS 默认 true 的效果——HTTP 端口对同一 URL 返回 302：

HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Location: https://127.0.0.1:8145/health

验证三：HTTPS 响应为 HTTP/2（Go 内建 TLS 栈自动协商）：

HTTP/2 200
content-type: application/json; charset=utf-8
content-length: 37

三个易踩的坑（均实测触发过）：

1. 私钥不可读即启动失败：证书放到 gotify 用户无法穿越/读取的路径时，重启直接失败，journalctl 记 INF Shutting down error="open /etc/gotify/tls/server.key: permission denied" 后进程退出——私钥属主/权限必须是 gotify 可读；
2. REDIRECTTOHTTPS=true 且仅想内网走 HTTP 的场景会带来意外 302，按需显式设 false；
3. 启用 HTTPS 后建议同步 GOTIFY_SERVER_SECURECOOKIE=true（见 5.5 节）。

实验后删除四行 SSL 配置重启还原，8145 释放。

5.8 未实测参数声明

以下参数组依赖外部系统，本文不提供实测，语义转述自官方配置文档（查询日期 2026-10-21）：

• Let's Encrypt 组（5 个变量）：要求 SSL_ENABLED=true 且 ACCEPTTOS=true，HOSTS 中的域名必须公网解析到本服务器；测试期建议把 DIRECTORYURL 指到 staging 环境规避限频；
• OIDC 组（12 个变量）：需具备支持 PKCE 的外部 IdP（Authelia、Dex、Keycloak 等）；REDIRECTURL 必须与 IdP 注册值完全一致且以 /auth/oidc/callback 结尾；GROUPS_CLAIM 设置后管理员权限每次登录由 IdP 覆盖；Android 客户端支持 OIDC 需在 IdP 额外注册 gotify://oidc/callback 回调；
• CORS 组 / TRUSTEDPROXIES / STREAM_ALLOWEDORIGINS：设置任一 CORS 变量即启用跨域处理，来源为正则（如 .+\.example\.com）；反代终止 TLS 时把代理地址（含 127.0.0.1/32）加入 TRUSTEDPROXIES 才能取到真实客户端 IP。

六、生产配置模板

综合以上实测与官方默认值，给出单机 SQLite 形态的生产模板（以 443 反代由 Nginx 承担、Gotify 本机监听为例）：

# /etc/gotify/server.env —— 生产基线（systemd EnvironmentFile + GOTIFY_CONFIG_FILE 双加载）
GOTIFY_LOGLEVEL=info

# 监听：仅回环，对外由反代负责
GOTIFY_SERVER_LISTENADDR=127.0.0.1
GOTIFY_SERVER_PORT=8080

# 数据库：SQLite 单文件（绝对路径）
GOTIFY_DATABASE_DIALECT=sqlite3
GOTIFY_DATABASE_CONNECTION=/var/lib/gotify/gotify.db

# 初始管理员：改掉默认值，仅在首次建库生效
GOTIFY_DEFAULTUSER_NAME=opsadmin
GOTIFY_DEFAULTUSER_PASS_FILE=/etc/gotify/admin_pass

# 口令哈希成本
GOTIFY_PASSSTRENGTH=10

# 目录
GOTIFY_UPLOADEDIMAGESDIR=/var/lib/gotify/images
GOTIFY_PLUGINSDIR=/var/lib/gotify/plugins

# 安全基线
GOTIFY_REGISTRATION=false
GOTIFY_SERVER_SECURECOOKIE=true
GOTIFY_SERVER_RESPONSEHEADERS={"X-Content-Type-Options":"nosniff"}
GOTIFY_SERVER_TRUSTEDPROXIES=127.0.0.1/32,::1

模板要点逐条对应实测结论：监听回环 8080（Gotify 标准默认 80 易与 Web 服务冲突，5.1 节已验证改端口即改即生效）；_FILE 后缀托管初始口令（2.3 节）；TRUSTEDPROXIES 只信任本机反代（5.8 节）；RESPONSEHEADERS 只对 API 路由生效，WebUI 静态资源的安全头交给反代（5.3 节）；若由 Gotify 直接对外提供 HTTPS，则改为 SSL_ENABLED=true + 证书路径方案（5.7 节）或 Let's Encrypt 方案，并保持 REDIRECTTOHTTPS=true。

七、常见问题（FAQ）

7.1 改了 config.yml 为什么不生效？

3.x 不再读取 config.yml。用 migrate-config 转换（2.1 节），或按第四章参数表直接写环境变量。

7.2 启动报 cannot read file .../gotify-server.env: permission denied

配置搜索序探测 $HOME 撞上 systemd ProtectHome=true（安装篇 8.1 节实录），或目录属主不可穿越（安装篇 8.2 节实录）。解决：单元里显式 Environment=GOTIFY_CONFIG_FILE=/etc/gotify/server.env，并确保 /etc/gotify 属主 root:gotify、组有执行位。

7.3 GOTIFY_DEFAULTUSER_PASS 改了为什么不生效？

仅首次建库生效（5.4 节闭环实测）。已有库改口令走 WebUI 或 PUT /current/user/password。

7.4 想限制单条消息/上传图片的大小怎么办？

3.1.1 参数全集没有此项（第三章末注）。请在反代层限制（如 Nginx client_max_body_size）；启用 HTTPS 直连时 Gotify 自身不可配。

7.5 开了 GOTIFY_REGISTRATION=true，为什么 curl POST /register 还是 404？

3.1.1 实测无公开注册 API 端点（5.6 节闭环），该开关只影响前端注册入口状态展示。开号走管理员 POST /user。

7.6 RESPONSEHEADERS 加的头在 /health 上看不到？

实测该自定义头只挂 API 路由响应，/health 与静态首页不经过该处理（5.3 节）。

7.7 相对路径的数据库/目录落在哪？

以进程工作目录为基准（本环境为 /var/lib/gotify，4.2 节）。生产统一写绝对路径。

7.8 日志级别调到 debug 为什么没有 DBG 行？

info 级别下请求日志即为 INF、凭据错误为 WRN（5.2 节样例）；debug 级别实验未观察到额外 DBG 输出，排障建议结合 status 码与 WRN 行定位。

八、参考链接

• 官方配置文档：https://gotify.net/docs/config （3.x 环境变量全集、值类型、加载顺序、2.x config.yml 遗留说明）
• 官方 systemd 指南：https://gotify.net/docs/systemd
• 官方迁移指南：https://gotify.net/docs/migrate （Migrate to 3.x）
• 版本发布页：https://github.com/gotify/server/releases
• 认知与选型：《Gotify 3.1.1 介绍与选型指南》（三模型架构、3.x 破坏性变更明细、同类对比）
• 安装部署：《Ubuntu 22.04 安装 Gotify 3.1.1 指南》（二进制安装、systemd 加固、FTL 排障实录）
• API 使用详解：《Gotify 3.1.1 API 使用详解》（CLI 子命令、REST API 与 WebSocket 逐条实测）