255 lines
13 KiB
Markdown
255 lines
13 KiB
Markdown
# ACS 작업일지
|
|
|
|
## 2026-07-10
|
|
|
|
### 작업 범위 합의
|
|
- Codex는 `C:\ai-dev\workspace\acs`의 ACS 개선 및 배포 준비를 담당하기로 함.
|
|
- RTGS 프로젝트는 별도 담당자가 작업하므로, 사용자가 명시적으로 요청하지 않는 한 `C:\ai-dev\workspace\rtgs`는 읽기/수정/빌드/배포하지 않기로 함.
|
|
- ACS 관련 설치, 구성, 변경, 배포, 검증 내용은 이 파일에 계속 갱신하기로 함.
|
|
- 서버/저장소 계정 정보와 비밀번호는 일지에 기록하지 않기로 함.
|
|
|
|
### 로컬 프로젝트 확인
|
|
- ACS 구조 확인:
|
|
- 백엔드: Spring Boot 3.4.5, Java 21, Maven, JPA, Flyway, PostgreSQL 운영 구성
|
|
- 프론트엔드: React 19, Vite 6, TypeScript
|
|
- 배포 구성: `infra/docker-compose.yml`, `infra/docker-compose.tls.yml`, nginx reverse proxy
|
|
- Git 원격 저장소는 아직 등록되어 있지 않음을 확인함.
|
|
- `.git/index.lock` 파일이 남아 있어, 추후 `git add/commit/push` 전 정리가 필요함.
|
|
|
|
### 배포 전 빌드/테스트 검증
|
|
- 프론트엔드 `npm run build` 성공.
|
|
- 백엔드 최초 테스트에서 운영 Flyway 스키마와 엔티티 불일치 발견:
|
|
- `visit_requests` 테이블에 `work_name`, `control_*`, `watcher*_ *` 계열 컬럼 누락.
|
|
- 신규 Flyway 마이그레이션 추가:
|
|
- `backend/src/main/resources/db/migration/V4__visit_request_contact_fields.sql`
|
|
- 기존 DB에도 적용 가능하도록 `ALTER TABLE ... ADD COLUMN` 방식 사용.
|
|
- 테스트용 H2 호환성을 위해 컬럼 추가 구문을 개별 `ALTER TABLE` 문으로 분리함.
|
|
- `DataSeeder`의 로컬 계정과 테스트 코드 기대 계정 불일치 수정:
|
|
- 기존 단축 계정 `a/s/h` 유지
|
|
- 테스트 및 CSV seed와 맞는 `admin/security/host`도 함께 생성하도록 보정
|
|
- 백엔드 `mvn -B -ntp test` 성공:
|
|
- 9 tests, 0 failures, 0 errors
|
|
- 백엔드 `mvn -B -ntp -DskipTests package` 성공:
|
|
- `backend/target/acs-0.0.1-SNAPSHOT.jar` 생성 확인
|
|
|
|
### Docker/Compose 확인
|
|
- 로컬 Docker 설치 확인:
|
|
- `docker --version` 성공
|
|
- `docker compose` 플러그인은 없음
|
|
- `docker-compose --version`은 사용 가능
|
|
- Compose 설정 문법 확인:
|
|
- `docker-compose --env-file infra/.env.example -f infra/docker-compose.yml config` 성공
|
|
- `docker-compose --env-file infra/.env.example -f infra/docker-compose.yml -f infra/docker-compose.tls.yml config` 성공
|
|
- 운영 배포 URL을 환경변수로 넣은 HTTPS 구성 확인:
|
|
- `ACS_PUBLIC_BASE_URL=https://acs.apps.bokdev.in`
|
|
- `ACS_COOKIE_SECURE=true`
|
|
- Compose config 정상
|
|
- Docker 이미지 빌드는 로컬 Docker 빌더 문제로 실패:
|
|
- buildx 플러그인 없음
|
|
- Docker legacy builder가 Docker API v1.54 build 요청에서 `500 Internal Server Error` 반환
|
|
- 코드/Compose 문법 문제보다는 로컬 Docker Desktop/빌더 환경 문제로 판단
|
|
|
|
### 서버/URL 접근성 확인
|
|
- `https://portal.bokdev.in/`:
|
|
- HTTPS 접근 가능
|
|
- HTTP 200 OK 확인
|
|
- `https://acs.apps.bokdev.in`:
|
|
- DNS 해석 가능
|
|
- 현재 HTTP 503 Service Unavailable 확인
|
|
- 아직 앱이 정상 배포/기동되지 않은 상태로 판단
|
|
- `https://acs.bokdev.in/0420301/repo`:
|
|
- 현재 PC 네트워크에서 `acs.bokdev.in` DNS 해석 실패
|
|
- 저장소 원격 등록/푸시 전 네트워크 또는 도메인 확인 필요
|
|
|
|
### 저장소 URL/DNS 추가 확인
|
|
- 저장소 후보 URL `https://acs.bokdev.in/0420301/repo` 확인.
|
|
- 로컬 ACS Git remote 확인 결과, 등록된 원격 저장소 없음.
|
|
- `git ls-remote https://acs.bokdev.in/0420301/repo` 실행 결과:
|
|
- `Could not resolve host: acs.bokdev.in`
|
|
- 현재 PC DNS 서버:
|
|
- `210.104.132.1`, `210.104.132.2`
|
|
- `10.168.198.34`, `10.168.198.35`
|
|
- 기본 DNS 및 공개 DNS 확인 결과:
|
|
- `portal.bokdev.in`은 `27.96.158.129`로 해석됨.
|
|
- `acs.apps.bokdev.in`은 `27.96.158.129`로 해석됨.
|
|
- `acs.bokdev.in`은 해석 실패.
|
|
- `bokdev.in` 권한 DNS 서버 확인:
|
|
- `salvador.ns.porkbun.com`
|
|
- `fortaleza.ns.porkbun.com`
|
|
- `curitiba.ns.porkbun.com`
|
|
- `maceio.ns.porkbun.com`
|
|
- 권한 DNS 서버 `curitiba.ns.porkbun.com`에 직접 질의한 결과:
|
|
- `portal.bokdev.in` A 레코드 존재: `27.96.158.129`
|
|
- `acs.apps.bokdev.in` A 레코드 존재: `27.96.158.129`
|
|
- `acs.bokdev.in` A/CNAME 레코드 없음
|
|
- `nslookup acs.bokdev.in curitiba.ns.porkbun.com` 결과: `Non-existent domain`
|
|
- 결론:
|
|
- 현재 저장소 URL의 호스트명 `acs.bokdev.in`은 DNS에 등록되어 있지 않은 것으로 판단.
|
|
- 저장소 URL이 잘못 전달되었거나, DNS 레코드 생성이 아직 완료되지 않았을 가능성이 큼.
|
|
- 원격 저장소 등록/푸시 전에 정확한 저장소 URL 재확인이 필요.
|
|
|
|
### AI DEV 매뉴얼 확인
|
|
- 참조 파일: `docs/AIdev.md`
|
|
- 매뉴얼 기준 주요 서비스:
|
|
- 포털: `https://portal.bokdev.in`
|
|
- Coder: `https://coder.bokdev.in`
|
|
- Gitea: `https://gitea.bokdev.in`
|
|
- Kubero: `https://kubero.bokdev.in`
|
|
- Coolify: `https://coolify.bokdev.in`
|
|
- Gitea 저장소 생성/Push 기준:
|
|
- Gitea의 `playground` 조직에 저장소를 생성.
|
|
- 저장소 URL 형식은 `https://gitea.bokdev.in/playground/<repo>.git`.
|
|
- 예: ACS 저장소명이 `acs`라면 `https://gitea.bokdev.in/playground/acs.git`.
|
|
- 배포 기준:
|
|
- Gitea 저장소 1개가 배포 앱 1개에 대응.
|
|
- Kubero 또는 Coolify 중 하나를 사용.
|
|
- Coolify는 Public Repository 방식으로 Gitea 저장소 URL 전체를 입력하고 Dockerfile 빌드를 사용.
|
|
- Coolify에서 도메인 생성 시 `https://<repo>.apps.bokdev.in` 형식으로 지정되는 것으로 매뉴얼에 기재되어 있음.
|
|
- ACS에 대한 적용 판단:
|
|
- 기존 후보 `https://acs.bokdev.in/0420301/repo`는 매뉴얼 기준 저장소 URL 형식이 아님.
|
|
- ACS 저장소 URL은 우선 `https://gitea.bokdev.in/playground/acs.git`로 보는 것이 타당.
|
|
- 저장소가 아직 없다면 Gitea `playground` 조직에 `acs` repository를 생성해야 함.
|
|
- 배포 URL `https://acs.apps.bokdev.in`은 Coolify 도메인 형식과 일치.
|
|
|
|
### 프로젝트 설정 URL 오류 확인
|
|
- 사용자가 포털 프로젝트 수정 화면에서 저장소 URL을 `https://acs.bokdev.in/0420301/repo`로 임의 입력한 사실 확인.
|
|
- 해당 값은 Gitea 저장소 URL이 아니므로 수정 필요.
|
|
- 후보 저장소 페이지 확인:
|
|
- `https://gitea.bokdev.in/playground/acs`: Not found
|
|
- `https://gitea.bokdev.in/playground/ACS`: Not found
|
|
- `https://gitea.bokdev.in/0420301/acs`: Not found
|
|
- `https://gitea.bokdev.in/0420301/ACS`: Not found
|
|
- 결론:
|
|
- 현재 ACS Gitea 저장소는 아직 생성되지 않았거나, 비공개/다른 이름으로 생성된 상태일 수 있음.
|
|
- 매뉴얼 기준으로는 `playground` 조직에 `acs` 저장소를 새로 만들고, 프로젝트 저장소 URL을 `https://gitea.bokdev.in/playground/acs.git`로 설정하는 것이 우선 추천.
|
|
- 배포 URL `https://acs.apps.bokdev.in`은 유지 가능.
|
|
|
|
### Gitea Credential Helper 및 저장소 재확인
|
|
- Git 접근 중 Windows `CredentialHelperSelector` 팝업 발생.
|
|
- 권장값인 `manager` 선택 완료.
|
|
- 이후 `git ls-remote https://gitea.bokdev.in/playground/acs.git` 재시도 시 인증 대기 상태로 타임아웃됨.
|
|
- 비대화식 확인:
|
|
- `GIT_TERMINAL_PROMPT=0`
|
|
- `git -c credential.helper= ls-remote https://gitea.bokdev.in/playground/acs.git`
|
|
- 결과: `could not read Username for 'https://gitea.bokdev.in': terminal prompts disabled`
|
|
- Gitea API 비교 확인:
|
|
- `https://gitea.bokdev.in/api/v1/repos/playground/MANUAL`: 200 OK
|
|
- `https://gitea.bokdev.in/api/v1/repos/playground/acs`: `The target couldn't be found`
|
|
- 판단:
|
|
- Gitea 서버와 API는 정상 접근 가능.
|
|
- `playground/acs` 저장소는 비로그인/API 기준으로 존재하지 않거나 private/권한 미승인 상태.
|
|
- 포털 프로젝트의 저장소 URL 수정만으로 Gitea 저장소가 자동 생성되는 것은 아니므로, Gitea에서 `playground/acs` repository 생성 여부를 별도로 확인해야 함.
|
|
|
|
### Gitea ACS 저장소 생성 및 원격 등록
|
|
- 사용자가 Gitea에서 ACS 저장소 생성 완료.
|
|
- 생성된 저장소 확인:
|
|
- 웹 URL: `https://gitea.bokdev.in/0420301/acs`
|
|
- Git URL: `https://gitea.bokdev.in/0420301/acs.git`
|
|
- `playground/acs`가 아니라 개인 네임스페이스 `0420301/acs`로 생성됨.
|
|
- 빈 저장소 상태 확인:
|
|
- `git ls-remote https://gitea.bokdev.in/0420301/acs.git` 결과가 비어 있으나 exit code 0으로 정상.
|
|
- 이전 타임아웃된 Gitea 확인용 Git 프로세스와 stale lock 파일 정리:
|
|
- `.git/config.lock`
|
|
- `.git/index.lock`
|
|
- 로컬 ACS Git remote 등록 완료:
|
|
- `origin https://gitea.bokdev.in/0420301/acs.git`
|
|
- 남은 사항:
|
|
- push 전 커밋 대상 정리 필요.
|
|
- 로그 파일(`backend/backend-run.log`, `frontend/frontend-dev.log`)과 백업 파일(`docs/ACS작업일지.md.bak`)은 커밋 제외 권장.
|
|
- 작업트리 변경분 검토 후 최초 commit/push 진행 필요.
|
|
|
|
### 최초 커밋 및 Gitea Push
|
|
- 커밋 대상 정리:
|
|
- `.gitignore`에 `*.log`, `*.bak` 제외 규칙 추가.
|
|
- `backend/backend-run.log`, `frontend/frontend-dev.log`, `docs/ACS작업일지.md.bak`는 커밋 제외.
|
|
- 최초 Gitea push용 커밋 생성:
|
|
- 커밋: `01d48fe`
|
|
- 메시지: `feat: prepare ACS deployment`
|
|
- 포함: ACS 코드 변경, Flyway V4, 문서, 작업일지, AI DEV 매뉴얼 참조 파일.
|
|
- 원격 push 완료:
|
|
- remote: `origin`
|
|
- URL: `https://gitea.bokdev.in/0420301/acs.git`
|
|
- branch: `main`
|
|
- `origin/main` 추적 설정 완료.
|
|
- 원격 검증:
|
|
- `git ls-remote origin main` 결과 `01d48fe... refs/heads/main` 확인.
|
|
- `https://gitea.bokdev.in/0420301/acs` 웹 페이지 접근 200 OK 확인.
|
|
|
|
### 테스트용 화면 URL 확인
|
|
- 프론트 라우트 정의 파일: `frontend/src/App.tsx`
|
|
- 관리자/담당자 로그인 화면:
|
|
- 운영 배포 기준: `https://acs.apps.bokdev.in/login`
|
|
- 로컬 개발 기준: `http://localhost:5173/login`
|
|
- 로그인 후 주요 내부 화면:
|
|
- 대시보드: `/dashboard`
|
|
- 방문 신청 목록: `/visit-requests`
|
|
- 방문 신청 등록: `/visit-requests/new`
|
|
- 승인 대기: `/approvals`
|
|
- 출입 콘솔: `/access`
|
|
- 관리자 감사 로그: `/audit`
|
|
- 발송 내역: `/deliveries`
|
|
- 방문자/출입 QR 관련 공개 화면:
|
|
- 방문자 휴대폰 출입증 화면: `/pass/{qrToken}`
|
|
- 출입구 키오스크 QR 태깅/스캔 화면: `/kiosk`
|
|
- 운영 배포 기준 키오스크 URL: `https://acs.apps.bokdev.in/kiosk`
|
|
- QR/출입증 API:
|
|
- 공개 출입증 조회: `/api/public/passes/{qrToken}`
|
|
- 공개 QR 이미지: `/api/public/passes/{qrToken}/qr.png`
|
|
- 키오스크 체크인: `/api/public/passes/{qrToken}/check-in`
|
|
- 키오스크 체크아웃: `/api/public/passes/{qrToken}/check-out`
|
|
- QR 토큰은 방문 신청 승인 후 `qrToken`으로 발급됨.
|
|
- 문자/이메일 발송 링크는 `ACS_PUBLIC_BASE_URL + "/pass/" + qrToken` 형식으로 생성됨.
|
|
|
|
### 배포 URL 접속 상태 확인
|
|
- 운영 배포 후보 URL 확인:
|
|
- `https://acs.apps.bokdev.in`
|
|
- `https://acs.apps.bokdev.in/login`
|
|
- 확인 결과:
|
|
- 두 URL 모두 `no available server` 응답.
|
|
- 판단:
|
|
- Gitea push는 완료되었으나, Coolify 등 배포 플랫폼에서 해당 도메인에 연결된 앱 서버가 아직 생성/기동되지 않았거나 배포가 실패한 상태로 판단.
|
|
- 포털의 프로젝트 등록/저장소 URL 설정과 실제 앱 배포는 별도 단계임.
|
|
- 다음 확인 필요:
|
|
- Coolify에 ACS resource/app 생성 여부.
|
|
- Repository URL이 `https://gitea.bokdev.in/0420301/acs.git`로 설정되었는지.
|
|
- Branch가 `main`인지.
|
|
- 빌드 방식이 Docker Compose 또는 Dockerfile 중 무엇인지.
|
|
- 배포 도메인이 `https://acs.apps.bokdev.in`로 연결되었는지.
|
|
- Deployments 로그에서 빌드/기동 실패 원인 확인.
|
|
|
|
### 인증서 확인
|
|
- `infra/certs/fullchain.pem`, `infra/certs/privkey.pem` 존재 확인.
|
|
- 현재 인증서는 `CN=localhost`, SAN도 `localhost`, `127.0.0.1`용임.
|
|
- 운영 도메인 `acs.apps.bokdev.in`용 인증서가 아니므로 실제 HTTPS 운영 배포에는 부적합.
|
|
- 운영 배포 전 포털/플랫폼 인증서 자동 제공 여부 또는 도메인 인증서 교체 필요.
|
|
|
|
### 배포 정책 추천
|
|
- 권장 흐름:
|
|
- 로컬 개발
|
|
- Git commit/push
|
|
- 서버 개발환경 배포
|
|
- 서버 개발환경 검증
|
|
- 운영 배포 승인
|
|
- 서버 운영환경 배포
|
|
- 서버에서 직접 코드를 수정하며 개발하는 방식은 비추천.
|
|
- 서버 개발환경도 Git으로 받은 검증 대상 환경으로 운영하고, 운영환경에는 검증된 커밋/태그만 배포하는 정책을 권장.
|
|
- 권장 브랜치/환경:
|
|
- `dev` 또는 `develop`: 서버 개발환경 배포
|
|
- `main`: 운영 배포 가능 브랜치
|
|
- 운영 배포 시 태그 사용 예: `acs-v0.1.0`
|
|
- DB 변경은 Flyway migration으로만 반영하는 정책 유지.
|
|
|
|
### 남은 작업
|
|
- `.git/index.lock` 정리 후 Git 작업 가능 상태 확인.
|
|
- ACS 원격 저장소 URL/DNS 문제 확인.
|
|
- 원격 저장소 등록 및 최초 push 여부 결정.
|
|
- 서버 개발환경과 운영환경을 포털에서 분리 구성할 수 있는지 확인.
|
|
- 운영 도메인 인증서 처리 방식 확인.
|
|
- 로컬 Docker buildx 또는 Docker Desktop 빌더 문제 해결.
|
|
- 실제 배포 전 운영 `.env` 값 확정:
|
|
- `POSTGRES_PASSWORD`
|
|
- `ACS_PUBLIC_BASE_URL`
|
|
- `ACS_COOKIE_SECURE`
|
|
- `ACS_SMS_PROVIDER`
|
|
- SMTP 또는 사내 메시지 API 설정
|