AriWeb-Suite/modules/webmaker/docs/GITEA-LOCAL.md

사이트 소스 저장소 — 서비스 서버의 로컬 Gitea

AI Webmaker v1.4.14 · 2026-10-10 · 대상: 운영자

1. 무엇이 바뀌었나

	1.4.5 까지	1.4.14 부터
사이트 버전(생성·AI 수정·직접 편집·배포본)을 올리는 곳	회사 소스 저장소 source.ibit.kr 의 OZ-Group/WebHosting_AI_agent (이 도구의 코드 저장소에 sites/<ID>/… 브랜치로 섞여 있었음)	서비스 서버 안의 전용 Gitea — 계정 webmaker, 비공개 저장소 webmaker/sites
저장소 접근	두 운영 서버(webmaker.ibit.kr, 192.168.20.66)가 같은 저장소에 같은 사이트 ID 로 푸시 → 이력이 서로 엇갈릴 수 있었음	서버마다 자기 Gitea 에만 푸시 (서버 밖으로 나가지 않음)
설치	사람이 Gitea 에 배포 키를 등록	deploy/install-gitea.sh 한 번 (컨테이너·계정·저장소·키·서비스 설정)

브랜치 구조(sites/<ID>/main, sites/<ID>/changes/NNNN-종류)와 빌더의 "이전 버전으로 되돌리기" 동작은 그대로다.

2. 구성

• Docker 컨테이너 webmaker-gitea (gitea/gitea:1.27, SQLite). 데이터 /srv/webmaker-gitea (서비스 사용자 소유).
• HTTP: <LAN IP>:3030 — 운영자가 브라우저로 버전을 본다. 바깥(공인망)에는 열지 않는다. 가입 금지, 로그인해야 열람.
• SSH: 127.0.0.1:2230 — 서비스가 같은 서버에서만 푸시한다.
• 계정
  • webmaker-admin — Gitea 관리자(콘솔용)
  • webmaker — 서비스 전용. 저장소 webmaker/sites 소유자. 서비스 서버의 키 ~/.ssh/id_ed25519_webmaker_gitea 가 이 계정의 SSH 키로 등록된다.
  • 비밀번호는 /srv/webmaker-gitea/credentials.env (0600). 화면에 다시 보이지 않는다.
