From 5b89b1046f913f3cc9ce8a6a67b515a0ab973110 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 30 May 2026 21:19:05 +0900 Subject: [PATCH] Update server infrastructure docs --- README.md | 5 +++++ docs/network.md | 6 +++++- docs/ops.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/services.md | 28 +++++++++++++++++++++++++--- docs/sso.md | 18 ++++++++++++++++++ docs/storage.md | 7 +++++++ 6 files changed, 108 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 657a9b4..911f31b 100644 --- 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 ``` diff --git a/docs/network.md b/docs/network.md index d54a7ea..7dc355f 100644 --- 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) diff --git a/docs/ops.md b/docs/ops.md index a60b0d5..a87cbe5 100644 --- a/docs/ops.md +++ b/docs/ops.md @@ -40,8 +40,11 @@ systemctl restart .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 --email --password ``` +## 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 diff --git a/docs/services.md b/docs/services.md index 0e0efb7..b091a74 100644 --- 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`와 매핑된 경우에만 허용된다. diff --git a/docs/sso.md b/docs/sso.md index 2a0540b..5897b36 100644 --- 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)으로 설정한다. diff --git a/docs/storage.md b/docs/storage.md index ca99796..8065ea1 100644 --- 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`