playground/acs
121
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
98b7f117b59c49c387411a151293fd129195e16a
acs/docs/ACS작업일지.md
unknown 98b7f117b5 docs: record infrastructure deployment feedback
2026-07-10 16:42:36 +09:00

17 KiB
Raw Blame History

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 확인.

Gitea 저장소 위치 수정

  • 서버담당자/매뉴얼 기준 배포용 저장소는 개인 네임스페이스가 아니라 playground 조직 아래여야 함을 확인.
  • 기존 개인 저장소:
    • https://gitea.bokdev.in/0420301/acs.git
  • 새 배포용 저장소:
    • https://gitea.bokdev.in/playground/acs.git
  • 사용자가 Gitea playground 조직 아래 acs 저장소 생성 완료.
  • 로컬 ACS Git remote 변경:
    • origin을 https://gitea.bokdev.in/playground/acs.git로 변경.
  • main 브랜치 push 완료:
    • git push -u origin main
    • 원격 origin/main 확인: 4fe4c37... refs/heads/main
  • 포털 프로젝트의 저장소 URL도 https://gitea.bokdev.in/playground/acs.git로 맞춰야 함.

테스트용 화면 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 로그에서 빌드/기동 실패 원인 확인.

Coolify Docker Compose 리소스 설정 진행

  • 사용자가 Coolify aidev 프로젝트에서 + Add Resource를 통해 Docker Compose Empty 리소스 생성 화면 진입.
  • Docker Compose file 입력 화면에 최초로 https://acs.apps.bokdev.in만 입력했으나, 해당 칸은 도메인 입력칸이 아니라 compose YAML 전체를 입력하는 영역임을 안내.
  • Coolify용 compose는 repository root 기준으로 ./backend, ./frontend build context를 사용하는 형태가 필요하다고 안내.
  • 도메인 https://acs.apps.bokdev.in은 compose file 영역이 아니라 resource의 Domains 설정에서 별도 입력해야 함.
  • 환경변수는 리소스 저장 후 resource 상세 화면의 Environment Variables, Variables, 또는 Developer view에서 입력해야 함.
  • Coolify 배포에 필요한 최소 환경변수:
    • POSTGRES_PASSWORD
    • POSTGRES_USER=acs
    • POSTGRES_DB=acs
    • ACS_PUBLIC_BASE_URL=https://acs.apps.bokdev.in
    • ACS_COOKIE_SECURE=true
    • ACS_SMS_PROVIDER=dev
  • Docker Compose 입력 화면에서 저장 시 권한 없음 메시지 발생.
  • Teams > aidev > General 화면 확인:
    • 팀 설정 입력칸이 비활성화된 상태로 보임.
    • 현재 계정은 aidev 팀/프로젝트 조회는 가능하지만 resource 생성/수정 권한이 부족할 가능성이 큼.
  • 다음 확인 필요:
    • Teams > aidev > Members에서 사용자 0420301의 역할 확인.
    • aidev 팀 또는 프로젝트에서 resource create/update/deploy 권한 부여 요청.
    • 권한이 없는 경우 권한 있는 관리자가 ACS resource를 생성하거나, 사용자에게 프로젝트 관리자 권한을 부여해야 함.

인프라 담당자 피드백 반영 필요

  • 인프라 담당자 피드백 요지:
    • AI DEV 표준 환경에는 .project-env가 미리 정의되어 있음.
    • DB를 로컬/compose 내부에 직접 만들고 전체 기술구조를 통째로 배포하는 방식은 표준 흐름과 맞지 않을 수 있음.
    • 개발은 PC 로컬보다 포털의 Coder 환경에서 진행하는 것을 권장.
    • 배포 앱은 Node.js 기반으로 맞추는 것이 좋다는 의견.
    • CLAUDE.md 등 프로젝트 작업 규칙 파일이 표준 템플릿에 이미 준비되어 있음.
  • 현재 ACS와의 차이:
    • 현재 ACS는 Spring Boot 백엔드 + React 프론트 + PostgreSQL + nginx의 다중 컨테이너 구조.
    • 기존 compose는 자체 PostgreSQL 컨테이너를 포함함.
    • AI DEV 표준은 Coder에서 제공하는 .project-env의 DATABASE_URL 등 환경값을 사용하고, 앱 소스 중심으로 배포하는 방식으로 보임.
  • 대응 방향:
    • Coolify Docker Compose 직접 배포 시도를 잠시 중단.
    • Coder 환경에서 playground/acs를 clone한 뒤, 실제 제공되는 .project-env와 sample/템플릿 구조를 먼저 확인.
    • 인프라 담당자에게 Java/Spring Boot Dockerfile 배포 허용 여부를 확인.
    • Node.js가 필수라면 ACS 백엔드 구조를 Node 기반으로 전환하거나, 최소 배포 가능 범위를 재설계해야 함.
    • 자체 DB 컨테이너 대신 플랫폼 제공 PostgreSQL 접속정보(DATABASE_URL)를 쓰는 구조로 변경 검토.
    • ACS용 CLAUDE.md 또는 동등한 작업 규칙 문서를 추가해 Claude/Codex 협업 기준을 명시하는 방안 검토.

인증서 확인

  • 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 설정