1. 서론: Gitea 로그인 화면 접근 장애 시

이 글을 열어보신 분은 아마도 Gitea의 로그인 페이지 앞에서 고민 중일 가능성이 높습니다. 사용자명은 기억하고 있지만 비밀번호는 반복해서 입력해도 오류가 발생하거나 초기 설정을 전혀 기억하지 못하는 상황입니다. 이럴 때마다 스트레스를 받는 경험을 공유하려 합니다. 특히 자체 서버에 설치한 테스트 환경이나 소규모 팀 내부 사용용 Gitea 인스턴스에서 관리자 계정 비밀번호를 잊은 경우, 자신의 저장소 외부로 막혀 있는 듯한 감각을 느끼게 됩니다.

Gitea는 가벼운 오픈소스 Git 호스팅 솔루션으로, 개발자들이 자체 서버에 배포하여 보안과 제어권을 확보하려는 목적에서 많이 사용됩니다. 하지만 이러한 독자적 운영 방식은 SaaS 서비스처럼 '비밀번호 찾기' 기능을 통해 간단히 해결할 수 있는 문제를, 직접적인 개입이 필요하게 만듭니다. 다행히도 Gitea는 다양한 방법으로 계정 접근을 복원할 수 있도록 설계되어 있습니다. 명령행 도구부터 데이터베이스 직접 조작까지, 사용자의 환경에 따라 적합한 방법을 제공합니다.

이번 글에서는 개인적으로 경험한 방법들을 체계적으로 정리하여, Windows, Linux(Ubuntu), Docker 기반 환경 등 다양한 배포 형태와 최악의 경우 데이터베이스 수준에서 비밀번호를 재설정해야 하는 상황까지 모두 포함한 실용적인 해결책을 제시하겠습니다. 목표는 단순히 현재 문제가 해결되도록 하기보다는, 원리 이해를 통해 향후 유사한 상황에서도 대응 능력을 갖추는 것입니다. 시작해볼까요.

2. 권장 방법: CLI 도구를 통한 비밀번호 변경

Gitea 공식 문서에 명시된 표준적인 방법으로, 암호 변경 시 가장 안전하고 간편한 접근 방식입니다. 이 방법은 Gitea 프로그램 내장의 admin 명령어를 호출하여 사용자 정보를 직접 수정합니다. 데이터베이스에 직접 접근하지 않아 오류 발생 가능성을 줄이고, 원래의 시스템 키를 사용하는 것처럼 신뢰성 있게 작동합니다.

2.1 윈도우 환경에서의 실행

많은 개발자가 테스트 환경이나 경량 애플리케이션을 윈도우 서버에서 운영합니다. 여기서 핵심은 Gitea 실행 파일(gitea.exe)을 찾고 실행하는 것입니다.

관리자 권한으로 명령프롬프트(CMD)나 PowerShell을 열어야 합니다. 이는 이후 명령어 실행 시 권한 부족으로 인한 실패를 방지하기 위함입니다. 시작 메뉴에서 'cmd' 또는 'PowerShell'을 검색 후 우클릭하여 '관리자 권한으로 실행'을 선택하세요.

다음으로 Gitea 설치 경로로 이동해야 합니다. 일반적인 위치는 C:\gitea, D:\gitea 또는 해제한 파일 폴더입니다. 예를 들어 C:\gitea에 설치했다면 다음과 같은 명령어를 입력합니다:

cd C:\gitea

위치를 모르는 경우, 서비스 목록에서 확인할 수 있습니다. Win + R을 눌러 services.msc를 실행하고, 'Gitea' 서비스를 찾아 '속성'을 클릭하면 실행 파일 경로가 나타납니다. 해당 경로의 상위 폴더가 바로 작업 디렉토리입니다.

디렉토리로 이동한 후 비밀번호 변경 명령어를 실행합니다:

gitea.exe admin user change-password --username <사용자명> --password <새비밀번호>

예를 들어, root 사용자에게 NewSecurePass!라는 비밀번호를 설정하려면 다음과 같습니다:

gitea.exe admin user change-password --username root --password NewSecurePass!

수행이 완료되면 명령어가 아무런 출력 없이 종료됩니다. 마지막으로 Gitea 서비스를 재시작해야 합니다. 서비스 관리자에서 우클릭 후 '재시작'을 선택하거나 다음 명령어를 사용할 수 있습니다:

net stop gitea
net start gitea

이제 새 비밀번호로 로그인이 가능합니다.

2.2 리눅스(Ubuntu) 환경에서의 실행

리눅스는 Gitea의 주요 운영 환경입니다. Ubuntu에서의 절차는 유사하지만 경로와 명령어가 다릅니다.

터미널을 열고 sudo 권한을 가진 상태로 작업해야 합니다. 먼저 gitea 실행 파일의 위치를 확인해야 합니다. 일반적으로 /usr/local/bin/gitea에 존재합니다.