tinyauth v5.2.0 常用 CLI 命令与运维实操

目标：系统梳理 tinyauth v5.2.0 自带 CLI 的全部子命令（config、version、healthcheck、user、totp、oidc）及其参数与真实回显，并给出用户增补、数据备份恢复、健康巡检、日志排障、版本升级等日常运维场景的完整实操。本文全部命令与回显已在 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 部署指南》），服务端口 3000 映射宿主机 8131，编排项目名 tinyauth-v5.2.0-stack
管理员账号：admin / 密码 q1w2e3r4（bcrypt 哈希 admin:$2a$10$Edf9Rb8EMGOjyXIf1.yLCur3593A9DlmuZyi5tTeT0./1dmWv62UK，Compose 中 $ 双写）
编排目录：/opt/tinyauth/（内含 docker-compose.yml，与部署篇一致）
数据卷：tinyauth-v520-stack_tinyauth-data 挂载到容器 /data（SQLite 数据库 + OIDC 密钥 + 资源目录）
CLI 命令考证来源：官方 CLI 参考（https://tinyauth.app/docs/reference/cli ，2026-10-24 查证）+ 本地逐命令实测

二、工具概览

tinyauth 是单二进制 Go 程序，CLI 与服务共用一个入口：不带子命令时启动 API 与登录页服务，带子命令时执行管理操作。tinyauth --help 的命令清单（实测回显）：

tinyauth    The simplest way to protect your apps with a login screen

Usage: tinyauth [command] [flags] [arguments]

Use "tinyauth [command] --help" for help on any command.

Commands:
    help           Show the help message
    version        Print the version number of Tinyauth
    config         Dump the current configuration in YAML format, useful for debugging
    healthcheck    Perform a health check
    user           Manage users
    totp           Manage TOTP users
    oidc           Manage OIDC clients

Flag's usage: tinyauth [--flag=flag_argument] [-f [flag_argument]]    # set flag_argument to flag(s)
          or: tinyauth [--flag[=true|false| ]] [-f [true|false| ]]    # set true/false to boolean flag(s)

六个命令的职责分工：config 查看生效配置（完整参数解读见《tinyauth v5.2.0 配置参数详解》，本文不重复参数表）；version 查看版本；healthcheck 健康检查；user 管理本地用户（创建/校验）；totp 生成两步验证密钥；oidc 生成 OIDC 客户端凭据。后三个命令都是「生成配置值」的工具——输出直接回填到环境变量或 YAML 后重启生效。

💡 说明：除上述子命令外，tinyauth --help 还会列出约 200 个 -- 开头的全局标志（即全部配置参数的 CLI 形态，如 --auth.users、--server.port），与配置参数一一对应，完整对照表见《tinyauth v5.2.0 配置参数详解》第四章。

三、前置条件

已按部署篇完成 tinyauth 部署且服务健康，验证命令与回显：

docker compose -f /opt/tinyauth/docker-compose.yml ps

实测回显：

NAME                      IMAGE                                 STATUS
tinyauth-v5.2.0-app       ghcr.io/tinyauthapp/tinyauth:v5.2.0   Up 8 minutes (healthy)
tinyauth-v5.2.0-caddy     caddy:2.10-alpine                     Up 14 hours
tinyauth-v5.2.0-nginx     nginx:1.29-alpine                     Up 14 hours
tinyauth-v5.2.0-traefik   traefik:v3.5                          Up 14 hours
tinyauth-v5.2.0-whoami    traefik/whoami:v1.10.4                Up 14 hours

读者环境中的实例名与本文不同时，把 docker exec 后面的实例名（本文 tinyauth-v5.2.0-app）替换为自己的即可；用 Compose 管理时统一用 docker compose exec tinyauth ...（服务名固定为编排文件里的 tinyauth），无需关心实例名
本文所有「一次性命令」均在编排目录 /opt/tinyauth/ 内执行（docker compose run 需要读取编排文件）

四、CLI 运行入口与主命令

4.1 三种运行入口实测

CLI 命令有三种等价运行方式，按场景选用：

入口一：进入已运行实例执行（服务在跑时最常用，读写共享同一数据目录）：

docker compose exec tinyauth tinyauth version

实测回显：

Version: v5.2.0
Commit Hash: 653b747829cc72b5ad5232db63b075fb66f81796
Build Timestamp: 2026-09-07T17:15:08

