tinyauth v5.2.0 介绍与选型指南

目标：面向正在为自托管应用挑选「登录认证层」的工程师，梳理 tinyauth v5.2.0 的产品定位、核心架构、功能边界，并给出与 Authelia、oauth2-proxy、Kanidm 的量化选型对比。本文为 A1 认知篇（联网溯源），全部事实性内容均于 2026-10-24 从官方渠道（GitHub 仓库 tinyauthapp/tinyauth、官方文档站 tinyauth.app、releases.atom 订阅源、shields.io 徽章）实查取得并标注来源；部署、配置与命令的实测内容见本专栏后续各篇。

一、环境信息

本文为 A1 认知篇（联网溯源），写作时不依赖本地环境，所有版本、星数、许可与功能口径均于 2026-10-24 从下列官方渠道实查：

💡 说明：tinyauth 更新活跃，README 明确警告「Tinyauth is in active development and configuration may change often」，升级前须逐版阅读 Release Notes；本文版本口径截至 2026-10-24。

二、软件概述

2.1 定位与身份

tinyauth 的官方自我定位只有一句话：「你见过的最小的 OpenID Certified™ 认证与授权服务器」（The tiniest OpenID Certified™ authorization and authentication server you have ever seen，来源：GitHub README，查询日期 2026-10-24）。它同时扮演两个角色：

1. 认证中间件：作为反向代理的 Forward Auth 后端，给 Traefik、Nginx、Caddy 后面的任意 Web 应用加一道「统一登录页」，登录通过后把 Remote-User、Remote-Email、Remote-Name、Remote-Groups 等身份头转发给后端应用；
2. 独立认证服务器：内建符合 OpenID Connect 规范的 OP（OpenID Provider，已通过 OpenID 基金会 Basic OP 认证），可直接给支持 OIDC 登录的应用当身份源。

一句话理解它的产品逻辑：在「给几个自托管应用加个登录页」和「上一套完整身份基础设施」之间，tinyauth 选择把前者做到极致——单个 Go 二进制、默认内嵌 SQLite、一份环境变量就能跑起来，不要求你先部署数据库、消息队列或目录服务。

💡 技术拓展：自托管场景的「认证层」业界主要有三种形态，选型前应先分清——

形态	代表产品	原理	适用场景
反向代理 Forward Auth 网关	tinyauth、Authelia、oauth2-proxy	代理把每个请求先转给认证服务校验，未登录跳登录页	给已有 Web 应用统一加登录，应用零改造
独立身份提供者（IdP）	Keycloak、Kanidm、Zitadel	应用走 OIDC/SAML 标准协议对接 IdP	多团队、多应用、需要完整账号生命周期管理
目录服务	OpenLDAP、389 Directory Server	集中账号目录，应用通过 LDAP 绑定校验	已有应用原生支持 LDAP 的传统企业环境

tinyauth 属于第一种，但同时内建了轻量第二种（OIDC OP）与第三种（作为 LDAP 客户端对接上游目录）的能力。

2.2 版本与许可

• 当前稳定版：v5.2.0，2026-09-07 发布（来源：GitHub Releases / releases.atom，查询日期 2026-10-24）。
• 许可证：AGPL-3.0。README 的 TL;DR：可自由复制、分发、修改，但修改版（含通过网络提供服务）必须开源并提供构建说明。对「拿 tinyauth 改造后对外提供托管服务」的商用场景有传染性约束，个人自托管与内部使用不受影响。
• 治理与社区：个人主导的社区项目（作者 steveiliop56，仓库已迁移至 tinyauthapp 组织），配套 Discord 社区、Crowdin 多语言翻译，且有 OpenSSF Scorecard 与 OSSF Best Practices 徽章（来源：README 徽章区，查询日期 2026-10-24）。
• 文档与演示：官方文档站 tinyauth.app 提供完整指南与参考；官方在线演示 demo.tinyauth.app（演示账号 user / password）。

2.3 版本节奏（量化）

近期发布记录（来源：GitHub releases.atom，查询日期 2026-10-24）：

