Timmy
833dddd92e
v5 兩實例:tinyauth.lotimmy.com(:3005)、tinyauth.timmy.edu.kg(:3006) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
100 lines
4.8 KiB
Markdown
100 lines
4.8 KiB
Markdown
# 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/` 有近期備份。
|
||
```
|