入口二：临时起一次性实例执行（不占用常驻实例，适合服务未启动时操作；官方文档推荐形态）：

docker compose run --rm tinyauth user create --username ops2 --password q1w2e3r4

实测回显：

Created user 'ops2'.

Environment variable:

TINYAUTH_AUTH_USERS=ops2:$2a$10$7JOgUbk0Kerq04xCFIajvegWMit5.MmDoA7MZQObQezudESBFHEV.

CLI flags:

--auth.users=ops2:$2a$10$7JOgUbk0Kerq04xCFIajvegWMit5.MmDoA7MZQObQezudESBFHEV.

YAML config:

auth:
    users:
        - ops2:$2a$10$7JOgUbk0Kerq04xCFIajvegWMit5.MmDoA7MZQObQezudESBFHEV.

Use your config option of choice to add the user to Tinyauth and then restart.

入口三：直接用镜像跑一次性实例（未用 Compose 编排时）：

docker run --rm ghcr.io/tinyauthapp/tinyauth:v5.2.0 version

实测回显与入口一一致（Version/Commit Hash/Build Timestamp 三行相同）。

⚠️ 注意：user create、totp generate、oidc create 属于「生成配置值」类命令，不会自动写库或改配置，输出需人工回填到 TINYAUTH_AUTH_USERS 等配置项并重启才生效；config、healthcheck 则作用于当前实例的运行状态。

4.2 主命令与启动形态

tinyauth 不带子命令即为主命令，启动 API 服务与 Web 登录页并阻塞等待连接。Docker 部署下主命令由镜像入口封装，无需手工执行；二进制直跑形态为 ./tinyauth [options]，全部 [options] 即配置参数的 CLI 标志形态（约 200 个），完整清单可用 tinyauth --help 查看，参数含义详见《tinyauth v5.2.0 配置参数详解》。服务启动成功的标志日志（实测）：

Starting Tinyauth version: v5.2.0
Starting server on http://0.0.0.0:3000

4.3 version 命令

输出当前构建三元组，升级后核对版本用：

docker exec tinyauth-v5.2.0-app tinyauth version

实测回显：

Version: v5.2.0
Commit Hash: 653b747829cc72b5ad5232db63b075fb66f81796
Build Timestamp: 2026-09-07T17:15:08

五、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
...
log:
    level: info
    streams:
        http:
            enabled: true
        app:
            enabled: true

命令本身无参数；配合 grep 可快速定位单项生效值，例如核对会话有效期：

docker exec tinyauth-v5.2.0-app tinyauth config | grep -A1 session

实测回显：

    sessionExpiry: 86400

全文解读与配置文件形态的坑（TINYAUTH_CONFIGFILE 启用后环境变量失效）见《tinyauth v5.2.0 配置参数详解》第三章。

六、healthcheck 命令

healthcheck 对健康端点 /api/healthz 发起真实 HTTP 请求，用于巡检与容器健康探测。默认探测 http://127.0.0.1:3000（自动跟随 TINYAUTH_SERVER_PORT/TINYAUTH_SERVER_ADDRESS 配置），也可显式传 URL。

6.1 默认探测

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

response={"message":"Healthy","status":200} 即健康；命令退出码 0，可直接用于监控脚本判断。

6.2 自定义探测 URL

传位置参数可指定目标 URL，探测走内部网络的服务名（Compose 场景服务名 tinyauth 可直接解析）：

docker exec tinyauth-v5.2.0-app tinyauth healthcheck http://tinyauth:3000

实测回显：

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

6.3 探测失败回显（排障基准）

目标不可达时的失败回显（实测，注意错误含 DNS 解析细节，可直接定位网络问题）：

2026-10-24T11:34:27Z INF Performing health check app_url=http://nonexistent.example.internal:3000 stream=app
Failed to execute command: command healthcheck error: failed to perform request: Get "http://nonexistent.example.internal:3000/api/healthz": dial tcp: lookup nonexistent.example.internal on 127.0.0.11:53: no such host

官方注记建议 healthcheck 使用内部地址（如 http://127.0.0.1:3000）而非对外公开域名，避免外网抖动误报健康状态。

6.4 官方文档命令形态的坑（healthcheck 不在 PATH）

官方 CLI 参考给出的 docker compose exec tinyauth healthcheck 在 v5.2.0 镜像中直接报错（实测回显）：

