server-infra/docs/ops.md

운영 절차

서비스 관리 기본 패턴

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

# 상태 확인
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

헬스체크

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

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

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

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

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

Nextcloud occ 명령

# 앱 목록
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 관리

# 사용자 목록
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 관리

# 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도 함께 수정해야 한다.

# 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/ 에 저장된다.

# 현재 인증서 상태 확인
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 파일 커밋

로그 집중 조회

# 전체 서비스 오류만
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