kaffa/nginx-proxy-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update PROJECT_DOCUMENTATION.md with Podman + Quadlet automation

Browse Source 
Complete rewrite of project documentation focusing on Podman containerization
and systemd-based auto-start using Quadlet. Key improvements:

- Replace Cloudflare R2 log streaming with container automation
- Add comprehensive kernel tuning for production workloads
- Implement rootless container with privileged port binding
- Document complete auto-start system with 40-second boot time
- Include troubleshooting, security considerations, and operations guide
- Validate all configurations through reboot testing

System: Debian 13 (Trixie) + Podman 5.4.2 + Quadlet + systemd
Ports: 80 (HTTP), 81 (Admin UI), 443 (HTTPS)
Auto-start: ✅ Verified with full reboot test

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kappa
2025-09-11 10:17:40 +09:00
parent 3e19aaa090
commit 4b3e1a0baf
1 changed files with 295 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

516
PROJECT_DOCUMENTATION.md
View File

@@ -1,266 +1,340 @@
# Nginx Proxy Manager + Cloudflare R2 로그 시스템 구축 문서 # Nginx Proxy Manager 자동화 구축 문서
## 📅 프로젝트 개요 ## 📅 프로젝트 개요
**작업일**: 2025년 9월 10일 **작업일**: 2025년 9월 11일
**서버**: debian-jp-tyo-3 (100.115.167.93) **서버**: AWS EC2 Instance (3.35.209.51)
**목적**: Nginx Proxy Manager 로그를 Cloudflare R2에 실시간으로 업로드하여 CrowdSec 보안 분석 시스템과 연동 **OS**: Debian 13 (Trixie), Kernel 6.12.41
**목적**: Podman + Quadlet을 활용한 nginx-proxy-manager 자동 실행 시스템 구축
## 🏗️ 구축 완료 항목 ## 🏗️ 시스템 아키텍처
### 1. 시스템 환경 설정 ### 1. 컨테이너 런타임
- **Podman 5.4.2**: Rootless 컨테이너 엔진
- **Quadlet**: systemd 기반 컨테이너 오케스트레이션
- **systemd**: 서비스 자동 시작 및 관리
#### 1.1 서버 기본 설정 ### 2. 네트워크 구성
- **호스트명 변경**: npm-jp-tko3 → debian-jp-tyo-3 - **포트 바인딩**: 80 (HTTP), 81 (관리 UI), 443 (HTTPS)
- **타임존 설정**: UTC → Asia/Tokyo (JST) - **네트워크 백엔드**: netavark (Podman 기본)
- **시스템**: Debian 13 (trixie), Kernel 6.12.43 - **DNS**: pasta를 통한 네트워크 격리
#### 1.2 시스템 튜닝 ## 🔧 시스템 설정
**커널 파라미터 최적화** (`/etc/sysctl.d/99-container-tuning.conf`)
### 1. 커널 튜닝 설정
**파일**: `/etc/sysctl.d/99-container-tuning.conf`
```bash ```bash
# 메모리 관리 # 메모리 관리
vm.swappiness=10 # 스왑 사용률 최소화 vm.swappiness=10
vm.dirty_ratio=15 # 더티 페이지 비율 vm.dirty_ratio=15
vm.vfs_cache_pressure=50 # 캐시 압력 감소 vm.vfs_cache_pressure=50
# 네트워크 최적화 (프록시 워크로드) # 네트워크 최적화 (프록시 워크로드)
net.core.somaxconn=65535 # 연결 큐 크기 net.core.somaxconn=65535
net.core.netdev_max_backlog=5000 # 네트워크 백로그 net.core.netdev_max_backlog=5000
net.ipv4.tcp_fin_timeout=30 # TCP 연결 종료 시간 net.ipv4.tcp_fin_timeout=30
net.ipv4.tcp_max_syn_backlog=8192 # SYN 백로그 크기 net.ipv4.tcp_max_syn_backlog=8192
net.ipv4.ip_unprivileged_port_start=80 # 특권 포트 허용 net.ipv4.ip_unprivileged_port_start=80
# 컨테이너 최적화 # 컨테이너 최적화
kernel.pid_max=4194304 # 최대 PID 수 kernel.pid_max=4194304
vm.max_map_count=262144 # 메모리 매핑 수 vm.max_map_count=262144
fs.file-max=2097152 # 최대 파일 수 fs.file-max=2097152
``` ```
**시스템 리소스 제한** (`/etc/systemd/system.conf.d/limits.conf`) **핵심 설정**:
- `net.ipv4.ip_unprivileged_port_start=80`: rootless 컨테이너에서 포트 80 사용 허용
- `vm.swappiness=10`: 스왑 사용률 최소화로 컨테이너 성능 향상
- `net.core.somaxconn=65535`: 대용량 연결 처리를 위한 소켓 큐 확장
### 2. systemd 리소스 제한
**파일**: `/etc/systemd/system.conf.d/limits.conf`
```bash ```bash
[Manager]
DefaultLimitNOFILE=65536 DefaultLimitNOFILE=65536
DefaultLimitNPROC=65536 DefaultLimitNPROC=65536
DefaultLimitCORE=infinity DefaultLimitCORE=infinity
DefaultLimitMEMLOCK=infinity DefaultLimitMEMLOCK=infinity
``` ```
### 2. Nginx Proxy Manager 설치 (Podman + Quadlet) ### 3. 사용자 서비스 활성화
#### 2.1 컨테이너 서비스
- **npm-app.service**: Nginx Proxy Manager 메인 애플리케이션
- **npm-db.service**: MariaDB 10.11 데이터베이스
- **네트워크**: Podman 사용자 네트워크 (npm)
- **포트**: 80, 81 (관리자), 443
#### 2.2 데이터 디렉토리
```
/home/kaffa/nginx-proxy-manager/
├── data/ # NPM 데이터
├── letsencrypt/ # SSL 인증서
├── db/ # MariaDB 데이터
└── data/logs/ # 로그 파일
```
### 3. Cloudflare R2 연동
#### 3.1 rclone 설치 및 설정
**설치된 버전**: rclone v1.60.1-DEV
**설정 파일** (`~/.config/rclone/rclone.conf`):
```ini
[cloudflare-r2]
type = s3
provider = Cloudflare
access_key_id = 90b141de4479101392691a20c60d2696
secret_access_key = [REDACTED]
endpoint = https://d8e5997eb4040f8b489f09095c0f623c.r2.cloudflarestorage.com
region = auto
```
#### 3.2 R2 버킷 구조
```
npm-logs/
└── debian-jp-tyo-3/
└── 2025-09-10/
├── npm_access.log
├── npm_error.log
├── fallback_access.log
├── fallback_error.log
├── npm-app-recent.log
└── npm-db-recent.log
```
### 4. 로그 스트리밍 시스템
#### 4.1 로그 수집 스크립트
**백업 스크립트** (`/home/kaffa/scripts/npm-log-backup.sh`)
- 일일 백업용 (압축 아카이브)
- systemd 타이머로 자동 실행
- 로컬 백업 7일 보관
**실시간 스트리밍 스크립트** (`/home/kaffa/scripts/npm-log-streamer.sh`)
- CrowdSec용 실시간 업로드 (압축 없음)
- 1분 간격 동기화
- 에러 복구 로직 포함
#### 4.2 주요 기능
```bash ```bash
# 로그 수집 소스 # 사용자 서비스 영구 활성화 (로그인 없이 자동 시작)
- Podman 컨테이너 내부 로그 sudo loginctl enable-linger admin
- systemd journal (npm-app, npm-db)
- 호스트 마운트 로그 파일
# 업로드 특징
- 개별 파일 업로드 (압축 없음)
- 재시도 로직 (3회)
- 타임아웃 보호 (300초)
- 실패 시 계속 작동
``` ```
#### 4.3 systemd 서비스 ## 📦 Quadlet 설정
**npm-log-backup.timer**: 일일 백업 (00:00)
**npm-log-streamer.service**: 실시간 스트리밍 (상시 가동)
### 5. 문제 해결 내역 ### 1. 디렉토리 구조
#### 5.1 R2 연결 문제
**문제**: TLS handshake 실패
**원인**: 잘못된 API 자격증명
**해결**:
- API Token 대신 S3 호환 Access Key/Secret Key 사용
- 32자리 Access Key ID 형식 준수
- 올바른 Account ID로 엔드포인트 수정
#### 5.2 rootless 컨테이너 포트 바인딩
**문제**: 포트 80 바인딩 권한 오류
**해결**: `net.ipv4.ip_unprivileged_port_start=80` 설정
#### 5.3 스크립트 에러 판정 로직
**문제**: rclone 출력 텍스트 파싱으로 잘못된 실패 판정
**해결**: Exit code 기반 판정으로 변경 (0=성공)
## 📊 성능 및 비용 분석
### 현재 운영 현황
- **업로드 빈도**: 1분당 6-8개 파일
- **일일 업로드**: 약 8,640개 파일
- **월간 데이터**: 약 2.81GB
- **성공률**: 99.93%
### 월간 비용 예상
``` ```
스토리지: $0.042 (2.81GB × $0.015) ~/.config/containers/systemd/
PUT 작업: $0.78 (172,800회 × $4.50/백만) └── nginx-proxy-manager.container
총 비용: $0.822/월 (약 1,200원)
``` ```
### 비용 최적화 방안 ### 2. Quadlet 설정 파일
1. **현재 (4개 파일)**: $0.82/월
2. **500개 파일 시**: $102/월 → 주기 조정 필요
3. **권장**: 중요도별 차등 업로드
## 🔧 유지보수 명령어 **파일**: `~/.config/containers/systemd/nginx-proxy-manager.container`
```ini
[Unit]
Description=Nginx Proxy Manager
Wants=network-online.target
After=network-online.target
RequiresMountsFor=%t/containers
### 서비스 관리 [Container]
Image=docker.io/jc21/nginx-proxy-manager:latest
ContainerName=nginx-proxy-manager
AutoUpdate=registry
PublishPort=80:80
PublishPort=81:81
PublishPort=443:443
Volume=nginx-proxy-manager-data:/data
Volume=nginx-proxy-manager-letsencrypt:/etc/letsencrypt
Environment=DISABLE_IPV6=true
[Service]
Restart=always
TimeoutStartSec=900
[Install]
WantedBy=default.target
```
### 3. Quadlet 작동 원리
1. Quadlet이 `.container` 파일을 읽어 systemd 서비스 파일 자동 생성
2. systemd가 생성된 서비스를 `default.target`에 등록
3. 부팅 시 자동으로 컨테이너 시작
## 🚀 설치 및 배포 절차
### 1. 기본 시스템 설정
```bash
# 시스템 업데이트
sudo apt update
# Podman 설치
sudo apt install -y podman
# 사용자 lingering 활성화
sudo loginctl enable-linger admin
```
### 2. 커널 튜닝 적용
```bash
# 커널 파라미터 설정
sudo tee /etc/sysctl.d/99-container-tuning.conf << EOF
# [위의 커널 튜닝 설정 내용]
EOF
# systemd 리소스 제한 설정
sudo mkdir -p /etc/systemd/system.conf.d
sudo tee /etc/systemd/system.conf.d/limits.conf << EOF
# [위의 systemd 설정 내용]
EOF
# 커널 파라미터 즉시 적용
sudo sysctl -p /etc/sysctl.d/99-container-tuning.conf
```
### 3. Quadlet 설정 배포
```bash
# Quadlet 디렉토리 생성
mkdir -p ~/.config/containers/systemd
# nginx-proxy-manager 설정 파일 생성
cat > ~/.config/containers/systemd/nginx-proxy-manager.container << EOF
# [위의 Quadlet 설정 내용]
EOF
# systemd 데몬 재로드
systemctl --user daemon-reload
# 서비스 시작
systemctl --user start nginx-proxy-manager.service
```
## 📊 리부팅 테스트 결과
### 부팅 타임라인 (2025-09-11 테스트)
```
01:13:13 - 시스템 셧다운 시작
01:13:17 - nginx-proxy-manager 정상 종료
-- 리부팅 --
01:13:53 - nginx-proxy-manager 자동 시작 (부팅 후 40초)
01:13:58 - 서비스 완전 준비 완료
```
### 검증된 기능
- ✅ **자동 시작**: 부팅 후 40초 만에 서비스 시작
- ✅ **포트 바인딩**: 80, 81, 443 포트 정상 바인딩
- ✅ **커널 파라미터 유지**: 리부팅 후에도 모든 설정 유지
- ✅ **서비스 안정성**: systemd를 통한 자동 재시작
- ✅ **컨테이너 생성**: 새로운 컨테이너 ID로 정상 생성
## 🔧 운영 관리
### 서비스 관리 명령어
```bash ```bash
# 서비스 상태 확인 # 서비스 상태 확인
systemctl --user status npm-app npm-db npm-log-streamer systemctl --user status nginx-proxy-manager.service
# 로그 스트리밍 재시작 # 서비스 중지/시작/재시작
systemctl --user restart npm-log-streamer.service systemctl --user stop nginx-proxy-manager.service
systemctl --user start nginx-proxy-manager.service
systemctl --user restart nginx-proxy-manager.service
# 로그 확인
journalctl --user -u npm-log-streamer.service -f
# 수동 로그 동기화
/home/kaffa/scripts/npm-log-streamer.sh sync
# R2 연결 테스트
/home/kaffa/scripts/npm-log-streamer.sh test
```
### R2 작업
```bash
# 업로드된 파일 확인
rclone ls cloudflare-r2:npm-logs/
# 버킷 리스트
rclone lsd cloudflare-r2:
# 수동 업로드
rclone copy file.log cloudflare-r2:npm-logs/path/
```
### 모니터링
```bash
# 업로드 통계
grep -c 'SUCCESS:' /home/kaffa/logs/npm-streamer.log
# 최근 로그
tail -f /home/kaffa/logs/npm-streamer.log
# 디스크 사용량
du -sh /home/kaffa/nginx-proxy-manager/data/logs/
```
## 🚀 향후 개선 사항
### 단기 개선
1. CrowdSec 연동 구성 및 테스트
2. 로그 필터링 규칙 적용 (중요 로그 우선)
3. 알림 시스템 구축 (업로드 실패 시)
### 장기 개선
1. 로그 분석 대시보드 구축
2. 자동 스케일링 (로그 양에 따른 주기 조정)
3. 다중 지역 백업 (재해 복구)
4. 로그 압축 아카이빙 (30일 이상)
## 📝 트러블슈팅 가이드
### R2 연결 실패
```bash
# 자격증명 확인
cat ~/.config/rclone/rclone.conf
# 직접 연결 테스트
rclone lsd cloudflare-r2: --verbose
# 네트워크 확인
curl -v https://[account-id].r2.cloudflarestorage.com
```
### 서비스 재시작 루프
```bash
# 서비스 로그 확인 # 서비스 로그 확인
journalctl --user -u npm-log-streamer.service -n 50 journalctl --user -u nginx-proxy-manager.service -f
# 스크립트 권한 확인
ls -la /home/kaffa/scripts/
# 수동 실행 테스트
bash -x /home/kaffa/scripts/npm-log-streamer.sh sync
```
### 로그 누락
```bash
# 컨테이너 상태 확인 # 컨테이너 상태 확인
podman ps podman ps
# 로그 파일 존재 확인 # 포트 바인딩 확인
podman exec npm-app ls -la /data/logs/ ss -tlnp | grep ':80\|:81\|:443'
# 마운트 확인
ls -la /home/kaffa/nginx-proxy-manager/data/logs/
``` ```
### 컨테이너 관리
```bash
# 컨테이너 내부 접근
podman exec -it nginx-proxy-manager /bin/bash
# 볼륨 확인
podman volume ls
# 컨테이너 로그 확인
podman logs nginx-proxy-manager
# 이미지 업데이트 (AutoUpdate=registry로 자동)
podman auto-update
```
### 시스템 파라미터 확인
```bash
# 커널 파라미터 확인
cat /proc/sys/net/ipv4/ip_unprivileged_port_start
cat /proc/sys/vm/swappiness
cat /proc/sys/net/core/somaxconn
# Lingering 상태 확인
loginctl show-user admin | grep Linger
# 서비스 의존성 확인
systemctl --user list-dependencies nginx-proxy-manager.service
```
## 🛡️ 보안 고려사항
### 1. Rootless 컨테이너
- 루트 권한 없이 컨테이너 실행
- 호스트 시스템과 격리된 사용자 네임스페이스
- 보안 취약점 영향 범위 최소화
### 2. 네트워크 격리
- pasta를 통한 네트워크 네임스페이스 격리
- 컨테이너별 독립적인 네트워크 스택
- 불필요한 포트 노출 차단
### 3. 자동 업데이트
- `AutoUpdate=registry`: 레지스트리에서 최신 이미지 자동 갱신
- 보안 패치 자동 적용
- `podman auto-update` 명령으로 수동 업데이트 가능
## 📈 성능 최적화
### 1. 메모리 관리
- `vm.swappiness=10`: 메모리 우선 사용으로 I/O 대기 시간 감소
- `vm.dirty_ratio=15`: 쓰기 성능 최적화
- `vm.vfs_cache_pressure=50`: 파일시스템 캐시 효율성 향상
### 2. 네트워크 성능
- `net.core.somaxconn=65535`: 대용량 동시 연결 처리
- `net.core.netdev_max_backlog=5000`: 네트워크 패킷 처리 최적화
- `net.ipv4.tcp_fin_timeout=30`: TCP 연결 종료 시간 단축
### 3. 컨테이너 최적화
- `kernel.pid_max=4194304`: 대용량 프로세스 지원
- `fs.file-max=2097152`: 파일 디스크립터 한계 확장
- `vm.max_map_count=262144`: 메모리 매핑 영역 확장
## 🔍 트러블슈팅
### 서비스 시작 실패
```bash
# 서비스 상태 및 로그 확인
systemctl --user status nginx-proxy-manager.service --no-pager
journalctl --user -u nginx-proxy-manager.service -n 20
# Quadlet 설정 검증
/usr/libexec/podman/quadlet --user --dryrun
# 포트 충돌 확인
ss -tlnp | grep ':80\|:81\|:443'
```
### 포트 바인딩 실패
```bash
# 커널 파라미터 확인
cat /proc/sys/net/ipv4/ip_unprivileged_port_start
# 수동으로 커널 파라미터 적용
sudo sysctl net.ipv4.ip_unprivileged_port_start=80
# 영구 설정 확인
cat /etc/sysctl.d/99-container-tuning.conf
```
### 자동 시작 실패
```bash
# Lingering 상태 확인
loginctl show-user admin | grep Linger
# Lingering 활성화
sudo loginctl enable-linger admin
# 서비스 활성화 확인
systemctl --user is-enabled nginx-proxy-manager.service
```
## 🎯 확장 및 개선 방향
### 1. 모니터링 시스템
- Prometheus + Grafana를 통한 컨테이너 메트릭 수집
- 로그 중앙화 (ELK Stack 또는 Loki)
- 알림 시스템 (서비스 다운 시 Slack/이메일 알림)
### 2. 백업 및 복구
- 컨테이너 볼륨 정기 백업
- 설정 파일 버전 관리 (Git)
- 재해 복구 절차 수립
### 3. 고가용성
- 다중 노드 클러스터 구성
- 로드 밸런서를 통한 트래픽 분산
- 헬스체크 및 자동 복구
### 4. 보안 강화
- Podman의 SELinux 연동
- 컨테이너 이미지 취약점 스캔
- 네트워크 정책 세분화
## ✅ 프로젝트 성과 ## ✅ 프로젝트 성과
1. **보안 강화**: 실시간 로그 분석 기반 구축 1. **완전 자동화**: 부팅 시 무인 자동 시작 달성
2. **비용 효율**: 월 $0.82 (1,200원)로 엔터프라이즈급 로그 관리 2. **안정성**: systemd 기반 서비스 관리로 높은 안정성 확보
3. **자동화**: 무인 운영 가능한 시스템 구축 3. **성능 최적화**: 커널 튜닝을 통한 프록시 워크로드 최적화
4. **확장성**: 500개 파일까지 확장 가능한 아키텍처 4. **보안**: Rootless 컨테이너로 보안 위험 최소화
5. **신뢰성**: 99.93% 업로드 성공률 5. **유지보수성**: Quadlet을 통한 선언적 설정 관리
## 📝 기술 스택
- **컨테이너**: Podman 5.4.2 (Rootless)
- **오케스트레이션**: Quadlet + systemd
- **네트워킹**: netavark + pasta
- **OS**: Debian 13 (Trixie)
- **관리도구**: systemctl, journalctl, podman CLI
--- ---
*Documentation created: 2025-09-11* *Documentation created: 2025-09-11*
*System operational since: 2025-09-10 17:13 JST* *System tested and operational: 리부팅 테스트 완료*
*Auto-start verification: ✅ 40초 만에 자동 시작 확인*