• ~/.ssh/config 에 Host webmaker-gitea (127.0.0.1:2230, 위 키) 가 추가된다.
• v1.5.7 부터 접속 정보는 systemd 유닛이 아니라 설정 파일 data/config.json 의 source.* 에 들어간다(source.remote=git@webmaker-gitea:webmaker/sites.git, source.web=http://<LAN IP>:3030/webmaker/sites, source.apiUrl=http://<LAN IP>:3030, source.user, source.repo, API 토큰은 보관소 gitea). 1.4.14~1.4.18 의 SITES_GIT_REMOTE/WEB 유닛 줄은 1.5.7 첫 기동 때 설정 파일로 옮겨지고, install-gitea.sh 를 다시 실행하면 유닛에서 지워진다. 연동 모듈은 lib/connectors/gitea.js (docs/ARIMAIL.md 1절) — 초기 설정 페이지·관리자 콘솔 › 시스템 설정에서 값을 보고 바꾸며, API 토큰이 있으면 "저장소 만들기"·"공개키 등록" 버튼도 쓸 수 있다.

3. 설치·마이그레이션 (한 번)

서비스 서버에서, 서비스 사용자로:

# webmaker.ibit.kr (bear)
/home/master/webmaker/deploy/install-gitea.sh --bind 192.168.20.23 --service webmaker \
  --migrate-from git@source-webmaker:OZ-Group/WebHosting_AI_agent.git
# 192.168.20.66
~/work/WebHoting_AI_Agent/deploy/install-gitea.sh --bind 192.168.20.66 --service webhosting-agent \
  --migrate-from git@source-webhosting:OZ-Group/WebHosting_AI_agent.git

하는 일 (다시 실행해도 안전, 있는 것은 건너뜀):

1. 컨테이너를 만들고 준비될 때까지 기다린다.
2. 계정 2개와 저장소 webmaker/sites 를 만든다.
3. SSH 키를 만들고(없으면) webmaker 계정에 등록, ~/.ssh/config 에 별칭을 넣고 git ls-remote 로 확인한다.
4. --migrate-from 가 있으면 scripts/migrate-gitstore.sh 로 옛 저장소의 sites/* 브랜치를 모두 받아 새 저장소에 올리고, 이 서버의 data/git/<ID> 저장소들의 origin 을 새 주소로 바꾼 뒤 그 최신 상태(main 강제, 변경 브랜치)를 올린다. 마지막에 옛·새 저장소의 브랜치 목록을 비교해 빠진 것을 알린다.
5. (v1.5.7) 설정 파일 data/config.json 에 source.remote/source.web/source.apiUrl/source.user/source.repo 를 쓰고, webmaker 계정의 API 토큰을 만들어 보관소(gitea)에 넣는다. 유닛에 남은 옛 SITES_GIT_* 줄은 지운다. 서비스는 호출 때마다 설정을 읽어 푸시 주소가 바로 적용되며, 실행 중인 AI 작업이 없을 때 서비스를 재시작한다(--no-restart 로 생략).

옛 저장소의 브랜치는 지우지 않는다. 새 저장소를 확인한 뒤 정리하려면:

git ls-remote --heads git@source-webhosting:OZ-Group/WebHosting_AI_agent.git 'refs/heads/sites/*' | awk '{print $2}' | sed 's#refs/heads/##' | xargs git push git@source-webhosting:OZ-Group/WebHosting_AI_agent.git --delete

두 서버가 같은 사이트 ID 로 옛 저장소에 서로 다른 커밋을 올린 변경 브랜치가 있으면(2026-10-10 기준 1개), 새 저장소에는 옛 저장소의 커밋이 남고 그 서버의 로컬 커밋은 올라가지 않는다(빠른 진행만). 로컬 main 은 강제로 올리므로 "되돌리기" 와 최신 상태에는 영향이 없다.

4. 확인

• 관리자 콘솔 › 설정 › 소스 저장소 (로컬 Gitea) › 연결 확인 → "연결 성공 — 저장소에 사이트 브랜치 N개", 아래에 이 서버의 공개키.
• 브라우저: http://<LAN IP>:3030/webmaker/sites (webmaker-admin 로그인) → 브랜치 목록.
• 빌더에서 수정 지시를 한 번 보내면 sites/<ID>/changes/NNNN-ai-update 브랜치가 새로 생긴다.

5. 자주 나는 메시지

메시지	원인	해결
소스 저장소 서버에 연결할 수 없습니다 — 로컬 Gitea 컨테이너(webmaker-gitea)가 실행 중인지…	컨테이너가 멈춤·docker 재시작 중	docker start webmaker-gitea (restart=unless-stopped 라 부팅 때 자동 시작)
소스 저장소(Gitea) 접근 거부 — 이 서버의 키가 저장소 계정(webmaker)에 등록되지 않았거나…	키 파일이 바뀜·계정 키 삭제	deploy/install-gitea.sh 다시 실행(키를 다시 등록)
푸시 주소(source.remote)가 없어 소스를 원격에 보관하지 않습니다 (1.4.x: SITES_GIT_REMOTE 가 설정되지 않아…)	설정 파일에 값이 없음(새 서버)	deploy/install-gitea.sh --service <유닛 이름> 또는 초기 설정 페이지 › 소스 보관 연동에 푸시 주소 입력
Gitea API 토큰이 올바르지 않습니다 (401)	토큰 폐기·계정 변경	install-gitea.sh 다시 실행(토큰 재생성) 또는 Gitea › 설정 › 애플리케이션에서 토큰을 만들어 설정 페이지 source.token 에 입력
되돌리기 목록은 보이는데 Gitea 에 브랜치가 없음	푸시 실패분(컨테이너 정지 중 등)	다음 변경 때 자동 재시도. 서둘러 맞추려면 scripts/migrate-gitstore.sh <옛> <새> 를 다시 실행(로컬 저장소를 다시 올림)

6. 백업

/srv/webmaker-gitea 전체(SQLite DB + 저장소)를 그대로 복사하면 된다. 사이트 파일의 원본은 여전히 서비스 서버의 data/git/<ID> + /var/www/…/<ID> 이므로, Gitea 는 "볼 수 있는 사본·이력" 역할이다.