# 운영 절차

## 서비스 관리 기본 패턴

모든 서비스는 `systemd + Podman Quadlet`으로 관리된다.

```bash
# 상태 확인
systemctl status <service>.service

# 재시작
systemctl restart <service>.service

# 로그 확인
journalctl -u <service>.service -f

# Quadlet 파일 수정 후 반드시 daemon-reload
systemctl daemon-reload
systemctl restart <service>.service
```

## 서비스명 목록

| 서비스 | systemd unit |
|---|---|
| Authentik Server | `authentik-server.service` |
| Authentik Worker | `authentik-worker.service` |
| Gitea | `gitea.service` |
| Nextcloud | `nextcloud-app.service` |
| Jellyfin | `jellyfin.service` |
| Grafana | `grafana-server.service` |
| Prometheus | `prometheus.service` |
| cAdvisor | `cadvisor.service` |
| FileBrowser | `filebrowser.service` |
| SFTPGo | `sftpgo.service` |
| Open WebUI | `open-webui.service` |
| ComfyUI | `comfyui.service` |
| JupyterHub | `jupyterhub.service` |
| Ollama | `ollama.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` |

## 헬스체크

```bash
# Authentik
curl -sf http://localhost:19000/-/health/live/

# Gitea
curl -sf http://10.89.0.8:3000/api/healthz

# Nextcloud
curl -fsS http://10.89.0.42/status.php

# Prometheus
curl -sf http://10.89.0.30:9090/-/healthy

# Grafana
curl -sf http://172.30.1.41:3000/api/health

# Open WebUI
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 컨테이너 직접 조작

```bash
# 실행 중인 컨테이너 목록
podman ps

# 컨테이너 로그
podman logs <container-name>

# 컨테이너 셸 접속
podman exec -it <container-name> bash

# 컨테이너 재시작 (systemd 경유 권장)
systemctl restart <service>.service
```

## Nextcloud occ 명령

```bash
# 앱 목록
podman exec --user www-data nextcloud-app php occ app:list

# 시스템 설정 확인
podman exec --user www-data nextcloud-app php occ config:system:get <key>

# 캐시 초기화
podman exec --user www-data nextcloud-app php occ maintenance:repair

# 파일 스캔
podman exec --user www-data nextcloud-app php occ files:scan --all
```

## Gitea 관리

```bash
# 사용자 목록
podman exec --user git gitea gitea admin user list

# 인증 소스 목록
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
# API 토큰 재발급
podman exec authentik-worker python -m manage shell -c "
from authentik.core.models import Token, TokenIntents, User
user = User.objects.get(username='akadmin')
t = Token.objects.filter(identifier='cli-admin-token').first()
if t: t.delete()
token = Token.objects.create(identifier='cli-admin-token', user=user, intent=TokenIntents.INTENT_API)
print(token.key)
"

# 설정 초기화 (migration)
podman exec authentik-worker python -m manage migrate
```

## NPM 설정 변경 후 반영

NPM은 MariaDB에 설정을 저장한다. DB 직접 변경 시 nginx conf도 함께 수정해야 한다.

```bash
# NPM nginx 즉시 reload
podman exec npm-app nginx -s reload

# conf 파일 위치
ls /podman/data/npm/data/nginx/proxy_host/
```

## 인증서 갱신

NPM이 Let's Encrypt 인증서를 자동 갱신한다. 인증서는 `/podman/data/npm/letsencrypt/` 에 저장된다.

```bash
# 현재 인증서 상태 확인
podman exec npm-app certbot certificates
```

## 새 Quadlet 서비스 배포 절차

1. `/etc/containers/systemd/<service>.container` 작성
2. `systemctl daemon-reload`
3. `systemctl enable --now <service>.service`
4. 헬스체크 확인
5. NPM에 프록시 호스트 추가 (필요 시)
6. Authentik Application 등록 (필요 시)
7. Gitea 리포에 Quadlet 파일 커밋

## 로그 집중 조회

```bash
# 전체 서비스 오류만
journalctl -p err --since "1 hour ago" --no-pager

# 특정 서비스 최근 50줄
journalctl -u <service>.service -n 50 --no-pager

# 실시간 멀티 서비스
journalctl -fu authentik-server.service -u authentik-worker.service
```