从 v5.1.0 到 v5.2.0 约 2.5 个月，预发布（alpha→beta→rc→stable）链路完整，节奏可预期。v5.2.0 的主要变更（来源：官方 Release Notes / 文档站 Changelog，查询日期 2026-10-24）：LDAP 用户 displayName 支持、OAuth 自定义 claim 映射、OIDC 授权同意记忆、登录页 WebP 背景优化、Docker 连接退避重试、密钥常量时间比较、代理场景查询参数保留、域名支持下划线。

三、核心架构

3.1 运行时构成

tinyauth 是单进程单二进制架构（Go 编写），运行时只有它自己，外围依赖最少：

💡 技术拓展：tinyauth 内嵌的 SQLite 属于「嵌入式数据库」，同类可选形态对比——

形态	原理	适用场景
SQLite（tinyauth 默认）	单文件库，进程内读写	单实例部署，会话/资源数据量小，零运维
PostgreSQL（可选）	独立数据库服务，网络连接	多实例共享数据、已有 Postgres 运维体系
内存（可选）	数据驻留进程内存，重启即失	一次性验证、无状态测试

tinyauth 默认 SQLite，与它「最小化」的定位一致；生产长期运行建议至少把数据文件落到持久化卷（本专栏《tinyauth v5.2.0 Docker Compose 部署指南》有实测步骤）。

3.2 认证数据流与集成模式

tinyauth 与被保护应用之间没有 SDK、不需要改应用代码，一切都发生在反向代理层。以 Traefik 为例的官方标准链路（来源：官方文档站 Getting Started 与 Traefik 集成指南，查询日期 2026-10-24）：

浏览器 ──访问 whoami.example.com──→ 反向代理(Traefik/Nginx/Caddy)
                                        │ ① 每个请求先 Forward Auth 到 tinyauth
                                        ↓
                              tinyauth /api/auth/traefik 校验 Cookie/Basic 凭据
                                        │
                        未认证 ② 返回 401 + 登录跳转地址 → 代理 302 到登录页
                        已认证 ③ 返回 200 + Remote-User 等身份头 → 代理转发给后端应用

关键设计点：

1. 统一 Forward Auth 端点族：官方为 Traefik（/api/auth/traefik）、Caddy（/api/auth/caddy）、Nginx（/api/auth/nginx）分别提供端点（来源：官方文档站各代理集成指南；Nginx 端点自 v5.2.0 起提供）。
2. 身份头转发：认证通过后，代理把 Remote-User / Remote-Name / Remote-Email / Remote-Groups 注入上游请求，应用据此识别用户。
3. 父域 Cookie：TINYAUTH_APPURL 填 auth.example.com 这类三段子域时，会话 Cookie 落在父域 example.com，同父域下所有被保护应用共享登录态，一次登录全站通行。
4. 域前置校验：Forward Auth 请求必须携带代理注入的原始请求上下文头（X-Forwarded-*），直接裸打端点会得到 400——这是防绕过的设计而非缺陷。

💡 技术拓展：Forward Auth 的实现机制随代理而异，接入时配置写法完全不同——

机制	代表代理	工作方式
ForwardAuth 中间件	Traefik	代理内置中间件直接子请求认证端点，响应头可回注
auth_request 子请求	Nginx / OpenResty	auth_request 模块发子请求，401 时 error_page 重定向登录
forward_auth 指令	Caddy	forward_auth 简化指令（本质是 reverse_proxy + copy_headers）
ext_authz 扩展	Envoy	gRPC/HTTP 外部授权过滤器

tinyauth 三大主流代理官方均有逐条配置指南；本文与专栏部署篇实际采用 Traefik + Caddy + Nginx 三种各成一节验证。

3.3 部署形态

官方支持的部署形态（来源：官方文档站 Getting Started / Using the Binary / Kubernetes 指南，查询日期 2026-10-24）：

四、功能特性

4.1 多身份源认证

• 本地用户：配置格式 username:bcrypt_hash[:totp_secret]，密码使用 bcrypt 哈希存储（来源：官方文档站 Authentication 与 CLI 参考）。官方 CLI 提供 user create / user verify / totp generate 子命令生成与校验该格式。

💡 技术拓展：bcrypt 是 tinyauth 的密码哈希选择。常见口令哈希算法横向对比——

