tinyauth v5.2.0 配置参数详解

目标：逐项梳理 tinyauth v5.2.0 的全部配置参数（环境变量、CLI 标志、YAML 配置文件三种形态），讲清每种参数的默认值、取值范围与改动后的实际效果，并对配置查看、配置文件加载、登录防爆破锁定、会话时效、日志格式等关键行为做全量实测。本文全部命令与回显已在 Ubuntu 22.04 + Docker Engine 29.8.1 环境、tinyauth v5.2.0（2026-09-07 构建）实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（x86_64）
• Docker Engine：29.8.1，Docker Compose 插件 v5.5.1
• tinyauth 版本：v5.2.0（官方镜像 ghcr.io/tinyauthapp/tinyauth:v5.2.0，Commit 653b7478，构建时间 2026-09-07T17:15:08）
• 部署形态：单机 Docker Compose 部署（部署过程见 《tinyauth v5.2.0 Docker Compose 部署指南》），tinyauth 服务端口 3000 映射宿主机 8131
• 域名规划：auth.example.com（tinyauth 登录入口）、whoami.example.com（受保护应用示例）
• 数据目录：容器内 /data（SQLite 数据库 tinyauth.db、OIDC 密钥 oidc/、资源目录 resources/）
• 参数考证来源：官方 Configuration 参考（https://tinyauth.app/docs/reference/configuration ，2026-10-24 查证）+ 本地实测逐项验证

二、前置条件

• 已按 《tinyauth v5.2.0 Docker Compose 部署指南》完成 tinyauth 部署并能访问登录页；本文所有参数修改都在该部署形态之上进行
• 管理员账号 admin / 密码 q1w2e3r4（以 TINYAUTH_AUTH_USERS 中的 bcrypt 哈希配置），登录接口实测命令为：

curl -s -X POST -H 'Content-Type: application/json' -H 'Host: auth.example.com' \
  -d '{"username":"admin","password":"q1w2e3r4"}' http://127.0.0.1:8131/api/user/login

实测回显：

{"message":"Login successful","status":200}

• 验证服务健康状态（后续多处用到）：

docker exec tinyauth-v5.2.0-app tinyauth healthcheck

实测回显：

2026-10-24T11:34:27Z INF Performing health check app_url=http://127.0.0.1:3000 stream=app
2026-10-24T11:34:27Z INF Tinyauth is healthy response={"message":"Healthy","status":200} stream=app

三、参数查看与修改方式

tinyauth 的每个参数都有三种等价配置形态：环境变量（TINYAUTH_ 前缀）、CLI 标志（-- 前缀）、YAML 配置文件（TINYAUTH_CONFIGFILE 指向）。本章先讲怎么「看」当前生效配置，再讲三种形态怎么「改」以及它们的生效关系。

3.1 查看当前生效配置：config 子命令

tinyauth config 会把当前进程实际生效的全部配置以 YAML 格式转储出来，是核对参数是否按预期生效的第一工具：

docker exec tinyauth-v5.2.0-app tinyauth config

实测回显（正式栈当前生效值）：

Your current configuration in YAML is:

appUrl: http://auth.example.com
labelProvider: auto
database:
    driver: sqlite
    path: /data/tinyauth.db
analytics:
    enabled: true
resources:
    enabled: true
    path: /data/resources
server:
    port: 3000
    address: 0.0.0.0
auth:
    users:
        - admin:$2a$10$Edf9Rb8EMGOjyXIf1.yLCur3593A9DlmuZyi5tTeT0./1dmWv62UK
    subdomainsEnabled: true
    sessionExpiry: 86400
    loginTimeout: 300
    loginMaxRetries: 3
    trustedProxies:
        - 10.89.57.0/24
    acls:
        policy: allow
oidc:
    privateKeyPath: /data/oidc/key.pem
    publicKeyPath: /data/oidc/key.pub
ui:
    title: Tinyauth
    forgotPasswordMessage: You can change your password by changing the configuration.
    backgroundImage: /background.webp
    warningsEnabled: true
ldap:
    searchFilter: (uid=%s)
    groupCacheTTL: 900
