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](ARIMAIL.md) 1절) — 초기 설정 페이지·관리자 콘솔 › 시스템 설정에서 값을 보고 바꾸며, API 토큰이 있으면 "저장소 만들기"·"공개키 등록" 버튼도 쓸 수 있다.

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

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

```bash
# 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` 로 생략).

옛 저장소의 브랜치는 **지우지 않는다**. 새 저장소를 확인한 뒤 정리하려면:
```bash
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 는 "볼 수 있는 사본·이력" 역할이다.