OCI runtime exec failed: exec failed: unable to start container process: exec: "healthcheck": executable file not found in $PATH

⚠️ 排障结论：healthcheck 是 tinyauth 二进制的子命令而非独立可执行文件，exec 时必须带上二进制名——正确形态是 docker compose exec tinyauth tinyauth healthcheck（6.1 实测通过）。本文全部 exec 形态命令均已按此规则书写。

七、user 命令详解

user 命令管理本地用户，含 create（生成用户配置值）与 verify（校验凭据）两个子命令（tinyauth user --help 实测清单：verify Verify a user is set up correctly、create Create a user）。

7.1 user create：创建用户

生成 用户名:bcrypt哈希 配置值（4.1 入口二已给出完整回显）。参数表（实测 create --help 回显整理）：

标志	说明	默认值	必填
`--username`	用户名	空	是
`--password`	密码	空	是
`--docker`	按 Compose 环境变量格式输出（`$` 双写转义）	`false`	否
`--interactive`	交互式 TUI 创建	`false`	否

标准用法与回显（4.1 入口二实测）：docker compose run --rm tinyauth user create --username ops2 --password q1w2e3r4，输出三形态配置值（环境变量/CLI 标志/YAML），任选一种回填配置后重启生效。

7.2 user create --docker：Compose 转义形态

加 --docker 后输出的环境变量形态自动把 $ 双写，可直接粘贴进 Compose 文件（实测回显）：

docker run --rm ghcr.io/tinyauthapp/tinyauth:v5.2.0 user create --username admin --password q1w2e3r4 --docker

Created user 'admin'.

Environment variable:

TINYAUTH_AUTH_USERS=admin:$$2a$$10$$znGmVq.l0UmU91D7g5irQOwBY.HohGn8vNEahjCEgwnh/NzMWmWuC

CLI flags:

--auth.users=admin:$2a$10$znGmVq.l0UmU91D7g5irQOwBY.HohGn8vNEahjCEgwnh/NzMWmWuC

YAML config:

auth:
    users:
        - admin:$2a$10$znGmVq.l0UmU91D7g5irQOwBY.HohGn8vNEahjCEgwnh/NzMWmWuC

Use your config option of choice to add the user to Tinyauth and then restart.

对比可见：Environment variable 段输出 $$2a$$10$$（Compose 转义形态），CLI flags 与 YAML config 段保持单 $。手写 Compose 配置时漏双写 $ 会导致哈希被变量插值破坏、登录永远 401，这是最高频的配置事故，--docker 输出可彻底避免。

7.3 user create --interactive：交互式创建与 TTY 排障

--interactive 启动 TUI 交互输入用户名与密码，需真实终端。在无终端的管道/定时任务环境执行会失败（实测回显）：

docker run -i --rm ghcr.io/tinyauthapp/tinyauth:v5.2.0 user create --interactive < /dev/null

Failed to execute command: command create error: failed to run interactive prompt: huh: bubbletea: error opening TTY: bubbletea: could not open TTY: open /dev/tty: no such device or address

⚠️ 排障结论：报 could not open TTY 说明当前环境没有交互终端，改用非交互形态（--username + --password，7.1 实测）即可；交互形态仅在 SSH 登录服务器后手工执行时使用。

7.4 user verify：校验用户配置

校验一组 用户名:哈希 与账密是否匹配，用于改配置后先验证再重启。参数（实测 verify --help 回显整理）：

标志	说明	默认值	必填
`--user`	待校验的 `用户名:哈希`（配置原文，含单引号防 shell 展开）	空	是
`--username`	用户名	空	是
`--password`	密码	空	是
`--totp`	两步验证码（TOTP 用户时使用）	空	否
`--interactive`	交互式 TUI 校验	`false`	否

正确凭据实测：

docker run --rm ghcr.io/tinyauthapp/tinyauth:v5.2.0 user verify \
  --user 'ops2:$2a$10$7JOgUbk0Kerq04xCFIajvegWMit5.MmDoA7MZQObQezudESBFHEV.' \
  --username ops2 --password q1w2e3r4

✓ User verified

密码错误实测（--password wrong-pass）：

Failed to execute command: command verify error: password is incorrect: crypto/bcrypt: hashedPassword is not the hash of the given password

💡 说明：--user 的值务必用单引号包裹——bcrypt 哈希内含多个 $，不加引号会被 shell 当变量展开导致校验对象失真（官方 CLI 参考同样如此注记）。