tailscale:
    cacheDuration: 300
log:
    level: info
    streams:
        http:
            enabled: true
        app:
            enabled: true

💡 说明：config dump 里 bcrypt 哈希是配置原文回显，排查用户配置问题时可直接与 TINYAUTH_AUTH_USERS 对照。dump 中未出现的键（如 oauth、experimental）表示全部取默认零值/关闭态，未显式渲染。

⚠️ 注意：官方文档中的默认路径写的是二进制直跑形态（如 --database.path 默认 ./tinyauth.db、--resources.path 默认 ./resources）；官方 Docker 镜像内的默认值已改为挂载点路径（/data/tinyauth.db、/data/resources、/data/oidc/key.pem）。上表实测回显即镜像形态默认值，读者对照官方文档时不要被 ./ 前缀迷惑。

3.2 三种配置源的写法与生效关系

以「会话有效期 2 小时（7200 秒）」为例，三种形态的写法分别是：

形态一，环境变量（Docker Compose environment: 注入，最常见的形态）：

environment:
  - TINYAUTH_AUTH_SESSIONEXPIRY=7200

形态二，CLI 标志（追加到服务启动命令之后）：

tinyauth --auth.sessionexpiry=7200

形态三，YAML 配置文件（TINYAUTH_CONFIGFILE 指向，键名采用驼峰）：

auth:
  sessionExpiry: 7200

三者的层级关系实测结论：环境变量与 CLI 标志可以混用，YAML 配置文件一旦启用则成为唯一配置源，环境变量不再参与（见 3.3 实测）。日常运维建议固定使用环境变量一种形态，避免多源混用导致排障困难。

3.3 配置文件形态（TINYAUTH_CONFIGFILE）实测与坑

配置文件形态是官方支持但坑点最多的方式，本节用三次递进实验还原完整行为。实验配置文件 config.yml 先只写 UI 标题与关闭分析上报：

ui:
  title: Ops Portal
analytics:
  enabled: false

第一次实验：挂载该文件并设置 TINYAUTH_CONFIGFILE=/config.yml，同时按旧习惯把 TINYAUTH_APPURL=http://auth.example.com 写在环境变量里。容器直接启动失败：

Failed to execute command: command tinyauth error: failed to bootstrap app: failed to parse app url: invalid url

⚠️ 排障结论：TINYAUTH_CONFIGFILE 生效时环境变量被整体忽略，TINYAUTH_APPURL 等于没配，appUrl 解析为空报 invalid url。启用配置文件后必须把所有必要参数全部写进 YAML。

第二次实验：把 appUrl 补进 YAML，但用户列表仍留在环境变量里：

appUrl: http://auth.example.com
ui:
  title: Ops Portal
analytics:
  enabled: false

容器依旧启动失败，错误变成：

Failed to execute command: command tinyauth error: failed to bootstrap app: no authentication providers configured

⚠️ 排障结论：错误信息从「app url 无效」变成「没有任何认证提供者」，进一步印证环境变量里的 TINYAUTH_AUTH_USERS 也被忽略了。tinyauth 至少要配一种认证提供者（本地用户 / OAuth / OIDC / LDAP / Tailscale 任一）才能启动。

第三次实验（成功）：把用户列表、可信代理一并写入 YAML，同时在环境变量里故意放一个冲突项 TINYAUTH_UI_TITLE=EnvTitleWins，验证环境变量是否真的完全失效：

appUrl: http://auth.example.com
auth:
  users:
    - admin:$2a$10$Edf9Rb8EMGOjyXIf1.yLCur3593A9DlmuZyi5tTeT0./1dmWv62UK
  trustedProxies:
    - 10.89.57.0/24
ui:
  title: Ops Portal
analytics:
  enabled: false

容器正常启动，config dump 关键节选（实测）：

auth:
    users:
        - admin:$2a$10$Edf9Rb8EMGOjyXIf1.yLCur3593A9DlmuZyi5tTeT0./1dmWv62UK
    trustedProxies:
        - 10.89.57.0/24
ui:
    title: Ops Portal

