Update server infrastructure docs

2026-05-30 21:19:05 +09:00
parent b382d99800
commit 5b89b1046f
6 changed files with 108 additions and 4 deletions
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@

 Rocky Linux 8.10 기반 홈서버의 전체 서비스 인프라 현황 문서다.

+> 기준일: 2026-05-30
+
 ## 빠른 링크

 | 문서 | 설명 |
@@ -45,8 +47,11 @@ gm/jellyfin
 gm/sftpgo
 gm/asr
 gm/reservation
+gm/telegram-reminder-bot
+gm/telegram-calendar-bot
 gm/cadvisor
 gm/postgres
 gm/proxy-network
 gm/wikijs
+gm/server-infra
 ```
--- a/docs/network.md
+++ b/docs/network.md
@@ -29,6 +29,7 @@
 | `10.89.0.20` | `authentik-server` | Authentik Server + Embedded Outpost |
 | `10.89.0.21` | `authentik-worker` | Authentik Worker |
 | `10.89.0.22` | `reservation` | Reservation App |
+| `10.89.0.23` | `telegram-reminder-bot` | Telegram Reminder Bot 관리자 UI / Bot runtime |
 | `10.89.0.30` | `prometheus` | Prometheus |
 | `10.89.0.31` | `cadvisor` | cAdvisor |
 | `10.89.0.40` | `postgres-main` | PostgreSQL |
@@ -37,6 +38,8 @@
 | `10.89.0.43` | `onlyoffice-docs` | OnlyOffice |
 | `10.89.0.44` | `redis-nextcloud` | Redis (Nextcloud) |
 | `10.89.0.45` | `wikijs` | Wiki.js |
+| `10.89.0.50` | `postfix` | SMTP Relay |
+| `10.89.0.99` | `telegram-calendar-bot` | Telegram Calendar Bot |

 ## 외부 포트 노출 현황

@@ -72,7 +75,8 @@ Internet
   ├── jupyter.du5t.xyz       → 172.30.1.41:8000 (JupyterHub)
   ├── asr.du5t.xyz           → 172.30.1.41:18100 (ASR)
   ├── wiki.du5t.xyz          → 10.89.0.45:3000 (Wiki.js)
-   ├── reservation.du5t.xyz   → 10.89.0.10:3000 (Reservation)
+   ├── reservation.du5t.xyz   → 10.89.0.22:3000 (Reservation)
+   ├── reminder.du5t.xyz      → 10.89.0.23:8088 (Telegram Reminder Bot Admin)
   ├── sftp.du5t.xyz          → 172.30.1.41:8080 (SFTPGo Web)
   ├── webdav.du5t.xyz        → 172.30.1.41:10080 (SFTPGo WebDAV)
   ├── ollama.du5t.xyz        → 172.30.1.41:11434 (Ollama)
--- a/docs/ops.md
+++ b/docs/ops.md
@@ -40,8 +40,11 @@ systemctl restart <service>.service
 | NPM | `npm-app.service` |
 | ASR | `asr.service` |
 | Reservation | `reservation.service` |
+| Telegram Reminder Bot | `telegram-reminder-bot.service` |
+| Telegram Calendar Bot | `telegram-calendar-bot.service` |
 | PostgreSQL | `postgres-main.service` |
 | MariaDB | `mariadb.service` |
+| Postfix Relay | `postfix.service` |

 ## 헬스체크

@@ -66,6 +69,12 @@ curl -sf http://localhost:8079/health

 # Ollama
 curl -sf http://localhost:11434/api/version
+
+# Reservation
+curl -sf http://10.89.0.22:3000/health
+
+# Telegram Reminder Bot
+curl -sf http://10.89.0.23:8088/health
 ```

 ## Podman 컨테이너 직접 조작