7.5 user verify --totp：带两步验证码校验

对配置了 TOTP 的用户（三段式 用户名:哈希:TOTP密钥），用 --totp 传入当前 6 位验证码校验。实测一组真实校验（TOTP 密钥 GCCWZL3RV42DH2PRKHHZYCE2Z5OGQL6U，验证码由标准 RFC 6238 算法按当前时间片计算，读者用手机验证器等价操作）：

docker run --rm ghcr.io/tinyauthapp/tinyauth:v5.2.0 user verify \
  --user 'ops2:$2a$10$7JOgUbk0Kerq04xCFIajvegWMit5.MmDoA7MZQObQezudESBFHEV.:GCCWZL3RV42DH2PRKHHZYCE2Z5OGQL6U' \
  --username ops2 --password q1w2e3r4 --totp 771594

✓ User verified

验证码错误实测（--totp 000000）：

Failed to execute command: command verify error: TOTP code incorrect

注意 --user 的形态差异：两段式（无 TOTP 用户）传 --totp 会得到告警但仍验证密码（实测回显：⚠ TOTP code provided but user does not have TOTP enabled + ✓ User verified）；三段式才走 TOTP 校验。用户配置格式详见《tinyauth v5.2.0 配置参数详解》4.6 节。

八、totp 命令详解

totp 命令当前只有 generate 子命令（tinyauth totp --help 实测清单：generate Generate a TOTP secret），为现有用户生成两步验证密钥。

8.1 totp generate：生成 TOTP 密钥

参数（实测 generate --help 回显整理）：

标志	说明	默认值	必填
`--user`	现有用户的 `用户名:哈希` 两段式原文	空	是
`--interactive`	交互式 TUI 生成	`false`	否

实测（用 7.1 创建的 ops2 配置值，QR 码区体积大，此处保留输出节选（实测首尾））：

docker run --rm ghcr.io/tinyauthapp/tinyauth:v5.2.0 totp generate \
  --user 'ops2:$2a$10$7JOgUbk0Kerq04xCFIajvegWMit5.MmDoA7MZQObQezudESBFHEV.'

Scan the following QR code with your authenticator app (e.g., Google Authenticator, 2fauth, Microsoft Authenticator):

<ANSI 块字符绘制的 QR 码，数十行，略>

Or add the following TOTP secret to your authenticator app: GCCWZL3RV42DH2PRKHHZYCE2Z5OGQL6U
Finally, add your user 'ops2' back to your configuration: ops2:$2a$10$7JOgUbk0Kerq04xCFIajvegWMit5.MmDoA7MZQObQezudESBFHEV.:GCCWZL3RV42DH2PRKHHZYCE2Z5OGQL6U

输出三段信息：QR 码（手机验证器扫码）、明文 TOTP 密钥（手动录入用）、以及最关键的回填行——把原两段式用户值升级为 用户名:哈希:密钥 三段式后写回配置并重启，该用户下次登录即需输入验证码。官方注记 QR 码可能大到超出终端显示，遇此情况改用明文密钥行录入即可。

8.2 生成报错与格式陷阱

给已含 TOTP 密钥的三段式用户再次执行 generate 时报错（实测回显）：

Failed to execute command: command generate error: user already has a TOTP secret

⚠️ 排障结论：--user 传三段式（用户名:哈希:密钥）时 generate 认为该用户已有密钥拒绝再生成。正确姿势：重置 TOTP 用两段式原文重新 generate 得到新密钥，再整行替换配置值。同理，7.4 中 verify --user 传错段数会报 failed to parse user: invalid user format（实测），两段式/三段式务必与用途匹配。

九、oidc 命令详解

oidc 命令管理 OIDC 客户端（tinyauth 作为 OpenID Provider 对外供应用接入），当前只有 create 子命令（tinyauth oidc --help 实测清单：create Create a new OIDC Client）。

9.1 oidc create：生成客户端凭据

create 的参数是位置参数——第一个位置参数为客户端名（实测裸跑回显）：

docker exec tinyauth-v5.2.0-app tinyauth oidc create

Failed to execute command: command create error: client name is required. use tinyauth oidc create <name>

按提示传入名称创建（实测完整回显）：

docker exec tinyauth-v5.2.0-app tinyauth oidc create testapp