ui.title 最终值是 YAML 里的 Ops Portal 而不是环境变量里的 EnvTitleWins；同时 dump 中 analytics 小节整体消失（enabled: false 生效，关闭分析上报后不再渲染该节）。登录功能正常：

{"message":"Login successful","status":200}

💡 结论：YAML 配置文件 = 唯一配置源，环境变量、CLI 标志同时失效。迁移到配置文件形态时必须整体搬迁全部参数，推荐用 tinyauth config 先导出现有生效值再改造为 YAML。

四、参数总览

本节按官方 Configuration 参考的分组给出全部参数（2026-10-24 查证 v5.2.0），列为「环境变量 | 对应 CLI 标志 | 默认值 | 说明」四列。环境变量与 CLI 标志一一对应（规则：TINYAUTH_ + 大写下划线 ↔ -- + 小写点分），表中默认值以官方 Docker 镜像内实测 --help 回显为准。[NAME] 为占位模式名，使用时替换为实际名称（如 TINYAUTH_APPS_WHOAMI_CONFIG_DOMAIN）。

4.1 main（基础参数）

4.2 database（数据库参数）

4.3 analytics（分析上报）

4.4 resources（资源服务）

4.5 server（服务监听）

4.6 auth（认证与会话参数）

USERATTRIBUTES 属性族支持的 [NAME] 后缀全表（YAML/CLI 键名采用驼峰，如 givenName）：

4.7 apps（按应用 ACL 参数）

每个受保护应用可用 [NAME] 独立配置访问策略，[NAME] 替换为应用标识（如 WHOAMI）：

4.8 oauth（OAuth 提供者参数）

💡 说明：[NAME] 使用 google 或 github 时，授权端点、scope 等信息会自动填充，只需提供 client ID 与 secret（官方 Configuration 参考注记，2026-10-24 查证）；自建提供者则需完整给出 authUrl/tokenUrl/userinfoUrl 三件套。

4.9 oidc（OIDC 参数）

OIDC 客户端凭据推荐用 tinyauth oidc create <名称> 命令生成（完整实测见 《tinyauth v5.2.0 常用 CLI 命令与运维实操》第九章），生成后按上表键名写入配置并重启生效。

4.10 ui（界面参数）

4.11 ldap（LDAP 参数）

4.12 tailscale（Tailscale 集成参数）

4.13 log（日志参数）

4.14 experimental（实验性参数）

💡 说明：带密钥语义的参数（如 TINYAUTH_AUTH_USERS、各 CLIENTSECRET、BINDPASSWORD、APITOKEN）官方均提供对应的 *FILE 变体（如 TINYAUTH_AUTH_USERSFILE、CLIENTSECRETFILE），可用挂载文件替代明文环境变量（官方 Configuration 参考注记，2026-10-24 查证）。

五、核心参数分类详解

本章对影响行为最大的参数组做逐项实测。凡标注「实测」的行为均在本文环境真实复现，命令与回显逐行照抄。

5.1 入口参数 TINYAUTH_APPURL

TINYAUTH_APPURL 是 tinyauth 最容易配错的参数：它决定会话 Cookie 的父域与登录后跳转地址。实测环境取 http://auth.example.com，登录成功后下发的 Cookie 为（实测回显）：

Set-Cookie: tinyauth-session-26742baf=aac628e6-e7d3-4fa9-9db4-176bed051667; Path=/; Domain=example.com; Expires=Sat, 24 Oct 2026 21:29:27 GMT; Max-Age=86399; HttpOnly; SameSite=Lax

Cookie 的 Domain 自动派生为 example.com（三段域名 auth.example.com 的父域），同主域下其他子域应用才能共享会话。实测还确认：APPURL 若配成两段式域名（如 auth.localtest），派生出的 Cookie 域无法覆盖兄弟子域，其他子域应用直接拒绝访问。域名规划必须在部署前定好，细节见 《tinyauth v5.2.0 Docker Compose 部署指南》第十二章。

5.2 数据库参数 database（含驱动选型拓展）

