docs: add operations runbook for all services

docs/ops.md

@@ -0,0 +1,175 @@
+# 운영 절차
+
+## 서비스 관리 기본 패턴
+
+모든 서비스는 `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` |
+| PostgreSQL | `postgres-main.service` |
+| MariaDB | `mariadb.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
+```
+
+## 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>
+```
+
+## 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
+```