Created 'testapp' OIDC client.

Credentials:

Client Name: testapp
Client ID: cd9921f2-4e0b-42ee-bc0d-9e4c468a75a8
Client Secret: ta-RjVPZIlCD9zYIqVfHTB400wNXFLd73xNjF-alTTSrqOX4IEBaBCNrODDH0sQ5

Environment variables:

TINYAUTH_OIDC_CLIENTS_TESTAPP_CLIENTID=cd9921f2-4e0b-42ee-bc0d-9e4c468a75a8
TINYAUTH_OIDC_CLIENTS_TESTAPP_CLIENTSECRET=ta-RjVPZIlCD9zYIqVfHTB400wNXFLd73xNjF-alTTSrqOX4IEBaBCNrODDH0sQ5
TINYAUTH_OIDC_CLIENTS_TESTAPP_NAME=Testapp

CLI flags:

--oidc.clients.testapp.clientid=cd9921f2-4e0b-42ee-bc0d-9e4c468a75a8
--oidc.clients.testapp.clientsecret=ta-RjVPZIlCD9zYIqVfHTB400wNXFLd73xNjF-alTTSrqOX4IEBaBCNrODDH0sQ5
--oidc.clients.testapp.name=Testapp

YAML config:

clients:
    testapp:
        clientId: cd9921f2-4e0b-42ee-bc0d-9e4c468a75a8
        clientSecret: ta-RjVPZIlCD9zYIqVfHTB400wNXFLd73xNjF-alTTSrqOX4IEBaBCNrODDH0sQ5
        name: Testapp

You can use any of the above options to configure your OIDC client. Make sure to save these credentials as there is no way to regenerate them.

输出即配置：把 Environment variables 三行加进实例环境并重建，或把 YAML config 段并入配置文件，应用侧拿 Client ID/Secret 接 https://<tinyauth域名>/.well-known/openid-configuration 发现的端点即可完成 OIDC 接入。

⚠️ 注意：客户端 Secret 只在此刻显示一次，命令末行明确警告 there is no way to regenerate them——丢失只能重建客户端并同步更新应用侧配置。

9.2 重名覆盖陷阱

对同名客户端重复执行 create 不会报错，而是静默生成一套新凭据（实测：再次执行 oidc create testapp 返回全新的 Client ID 54c5ad98-... 与新 Secret，凭据段结构同 9.1）。旧凭据即刻作废，依赖旧 Secret 的应用会突然登录失败。

⚠️ 排障结论：应用突然 OIDC 认证失败时，先核对是否有人在实例上重复执行过 oidc create 同名命令。tinyauth 未提供 list/delete 子命令，客户端清单只能从生效配置（tinyauth config 的 oidc 节或环境变量）反查。

9.3 位置参数吞掉标志的陷阱

create 的位置参数解析会把标志样式的词当客户端名（实测）：

docker exec tinyauth-v5.2.0-app tinyauth oidc create --interactive

Created '--interactive' OIDC client.

Credentials:
...

本想触发交互模式，结果创建了一个名字叫 --interactive 的客户端。该误建客户端需从配置侧清理（若已回填配置则删除对应键后重启；仅在凭据输出层面未回填则无需处理）。使用 oidc create 时第一个参数必须是业务客户端名，不要盲目追加标志。

十、运维实操

10.1 增补用户全流程（生成 → 校验 → 回填 → 重启 → 验证）

以新增用户 ops2 为例的完整闭环（每步实测回显见对应章节）：

第一步，生成配置值：docker compose run --rm tinyauth user create --username ops2 --password q1w2e3r4（回显见 4.1 入口二）。

第二步，离线校验凭据无误：user verify --user 'ops2:$2a$10$7JOg...' --username ops2 --password q1w2e3r4 → ✓ User verified（回显见 7.4）。

第三步，把 TINYAUTH_AUTH_USERS=admin:$$2a$$10$$Edf9...,ops2:$2a$10$7JOgUbk0Kerq04xCFIajvegWMit5.MmDoA7MZQObQezudESBFHEV. 追加进 /opt/tinyauth/docker-compose.yml 的 environment 段（多个用户逗号分隔，admin 哈希的 $$ 转义保持原样，新增哈希为 docker run -e 场景单 $ 形态，混用时各自保持来源形态）。

第四步，重建实例使配置生效：

docker compose -f /opt/tinyauth/docker-compose.yml up -d tinyauth