database.driver 决定 tinyauth 把会话、OIDC 客户端等持久化数据放哪。三种取值的行为差异与选型：

💡 技术拓展：tinyauth 的存储驱动共三种，横向对比——

驱动	原理/特点	适用场景
sqlite（默认）	单文件嵌入式数据库，落到 database.path，重启数据保留	单机部署、家庭实验室、中小规模（官方默认）
postgres	外部 PostgreSQL，连接 URL 写在 database.path	多实例共享状态、已有 PG 运维体系、中大规规模
memory	纯内存，重启全部丢失	一次性测试、临时演示

本文实测环境采用默认 sqlite：单机场景无共享需求，文件级备份即可覆盖（备份实操见 CLI 篇）。

memory 驱动实测：单独起一个 TINYAUTH_DATABASE_DRIVER=memory 的 tinyauth 实例（端口 8138），登录正常返回：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Set-Cookie: tinyauth-session-26742baf=0c9334f3-48d8-4961-8a55-cfab9fecbf13; Path=/; Domain=example.com; Expires=Sat, 24 Oct 2026 11:34:00 GMT; Max-Age=119; HttpOnly; SameSite=Lax
Date: Sat, 24 Oct 2026 11:32:00 GMT
Content-Length: 43

{"message":"Login successful","status":200}

sqlite 驱动下重启服务后数据保留（数据库文件 /data/tinyauth.db 实测 53248 字节），但旧会话 Cookie 重启后失效需重新登录（实测 401 后重新登录成功）；memory 驱动重启则一切归零。生产一律用 sqlite 或 postgres。

5.3 服务监听参数 server

server.port/server.address 控制监听，默认 0.0.0.0:3000，config dump 实测值一致。变更场景：宿主机 3000 端口已被占用时改容器侧端口映射即可，一般不动服务端口；server.socketpath 适合同机反代走 Unix socket 的场景（如 Caddy forward_auth 到 unix//run/tinyauth.sock），配置后 TCP 监听不再是主要通道，注意卷挂载要覆盖 socket 目录。

5.4 认证与会话参数 auth（用户文件、会话时效、Secure Cookie 实测）

用户文件形态实测：不用环境变量塞用户，改为挂载 users.txt（内容一行 ops1:$2a$10$Edf9Rb8EMGOjyXIf1.yLCur3593A9DlmuZyi5tTeT0./1dmWv62UK，即用户 ops1 密码 q1w2e3r4 的 bcrypt 哈希）并配置 TINYAUTH_AUTH_USERSFILE=/users.txt。启动后用该用户登录（实测回显）：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Set-Cookie: tinyauth-session-26742baf=ece12533-de2e-4dbc-af80-e80d1e7330e1; Path=/; Domain=example.com; Expires=Sun, 25 Oct 2026 11:31:56 GMT; Max-Age=86399; HttpOnly; SameSite=Lax
Date: Sat, 24 Oct 2026 11:31:56 GMT
Content-Length: 43

{"message":"Login successful","status":200}

用户文件生效，适合用户稍多、不想把哈希挤在 compose 文件里的场景。哈希生成用 tinyauth user create 命令（见 CLI 篇第七章）。

会话时效实测：TINYAUTH_AUTH_SESSIONEXPIRY=120 时登录，Cookie 立即变为（实测回显节选）：

Set-Cookie: tinyauth-session-26742baf=0c9334f3-48d8-4961-8a55-cfab9fecbf13; Path=/; Domain=example.com; Expires=Sat, 24 Oct 2026 11:34:00 GMT; Max-Age=119; HttpOnly; SameSite=Lax

Max-Age=119 与配置的 120 秒一致（1 秒差为响应耗时），证明该参数直接驱动 Cookie 有效期。默认 86400（24 小时）适合内部工具；安全要求高的场景可降到 3600 并配合 SESSIONMAXLIFETIME 强制重登。

Secure Cookie 实测：TINYAUTH_AUTH_SECURECOOKIE=true 时登录（实测回显节选）：