算法	特点	现状
bcrypt	基于 blowfish，自带盐，成本因子可调	成熟通用，tinyauth 采用
argon2id	内存困难型，抗 GPU 破解更强	新一代推荐（PHC 冠军）
scrypt	内存困难型	可用，采用率低于 argon2
PBKDF2	纯 CPU 迭代，FIPS 认证	合规场景用
SHA-256/MD5 裸哈希	无盐快速哈希	口令存储禁用

tinyauth 选用 bcrypt：单机认证场景下安全性与实现简单度的平衡点。

• OAuth2 登录：官方指南覆盖 GitHub、Google、Pocket ID 与任意通用 OAuth2 提供商；使用 google/github 作为提供商 ID 时自动填充授权/令牌端点与 scopes，只需提供 client ID/secret（来源：官方 Configuration 参考 Notes 节）。
• LDAP：作为 LDAP 客户端对接 OpenLDAP/Active Directory 等，支持 Bind DN 认证、自定义搜索过滤器（默认 (uid=%s)，Windows AD 推荐 (&(sAMAccountName=%s))）、组成员缓存（默认 900 秒）、mTLS 证书认证（来源：官方 Configuration 参考 ldap 组）。
• Tailscale：可开启 Tailscale 集成，按 Tailnet 设备/用户列表做身份判定（来源：官方 Tailscale 指南）。
• 双因子（2FA）：本地用户可叠加 TOTP（username:hash:totp_secret 三段格式），CLI 一键生成带二维码的 TOTP 配置。

4.2 访问控制（ACL）

按应用维度配置（TINYAUTH_APPS_<NAME>_* 环境变量族，来源：官方 Access Controls 指南与 Configuration 参考）：

4.3 OIDC 提供者（独立身份服务器）

tinyauth 自 v5.1.0 起通过 OpenID Certified™ Basic OP 认证（来源：README 与 OpenID 基金会认证页，查询日期 2026-10-24），可作为标准 OP 给 Immich、Beszel 等支持 OIDC 的应用做身份源（官方 Integrations 章节提供 Immich、Beszel、Zerobyte、Zitadel 对接指南）。OIDC 客户端通过 TINYAUTH_OIDC_CLIENTS_<NAME>_* 声明，密钥文件路径默认 /data/oidc/key.pem（镜像形态）。

4.4 运维与可观测

• 三种配置方式等价：环境变量 / CLI 标志 / YAML 配置文件（TINYAUTH_CONFIGFILE），官方 Configuration 参考三列对照（来源：官方 Configuration 页 Environment/Flags/YAML 三个标签页）。
• 配置自检命令：tinyauth config 可把当前生效配置转储为 YAML，排障时直接核对生效值（来源：官方 CLI 参考）。
• 健康检查：tinyauth healthcheck 子命令打内部健康端点，官方文档建议使用内部地址而非公网 URL。
• 审计日志：TINYAUTH_LOG_STREAMS_AUDIT_ENABLED 可开启独立审计日志流；日志级别 trace–error 五档，可选 JSON 格式。
• 遥测：默认开启匿名版本信息上报（TINYAUTH_ANALYTICS_ENABLED=true），可关闭。

五、快速开始（最小可用示例）

以下为官方文档站 Getting Started 给出的最小路径（来源：tinyauth.app Getting Started 与 CLI 页，查询日期 2026-10-24；完整步骤与三代理集成实测见本专栏部署篇）：

第 1 步：生成用户条目（交互式 TUI，输出 username:hash 格式）：

docker run -i -t --rm ghcr.io/tinyauthapp/tinyauth:v5 user create --interactive

第 2 步：以 Compose + Traefik 标签启动（官方示例编排的 tinyauth 服务段）：

tinyauth:
  image: ghcr.io/tinyauthapp/tinyauth:v5
  restart: unless-stopped
  environment:
    - TINYAUTH_APPURL=https://tinyauth.example.com
    - TINYAUTH_AUTH_USERS=your-username-password-hash
  labels:
    traefik.enable: true
    traefik.http.routers.tinyauth.rule: Host(`tinyauth.example.com`)
    traefik.http.middlewares.tinyauth.forwardauth.address: http://tinyauth:3000/api/auth/traefik

