ivada-infra/DOCS

Fork 0

0914eagle 1cd520b101 rb8001 종합 트러블슈팅

2025-08-13 14:04:25 +09:00

6.7 KiB

Executable File

Raw Blame History

Gitea Actions 설정 및 Self-hosted Runner 구성 가이드

날짜: 2025-07-14
작업자: Claude (RO-BEING 시스템 관리)

개요

nginx-infra 저장소에서 Gitea Actions 자동 배포를 설정하는 과정에서 발생한 문제들과 해결 방법을 기록합니다.

문제 상황

초기 문제: Runner 실행 환경 불일치

증상: Gitea Actions 워크플로우가 대기 상태(waiting)에서 벗어나지 못함

원인:

워크플로우: runs-on: ubuntu-latest (컨테이너 환경)
실제 작업: 로컬 시스템 /etc/nginx 직접 접근 시도
→ 컨테이너에서는 호스트 시스템 파일에 접근 불가

해결 과정

1단계: Self-hosted Runner 설치 확인

# act_runner 설치 상태 확인
which act_runner
# /usr/local/bin/act_runner

act_runner --version
# act_runner version v0.2.6

결과: 이미 설치되어 있었음

2단계: Runner 등록 토큰 생성

Gitea 웹 인터페이스에서:

Site Administration → Actions → Runners
"Create new Runner" 클릭
등록 토큰 생성: j0JCOcmeK02Khp4uIROhj8enbACwqUVuhMjxn7FI

3단계: Runner 등록 (잘못된 라벨)

첫 번째 시도:

act_runner register --no-interactive \
  --instance http://localhost:3000 \
  --token j0JCOcmeK02Khp4uIROhj8enbACwqUVuhMjxn7FI \
  --name admin-runner \
  --labels ubuntu-latest

문제: 워크플로우에서 self-hosted를 요구하는데 ubuntu-latest 라벨로 등록

4단계: 라벨 불일치 문제 해결

원인:

워크플로우: runs-on: self-hosted
Runner 라벨: ubuntu-latest
→ 매칭되지 않아 작업 할당 안됨

해결책: Runner를 올바른 라벨로 재등록

# 기존 runner 종료
killall act_runner

# 설정 파일 삭제
rm -f .runner

# 대화형으로 재등록
act_runner register
# URL: http://localhost:3000
# Token: j0JCOcmeK02Khp4uIROhj8enbACwqUVuhMjxn7FI
# Name: admin-runner
# Labels: self-hosted  # 중요!

5단계: Runner 실행

# /etc/act_runner 디렉토리에서 실행
cd /etc/act_runner
nohup act_runner daemon --config .runner > ~/act_runner.log 2>&1 &

핵심: admin 계정으로 실행하여 sudo NOPASSWD 권한 활용

6단계: 워크플로우 nginx 설정 검증 오류 수정

문제: nginx 설정 검증 단계에서 오류 발생

nginx: [emerg] "server" directive is not allowed here in /tmp/nginx-test-config:21

원인: -c 옵션으로 site 설정 파일을 전체 nginx.conf로 검증 시도

해결책: 임시 교체 방식으로 검증 방법 변경

# 변경 전
sudo nginx -t -c /tmp/nginx-test-config

# 변경 후  
sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/default.temp.backup
sudo cp server-nginx-default /etc/nginx/sites-available/default
sudo nginx -t || {
  sudo cp /etc/nginx/sites-available/default.temp.backup /etc/nginx/sites-available/default
  exit 1
}
sudo cp /etc/nginx/sites-available/default.temp.backup /etc/nginx/sites-available/default

최종 구성

워크플로우 설정

jobs:
  deploy:
    runs-on: self-hosted  # Self-hosted runner 사용

Runner 상태

# Runner 프로세스 확인
ps aux | grep act_runner
# admin     429705  0.1  0.0 1243692 18304 pts/4   Sl   17:52   0:00 act_runner daemon

# Nginx 서비스 상태
sudo systemctl status nginx
# Active: active (running)

# Nginx 설정 검증
sudo nginx -t
# nginx: configuration file /etc/nginx/nginx.conf test is successful

권한 설정 확인

admin 계정 sudo 권한

sudo -l
# (ALL) NOPASSWD: ALL
# (ALL) NOPASSWD: /usr/sbin/nginx, /bin/systemctl * nginx, /bin/cp * /etc/nginx/sites-available/default

결과: admin 계정이 패스워드 없이 nginx 관련 sudo 명령 실행 가능

트러블슈팅

일반적인 문제들

문제: Gitea Actions가 waiting 상태에서 멈춤 해결: Runner 라벨과 워크플로우 runs-on 설정 일치 확인

문제: nginx 설정 검증 실패 (server directive error) 해결: 전체 nginx.conf 컨텍스트에서 검증하도록 방법 변경

문제: sudo 권한 없음 오류 해결: admin 계정으로 runner 실행 및 NOPASSWD 설정 확인

문제: 파일 권한 오류 (Permission denied) 해결: 로그 파일을 홈 디렉토리(~/)에 저장

권장 설정

Runner 등록 시 주의사항:
- 라벨을 self-hosted로 정확히 설정
- admin 계정에서 등록 및 실행
디렉토리 구조:
- Runner 설정: /etc/act_runner/.runner
- 로그 파일: ~/act_runner.log

모니터링 명령어:

# Runner 상태 확인
ps aux | grep act_runner

# 로그 실시간 확인
tail -f ~/act_runner.log

# nginx 상태 확인
sudo systemctl status nginx
sudo nginx -t

조직 레벨 Runner 설정 (추가)

개별 저장소 → 조직 공유 Runner 변경

배경: 각 저장소마다 개별 runner를 설정하는 것보다 조직 단위 공유 runner가 효율적

절차:

기존 runner 정리:

killall act_runner
rm -f .runner
rm -f /etc/act_runner/.runner

조직 runner 토큰 생성:
- Gitea 웹 → Organizations → ivada_Ro-being → Settings → Actions → Runners
- "Add new runner" 클릭
- 조직 토큰 생성: kn5nLcoJgHUh4vgdPTF2cjL9eOHPOArWIHGFJIQq
조직 레벨 runner 등록:

cd /etc/act_runner
act_runner register
# URL: http://localhost:3000
# Token: kn5nLcoJgHUh4vgdPTF2cjL9eOHPOArWIHGFJIQq
# Name: org-shared-runner
# Labels: self-hosted

실행:

cd /etc/act_runner
nohup act_runner daemon --config .runner > ~/org_runner.log 2>&1 &

장점:

✅ 모든 조직 저장소에서 자동 사용 가능
✅ 통합 관리 및 모니터링
✅ Runner 리소스 효율적 활용
✅ 권한 설정 간편

적용 저장소:

nginx-infra
test (Python FastAPI)
frontend-base
api-base
기타 모든 ivada_Ro-being 저장소

트러블슈팅 (조직 Runner)

문제: runner registration token not found 원인: 토큰 만료 또는 잘못된 조직 설정 해결: 새 토큰 생성 또는 조직 Actions 설정 확인

문제: 조직 runner가 개별 저장소에서 인식 안됨 해결: 저장소 Actions 설정에서 "Allow organization runners" 활성화

참고 자료

Gitea Actions 문서: https://docs.gitea.io/en-us/actions/
act_runner GitHub: https://github.com/nektos/act_runner
Nginx 설정: /etc/nginx/sites-available/default
워크플로우 파일: .gitea/workflows/deploy.yml
조직 Runner 로그: ~/org_runner.log

이 문서는 Claude에 의해 자동 생성되었습니다.

6.7 KiB Executable File Raw Blame History