HTTP/1.1 200 OK
Set-Cookie: tinyauth-session-26742baf=349797bf-b1c2-46f0-975f-bffb20888b12; Path=/; Domain=example.com; Expires=Sun, 25 Oct 2026 11:37:38 GMT; Max-Age=86399; HttpOnly; Secure; SameSite=Lax

Cookie 末尾多出 Secure 属性，浏览器将只在 HTTPS 连接中回传。HTTPS 部署（生产标准形态）必须开启；纯 HTTP 内网测试环境保持默认 false，否则 Cookie 不回传导致登录循环。

5.5 登录防爆破参数实测（LOGINMAXRETRIES + LOGINTIMEOUT → 429 锁定）

tinyauth 内置登录防爆破：连续失败超过 LOGINMAXRETRIES 次后锁定 LOGINTIMEOUT 秒。实测组合 TINYAUTH_AUTH_LOGINMAXRETRIES=2、TINYAUTH_AUTH_LOGINTIMEOUT=15：

第 1 次、第 2 次错误密码返回：

{"message":"Unauthorized","status":401}

第 3 次请求（哪怕密码正确）返回（实测完整回显）：

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
X-Tinyauth-Lock-Locked: true
X-Tinyauth-Lock-Reset: 2026-10-24T11:32:19Z
Date: Sat, 24 Oct 2026 11:32:05 GMT
Content-Length: 82

{"message":"Too many failed login attempts. Try again in 14 seconds","status":429}

锁定期间继续尝试仍是 429；等待 15 秒窗口过后再试正确密码，恢复正常 200 登录。两个响应头可直接用于反代监控告警：X-Tinyauth-Lock-Locked 标识锁定状态，X-Tinyauth-Lock-Reset 给出解锁时间点。

💡 说明：生产暴露公网时建议保持默认 3 次 / 300 秒，或进一步收紧到 5 次 / 900 秒；该防护是实例级的，前置多层反代时按来源 IP 的细分防护需由 fail2ban 类工具补足。

5.6 访问控制（ACL）参数

ACL 决定「谁登录后能访问哪个应用」。全局策略由 auth.acls.policy 控制：allow（默认，未匹配 ACL 的应用全部放行）或 deny（未匹配即拒绝，白名单模式）。应用级策略用 apps.[NAME].* 配置，实测一组「只允许指定用户访问 whoami 应用」的配置：

# 环境变量形态
TINYAUTH_APPS_WHOAMI_CONFIG_DOMAIN=whoami.example.com
TINYAUTH_APPS_WHOAMI_USERS_ALLOW=nobody

已登录的 admin 访问该应用被拒（实测回显）：

HTTP/1.1 403 Forbidden
Content-Length: 36
Content-Type: application/json; charset=utf-8
X-Tinyauth-Location: http://auth.example.com/unauthorized?groupErr=false&ip=&resource=whoami&username=admin

{"message":"Forbidden","status":403}

把 USERS_ALLOW 改为 admin 后同一用户访问变为 200。X-Tinyauth-Location 头带出 resource、username、groupErr 等诊断字段，是 ACL 排障的第一入口。路径级放行（PATH_ALLOW，如健康检查路径免认证）按正则匹配，注意正则要锚定完整路径避免过度放行。

5.7 OAuth / OIDC 参数

OAuth 参数按 providers.[NAME].* 配置外部身份源，OIDC 参数按 clients.[NAME].* 把 tinyauth 自身作为符合 OpenID Certified™ Basic OP 规范的提供者（v5.1.0 起获得认证）对外签发身份。两套参数的配置方法在官方指南（GitHub OAuth / Google OAuth / Pocket ID / OpenID Connect 等章节）有逐提供者教程，本文不重复展开；要点三条：

1. OAuth 提供者名用 google/github 可自动填充端点与 scope，自建提供者必须完整配置 authUrl/tokenUrl/userinfoUrl；
2. OIDC 客户端凭据必须保存好，oidc create 输出明确提示 there is no way to regenerate them（生成后丢失只能重建客户端并更新应用侧配置）；
3. v5.2.0 的 claims.* 映射族可把任意提供者的用户信息字段对齐到 tinyauth 的标准字段，替代旧版写死的字段名。

