docs: add operations runbook for all services
This commit is contained in:
175
docs/ops.md
Normal file
175
docs/ops.md
Normal file
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user