@@ -113,6 +122,45 @@ podman exec --user git gitea gitea admin auth list
 podman exec --user git gitea gitea admin user create --admin --username <user> --email <email> --password <pass>
 ```

+## Telegram 봇 운영
+
+### Telegram Reminder Bot
+
+```bash
+cd /root/telegram-reminder-bot
+
+# 상태 확인
+./scripts/status.sh
+
+# 코드 업데이트/이미지 재빌드/서비스 재시작
+./scripts/update.sh
+
+# 컨테이너 로그
+podman logs -f telegram-reminder-bot
+
+# 헬스체크
+curl -sf http://10.89.0.23:8088/health
+```
+
+운영 메모:
+
+- 런타임 설정 파일: `/podman/data/telegram-reminder-bot/data/runtime.env`
+- DB: `postgres-main`의 `telegram_reminder`
+- 이전 SQLite 파일/백업은 `/podman/data/telegram-reminder-bot/data/`에 남아 있을 수 있다.
+- 관리자 UI: `https://reminder.du5t.xyz/setup`
+
+### Telegram Calendar Bot
+
+```bash
+systemctl status telegram-calendar-bot.service
+podman logs -f telegram-calendar-bot
+```
+
+운영 메모:
+
+- 환경파일: `/podman/data/telegram-calendar-bot/.env`
+- Nextcloud CalDAV와 연동한다.
+
 ## Authentik 관리

 ```bash
--- a/docs/services.md
+++ b/docs/services.md
@@ -1,6 +1,6 @@
 # 서비스 전체 목록

-> 기준일: 2026-05-23 | 호스트: srv (Rocky Linux 8.10)
+> 기준일: 2026-05-30 | 호스트: srv (Rocky Linux 8.10)

 ## 서비스 맵

@@ -25,6 +25,9 @@
 | **ASR Whisper** | `asr.du5t.xyz` | `10.89.0.2:8000` | — | *(미적용)* | [gm/asr](https://git.du5t.xyz/gm/asr) |
 | **Wiki.js** | `wiki.du5t.xyz` | `10.89.0.45:3000` | 2.5.314 | Authentik OIDC | [gm/wikijs](https://git.du5t.xyz/gm/wikijs) |
 | **Reservation App** | `reservation.du5t.xyz` | `10.89.0.22:3000` | — | JWT 자체 인증 | [gm/reservation](https://git.du5t.xyz/gm/reservation) |
+| **Telegram Reminder Bot** | `reminder.du5t.xyz/setup` | `10.89.0.23:8088` | 0.1.2 | Authentik OIDC + Telegram 관리자 매핑 | [gm/telegram-reminder-bot](https://git.du5t.xyz/gm/telegram-reminder-bot) |
+| **Telegram Calendar Bot** | *(Telegram Bot)* | `10.89.0.99` | — | Telegram + Nextcloud CalDAV 계정 | [gm/telegram-calendar-bot](https://git.du5t.xyz/gm/telegram-calendar-bot) |
+| **Postfix Relay** | *(SMTP 내부)* | `10.89.0.50` | latest | 내부 릴레이 | — |
 | **MariaDB** | *(내부 전용)* | `0.0.0.0:3306` | 12.2.1 | 내부망 전용 | — |
 | **PostgreSQL** | *(내부 전용)* | `10.89.0.40:5432` | 16 | 내부망 전용 | [gm/postgres](https://git.du5t.xyz/gm/postgres) |

@@ -35,6 +38,7 @@
 - Gitea — `gitea admin auth add-oauth`
 - Nextcloud — `user_oidc` 앱
 - Open WebUI — 컨테이너 환경변수
+- Telegram Reminder Bot — `/setup` 관리자 UI 및 Telegram 관리자 계정 연결

 ### Authentik Proxy Provider (Embedded Outpost 경유)
 NPM이 트래픽을 `10.89.0.20:9000`으로 전달, Outpost가 인증 후 실제 서비스로 포워딩.
@@ -47,15 +51,33 @@ NPM이 트래픽을 `10.89.0.20:9000`으로 전달, Outpost가 인증 후 실제
 - ASR API (`asr.du5t.xyz`) — 내부 사용 전제

 ### 자체 인증
- Jellyfin, SFTPGo, JupyterHub, Reservation App, NPM
+- Jellyfin, SFTPGo, JupyterHub, Reservation App, NPM, Telegram Calendar Bot

 ## 기반 인프라 서비스

 | 서비스 | 역할 | 내부 주소 |
 |---|---|---|
-| `postgres-main` | Authentik, Nextcloud, Wiki.js DB | `10.89.0.40:5432` |
+| `postgres-main` | Authentik, Nextcloud, Wiki.js, Telegram Reminder Bot DB | `10.89.0.40:5432` |
 | `authentik-redis` | Authentik 캐시/큐 | `10.89.0.41:6379` |
 | `redis-nextcloud` | Nextcloud 캐시/세션 | `10.89.0.44:6379` |
+| `postfix` | 내부 SMTP 릴레이 | `10.89.0.50` |
 | `MariaDB` | NPM DB | `host:3306` |
 | `proxy.network` | 서비스 간 통신 브리지 | `10.89.0.0/24` |
 | `fail2ban` | SSH/서비스 브루트포스 차단 | host |
+
+## Telegram Reminder Bot 운영 특이사항
+
+- 컨테이너: `telegram-reminder-bot`
+- systemd unit: `telegram-reminder-bot.service`
+- 데이터베이스: `postgres-main`의 `telegram_reminder` DB 사용
+- 런타임 설정: `/podman/data/telegram-reminder-bot/data/runtime.env`
+- 관리자 UI: `https://reminder.du5t.xyz/setup`
+- 웹 UI 기능:
+  - 런타임 상태/재시작
+  - 대상 등록
+  - 리마인더 생성
+  - 리마인더 일시중지/재개/보관
+  - Tabulator 기반 통계 조회
+- 접근 제어:
+  - `/setup`은 Authentik OIDC로 보호된다.
+  - 대상/리마인더 조작은 Authentik `sub`가 Telegram 로그인으로 검증된 `admin_identities`와 매핑된 경우에만 허용된다.
--- a/docs/sso.md
+++ b/docs/sso.md
@@ -15,6 +15,7 @@
 | 7 | `filebrowser-proxy` | Proxy | FileBrowser |
 | 8 | `comfyui-proxy` | Proxy | ComfyUI |
 | 9 | `wikijs-provider` | OAuth2/OIDC | Wiki.js |