第 3 步：给要保护的路由挂上中间件（官方示例）：

traefik.http.routers.[your-router].middlewares: tinyauth

完成后，未登录访问被保护应用会被 302 到 tinyauth 登录页，登录后回跳原页面并携带身份头。

六、适用场景与限制

6.1 适用场景

1. 家庭实验室/个人自托管应用统一登录：几个到十几个应用（相册、下载器、面板、监控）都要加登录页，tinyauth 的「一份环境变量 + 代理中间件」是成本最低的方案。
2. 小团队内部工具防护：本地用户 + OAuth（GitHub/Google）双通道，配合 ACL 按应用授权，覆盖小型团队权限需求。
3. 给 OIDC 应用作轻量身份源：不想部署 Keycloak，又要给 Immich 这类支持 OIDC 的应用提供标准登录。
4. 已有 LDAP/AD 的环境做 Web 层认证：tinyauth 作为 LDAP 客户端把目录账号接到 Web 登录页。

6.2 资源参考

• 官方未给出硬性资源下限；架构上为单 Go 进程 + SQLite，属「百兆级内存」的轻量形态（同类 Authelia 为 Go 单进程、Keycloak 需 JVM 数百 MB 至数 GB）。
• 会话数据落 Cookie + 数据库，认证链路每请求一次 Forward Auth 子请求，延迟敏感场景应保证 tinyauth 与代理同机/同内网。

6.3 限制（评估前必须知道）

1. 必须使用子域：TINYAUTH_APPURL 须为 auth.example.com 形态的子域，DDNS 裸域（如 myhome.duckdns.org 整域当应用域）场景不受支持（来源：官方文档站对 APPURL/父域 Cookie 的说明）。
2. 单实例架构：无内建集群/多副本会话共享方案（会话依赖本地库与父域 Cookie），高可用需自行在代理层权衡；这与其「最小化」定位一致。
3. 配置演进快：README 明确警告配置可能随版本频繁变化，跨大版本升级（v3→v4→v5 均有 Breaking Updates 专页）需逐版核对。
4. AGPL-3.0 传染性：二次开发后对外提供网络服务须开源修改。
5. 功能面小于全功能 IdP：无 SAML、无细粒度用户管理后台（用户在配置中声明），大规模组织账号管理不是它的目标场景。

七、同类选型对比

7.1 竞品对照表

以下星数均来自 shields.io github/stars 徽章实查（查询日期 2026-10-24）；定性维度来自各项目官方 README/文档站的定位描述（同日期实查）：

关键差异解读：四者不是同位替代关系——oauth2-proxy 是「把已有 IdP 接到代理」的胶水层，没有本地账号；Authelia 是功能最全的网关型方案但配置复杂度陡增；Kanidm 是自建身份基础设施；tinyauth 卡位在「最小成本拿到可靠登录 + 够用的 OIDC/ACL」。

7.2 选型建议（「如果…则…」）

• 如果只有几台服务器上的自托管应用要加登录页、不想维护数据库和复杂配置 → tinyauth。
• 如果需要按路径/域的细粒度 ACL、WebAuthn、多用户管理后台、企业级会话策略 → Authelia。
• 如果已有 Keycloak/Google 等身份源，只需在网关层统一接入 → oauth2-proxy。
• 如果要建组织级账号体系（LDAP 目录 + OIDC + 账号自助管理） → Kanidm（或传统 OpenLDAP + Keycloak 组合）。
• 如果AGPL 传染性不可接受 → 改选 Apache-2.0 的 Authelia 或 MIT 的 oauth2-proxy。

八、参考链接

• GitHub 仓库：https://github.com/tinyauthapp/tinyauth
• 官方文档站：https://tinyauth.app
• Getting Started：https://tinyauth.app/docs/getting-started
• Configuration 参考：https://tinyauth.app/docs/reference/configuration
• CLI 参考：https://tinyauth.app/docs/reference/cli
• OpenID 认证页：https://openid.net/certification-old/certified-openid-providers-profiles/
• 官方在线演示：https://demo.tinyauth.app