# CT124 tinyauth(反向代理認證 / SSO)— 操作手冊

> 主機:CT124（192.168.42.124，Ubuntu 24.04 LXC）　|　位置:`/opt/tinyauth`、`/opt/tinyauth2`
> 用途:輕量認證/授權伺服器,可當反向代理的 forward-auth 中介層(保護沒有內建登入的服務),或獨立登入伺服器。支援 OAuth / LDAP / 存取控制。專案:<https://github.com/tinyauthapp/tinyauth>

---

## 一、基本資訊

- 版本:**tinyauth v5**（`ghcr.io/tinyauthapp/tinyauth:v5`,實際 v5.0.7)
- **兩個獨立實例**(各自獨立 SQLite DB、獨立設定,互不相干):

  | 實例 | 目錄 | 容器 | 埠 | 對外網域(NPM) |
  |---|---|---|---|---|
  | 1 | `/opt/tinyauth` | `tinyauth` | `3005 → 3000` | `https://tinyauth.lotimmy.com`（NPM #58, cert 86,已驗證 200) |
  | 2 | `/opt/tinyauth2` | `tinyauth2` | `3006 → 3000` | `https://tinyauth.timmy.edu.kg`（NPM #59, cert 87,已驗證 200) |

- 皆 `restart: unless-stopped`、內建 healthcheck(`healthy`)。
- 實例 1(`tinyauth`)帶 `com.centurylinklabs.watchtower.enable=true` → Watchtower 會自動拉新版;實例 2 未帶此標籤,需手動更新。
- DNS:`tinyauth.lotimmy.com` A 記錄 → `125.229.110.50`(WAN,Cloudflare DNS-only 灰雲),與 picsur/headscale 同模式。

## 二、存取與帳號

- Web:`https://tinyauth.lotimmy.com`（內網 `http://192.168.42.124:3005`);實例 2 同理走 `:3006`。
- 管理員帳號:`admin`(兩個實例目前**共用同一組 bcrypt 雜湊**,寫在各自 `stack.env` 的 `TINYAUTH_AUTH_USERS`)。
  - **密碼見密碼管理器**(不落在此手冊)。`stack.env` 只存雜湊,無法反推明文。

### 改密碼 / 加使用者

tinyauth 沒有註冊 UI,帳號由環境變數帶入。用 CLI 產生 bcrypt 雜湊:

```bash
docker run --rm ghcr.io/tinyauthapp/tinyauth:v5 user create --username <帳號> --password <密碼>
# 輸出 <帳號>:$2a$10$...  貼回對應目錄的 stack.env 的 TINYAUTH_AUTH_USERS(多人以逗號分隔)
cd /opt/tinyauth && docker compose up -d   # 套用
```

> `--docker` 旗標會把 `$` 跳脫成 `$$` 供 compose 插值使用;放進 `env_file`(`stack.env`)時用哪種都可,兩個實例現況分別是單 `$` 與 `$$`,均正常運作。

## 三、操作

```bash
cd /opt/tinyauth          # 或 /opt/tinyauth2
docker compose up -d      # 啟動 / 套用設定變更
docker compose ps
docker compose logs -f
docker compose pull && docker compose up -d   # 更新 image(實例 1 平常 Watchtower 也會自動更)
docker compose down       # 停止並移除容器(data/ 保留)
```

## 四、設定與資料

每個實例目錄含:

| 檔案 | 用途 |
|---|---|
| `docker-compose.yml` | 服務定義 |
| `stack.env` | 環境變數(`TINYAUTH_APPURL`、`TINYAUTH_DATABASE_PATH`、`TINYAUTH_AUTH_USERS`)。用獨立檔名而非 `.env`,避免被 compose 當插值來源 |
| `data/` | SQLite DB(`/data/tinyauth.db`)+ resources,**備份只認這個目錄** |

備份:`cd /opt/tinyauth && docker compose stop && tar -czf tinyauth-data-$(date +%F).tar.gz data && docker compose start`(兩個實例分別備)。

關鍵環境變數:

- `TINYAUTH_APPURL` — 對外完整網址。**必須是 hostname,不接受 IP**(填 IP 會 `IP addresses not allowed` 直接 crash-loop);cookie/OAuth 導向都依賴它。
- `TINYAUTH_AUTH_USERS` — `帳號:bcrypt雜湊`,逗號分隔多人。
- `TINYAUTH_DATABASE_PATH` — 指到 `/data/tinyauth.db` 讓 DB 落在綁定卷。

## 五、用 tinyauth 保護其他服務(forward-auth,NPM)

NPM 沒有原生 forward-auth UI,需在**被保護服務**的 Proxy Host → Advanced 分頁加 `auth_request`,指向 tinyauth 的 `/api/auth/nginx`。大致片段(依實際調整):

```nginx
location /tinyauth {
    internal;
    proxy_pass http://192.168.42.124:3005/api/auth/nginx;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host  $host;
    proxy_set_header X-Forwarded-Uri   $request_uri;
}
error_page 401 = @tinyauth_login;
location @tinyauth_login {
    return 302 https://tinyauth.lotimmy.com/login?redirect_uri=https://$host$request_uri;
}
location / {
    auth_request /tinyauth;
    # ...原本的 proxy_pass...
}
```

設定細節與 OAuth/LDAP 供應商請參官方文件 <https://tinyauth.app>(頁面偶爾 404,以 repo 的 `.env.example` 為準)。

## 六、注意事項

- **兩個實例是各自獨立的**:改帳號、改設定、備份都要分目錄做;`tinyauth.lotimmy.com` 的變更不會同步到 `tinyauth.timmy.edu.kg`。
- 主機埠 `3005`/`3006` 對 LAN 開放(`0.0.0.0`),任何能連到 CT124 的人可直接打登入頁。真要收斂可把 `ports` 拿掉、只留 NPM 內網存取。
- 對外 443 經 NPM → 依賴 docker daemon 與 NPM 容器(見 [`CT124_故障復原_20260529.md`](CT124_故障復原_20260529.md));NPM 掛了兩個網域都不通。
- tinyauth 仍在活躍開發,升級前先看 release notes 並確認 `data/` 有近期備份。
```