+| — | `reminder` | OAuth2/OIDC | Telegram Reminder Bot 관리자 UI |

 ## OIDC 연동 상세

@@ -97,6 +98,23 @@ curl -s -X PATCH -H "Authorization: Bearer $AUTHENTIK_TOKEN" \

 전략은 Wiki.js GraphQL API(`updateStrategies` mutation)로 등록한다. 자세한 내용은 [gm/wikijs](https://git.du5t.xyz/gm/wikijs) 참고.

+### Telegram Reminder Bot
+
+Telegram Reminder Bot은 작은 내장 HTTP 관리자 UI(`/setup`)를 제공하고, 이 화면을 Authentik OIDC로 보호한다.
+
+| 항목 | 값 |
+|---|---|
+| 관리자 URL | `https://reminder.du5t.xyz/setup` |
+| Callback URL | `https://reminder.du5t.xyz/setup/callback` |
+| Discovery URL 패턴 | `https://auth.du5t.xyz/application/o/reminder/.well-known/openid-configuration` |
+| 런타임 설정 | `/podman/data/telegram-reminder-bot/data/runtime.env` |
+
+주의점:
+
+- 웹 UI 로그인은 Authentik 세션을 확인한다.
+- 대상/리마인더 생성·수정은 Telegram에서 `/login`으로 연결된 `admin_identities.authentik_sub`와 현재 Authentik `sub`가 일치할 때만 허용된다.
+- `AUTHENTIK_REQUIRED_GROUP` 값이 설정되어 있으면 해당 그룹 구성원만 `/setup`에 접근할 수 있다.
+
 ## Proxy Provider 연동 상세

 NPM의 백엔드를 `10.89.0.20:9000` (Authentik Embedded Outpost)으로 설정한다.
--- a/docs/storage.md
+++ b/docs/storage.md
@@ -23,6 +23,12 @@
 | `/podman/data/prometheus/data/` | Prometheus | TSDB (30일 보존) |
 | `/podman/data/reservation/` | Reservation | SQLite DB, 업로드 파일 |
 | `/podman/data/sftpgo/` | SFTPGo | 설정, 사용자 DB |
+| `/podman/data/telegram-reminder-bot/data/` | Telegram Reminder Bot | 런타임 설정, 이전 SQLite 백업 |
+| `/podman/data/telegram-calendar-bot/` | Telegram Calendar Bot | 환경변수 |
+| `/podman/data/postgres-main/data/` | PostgreSQL | 공용 PostgreSQL 데이터 |
+| `/podman/data/postgres-main/initdb/` | PostgreSQL | 초기화 스크립트 |
+| `/podman/data/wikijs/` | Wiki.js | Wiki.js 데이터 |
+| `/podman/data/onlyoffice/` | OnlyOffice | 문서 서버 데이터/로그 |

 ### /mnt/storage (대용량 스토리지)

@@ -55,6 +61,7 @@

 백업 대상 권장 경로:
 - `/podman/data/` (DB, 설정 전체)
+- `postgres-main` 논리 백업 (`pg_dumpall` 또는 서비스별 DB dump)
 - `/mnt/storage/` (미디어, AI 모델 제외 가능)
 - `/etc/containers/systemd/` (Quadlet 파일)
 - `/etc/grafana/grafana.ini`