5.8 UI 参数

UI 四参数均可在不改镜像的情况下定制登录页。实测 ui.title 经配置文件设为 Ops Portal 后 config dump 生效值同步变化（3.3 实验回显）。backgroundimage 默认 /background.webp 为镜像内置背景，替换时把图片文件放进 resources.path 目录并把该参数指向新路径。warningsenabled 建议生产保持开启：它会在登录页提示 APPURL 未配置 HTTPS、缺少可信代理等配置问题。

5.9 LDAP 参数

LDAP 是 v5.2.0 增强的认证源（新增 displayName 支持）。最小可用配置为 ADDRESS + BINDDN + BINDPASSWORD + BASEDN 四项；SEARCHFILTER 默认 (uid=%s) 面向 OpenLDAP 系，对接 Windows AD 必须改为官方注记的 (&(sAMAccountName=%s))。GROUPCACHETTL 默认 900 秒，调小可加快组变更生效但增加 LDAP 服务器压力。INSECURE=true 仅限测试，生产应配置 mTLS（AUTHCERT + AUTHKEY）或 LDAPS。

5.10 Tailscale 参数

Tailscale 集成（默认关闭）允许把 Tailnet 内设备身份作为认证来源，适合已全网上 Tailscale 的团队零账号接入。开启需 ENABLED=true + API 令牌（推荐 APITOKENFILE 文件形态）+ TAILNET 名称；CACHEDURATION 默认 300 秒控制设备/用户列表刷新频率。数据目录下实测存在 tailscale/ 工作子目录（/data 目录清单实测：oidc/、resources/、tailscale/、tinyauth.db）。

5.11 日志参数实测（JSON 格式 + debug 级别）

默认日志为带色彩的人类可读格式（INF/WRN/ERR 前缀）。开启 TINYAUTH_LOG_JSON=true 并把级别调到 debug 后，同一请求序列的日志变为（实测逐行照抄）：

{"level":"warn","stream":"app","time":"2026-10-24T11:31:47Z","time":"2026-10-24T11:31:47Z","caller":"/tinyauth/internal/bootstrap/router_bootstrap.go:42","message":"Trusted proxies are not configured, IP access controls will NOT work"}
{"level":"debug","stream":"app","time":"2026-10-24T11:31:47Z","time":"2026-10-24T11:31:47Z","caller":"/tinyauth/internal/bootstrap/app_bootstrap.go:307","message":"Starting database cleanup routine"}
{"level":"debug","stream":"app","time":"2026-10-24T11:31:47Z","time":"2026-10-24T11:31:47Z","caller":"/tinyauth/internal/bootstrap/app_bootstrap.go:312","message":"Starting heartbeat routine"}
{"level":"info","stream":"app","time":"2026-10-24T11:31:47Z","time":"2026-10-24T11:31:47Z","caller":"/tinyauth/internal/bootstrap/router_bootstrap.go:152","message":"Starting server on http://0.0.0.0:3000"}
{"level":"debug","stream":"app","username":"admin","time":"2026-10-24T11:31:51Z","time":"2026-10-24T11:31:51Z","caller":"/tinyauth/internal/controller/user_controller.go:73","message":"Login attempt"}
{"level":"info","stream":"app","username":"admin","time":"2026-10-24T11:31:51Z","time":"2026-10-24T11:31:51Z","caller":"/tinyauth/internal/controller/user_controller.go:215","message":"Login successful"}
{"level":"info","stream":"http","method":"POST","path":"/api/user/login","address":"10.89.57.1:47122","client_ip":"10.89.57.1","status":200,"latency":"42.583317ms","time":"2026-10-24T11:31:51Z","time":"2026-10-24T11:31:51Z","caller":"/tinyauth/internal/middleware/zerolog_middleware.go:74","message":"Request"}
{"level":"debug","stream":"http","method":"GET","path":"/api/healthz","address":"127.0.0.1:56584","client_ip":"127.0.0.1","status":200,"latency":"22.294µs","time":"2026-10-24T11:31:52Z","time":"2026-10-24T11:31:52Z","caller":"/tinyauth/internal/middleware/zerolog_middleware.go:77","message":"Request"}