实测回显：

 Container tinyauth-v5.2.0-app  Recreate
 Container tinyauth-v5.2.0-app  Recreated
 Container tinyauth-v5.2.0-app  Started

第五步，验证新用户可登录：

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

实测回显：

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

10.2 数据备份与恢复

tinyauth 的全部持久化状态都在数据卷 /data 内（SQLite 库 tinyauth.db + oidc/ 密钥 + resources/ 资源，实测目录清单）：

total 72
drwxr-xr-x    5 tinyauth tinyauth      4096 Oct 23 21:30 .
drwxr-xr-x    1 root     root          4096 Oct 23 21:30 ..
drwxr-xr-x    2 tinyauth tinyauth      4096 Sep  7 17:16 oidc
drwxr-xr-x    2 tinyauth tinyauth      4096 Sep  7 17:16 resources
drwxr-xr-x    2 tinyauth tinyauth      4096 Sep  7 17:16 tailscale
-rw-r--r--    1 root     root         53248 Oct 23 21:30 tinyauth.db

备份流程（实测）：停实例保证 SQLite 文件一致性 → 打包数据卷 → 重启：

cd /opt/tinyauth
docker compose stop tinyauth
docker run --rm -v tinyauth-v520-stack_tinyauth-data:/data:ro \
  -v /opt/backup:/backup alpine \
  sh -c 'tar czf /backup/tinyauth-data-backup.tgz -C /data . && ls -la /backup'
docker compose start tinyauth

实测回显：

 Container tinyauth-v5.2.0-app  Stopped
total 12
drwxr-xr-x    2 root     root          4096 Oct 24 11:34 .
drwxr-xr-x    1 root     root          4096 Oct 24 11:34 ..
-rw-r--r--    1 root     root          1497 Oct 24 11:34 tinyauth-data-backup.tgz
 Container tinyauth-v5.2.0-app  Started

备份后立即验证服务与数据完好（登录实测回显）：

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

恢复流程：停实例 → 清空数据卷内容 → 解包备份 → 启动：

cd /opt/tinyauth
docker compose stop tinyauth
docker run --rm -v tinyauth-v520-stack_tinyauth-data:/data -v /opt/backup:/backup:ro alpine \
  sh -c 'rm -rf /data/* && tar xzf /backup/tinyauth-data-backup.tgz -C /data'
docker compose start tinyauth

恢复后同样用登录接口与 tinyauth version 双重验证。建议每日定时执行备份脚本并保留 7 天滚动副本；用户/客户端等配置值在环境变量或配置文件中另有原文，配合 tinyauth config 导出一起归档最稳妥。

10.3 日常巡检

三件套巡检脚本可直接进 crontab（每条均实测）：

docker inspect --format '{{.State.Health.Status}}' tinyauth-v5.2.0-app

实测回显：

healthy

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

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8131/

实测回显：

三者分别核对容器健康位、应用层健康端点、HTTP 可达性；任一异常即告警。登录功能抽检用 10.1 第五步的登录接口。

10.4 日志查看与排障

实时日志（默认人类可读格式）：

docker logs -f tinyauth-v5.2.0-app

典型排障日志对照表（均为实测日志行）：

日志关键字	含义与处置
`Login successful ... username=admin`	登录成功，正常
`WRN ... Client Error ... status=401`	forward auth 端点拒绝未认证请求，配合 `X-Tinyauth-Location` 响应头定位跳转
`ERR ... Failed to get proxy context from request`	请求未携带反代上下文头（直连探测常见），检查反代是否传 `Host`/`X-Forwarded-*`
`WRN ... Trusted proxies are not configured`	未配 `TINYAUTH_AUTH_TRUSTEDPROXIES`，IP 类 ACL 失效，按参数详解篇 5.11 处置

需要结构化日志（接入集中式日志栈）时开启 TINYAUTH_LOG_JSON=true，JSON 行格式实测样例见《tinyauth v5.2.0 配置参数详解》5.11 节。

10.5 版本升级与回滚

tinyauth 发版节奏快，镜像 tag 推荐固定具体版本（本文 v5.2.0）而非 v5 浮动 tag，升级即换版本号：

cd /opt/tinyauth
# 1. 备份（10.2 流程，升级前必做）
docker compose stop tinyauth
docker run --rm -v tinyauth-v520-stack_tinyauth-data:/data:ro -v /opt/backup:/backup alpine \
  sh -c 'tar czf /backup/tinyauth-data-$(date +%Y%m%d).tgz -C /data .'