要点三条：其一，stream 字段区分 app（应用日志）与 http（请求日志）两条流，对应 LOG_STREAMS_* 参数可独立开关与定级；其二，这条实测日志同时抓到了未配置可信代理的告警 Trusted proxies are not configured, IP access controls will NOT work——正是 4.6 中 TINYAUTH_AUTH_TRUSTEDPROXIES 不配置的直接后果，凡是用到 IP 类 ACL 的部署必须配它；其三，JSON 日志带 caller（源码位置）与结构化字段，接入 Loki/ELK 后按 stream/level 拆分索引即可。

💡 技术拓展：日志采集格式两种主流选择的取舍——

形态	特点	适用场景
人类可读（默认）	彩色分级前缀，肉眼排障快	单机、低流量、人工查看
JSON 结构化	字段固定、机器可解析、含 caller/latency	接入集中式日志栈（Loki/ELK）、需要告警规则

本文实测环境默认可读形态排障，生产建议 LOG_JSON=true。

5.12 实验性参数 experimental

experimental.oauthbridgeenabled 与 experimental.disableauthmodulefallback 均默认关闭。前者切换 OAuth 用户信息的新格式化通道（受旧提供者 claim 兼容问题困扰时按官方 Issue 指引尝试）；后者关闭「auth_request/ext_authz 模块失败时自动回退 forward_auth 端点」的兜底行为，用于强制暴露模块级故障而非静默回退。实验性参数随版本可能变动，升级前应对照 Release Notes 复核。

六、生产配置模板

6.1 小型场景模板（单机、SQLite、≤20 个受保护应用）

适用：2GB 内存、20GB 磁盘即可运行（tinyauth 为 Go 单进程，实测空闲内存占用很低），家庭实验室或小团队内部工具统一认证。Compose 环境变量段（哈希为 q1w2e3r4 的真实 bcrypt 值，Compose 中 $ 双写转义）：

environment:
  - TINYAUTH_APPURL=https://auth.example.com
  - TINYAUTH_AUTH_USERS=admin:$$2a$$10$$Edf9Rb8EMGOjyXIf1.yLCur3593A9DlmuZyi5tTeT0./1dmWv62UK
  - TINYAUTH_AUTH_TRUSTEDPROXIES=10.89.57.0/24
  - TINYAUTH_AUTH_SECURECOOKIE=true
  - TINYAUTH_AUTH_SESSIONEXPIRY=86400
  - TINYAUTH_AUTH_LOGINMAXRETRIES=3
  - TINYAUTH_AUTH_LOGINTIMEOUT=300
  - TINYAUTH_ANALYTICS_ENABLED=false
  - TINYAUTH_LOG_JSON=true

逐项说明：APPURL 用三段式域名且与反代对外协议一致；TRUSTEDPROXIES 填反代所在网段（配 IP ACL 的前提，5.11 实测告警即缺失此项）；SECURECOOKIE=true 因为模板走 HTTPS；会话与防爆破保持默认；关闭分析上报、开 JSON 日志便于集中采集。改完后用 docker exec <tinyauth 实例名> tinyauth config 核对生效值（回显形态见 3.1）。

6.2 中型场景模板（Postgres 集中存储 + OAuth 身份源）

适用：多台反代/多实例 tinyauth 共享会话，或已有 PostgreSQL 运维体系。在 6.1 基础上增改：

environment:
  - TINYAUTH_DATABASE_DRIVER=postgres
  - TINYAUTH_DATABASE_PATH=postgres://tinyauth:q1w2e3r4@pg.internal:5432/tinyauth
  - TINYAUTH_OAUTH_PROVIDERS_GITHUB_CLIENTID=Iv1.0123456789abcdef
  - TINYAUTH_OAUTH_PROVIDERS_GITHUB_CLIENTSECRET=0123456789abcdef0123456789abcdef01234567
  - TINYAUTH_OAUTH_WHITELIST=example.com
  - TINYAUTH_OAUTH_AUTOREDIRECT=github