docker compose start tinyauth
# 2. 修改 docker-compose.yml 中 image 为新版本号（如 v5.3.0）后拉取并重建
docker compose pull tinyauth
docker compose up -d tinyauth
# 3. 验证版本与健康
docker compose exec tinyauth tinyauth version
docker compose exec tinyauth tinyauth healthcheck

升级后重点回归三件事：version 确认新版本号生效；healthcheck 确认健康；用一个受保护应用走一遍 401 → 登录 → 200 认证链路。回滚即把 image 改回旧版本号执行 up -d，数据卷向下兼容（跨大版本升级前先读官方 Breaking Updates 文档，如 Updating from v4 to v5 章节核对破坏性变更清单）。

十一、注意事项

exec 形态命令必须带二进制名：docker compose exec tinyauth tinyauth healthcheck，官方文档的 exec tinyauth healthcheck 在 v5.2.0 镜像内报 PATH 错误（6.4 实测）
生成类命令（user create/totp generate/oidc create）只输出配置值，不自动生效，必须回填配置并重建实例（4.1 注意事项）
bcrypt 哈希一律单引号包裹，Compose 文件内 $ 双写，两种形态不可混写（7.2、7.4 实测与官方注记）
oidc create 重名静默换发凭据，执行前先确认客户端名未占用（9.2 实测）
--interactive 系列需要真实 TTY，定时任务/管道环境改用非交互参数（7.3 实测）
备份必须先停实例再打包，避免 SQLite 文件写到一半的不一致副本（10.2 流程）
官方 Docker 镜像与二进制直跑的默认路径不同（镜像内为 /data/...），写巡检脚本时以 tinyauth config 的 dump 值为准，不要照抄文档的 ./ 相对路径

十二、常见问题

Q1：docker compose exec tinyauth healthcheck 报 executable file not found in $PATH？ healthcheck 不是独立可执行文件，是 tinyauth 的子命令。改为 docker compose exec tinyauth tinyauth healthcheck（6.4 实测对照）。

Q2：user create 生成的哈希贴进 Compose 后登录 401？ Compose 文件中 $ 被变量插值吃掉了。用 --docker 参数重新生成（输出即 $$ 转义形态，7.2 实测），或手工把 : 后哈希里的每个 $ 双写，改完 up -d 重建。

Q3：user verify 报 failed to parse user: invalid user format？ --user 值的段数不对：普通用户两段式 用户名:哈希，TOTP 用户三段式 用户名:哈希:密钥（8.2 实测）。同时确认值用了单引号，$ 未被 shell 展开。

Q4：totp generate 报 user already has a TOTP secret？ --user 传成了三段式。用两段式 用户名:哈希 重新生成新密钥（8.1），再把输出的三段式整行替换配置值。

Q5：oidc create 想加交互参数结果建了个奇怪名字的客户端？ create 只收位置参数，--interactive 被当成了客户端名（9.3 实测）。tinyauth 未提供删除命令，误建的客户端忽略即可（未回填配置不生效）；已回填则删除对应配置键重建实例。

Q6：升级后所有用户登录失败？ 先看 tinyauth version 确认真升级成功，再检查数据卷是否还是原卷（换了卷名等于全新库）；跨大版本升级按官方 Breaking Updates 文档核对配置项改名（如 v4 → v5 的路径与键名调整），必要时按 10.2 恢复备份回滚。

Q7：定时任务里跑 CLI 命令报 could not open TTY？ 用了 --interactive 形态。定时任务一律改非交互参数（7.3 实测对照），并给 docker compose run 加 --rm 清理一次性实例。

十三、参考链接

官方 CLI 参考：https://tinyauth.app/docs/reference/cli
官方 Configuration 参考：https://tinyauth.app/docs/reference/configuration
官方文档站：https://tinyauth.app
GitHub 仓库（含 Releases 与 Breaking Updates）：https://github.com/tinyauthapp/tinyauth
本专栏系列：《tinyauth v5.2.0 介绍与选型指南》（定位、架构与同类对比）、《tinyauth v5.2.0 Docker Compose 部署指南》（部署与三类反代集成）、《tinyauth v5.2.0 配置参数详解》（全部配置参数参考）