逐项说明：DATABASE_DRIVER=postgres 后 DATABASE_PATH 承载连接 URL（格式依据官方 Configuration 参考，2026-10-24 查证；本文实测环境未接入 Postgres 实例，采用该模板前建议先在测试实例验证连通）；providers.github 享受官方自动填充端点红利，只需 ID 与 secret；OAUTH_WHITELIST 限定允许登录的邮箱域；AUTOREDIRECT 跳过提供者选择页直达 GitHub 授权。生产密钥建议改用 CLIENTSECRETFILE 文件形态注入。

七、常见问题

Q1：启动报 failed to parse app url: invalid url 是什么问题？ 两种可能：一是 TINYAUTH_APPURL 根本没配或为空（本文 3.3 实测：配置文件形态下环境变量被忽略就会出现此错，需把 appUrl 写进 YAML）；二是 APPURL 不是合法 URL（缺协议头等）。修复后用 tinyauth config 确认 appUrl 有值。

Q2：启动报 no authentication providers configured？ tinyauth 至少需要一种认证提供者：本地用户（TINYAUTH_AUTH_USERS 或 TINYAUTH_AUTH_USERSFILE）、OAuth、OIDC、LDAP、Tailscale 任一。最常见原因是启用了配置文件形态但 YAML 里漏掉 auth.users（本文 3.3 第二次实验复现）。

Q3：登录一直 401，Cookie 明明带上了？ 依次排查三点：APPURL 是否三段式域名（两段式派生的 Cookie 域覆盖不了兄弟子域，见 5.1）；服务重启过则旧会话已失效（实测重启后旧 Cookie 401，重新登录即可）；HTTPS 部署是否开了 SECURECOOKIE=true 而实际仍走 HTTP（或反之，HTTP 环境开了 Secure 导致浏览器不回传）。

Q4：登录时报 429 Too Many Requests？ 触发了登录防爆破锁定（5.5 实测机制）：连续失败超过 LOGINMAXRETRIES 次后锁定 LOGINTIMEOUT 秒。等待响应头 X-Tinyauth-Lock-Reset 指示的时间点后重试；忘记密码时应直接改配置中的用户哈希而不是继续试错。

Q5：日志出现 Trusted proxies are not configured, IP access controls will NOT work？ 未配置 TINYAUTH_AUTH_TRUSTEDPROXIES。反代转发场景下 tinyauth 依赖该列表识别真实客户端 IP，不配置则所有 IP 类访问控制（IP_ALLOW/IP_BLOCK/应用级 IP 策略）失效。填入反代所在网段（本文实测 10.89.57.0/24）并重启。

Q6：改了环境变量不生效？ 先确认容器确实重建而非仅重启（Compose 改 environment: 需要 up -d 重建）；再确认没有同时启用 TINYAUTH_CONFIGFILE——配置文件形态下环境变量整体失效（3.3 实测）；最后用 tinyauth config 对照 dump 值定位实际生效来源。

Q7：TINYAUTH_AUTH_USERS 里的哈希在 Compose 中写法报错？ Compose 文件中 $ 是变量插值符，bcrypt 哈希的 $2a$10$... 必须双写为 $$2a$$10$$...（本文 6.1 模板即此形态）；docker run -e 或 shell 单引号场景则保持单 $ 原样。

八、参考链接

• 官方 Configuration 参考：https://tinyauth.app/docs/reference/configuration
• 官方 Authentication 参考（用户格式与认证机制）：https://tinyauth.app/docs/reference/authentication
• 官方 CLI 参考：https://tinyauth.app/docs/reference/cli
• 官方文档站：https://tinyauth.app
• GitHub 仓库（含 Releases）：https://github.com/tinyauthapp/tinyauth
• 本专栏系列：《tinyauth v5.2.0 介绍与选型指南》（定位、架构与同类对比）、《tinyauth v5.2.0 Docker Compose 部署指南》（部署与三类反代集成）、《tinyauth v5.2.0 常用 CLI 命令与运维实操》（CLI 子命令与备份恢复实操）