Ongo Framework 코어 개발가이드 · 삼카 확장

• 0. 케이스 선택 의사결정 트리
• 1. 모든 케이스 공통 전제
• A. IaaS — 실행형 jar 멀티 인스턴스
• B. IaaS — JEUS + WebToB
• C. 중앙 빌드/배포 관리 시스템 + 에이전트(원격 쉘)
• D. PaaS — Dockerfile + CI/CD
• E. 엔터프라이즈 PaaS — Tekton + Jira + ArgoCD
• F. 공통 운영 전환 체크리스트
• G. 장애 대응 런북(공통)

flowchart TD
  S([시작]) --> Q1{컨테이너 플랫폼<br/>K8s/OpenShift?}
  Q1 -- 예 --> Q2{빌드=Tekton<br/>승인=Jira<br/>배포=ArgoCD?}
  Q2 -- 예 --> E[E. Tekton+Jira+ArgoCD]
  Q2 -- 아니오 --> D[D. Dockerfile + CI/CD<br/>Jenkins/GHA/GitLab]
  Q1 -- 아니오 --> Q3{WAS 표준이<br/>JEUS 강제?}
  Q3 -- 예 --> B[B. JEUS + WebToB WAR]
  Q3 -- 아니오 --> A[A. 실행형 jar + systemd]
  A --> Q4{빌드/배포를 중앙 시스템이<br/>서버 에이전트 쉘로 수행?}
  B --> Q4
  Q4 -- 예 --> C[C. 중앙 관리 + 에이전트 쉘<br/>A/B 와 조합]
  Q4 -- 아니오 --> M[수동/사이트 표준 절차<br/>C 의 스크립트 재사용 권장]

1.1 산출물(아티팩트) 규칙

• 모든 산출물은 불변(immutable): 같은 버전 이름으로 다시 빌드하지 않는다. 버전 = <semver>+<git-sha12> 또는 <yyyyMMddHHmm>-<sha12>.
• 산출물과 함께 BUILD-INFO(git sha, 브랜치, 빌드 시각 KST, JDK, Gradle, 빌더)와 sha256 을 남긴다. springBoot { buildInfo() } 를 켜면 /actuator/info 에 노출된다.
• 운영 아티팩트에는 ongo-framework-devtools·springdoc(openapi) 를 포함하지 않는다. 프로파일로 끄는 것보다 의존성 자체를 빼는 것이 안전하다(예: if (!project.hasProperty('prod')) { developmentOnly project(':ongo-framework-devtools') }).

1.2 설정·비밀값

• 프로파일: local(개발 PC) / dev / stg / prod. SPRING_PROFILES_ACTIVE 로 지정.
• 설정 우선순위(높음→낮음): 명령행 인자 > 시스템 프로퍼티(-D) > OS 환경변수 > 외부 application-<env>.yml > jar 내부 yml.
• 비밀값(DB 비밀번호, 암호화·HMAC 키, 외부 API 토큰)은 yml·Git 금지. 주입 경로: OS 환경변수 파일(권한 600) / Vault·KMS / K8s Secret(External Secrets·Sealed Secrets) → 프레임 CryptoKeyProvider 등 SPI(가이드 #crypto).
• 데모용 ongo.framework.auth.users(평문 사용자) 는 운영 설정에서 반드시 제거하고 IdentityService 실구현으로 교체.

1.3 헬스·종료(모든 케이스 동일)

# application-prod.yml (공통 권장)
server:
  shutdown: graceful
  forward-headers-strategy: framework     # 프록시(WebToB/nginx/L4/Ingress) 뒤에서 X-Forwarded-* 신뢰
  tomcat:
    max-threads: 200                       # Boot3: server.tomcat.threads.max
    accept-count: 100
    connection-timeout: 20s
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s
management:
  server:
    port: 18080                            # 관리 포트 분리(외부 LB 미노출)
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  endpoint:
    health:
      probes:
        enabled: true                      # /actuator/health/liveness, /readiness
      show-details: never
  health:
    db:
      enabled: true

• spring-boot-starter-actuator 의존성 추가 필요(데모 인터셉터 제외 패턴에 /actuator/** 가 이미 있다).
• readiness = 트래픽 받을 준비(DB·필수 캐시 로드 완료). liveness = 프로세스 정상. LB/프로브는 readiness 로 판단한다.
• Boot2(2.7)도 동일 키 사용 가능(server.tomcat.threads.max 가 2.3+ 공식 키).

1.4 타임아웃 체인(바깥이 항상 더 길게)

클라이언트(브라우저/채널) 60s > L4 idle 55s > 웹서버(nginx/WebToB) 50s > WAS 요청 처리 45s > 앱 아웃바운드(HTTP/EAI) 30s > DB 쿼리 timeout 20s

안쪽이 더 길면 바깥이 먼저 끊어 「응답은 실패, 처리는 성공」(이중 처리) 사고가 난다. 중복 방지는 Idempotency-Key(가이드 #idem)로 보완.

1.5 멀티 인스턴스 필수 교체 SPI

인메모리 기본 구현은 단일 인스턴스 전용이다. 인스턴스가 2개 이상이면 반드시 교체한다(예제: docs/CUSTOMIZATION-EXAMPLES.md, 가이드 #extmock).

적용: VM/물리 서버에 JDK 만 설치하고 Spring Boot 실행형 jar 를 OS 서비스(systemd)로 N개 띄운 뒤 nginx 또는 L4 로 분산하는 방식. 외부 WAS 가 필요 없는 사이트의 기본 선택지.

A.1 표준 토폴로지

flowchart LR
  U[사용자/채널] --> L4[L4 / VIP :443]
  L4 --> W1[nginx web01 :80/443]
  L4 --> W2[nginx web02 :80/443]
  W1 --> A11[was01 inst1 :8081]
  W1 --> A12[was01 inst2 :8082]
  W1 --> A21[was02 inst1 :8081]
  W1 --> A22[was02 inst2 :8082]
  W2 --> A11 & A12 & A21 & A22
  A11 & A12 & A21 & A22 --> R[(Redis<br/>세션·멱등·캐시)]
  A11 & A12 & A21 & A22 --> DB[(DB)]

• 최소 권장: WAS 서버 2대 × 인스턴스 2개(서버 장애와 인스턴스 재기동을 각각 흡수). 인스턴스 수는 CPU 코어·힙 기준으로 산정(서버당 코어/2 이하, 힙 합계 ≤ 물리 메모리의 60%).
• 웹서버를 생략하고 L4 → WAS 직접도 가능하나, 정적 리소스·TLS 종료·요청 크기 제한·접근 로그를 위해 nginx 를 두는 것을 권장.

A.2 사전 준비(서버별 1회)

# 1) 실행 계정(로그인 불가, 홈=/app)
sudo groupadd -r ongo && sudo useradd -r -g ongo -d /app -s /sbin/nologin ongo
# 2) JDK (Boot3: 17/21, Boot2: 8/11) — 사내 저장소 rpm/tar 사용
sudo mkdir -p /opt/java && sudo tar -xzf OpenJDK21U-jdk_x64_linux.tar.gz -C /opt/java
sudo alternatives --install /usr/bin/java java /opt/java/jdk-21*/bin/java 1   # 또는 유닛에서 절대경로 사용
# 3) 디렉터리
SVC=ongo-app
sudo mkdir -p /app/$SVC/{releases,config,env,logs,tmp,dumps,bin}
sudo chown -R ongo:ongo /app/$SVC && sudo chmod 750 /app/$SVC/env
# 4) OS 한도·타임존
echo 'ongo soft nofile 65536
ongo hard nofile 65536' | sudo tee /etc/security/limits.d/ongo.conf
sudo timedatectl set-timezone Asia/Seoul

A.3 서버 디렉터리 표준

/app/<svc>/
├─ releases/
│   ├─ 202610301930-9018c6e1a2b3/
│   │   ├─ app.jar                 # 불변 릴리스 (Boot2: bin/ lib/)
│   │   ├─ BUILD-INFO
│   │   └─ app.jar.sha256
│   └─ 202610291010-f705a70c4d5e/
├─ current -> releases/202610301930-9018c6e1a2b3   # 배포 = 링크 전환
├─ previous -> releases/202610291010-f705a70c4d5e  # 롤백 대상
├─ config/
│   ├─ application-prod.yml        # 서버 공통 외부 설정(비밀값 없음)
│   └─ logback-spring.xml          # (선택) 외부 로그 설정
├─ env/
│   ├─ common.env                  # 공통 환경변수(비밀값, 600 권한)
│   ├─ inst1.env                   # 인스턴스별 PORT·MGMT_PORT·JAVA_OPTS
│   └─ inst2.env
├─ logs/inst1/ logs/inst2/         # 인스턴스별 로그
├─ dumps/                          # 힙덤프·GC 로그
├─ tmp/                            # java.io.tmpdir (멀티파트 임시파일)
└─ bin/                            # deploy.sh, health.sh, rollback.sh (§C 와 공유)

• releases/ 는 최근 5개 보관(§A.12 정리 스크립트). 디스크 = jar 크기 × 5 + 로그 보관량.
• tmp/ 를 별도로 두는 이유: /tmp 가 tmpfs/정리 cron 대상이면 업로드 중 파일이 삭제된다(java.io.tmpdir, server.tomcat.basedir).

A.4 외부 설정 예 (config/application-prod.yml)

spring:
  datasource:
    url: jdbc:oracle:thin:@//db-vip:1521/ONGO
    username: ongo_app
    password: ${DB_PASSWORD}             # env/common.env 에서 주입
    hikari:
      maximum-pool-size: 20              # 인스턴스 수 × 20 ≤ DB 허용 세션
      minimum-idle: 5
      connection-timeout: 3000
      max-lifetime: 1700000              # DB/방화벽 idle timeout 보다 짧게
  data:
    redis:
      host: redis-vip
      port: 6379
      password: ${REDIS_PASSWORD}
ongo:
  framework:
    crypto:
      key-ref: env:ONGO_CRYPTO_KEY       # CryptoKeyProvider 가 해석(사이트 구현)
logging:
  file:
    path: ${LOG_PATH}

env/common.env (권한 600, 소유 ongo)

SPRING_PROFILES_ACTIVE=prod
DB_PASSWORD=****
REDIS_PASSWORD=****
ONGO_CRYPTO_KEY=****
TZ=Asia/Seoul

env/inst1.env

INSTANCE=inst1
PORT=8081
MGMT_PORT=18081
JAVA_OPTS=-Xms2g -Xmx2g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/app/ongo-app/dumps/inst1 -Xlog:gc*:file=/app/ongo-app/logs/inst1/gc.log:time,uptime:filecount=10,filesize=20m -Dfile.encoding=UTF-8 -Duser.timezone=Asia/Seoul -Djava.io.tmpdir=/app/ongo-app/tmp -Djava.security.egd=file:/dev/./urandom

env/inst2.env 는 INSTANCE=inst2, PORT=8082, MGMT_PORT=18082, 덤프·로그 경로만 다르게.

A.5 JVM 옵션 가이드

A.6 systemd 유닛 — 방법 1: 템플릿 유닛(권장)

/etc/systemd/system/[email protected]

[Unit]
Description=Ongo App instance %i
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ongo
Group=ongo
EnvironmentFile=/app/ongo-app/env/common.env
EnvironmentFile=/app/ongo-app/env/%i.env
Environment=LOG_PATH=/app/ongo-app/logs/%i
WorkingDirectory=/app/ongo-app/current
ExecStart=/opt/java/jdk-21/bin/java $JAVA_OPTS \
  -Dserver.port=${PORT} -Dmanagement.server.port=${MGMT_PORT} \
  -jar /app/ongo-app/current/app.jar \
  --spring.config.additional-location=file:/app/ongo-app/config/
# SIGTERM(143) 은 정상 종료로 간주
SuccessExitStatus=143
KillSignal=SIGTERM
# graceful(30s) + 여유 → 40s 후 SIGKILL
TimeoutStopSec=45
TimeoutStartSec=180
Restart=on-failure
RestartSec=10
StartLimitIntervalSec=300
StartLimitBurst=3
LimitNOFILE=65536
# 보안 하드닝(사이트 정책에 맞게)
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ReadWritePaths=/app/ongo-app

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now ongo-app@inst1 ongo-app@inst2
systemctl status 'ongo-app@*'
journalctl -u ongo-app@inst1 -f

• WorkingDirectory 가 심볼릭 링크라도 systemd 는 기동 시점에 해석한다 → 링크 전환 후 반드시 restart.
• Boot2 installDist: ExecStart=/app/ongo-app/current/bin/<app> 로 바꾸고 JAVA_OPTS 는 env 로 그대로 전달(스크립트가 $JAVA_OPTS 를 읽음). 인자 --server.port=${PORT} 추가.

A.6b systemd 유닛 — 방법 2: 인스턴스별 개별 서비스 파일

템플릿을 쓰지 못하는 사이트(감사 정책상 유닛별 승인 등)는 파일을 나눈다. /etc/systemd/system/ongo-app-inst1.service

[Unit]
Description=Ongo App inst1
After=network-online.target
[Service]
User=ongo
EnvironmentFile=/app/ongo-app/env/common.env
EnvironmentFile=/app/ongo-app/env/inst1.env
Environment=LOG_PATH=/app/ongo-app/logs/inst1
WorkingDirectory=/app/ongo-app/current
ExecStart=/opt/java/jdk-21/bin/java $JAVA_OPTS -Dserver.port=8081 -Dmanagement.server.port=18081 -jar app.jar --spring.config.additional-location=file:/app/ongo-app/config/
SuccessExitStatus=143
TimeoutStopSec=45
Restart=on-failure
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target

ongo-app-inst2.service 는 이름·env·포트만 바꾼다. 묶음 제어용 타깃(선택):

# /etc/systemd/system/ongo-app.target
[Unit]
Description=Ongo App all instances
Wants=ongo-app-inst1.service ongo-app-inst2.service

systemd 가 없는 구형 OS(RHEL6 등)는 bin/start.sh(nohup java ... & echo $! > inst1.pid) / stop.sh(kill -TERM $(cat pid) 후 45s 대기, 남으면 kill -9) 쌍으로 대체한다. PID 파일 경로를 인스턴스별로 분리할 것.

A.7 앞단 — nginx

/etc/nginx/conf.d/ongo.conf

upstream ongo_was {
    least_conn;
    server 10.0.0.11:8081 max_fails=2 fail_timeout=10s;
    server 10.0.0.11:8082 max_fails=2 fail_timeout=10s;
    server 10.0.0.12:8081 max_fails=2 fail_timeout=10s;
    server 10.0.0.12:8082 max_fails=2 fail_timeout=10s;
    keepalive 64;
}
server {
    listen 443 ssl http2;
    server_name app.example.com;
    ssl_certificate     /etc/nginx/tls/app.crt;
    ssl_certificate_key /etc/nginx/tls/app.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    client_max_body_size 50m;            # = spring.servlet.multipart.max-request-size
    proxy_connect_timeout 3s;
    proxy_read_timeout 50s;              # §1.4 타임아웃 체인
    proxy_send_timeout 50s;

    location = /healthz { access_log off; return 200 'ok'; }   # L4 → nginx 헬스
    location /static/ { root /app/web; expires 7d; }           # 정적 리소스 직접 서빙
    location /actuator/ { deny all; }                           # 관리 엔드포인트 외부 차단
    location / {
        proxy_pass http://ongo_was;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Correlation-Id $request_id;        # 웹·WAS 로그 연결
        proxy_next_upstream error timeout http_502 http_503;  # 멱등 요청만 재시도 원하면 non_idempotent 미지정 유지
    }
}

• 레퍼런스: docker/demo-web/default.conf.template(정적 + /api 프록시). 데모 백엔드는 2026-10-30 부터 컨테이너 앞단 nginx 없이 NPM(리버스 프록시) → WAS 직결이다(아래 Docker 절).
• 오픈소스 nginx 는 능동 헬스체크가 없다(수동 max_fails 만). 롤링 중 무오류가 필요하면 배포 스크립트가 upstream 에서 down 처리 후 nginx -s reload 하거나, L4 의 능동 헬스체크(관리 포트 readiness)를 사용.
• 앱 쪽 server.forward-headers-strategy=framework + 신뢰 프록시 대역 제한(내부망만 접근 가능하도록 방화벽).

A.8 세션 — sticky vs SessionStore SPI

결론: sticky 는 공유 저장소 도입 전 임시로만 사용. 프레임 인증은 SessionStoreService 를 거치므로 sticky 만으로는 「다른 인스턴스에서 강제 로그아웃」·「중복 로그인 차단」이 동작하지 않는다.

A.9 롤링 재기동 순서(무중단)

sequenceDiagram
  participant D as deploy.sh
  participant LB as nginx/L4
  participant I as instN
  loop 서버 순서: was01 inst1 → was01 inst2 → was02 inst1 → was02 inst2
    D->>LB: instN 제외(down + reload / L4 disable)
    D->>D: drain 대기(15~30s, 진행 요청 소진)
    D->>I: systemctl stop (graceful 30s)
    D->>D: ln -sfn releases/new current
    D->>I: systemctl start
    loop 최대 120s
      D->>I: GET :MGMT/actuator/health/readiness
    end
    alt UP
      D->>LB: instN 재투입 → 스모크 1건
    else 실패
      D->>D: 즉시 롤백(previous 링크) 후 중단·알림
    end
  end

규칙 1. 한 번에 1개 인스턴스(전체의 25% 이하)만 내린다. 서버 2대면 서버를 번갈아가며가 아니라 「한 서버 내 인스턴스를 순서대로 → 다음 서버」로 해도 되지만, 첫 인스턴스는 카나리로 보고 5분 관찰 후 나머지 진행 권장. 2. 첫 인스턴스 실패 시 전체 중단(나머지는 구버전 그대로이므로 서비스 영향 없음). 3. DB 스키마 변경이 있으면 하위호환(확장 → 배포 → 축소): 신구 버전이 동시에 떠 있는 구간이 반드시 존재한다. 4. 배치 앱(ongo-framework-batch*)은 롤링 대상이 아니다. 배치 스케줄러(사이트 스케줄러/cron)가 jar 를 실행·종료하며, 실행 중 Job 이 없는 시간대에 jar 교체. 중복 실행 방지는 공유 JobRepository.

A.10 헬스·readiness 확인 스크립트 (bin/health.sh)

#!/usr/bin/env bash
set -euo pipefail
INST=${1:?instance}; source /app/ongo-app/env/$INST.env
URL="http://127.0.0.1:${MGMT_PORT}/actuator/health/readiness"
for i in $(seq 1 60); do
  if curl -fsS --max-time 2 "$URL" | grep -q '"status":"UP"'; then
    echo "[health] $INST UP (${i}x2s)"; exit 0
  fi
  sleep 2
done
echo "[health] $INST NOT READY after 120s" >&2
journalctl -u "ongo-app@$INST" -n 80 --no-pager >&2 || true
exit 1

A.11 로그·logrotate

• 앱 로그: logback 롤링(Spring Boot 기본 logging.logback.rollingpolicy.max-file-size=100MB, max-history=30, total-size-cap=10GB). 앱이 스스로 롤링하므로 logrotate 대상에서 제외(이중 롤링 시 파일 핸들 유실).
• logrotate 대상: GC 로그(JDK 8 처럼 자체 회전 미사용 시), nohup.out, nginx 로그, 기동 스크립트 출력. /etc/logrotate.d/ongo-app

/app/ongo-app/logs/*/console.out /app/ongo-app/logs/*/gc-jdk8.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    copytruncate        # 자바가 파일을 계속 열고 있으므로
    su ongo ongo
}

• 힙덤프(dumps/)는 수 GB 이므로 cron 으로 7일 경과분 삭제: find /app/ongo-app/dumps -type f -mtime +7 -delete.
• 구조화 로그는 StructuredLogService → LoggingBridgeService 로 ELK/수집기 병렬 전송(가이드 #logging). 수집 에이전트(Filebeat 등)는 logs/*/*.log 를 읽도록.

A.12 방화벽·포트 표

# firewalld 예 (was 서버)
sudo firewall-cmd --permanent --add-rich-rule='rule family=ipv4 source address=10.0.1.0/24 port port=8081-8084 protocol=tcp accept'
sudo firewall-cmd --permanent --add-rich-rule='rule family=ipv4 source address=10.0.9.10/32 port port=18081-18084 protocol=tcp accept'
sudo firewall-cmd --reload

A.13 배포 스크립트 (bin/deploy.sh, 요약)

#!/usr/bin/env bash
set -euo pipefail
SVC=ongo-app; BASE=/app/$SVC; ART=${1:?artifact.jar}; VER=${2:?version}
INSTANCES=(inst1 inst2)
REL=$BASE/releases/$VER
[[ -d $REL ]] && { echo "이미 존재하는 버전 $VER — 재배포는 링크 전환만"; } || {
  mkdir -p "$REL" && cp "$ART" "$REL/app.jar" && sha256sum "$REL/app.jar" > "$REL/app.jar.sha256"; }
PREV=$(readlink -f $BASE/current || true)
for i in "${INSTANCES[@]}"; do
  ./lb.sh out "$i"; sleep 20
  sudo systemctl stop "$SVC@$i"
  ln -sfn "$REL" $BASE/current
  sudo systemctl start "$SVC@$i"
  if ! ./health.sh "$i"; then
     echo "롤백: $PREV"; ln -sfn "$PREV" $BASE/current; sudo systemctl restart "$SVC@$i"; ./health.sh "$i"; ./lb.sh in "$i"; exit 1
  fi
  ./lb.sh in "$i"
done
[[ -n $PREV && $PREV != $REL ]] && ln -sfn "$PREV" $BASE/previous
ls -1dt $BASE/releases/* | tail -n +6 | xargs -r rm -rf     # 최근 5개 보관

주의: 모든 인스턴스가 같은 current 를 보므로, 롤링 도중 이미 전환된 링크로 다른 인스턴스가 재기동(장애 재시작)되면 새 버전으로 뜬다. 인스턴스별 독립 버전이 필요하면 current-inst1, current-inst2 로 링크를 분리하고 유닛의 경로를 current-%i 로 둔다(권장).

A.14 롤백

A.15 체크리스트(A)

• □ JDK 버전·경로 확정, java -version 출력 증빙
• □ 실행 계정 ongo, 디렉터리 권한(env 600), ulimit 65536
• □ application-prod.yml 외부화, 비밀값은 env/Vault, 데모 사용자 제거
• □ 인스턴스별 PORT/MGMT_PORT/로그/덤프 경로 분리
• □ actuator readiness/liveness, 관리 포트 외부 차단
• □ server.shutdown=graceful 30s < TimeoutStopSec 45s
• □ nginx upstream·타임아웃 체인·client_max_body_size = multipart 한도
• □ 멀티 인스턴스 SPI(세션·멱등·캐시) 공유 구현
• □ logback 롤링 + logrotate(비 logback 파일만) + 덤프 정리 cron
• □ 방화벽 표 기준 개방 확인(nc -zv)
• □ 롤링 리허설 1회(스테이징), 롤백 리허설 1회
• □ 배치 jar 교체 시간대·스케줄러 등록 확인

적용: 사이트 WAS 표준이 TmaxSoft JEUS 이고 웹서버가 WebToB 인 경우. 앱은 WAR 로 JEUS 도메인의 클러스터(관리 서버 N개)에 배포하고, WebToB 가 정적 리소스 서빙·JEUS 라우팅을 맡는다. ⚠️ JEUS·WebToB 의 버전별 서블릿/JDK 인증 조합, 설정 파일 엘리먼트명, CLI 문법은 버전마다 다르다 — 모두 「확인 필요」. 이 절은 판단 규칙과 「무엇을 벤더 매트릭스에서 확인해야 하는가」를 구체적으로 제시한다.

B.1 표준 토폴로지

flowchart LR
  U[사용자] --> L4[L4 VIP]
  L4 --> WB1[WebToB web01<br/>정적·라우팅]
  L4 --> WB2[WebToB web02]
  WB1 -- WJP/JSV 커넥터 --> MS1[JEUS MS01<br/>was01]
  WB1 --> MS2[JEUS MS02<br/>was01]
  WB1 --> MS3[JEUS MS03<br/>was02]
  WB1 --> MS4[JEUS MS04<br/>was02]
  WB2 --> MS1 & MS2 & MS3 & MS4
  DAS[JEUS DAS<br/>도메인 관리 서버] -. 배포·설정 .-> MS1 & MS2 & MS3 & MS4
  MS1 & MS2 & MS3 & MS4 --> DS[(JNDI DataSource → DB)]
  MS1 & MS2 & MS3 & MS4 --> R[(Redis/DB SessionStore)]

• JEUS 7 이후 계열은 도메인(DAS, Domain Administration Server) + 관리 서버(MS) + 클러스터 구조. JEUS 6 이하(컨테이너/엔진 구조)는 설정 모델이 달라 이 절의 용어와 1:1 대응되지 않는다(확인 필요).
• WebToB ↔ JEUS 연결은 WebToB 가 리스닝하고 JEUS 웹 엔진이 역으로 접속(registration) 하는 구조가 일반적이다 → 방화벽은 JEUS → WebToB JSV 포트 방향으로 연다(일반 리버스 프록시와 반대 방향, 확인 필요).

B.2 Boot 버전 결정 트리(핵심)

Spring Boot 버전은 WAS 의 서블릿 API 패키지(javax vs jakarta)·서블릿 스펙 버전·인증 JDK 세 가지로 결정된다. 사양 기준 사실: - Spring Boot 3.x / Spring Framework 6.x → Jakarta EE 10 기준, Servlet 6.0 필요, JDK 17+. jakarta.servlet.* 패키지. - Spring Boot 2.7.x / Spring 5.3.x → Java EE 8(javax.servlet.*), Servlet 3.1+ (4.0 권장), JDK 8 이상(상한은 2.7 릴리스 노트로 확인, 이 저장소 Boot2 라인은 8/11 기준). - Jakarta EE 9/9.1(Servlet 5.0, jakarta.*)만 지원하는 WAS 는 Boot3 도 Boot2 도 아님에 주의 — Boot3 는 Servlet 6.0 을 요구하고, Boot2 는 javax 를 쓴다. 이 경우 WAS 업그레이드 또는 [A]/하이브리드.

flowchart TD
  S([JEUS 버전 확인<br/>jeusadmin version / 릴리스 노트]) --> J{서블릿 패키지?}
  J -- jakarta.* --> V6{Servlet 6.0 이상<br/>Jakarta EE 10?}
  V6 -- 예 --> K17{운영 JDK 17+<br/>해당 JEUS 인증 JDK?}
  K17 -- 예 --> B3[Boot3 라인 3.5.x WAR<br/>-PongoJavaRelease=17/21]
  K17 -- 아니오 --> UPJ[JDK 업그레이드 협의<br/>불가 시 하이브리드]
  V6 -- 아니오(EE9/Servlet5) --> NO1[Boot3 불가·Boot2 불가<br/>→ JEUS 패치/업그레이드 또는 하이브리드]
  J -- javax.* --> V4{Servlet 4.0 / 3.1?}
  V4 -- 4.0 EE8 --> K8{JDK 8 또는 11?}
  K8 -- 예 --> B2[Boot2 라인 2.7.18 WAR<br/>ongo-framework-boot2]
  V4 -- 3.1 EE7 --> B2L[Boot2 라인 가능<br/>기능 제약 점검 B.2.2]
  V4 -- 3.0 이하 --> NO2[미지원<br/>WAS 업그레이드 또는 A/하이브리드]

B.2.1 벤더 매트릭스에서 확인할 항목(확인 필요 — 반드시 문서/회신으로 증빙)

B.2.2 Boot2 라인 + Servlet 3.1(EE7) 에서 점검할 제약

• Servlet 4.0 전용 API(PushBuilder, HttpServletMapping) 미사용 확인. 프레임 코어는 의존하지 않음.
• 멀티파트 처리: StandardServletMultipartResolver 동작 확인, 한도는 WebToB/JEUS/Spring 3곳 일치.
• JDK 8 에서 TLS1.2 기본 활성 여부(구형 8u 초기 빌드 확인 필요), 외부 HTTPS 아웃바운드 영향.

B.2.3 하이브리드 대안

「JEUS 필수」가 아닌 「웹서버 WebToB 필수」인 사이트라면: WebToB → (리버스 프록시 또는 WebToB 의 HTTP 프록시 기능, 확인 필요) → 실행형 jar([A]) 인스턴스. 사전 아키텍처 심의 필수.

B.3 WAR 패키징

build.gradle(업무 앱 모듈, Boot3 예)

plugins {
    id 'org.springframework.boot'
    id 'io.spring.dependency-management'
    id 'war'
}
dependencies {
    implementation project(':ongo-framework-core-web')      // 사이트가 사용하는 프레임 모듈
    providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'  // 내장 톰캣은 WAR 에서 제외
    compileOnly 'jakarta.servlet:jakarta.servlet-api'       // Boot2: javax.servlet:javax.servlet-api:4.0.1
}
bootWar {
    archiveFileName = 'ongo-app.war'
}
war { enabled = false }   // plain war 생성 방지(선택)

초기화 클래스

public class ServletInitializer extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return builder.sources(OngoApplication.class);
    }
}

• Embedded vs WAR: 같은 소스로 둘 다 만들 수 있다. bootWar 결과물은 java -jar 로도 실행 가능(내장 톰캣이 WEB-INF/lib-provided 에 들어감) → 개발·스테이징은 jar 처럼, 운영은 JEUS 에 배포. 단 JEUS 에서 lib-provided 는 로딩되지 않으므로 무해.
• Boot2 라인: 저장소 ongo-framework-boot2 는 installDist 패키징이므로, 사이트 앱 저장소에서 위 war 구성을 별도로 한다(BOM 은 ongo-framework-boot2/core-web/build.gradle 의 Boot 2.7.18 오버라이드를 그대로 참고). 루트 Boot3 플러그인과 섞지 말 것.
• WAR 에 넣으면 안 되는 것: 서블릿/JSP/EL API, JTA API, JEUS 가 제공하는 JDBC 드라이버(드라이버를 WAS 공용 lib 에 둘지 WAR 에 둘지 사이트 표준 확인 — JNDI 사용 시 보통 WAS 공용).

B.4 context path 와 배포 서술자

• context-root 결정 우선순위(일반): WAS 배포 설정(관리 콘솔/명령 옵션) > jeus-web-dd.xml 의 context-root > WAR 파일명. Spring 의 server.servlet.context-path 는 외부 WAS 배포 시 무시된다.
• src/main/webapp/WEB-INF/jeus-web-dd.xml (개념 예 — 엘리먼트명은 JEUS 버전별 확인 필요)

<jeus-web-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
    <context-path>/</context-path>
    <!-- 웹앱 클래스 우선 로딩: 이름·위치는 버전별 확인 필요 -->
    <webinf-first>true</webinf-first>
    <session-config>
        <timeout>30</timeout>          <!-- 프레임 세션은 SessionStore TTL 이 기준, 여기선 보조 -->
    </session-config>
</jeus-web-dd>

• context-root 를 / 가 아닌 /ongo 로 두면: WebToB URI 매핑, 프론트 API base URL, 쿠키 Path, 정적 리소스 경로, 프레임 인터셉터 제외 패턴(/actuator/** → /ongo/actuator/** 아님, 서블릿 경로 기준) 을 모두 점검.

B.5 클래스로더·공유 라이브러리 주의

B.6 DataSource — JNDI vs Boot 자동구성

# application-prod.yml (JNDI)
spring:
  datasource:
    jndi-name: jdbc/ongoDS         # JEUS 에 등록한 export-name (java:comp/env 접두 여부 확인 필요)
  jta:
    enabled: false                 # XA 불필요 시

• JNDI 사용 시 DataSourceAutoConfiguration 의 Hikari 는 생성되지 않는다. MyBatis(가이드 #mybatis)는 이 DataSource 를 그대로 사용.
• 풀 크기 산정: MS 수 × 풀 max ≤ DB 최대 세션 × 0.8.
• 트랜잭션: 단일 DB 는 DataSourceTransactionManager(가이드 #tx), 2PC 필요 시에만 JEUS TM(JTA).

B.7 WebToB → JEUS 연계 패턴

WebToB http.m(개념 예 — 섹션·키 문법은 버전별 확인 필요). 수정 후 wscfl -i http.m 로 컴파일(wsconfig), wsboot/wsdown 으로 기동/정지.

*DOMAIN
ongo_web

*NODE
web01   WEBTOBDIR="/app/webtob", SHMKEY=54000,
        DOCROOT="/app/web/static",
        PORT="80", HTH=2,
        JSVPORT=9900,                 # JEUS 웹엔진이 접속해 오는 포트
        LOGGING="log1", ERRORLOG="log2"

*SVRGROUP
htmlg   SVRTYPE=HTML
jsvg    SVRTYPE=JSV

*SERVER
MS01    SVGNAME=jsvg, MinProc=10, MaxProc=20
MS02    SVGNAME=jsvg, MinProc=10, MaxProc=20
MS03    SVGNAME=jsvg, MinProc=10, MaxProc=20
MS04    SVGNAME=jsvg, MinProc=10, MaxProc=20

*URI
api     Uri="/api/",      SvrType=JSV          # /api/** → JEUS (서버 그룹 내 분산)
act     Uri="/actuator/", SvrType=HTML, Deny   # 관리 엔드포인트 외부 차단(차단 문법 확인 필요)

*EXT
html    MimeType="text/html", SvrType=HTML
js      MimeType="application/javascript", SvrType=HTML
css     MimeType="text/css", SvrType=HTML

JEUS 측(각 MS 웹 엔진 Web Connection, 개념):

웹 엔진 > Web Connections > WebToB Connector 추가
  name               : webtob1
  server-address     : 10.0.0.21         # WebToB 서버
  port               : 9900              # = JSVPORT
  registration-id    : MS01              # = WebToB *SERVER 이름 (MS 별로 다르게)
  thread-pool min/max: 10 / 20           # = MinProc/MaxProc 와 맞춤
  (WebToB 2대면 커넥터 2개: webtob1, webtob2)

연계 패턴 비교 | 패턴 | 구성 | 사용 시점 | |---|---|---| | ① 전량 JEUS | Uri="/" → JSV | 정적 리소스가 WAR 안에 있을 때(비권장, WAS 부하) | | ② 정적 WebToB + API JEUS | *EXT 정적 + Uri="/api/" JSV | 표준. Nuxt 분리 FE 빌드물(docker/demo-web 참고) 은 DOCROOT 에 배포 | | ③ 앱별 서버 그룹 | jsvg_a, jsvg_b 로 URI 분기 | 한 WebToB 로 여러 업무 앱 서비스 | | ④ WebToB → 실행형 jar | HTTP 프록시(확인 필요) | 하이브리드(B.2.3) | - 커넥터 수·MaxProc 는 JEUS 요청 스레드 수와 맞춘다. WebToB MaxProc 합 > JEUS 스레드면 대기열이 WebToB 에 쌓여 타임아웃. - 클라이언트 IP: WebToB 가 X-Forwarded-For 를 넘기는지(또는 JEUS 커넥터가 원 IP 를 보존하는지) 확인 필요. 프레임 감사 로그·IP 제한에 영향.

B.8 세션·sticky

• WebToB/JEUS 는 세션 라우팅(세션 ID 에 서버 식별자 부여) 기반 sticky 와 JEUS 세션 클러스터링을 지원한다(방식·설정은 버전별 확인 필요).
• 프레임 인증 세션은 HttpSession 이 아니라 SessionStoreService 를 사용하므로 JEUS 세션 클러스터링만으로는 프레임 로그인이 공유되지 않는다 → Redis/DB SessionStoreService 교체(§1.5). 교체 후에는 sticky·세션 클러스터링을 꺼도 된다(불필요한 복제 부하 제거).
• 쿠키: context-root 와 쿠키 Path, Secure/SameSite 속성은 WebToB TLS 종료 여부에 맞춰 설정.

B.9 MS JVM 옵션(JEUS 서버 설정의 JVM 옵션 항목)

-Xms2g -Xmx2g -XX:+UseG1GC -XX:MaxMetaspaceSize=512m
-Dspring.profiles.active=prod
-Dspring.config.additional-location=file:/app/ongo/config/
-Dlogging.file.path=/app/jeus/domains/<domain>/servers/MS01/logs/app
-Dfile.encoding=UTF-8 -Duser.timezone=Asia/Seoul
-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/app/jeus/dumps/MS01
-Xlog:gc*:file=/app/jeus/domains/<domain>/servers/MS01/logs/gc.log:time:filecount=10,filesize=20m   (JDK 8 은 -Xloggc)

• 비밀값은 JVM 옵션에 평문으로 넣지 않는다(관리 콘솔·ps 에 노출). JNDI·JEUS 암호화 프로퍼티·OS 환경변수 사용.

B.10 로깅 — 도메인 로그와 앱 로그 분리

B.11 배포·graceful undeploy 절차(클러스터 롤링)

1. 아티팩트 반입: ongo-app-<ver>.war + sha256 검증 → DAS 배포 저장소에 업로드.
2. MS01 을 WebToB 분산에서 제외(WebToB 관리 명령으로 해당 서버 down/suspend, 또는 JEUS 서버 suspend — 신규 요청 차단·진행 요청 완료, 명령 문법 확인 필요).
3. 진행 요청 소진 대기(20~30s, JEUS 스레드 모니터에서 active 0 확인).
4. MS01 정지 → 애플리케이션 교체(undeploy → deploy, 또는 redeploy 대상 MS 지정) → MS01 기동. 핫 리디플로이(서버 무정지 교체)는 운영 지양 — 클래스로더 누수.
5. 헬스: curl -fs http://was01:<MS01 http 리스너>/actuator/health/readiness (관리 포트 분리 시 해당 포트). WebToB 경유 스모크 curl -fs https://app/api/....
6. WebToB 재투입 → 5분 관찰 → MS02… 반복.
7. 실패 시: 해당 MS 에 이전 WAR 재배포(DAS 에 직전 버전 보관 필수) → 기동 → 재투입, 배포 중단.

jeusadmin 사용 예(개념 — 명령·옵션명은 버전별 확인 필요)

jeusadmin -host das01:9736 -u administrator -f /app/secure/jeus.pw <<'CMD'
suspend-server MS01
stop-server MS01
undeploy ongo-app -servers MS01
install-application /deploy/ongo-app-1.4.0.war -id ongo-app
deploy ongo-app -servers MS01
start-server MS01
resume-server MS01
CMD

• 비밀번호는 -p 인자로 넣지 말고 권한 600 파일/벤더 암호화 방식 사용.

B.12 자주 나는 장애(Failure modes)

B.13 체크리스트(B)

• □ B.2.1 매트릭스 12개 항목 증빙 완료 → 라인(Boot2/Boot3)·JDK 확정
• □ WAR: 서블릿/EL/JTA API 미포함, 내장 톰캣 providedRuntime, ServletInitializer
• □ jeus-web-dd.xml context-root·클래스 우선 로딩
• □ 공용 lib 충돌 기동 검증(-Xlog:class+load 1회)
• □ JNDI 이름·풀 크기(MS 수 × max ≤ DB 세션 80%)
• □ WebToB http.m URI/EXT, JSVPORT, MinProc/MaxProc = JEUS 스레드
• □ JEUS 커넥터 registration-id = WebToB SERVER 이름, 방화벽 JEUS→WebToB
• □ 타임아웃 WebToB > JEUS > 앱 아웃바운드 > DB
• □ multipart 한도 3곳 일치, 문자셋 UTF-8
• □ SessionStore 공유 구현, JEUS 세션 클러스터링 필요성 재검토
• □ 앱 로그 경로 MS 별 분리, 수집 대상 등록
• □ 롤링 절차(suspend→stop→deploy→start→health→resume) 리허설, 이전 WAR 보관
• □ devtools/openapi 운영 제외, /actuator 외부 차단

적용: 서버마다 데몬형 에이전트가 상주하고, 중앙의 자원관리·빌드/배포 관리 시스템이 에이전트에게 쉘 명령을 내리면 각 서버가 그 쉘을 실행해 빌드·배포를 수행하는 구조. A 또는 B 와 조합된다. 중앙 시스템이 결재·이력·스케줄을, 서버 쉘이 실제 작업을 담당한다.

C.1 흐름

sequenceDiagram
  autonumber
  participant Dev as 개발자
  participant CM as 중앙 관리 시스템
  participant BA as 빌드 서버 에이전트
  participant REPO as 아티팩트 저장소(Nexus/NAS)
  participant WA as WAS 서버 에이전트(N대)
  Dev->>CM: 배포 요청(브랜치/태그, 대상 환경)
  CM->>CM: 결재/승인
  CM->>BA: build.sh <tag> 실행 명령
  BA->>BA: fetch → test → package → sha256 → BUILD-INFO
  BA->>REPO: 아티팩트 업로드(불변 버전)
  BA-->>CM: exit 0 + 로그 + 버전
  loop 대상 서버·인스턴스 순차
    CM->>WA: deploy.sh <svc> <ver> <inst>
    WA->>REPO: 다운로드 + sha256 검증
    WA->>WA: lb_out → stop → switch → start → health
    alt health 실패
      WA->>WA: rollback.sh
      WA-->>CM: exit 20 (중단)
    else 성공
      WA-->>CM: exit 0
    end
  end
  CM-->>Dev: 결과 통지·이력 저장

C.2 스크립트 계약(중앙 시스템과의 인터페이스)

/etc/sudoers.d/ongodeploy

ongodeploy ALL=(root) NOPASSWD: /usr/bin/systemctl start ongo-app@*, /usr/bin/systemctl stop ongo-app@*, /usr/bin/systemctl restart ongo-app@*, /usr/bin/systemctl status ongo-app@*

C.3 공통 라이브러리 (bin/lib.sh)

#!/usr/bin/env bash
set -Eeuo pipefail
export TZ=Asia/Seoul
LOG_DIR=${LOG_DIR:-/app/${SVC:-ongo-app}/logs/deploy}; mkdir -p "$LOG_DIR"
LOG_FILE="$LOG_DIR/$(date +%Y%m%d-%H%M%S)-${STAGE:-job}.log"
log(){ printf '[%s][%s][%s] %s\n' "$(date '+%F %T KST')" "${STAGE:-?}" "$1" "$2" | tee -a "$LOG_FILE"; }
die(){ log ERROR "$2"; echo "RESULT=FAIL CODE=$1 VERSION=${VER:-?}"; exit "$1"; }
trap 'log ERROR "line $LINENO: $BASH_COMMAND"' ERR
with_lock(){ exec 9>"/app/$SVC/.deploy.lock"; flock -w 60 9 || die 30 "다른 배포 진행 중"; }

C.4 단계별 샘플 쉘

① fetch + build (build.sh, 빌드 서버)

#!/usr/bin/env bash
STAGE=build; source "$(dirname "$0")/lib.sh"
SVC=${1:?}; REF=${2:?git tag/sha}; MODULE=${3:?gradle module}; JDK=${4:-17}
WS=/build/ws/$SVC; mkdir -p "$WS"
# fetch — 태그/sha 고정 빌드(브랜치 HEAD 빌드 금지)
if [[ ! -d $WS/.git ]]; then git clone --no-tags "$GIT_URL" "$WS"; fi
cd "$WS" && git fetch --tags --force origin && git checkout --force "$REF" && git clean -fdx
SHA=$(git rev-parse --short=12 HEAD); VER="$(date +%Y%m%d%H%M)-$SHA"
# build — 사내 Gradle 미러/오프라인 캐시 사용(폐쇄망)
export GRADLE_USER_HOME=/build/gradle-home
timeout 1200 ./gradlew --no-daemon -PongoJavaRelease="$JDK" ":$MODULE:test" || die 11 "테스트 실패"
timeout 900  ./gradlew --no-daemon -PongoJavaRelease="$JDK" ":$MODULE:bootJar" -x test || die 10 "빌드 실패"
JAR=$(ls "$MODULE"/build/libs/*.jar | grep -v -- '-plain.jar' | head -1)
OUT=/build/out/$SVC/$VER; mkdir -p "$OUT"; cp "$JAR" "$OUT/app.jar"
( cd "$OUT" && sha256sum app.jar > app.jar.sha256 )
cat > "$OUT/BUILD-INFO" <<INFO
svc=$SVC
version=$VER
git.ref=$REF
git.sha=$(git rev-parse HEAD)
built.at=$(date '+%F %T KST')
jdk=$(java -version 2>&1 | head -1)
INFO
# 업로드 (Nexus raw 예) — 자격증명은 에이전트 계정의 ~/.netrc(600) 또는 중앙 시스템이 주입한 env
curl -fsS --netrc -T "$OUT/app.jar"        "$NEXUS/repository/ongo-raw/$SVC/$VER/app.jar"
curl -fsS --netrc -T "$OUT/app.jar.sha256" "$NEXUS/repository/ongo-raw/$SVC/$VER/app.jar.sha256"
curl -fsS --netrc -T "$OUT/BUILD-INFO"     "$NEXUS/repository/ongo-raw/$SVC/$VER/BUILD-INFO"
log INFO "built $VER"; echo "RESULT=OK VERSION=$VER"

Boot2 라인은 :$MODULE:installDist 후 build/install/<app> 을 tar.gz 로 묶어 업로드. JEUS([B])는 bootWar → app.war.

② stop / copy / start / health (deploy.sh, WAS 서버)

#!/usr/bin/env bash
STAGE=deploy; source "$(dirname "$0")/lib.sh"
SVC=${1:?}; VER=${2:?}; INST=${3:?}; BASE=/app/$SVC; REL=$BASE/releases/$VER
with_lock
# copy(다운로드 + 검증)
if [[ ! -f $REL/app.jar ]]; then
  mkdir -p "$REL.tmp"
  for f in app.jar app.jar.sha256 BUILD-INFO; do
    curl -fsS --netrc -o "$REL.tmp/$f" "$NEXUS/repository/ongo-raw/$SVC/$VER/$f" || die 12 "다운로드 실패 $f"
  done
  ( cd "$REL.tmp" && sha256sum -c app.jar.sha256 ) || die 12 "sha256 불일치"
  mv "$REL.tmp" "$REL"
fi
CUR=$(readlink -f "$BASE/current-$INST" || true)
[[ $CUR == "$REL" ]] && { "$(dirname "$0")/health.sh" "$INST" && { echo "RESULT=OK VERSION=$VER (already)"; exit 0; }; }
# stop
"$(dirname "$0")/lb.sh" out "$INST"; sleep "${DRAIN_SEC:-20}"
sudo systemctl stop "$SVC@$INST"
# switch
[[ -n $CUR ]] && ln -sfn "$CUR" "$BASE/previous-$INST"
ln -sfn "$REL" "$BASE/current-$INST"
# start + health
sudo systemctl start "$SVC@$INST"
if ! "$(dirname "$0")/health.sh" "$INST"; then
  log ERROR "health 실패 → 롤백"
  "$(dirname "$0")/rollback.sh" "$SVC" "$INST" || die 21 "롤백 실패(긴급)"
  die 20 "헬스 실패, 롤백 완료"
fi
"$(dirname "$0")/lb.sh" in "$INST"
log INFO "deployed $VER to $INST"; echo "RESULT=OK VERSION=$VER"

③ rollback (rollback.sh)

#!/usr/bin/env bash
STAGE=rollback; source "$(dirname "$0")/lib.sh"
SVC=${1:?}; INST=${2:?}; BASE=/app/$SVC
PREV=$(readlink -f "$BASE/previous-$INST") || die 21 "previous 없음"
sudo systemctl stop "$SVC@$INST" || true
ln -sfn "$PREV" "$BASE/current-$INST"
sudo systemctl start "$SVC@$INST"
"$(dirname "$0")/health.sh" "$INST" || die 21 "롤백 후에도 비정상"
"$(dirname "$0")/lb.sh" in "$INST"
echo "RESULT=OK VERSION=$(basename "$PREV") (rolled back)"

④ lb.sh — nginx upstream 토글 예(L4 는 장비 API/운영 요청으로 대체)

#!/usr/bin/env bash
# lb.sh out|in inst1  — web 서버에 ssh 하거나 중앙 시스템이 web 에이전트로 별도 명령
ACTION=$1; INST=$2; HOSTPORT="$(hostname -i):$(grep ^PORT= /app/ongo-app/env/$INST.env | cut -d= -f2)"
ssh web01 "sudo /app/nginx/bin/upstream-toggle.sh $ACTION $HOSTPORT && sudo nginx -s reload"

• systemd 유닛은 §A.6 템플릿에서 WorkingDirectory/-jar 경로를 current-%i 로 바꿔 인스턴스별 독립 링크를 쓴다.
• [B] JEUS 대상이면 deploy.sh 의 stop/switch/start 를 §B.11 jeusadmin 시퀀스로 교체하고, 아티팩트를 DAS 서버 에이전트에서만 다룬다.

C.5 아티팩트 보관(retention)

# cleanup.sh — 현재/이전 링크가 가리키는 릴리스는 절대 삭제하지 않는다
KEEP=5; BASE=/app/$1
PROTECT=$(for l in "$BASE"/current-* "$BASE"/previous-*; do readlink -f "$l"; done | sort -u)
ls -1dt "$BASE"/releases/* | tail -n +$((KEEP+1)) | grep -vxF "$PROTECT" | xargs -r rm -rf
find "$BASE/logs/deploy" -type f -mtime +90 -delete

C.6 롤백 정책

• 단일 인스턴스 실패: deploy.sh 가 자동 롤백(exit 20) → 중앙 시스템은 후속 인스턴스 중단.
• 전체 반영 후 장애: 중앙 시스템에서 「직전 버전으로 배포」 작업을 새로 실행(= 이전 VER 로 deploy.sh 롤링). 롤백도 결재/이력 대상.
• exit 21(롤백 실패)은 자동화 중단 + 담당자 호출(서버 접속해 수동 복구: ls releases, 정상 버전으로 링크 고정, 기동 로그 확인).

C.7 비밀값 처리

• 스크립트·중앙 시스템 작업 정의에 비밀번호 평문 금지. 중앙 시스템이 비밀 변수 기능을 제공하면 마스킹된 env 로 주입, 아니면 서버의 env/common.env(600) 를 서버 담당자가 직접 관리.
• 저장소 접근은 읽기 전용 배포 토큰(~/.netrc 600, 에이전트 계정 소유). Git 은 deploy key(읽기 전용).
• set -x 금지(비밀값이 로그로 회신됨). 디버그가 필요하면 log 함수로 키 이름만 출력.
• 중앙 회신 로그·서버 로그에 토큰/카드번호가 찍히지 않는지 마스킹(프레임 MaskingService, 가이드 #security) 점검.

C.8 체크리스트(C)

• □ 에이전트 실행 계정·sudo 허용 명령 최소화
• □ 종료코드 계약을 중앙 시스템 단계 판정 규칙에 등록
• □ 태그/sha 고정 빌드, 아티팩트 sha256 검증
• □ 인스턴스별 current-*/previous-* 링크, cleanup 보호
• □ flock 직렬화, 단계별 timeout < 중앙 타임아웃
• □ 비밀값 주입 경로 확정, set -x 미사용
• □ 롤백 실패(21) 시 호출 체계

C.9 삼카 부록 — ARM + oden

• 삼카 On-premise 빌드/배포는 자원관리·빌드/배포 관리 시스템 ARM 에서 진행한다. 각 서버에는 데몬형 솔루션 oden 이 상주하고, ARM 이 oden 으로 쉘 명령을 내리면 해당 서버가 쉘을 수행하며 빌드/배포를 처리한다.
• 매핑: 중앙 관리 시스템 = ARM, 서버 에이전트 = oden. §C.4 의 build.sh(빌드 서버 oden) / deploy.sh·rollback.sh(WAS 서버 oden) 를 ARM 작업 단계로 등록하고, §C.2 종료코드로 단계 성공/실패를 판정한다. 마지막 줄 RESULT=... 를 ARM 결과 메시지로 사용.
• 권장 ARM 작업 구성: ①빌드(빌드 서버) → ②결재 → ③was01 inst1 배포(카나리) → ④관찰/확인 → ⑤나머지 인스턴스 순차 → ⑥결과 통지.
• 확인 필요(ARM/oden 운영팀): oden 실행 계정·sudo 범위, 기본 작업 디렉터리, 환경변수/비밀 변수 전달 방식, 단계 타임아웃, 표준출력 회신 크기 한도, 아티팩트 저장 위치(ARM 자체 저장소 여부), 결재 단계 위치, 동시 실행 제어 기능 유무.
• 삼카 표준전문 채널 설정(ongo.framework.samsung-card.*)·EUC-KR charset 은 서버별 외부 yml(config/application-prod.yml)로 관리(가이드 #samsungcard).

적용: 컨테이너 플랫폼(Kubernetes/OpenShift/관리형 K8s 또는 Docker 호스트)에 이미지로 배포. CI 도구(Jenkins·GitHub Actions·GitLab CI 등)는 무엇이든 단계는 같다.

D.1 레퍼런스 Dockerfile 이해 (docker/app/Dockerfile)

• 빌드 컨텍스트 = docker/app, 소스 = 추가 컨텍스트 src(--build-context src=<repo> / compose additional_contexts). ARG MODULE(예 ongo-framework-generic-demo, ongo-framework-sc-demo, 배치 데모), ARG RUNTIME_JDK(17/21), ARG BASE_REGISTRY(사내 미러).
• 런타임이 JDK 인 이유: 데모의 devtools 동적 VO 컴파일(ToolProvider.getSystemJavaCompiler()). 운영 앱은 devtools 미포함이므로 JRE 로 바꾼다.
• Boot2: docker/app-boot2/Dockerfile(installDist, JDK 8/11). 백엔드 데모는 WAS 전용(앞단 도커 nginx docker/web 2026-10-30 폐지 — 이미지 빌드 1개 감소, TLS·Host 는 Cloudflare+NPM 이 담당, NPM → WAS AA01N 직결, 스모크 GET /api/runtime). 분리 FE: docker/demo-web(Nuxt, devfw-web :12003 → /api 12012) · docker/demo-web-custom(같은 빌드, devfw-web-custom :12004 → /api 12014). 데모별 compose: docker/{generic-demo,sc-demo,sc-custom-demo,boot2-*,boot3-j17-*}/compose.yaml. sc-custom-demo(APP ongo-sc-custom-demo, AA12 N4 WAS 12014, devfw21-sc-custom.ongosoft.com) = sc-demo 를 custom 프로필로 띄운 별도 참조 케이스(기본 ongo-sc-demo 그대로). FE 도 사이트로 분리 — devfw-web 은 sc, devfw-web-custom 은 sc-custom 으로 /api/** 전체를 보낸다.

D.2 운영용 멀티스테이지 Dockerfile 패턴

패턴 1 — 소스부터 빌드(자체 완결, 레퍼런스와 동일 구조 + 운영 하드닝)

# syntax=docker/dockerfile:1.7
ARG BASE_REGISTRY=docker.io
ARG RUNTIME_JDK=21
FROM ${BASE_REGISTRY}/library/eclipse-temurin:21-jdk AS build
ARG MODULE
ARG RUNTIME_JDK
WORKDIR /src
# 의존성 캐시 레이어: 빌드 스크립트만 먼저 복사
COPY --from=src gradlew settings.gradle build.gradle gradle.properties ./
COPY --from=src gradle ./gradle
RUN --mount=type=cache,target=/root/.gradle ./gradlew --no-daemon dependencies > /dev/null || true
COPY --from=src . .
RUN --mount=type=cache,target=/root/.gradle \
    ./gradlew --no-daemon --console=plain ":${MODULE}:bootJar" -x test -PongoJavaRelease=${RUNTIME_JDK} \
 && cp "$(ls ${MODULE}/build/libs/*.jar | grep -v -- '-plain' | head -1)" /app.jar \
 && mkdir /layers && cd /layers && java -Djarmode=tools -jar /app.jar extract --layers --launcher --destination .
#   Boot 3.3 미만: java -Djarmode=layertools -jar /app.jar extract

FROM ${BASE_REGISTRY}/library/eclipse-temurin:${RUNTIME_JDK}-jre
RUN groupadd -r -g 10001 ongo && useradd -r -u 10001 -g ongo ongo
WORKDIR /app
COPY --from=build /layers/dependencies/ ./
COPY --from=build /layers/spring-boot-loader/ ./
COPY --from=build /layers/snapshot-dependencies/ ./
COPY --from=build /layers/application/ ./
USER 10001
ENV JAVA_OPTS="-XX:MaxRAMPercentage=75 -XX:+ExitOnOutOfMemoryError -Dfile.encoding=UTF-8 -Duser.timezone=Asia/Seoul" \
    SPRING_PROFILES_ACTIVE=prod
EXPOSE 8080 18080
# Docker 단독 실행용(K8s 는 probe 사용, HEALTHCHECK 무시됨)
HEALTHCHECK --interval=15s --timeout=3s --start-period=60s --retries=4 \
  CMD bash -c 'exec 3<>/dev/tcp/127.0.0.1/18080 && printf "GET /actuator/health/readiness HTTP/1.0\r\n\r\n" >&3 && grep -q UP <&3'
ENTRYPOINT ["sh","-c","exec java $JAVA_OPTS org.springframework.boot.loader.launch.JarLauncher \"$@\"","--"]
#   Boot 3.2 미만/Boot2: org.springframework.boot.loader.JarLauncher

패턴 2 — CI 가 jar 를 만들고 Dockerfile 은 런타임만(Kaniko/Buildah·캐시 단순)

ARG BASE_REGISTRY=docker.io
ARG RUNTIME_JDK=21
FROM ${BASE_REGISTRY}/library/eclipse-temurin:${RUNTIME_JDK}-jre
RUN groupadd -r -g 10001 ongo && useradd -r -u 10001 -g ongo ongo
COPY build/app.jar /app/app.jar
USER 10001
ENV JAVA_OPTS="-XX:MaxRAMPercentage=75 -XX:+ExitOnOutOfMemoryError -Dfile.encoding=UTF-8"
ENTRYPOINT ["sh","-c","exec java $JAVA_OPTS -jar /app/app.jar \"$@\"","--"]

Boot2 이미지: docker/app-boot2/Dockerfile 처럼 installDist 결과(bin/, lib/)를 복사하고 ENTRYPOINT ["/app/bin/<app>"], 런타임 eclipse-temurin:8-jre 또는 11-jre. JDK 8 은 컨테이너 메모리 인식이 8u191+ 에서 기본 활성 — 그 이전이면 -XX:+UseContainerSupport 확인 필요.

D.3 이미지 규칙

• 태그: 불변 <git-sha12>(+ 선택적으로 <semver>). 운영 매니페스트는 태그 대신 digest(@sha256:...) 고정 권장. latest 금지.
• 비루트 UID(10001), 읽기 전용 루트 FS 가능하도록 쓰기 경로는 /tmp 볼륨(emptyDir)만.
• 베이스 이미지는 사내 미러(BASE_REGISTRY)에서만, 정기 재빌드(OS CVE 패치)와 스캔(Trivy/Grype) 게이트(Critical 0).
• .dockerignore: **/build, .git, **/node_modules, *.env.

D.4 환경변수·시크릿

D.5 compose vs Kubernetes

D.6 CI 공통 단계

flowchart LR
  A[checkout] --> B[test<br/>gradlew test]
  B --> C[SAST/SCA<br/>의존성 취약점]
  C --> D[build image<br/>tag=sha]
  D --> E[image scan<br/>Critical 0]
  E --> F[push registry]
  F --> G[deploy dev<br/>매니페스트 갱신]
  G --> H[smoke/health]
  H --> I{승인}
  I --> J[promote stg → prod<br/>같은 digest]

원칙: 한 번 빌드한 이미지(같은 digest)를 환경만 바꿔 승격한다. 환경별 재빌드 금지.

D.7 Jenkins (Declarative) 스케치

pipeline {
  agent { kubernetes { yamlFile 'ci/jenkins-pod.yaml' } }   // jdk + buildkit/kaniko 컨테이너
  options { timestamps(); disableConcurrentBuilds(); timeout(time: 40, unit: 'MINUTES') }
  parameters { choice(name: 'MODULE', choices: ['ongo-framework-generic-demo','my-biz-app'], description: '빌드 모듈') }
  environment {
    REG = 'registry.example.com/ongo'
    SVC = 'my-biz-app'
    TAG = "${env.GIT_COMMIT.take(12)}"
  }
  stages {
    stage('Test') { steps { container('jdk') { sh './gradlew --no-daemon test' } }
      post { always { junit '**/build/test-results/test/*.xml' } } }
    stage('Scan deps') { steps { container('jdk') { sh './gradlew --no-daemon dependencyCheckAnalyze || true' } } }
    stage('Image') { steps { container('buildkit') {
      withCredentials([usernamePassword(credentialsId: 'registry', usernameVariable: 'U', passwordVariable: 'P')]) {
        sh '''
          buildctl build --frontend dockerfile.v0 --local context=docker/app --local dockerfile=docker/app \
            --local src=. --opt context:src=local:src --opt build-arg:MODULE=$MODULE \
            --output type=image,name=$REG/$SVC:$TAG,push=true
        '''
      } } } }
    stage('Image scan') { steps { sh 'trivy image --exit-code 1 --severity CRITICAL $REG/$SVC:$TAG' } }
    stage('Deploy dev') { steps { sh './ci/bump-image.sh dev $REG/$SVC:$TAG' } }   // GitOps 커밋 또는 kubectl set image
    stage('Smoke dev')  { steps { sh './ci/smoke.sh https://dev.example.com' } }
    stage('Approve prod') { when { branch 'main' } steps { timeout(time: 1, unit: 'DAYS') { input message: 'prod 반영 승인?', submitter: 'release-approvers' } } }
    stage('Deploy prod') { when { branch 'main' } steps { sh './ci/bump-image.sh prod $REG/$SVC:$TAG' } }
  }
  post { failure { echo '실패 알림(메신저/메일 연동)' } }
}

D.8 GitHub Actions 스케치

name: ci
on:
  push: { branches: [develop, main] }
  pull_request:
permissions: { contents: read, packages: write, id-token: write }
concurrency: { group: ci-${{ github.ref }}, cancel-in-progress: true }
env: { IMAGE: ghcr.io/${{ github.repository_owner }}/my-biz-app, MODULE: ongo-framework-generic-demo }
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with: { distribution: temurin, java-version: '21', cache: gradle }
      - run: ./gradlew --no-daemon test
  image:
    needs: test
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    outputs: { digest: ${{ steps.push.outputs.digest }} }
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with: { registry: ghcr.io, username: ${{ github.actor }}, password: ${{ secrets.GITHUB_TOKEN }} }
      - id: push
        uses: docker/build-push-action@v6
        with:
          context: docker/app
          file: docker/app/Dockerfile
          build-contexts: src=.
          build-args: MODULE=${{ env.MODULE }}
          tags: ${{ env.IMAGE }}:${{ github.sha }}
          push: true
          cache-from: type=gha
          cache-to: type=gha,mode=max
      - uses: aquasecurity/[email protected]
        with: { image-ref: '${{ env.IMAGE }}:${{ github.sha }}', severity: CRITICAL, exit-code: '1' }
  deploy-dev:
    needs: image
    runs-on: ubuntu-latest
    environment: dev
    steps: [ { uses: actions/checkout@v4 }, { run: './ci/bump-image.sh dev ${{ env.IMAGE }}@${{ needs.image.outputs.digest }}' } ]
  deploy-prod:
    needs: [image, deploy-dev]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: prod          # Environment protection rule = 승인자 지정
    steps: [ { uses: actions/checkout@v4 }, { run: './ci/bump-image.sh prod ${{ env.IMAGE }}@${{ needs.image.outputs.digest }}' } ]

D.9 GitLab CI 스케치

stages: [test, image, scan, deploy-dev, deploy-prod]
variables: { MODULE: ongo-framework-generic-demo, IMAGE: $CI_REGISTRY_IMAGE }
default: { interruptible: true }
test:
  stage: test
  image: eclipse-temurin:21-jdk
  cache: { key: gradle, paths: [.gradle/caches] }
  variables: { GRADLE_USER_HOME: $CI_PROJECT_DIR/.gradle }
  script: [ "./gradlew --no-daemon test" ]
  artifacts: { reports: { junit: "**/build/test-results/test/*.xml" } }
image:
  stage: image
  image: docker:27
  services: [docker:27-dind]
  script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY
    - docker buildx create --use
    - docker buildx build -f docker/app/Dockerfile --build-context src=. --build-arg MODULE=$MODULE -t $IMAGE:$CI_COMMIT_SHORT_SHA --push docker/app
  rules: [ { if: '$CI_COMMIT_BRANCH == "develop" || $CI_COMMIT_BRANCH == "main"' } ]
scan:
  stage: scan
  image: { name: aquasec/trivy:latest, entrypoint: [""] }
  script: [ "trivy image --exit-code 1 --severity CRITICAL $IMAGE:$CI_COMMIT_SHORT_SHA" ]
deploy_dev:
  stage: deploy-dev
  environment: { name: dev }
  script: [ "./ci/bump-image.sh dev $IMAGE:$CI_COMMIT_SHORT_SHA" ]
deploy_prod:
  stage: deploy-prod
  environment: { name: prod }
  when: manual                      # Protected environment 로 승인자 제한
  rules: [ { if: '$CI_COMMIT_BRANCH == "main"' } ]
  script: [ "./ci/bump-image.sh prod $IMAGE:$CI_COMMIT_SHORT_SHA" ]

ci/bump-image.sh (GitOps 저장소 태그 갱신 예)

#!/usr/bin/env bash
set -euo pipefail
ENV=$1; IMG=$2
git clone --depth 1 "https://oauth2:${GITOPS_TOKEN}@git.example.com/infra/gitops.git" /tmp/gitops
cd /tmp/gitops/apps/my-biz-app/overlays/$ENV
kustomize edit set image app=$IMG
git -c user.name=ci -c [email protected] commit -am "deploy(my-biz-app/$ENV): $IMG" && git push

D.10 Kubernetes 매니페스트 기준

apiVersion: apps/v1
kind: Deployment
metadata: { name: my-biz-app, labels: { app: my-biz-app } }
spec:
  replicas: 2
  revisionHistoryLimit: 5
  strategy: { type: RollingUpdate, rollingUpdate: { maxUnavailable: 0, maxSurge: 1 } }
  selector: { matchLabels: { app: my-biz-app } }
  template:
    metadata: { labels: { app: my-biz-app } }
    spec:
      terminationGracePeriodSeconds: 45          # preStop 10s + graceful 30s + 여유
      securityContext: { runAsNonRoot: true, runAsUser: 10001, fsGroup: 10001 }
      topologySpreadConstraints:
        - { maxSkew: 1, topologyKey: kubernetes.io/hostname, whenUnsatisfiable: ScheduleAnyway, labelSelector: { matchLabels: { app: my-biz-app } } }
      containers:
        - name: app
          image: registry.example.com/ongo/my-biz-app@sha256:<digest>
          ports: [ { name: http, containerPort: 8080 }, { name: mgmt, containerPort: 18080 } ]
          env:
            - { name: SPRING_PROFILES_ACTIVE, value: prod }
            - { name: SERVER_PORT, value: "8080" }
            - { name: MANAGEMENT_SERVER_PORT, value: "18080" }
            - { name: SPRING_CONFIG_IMPORT, value: "optional:configtree:/run/secrets/app/" }
          envFrom: [ { configMapRef: { name: my-biz-app-config } } ]
          volumeMounts:
            - { name: secrets, mountPath: /run/secrets/app, readOnly: true }
            - { name: tmp, mountPath: /tmp }
          startupProbe:   { httpGet: { path: /actuator/health/liveness,  port: mgmt }, periodSeconds: 5, failureThreshold: 36 }  # 최대 180s 기동
          readinessProbe: { httpGet: { path: /actuator/health/readiness, port: mgmt }, periodSeconds: 5, failureThreshold: 3 }
          livenessProbe:  { httpGet: { path: /actuator/health/liveness,  port: mgmt }, periodSeconds: 10, failureThreshold: 3 }
          lifecycle: { preStop: { exec: { command: ["sh","-c","sleep 10"] } } }   # 엔드포인트 제거 전파 대기
          resources: { requests: { cpu: 500m, memory: 1Gi }, limits: { memory: 1Gi } }
          securityContext: { readOnlyRootFilesystem: true, allowPrivilegeEscalation: false }
      volumes:
        - { name: secrets, secret: { secretName: my-biz-app-secrets } }
        - { name: tmp, emptyDir: {} }
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata: { name: my-biz-app }
spec: { minAvailable: 1, selector: { matchLabels: { app: my-biz-app } } }

• Ingress: 요청 크기(nginx.ingress.kubernetes.io/proxy-body-size)·타임아웃을 §1.4 에 맞춘다. /actuator 는 Ingress 에 노출하지 않는다(관리 포트는 Service 에 미포함 또는 내부용 Service 분리).
• HPA: CPU 70% 기준 min 2. 세션·멱등·캐시 공유 구현 필수(§1.5).
• 배치: ongo-framework-batch* 이미지를 Job/CronJob(concurrencyPolicy: Forbid)으로.
• EAI TCP 수신이 필요한 앱: Service type: LoadBalancer/NodePort TCP 포트 별도, 파드 다중화 시 수신 분산·세션 정책 확인(가이드 #eaitcp).

D.11 체크리스트(D)

• □ 운영 이미지 JRE·비루트·devtools 제외, 스캔 Critical 0
• □ 태그=sha, 운영 digest 고정, 동일 digest 승격
• □ 시크릿은 Secret/ESO, 이미지·Git 평문 금지
• □ startup/readiness/liveness 관리 포트, preStop + graceful, PDB
• □ 리소스 requests/limits, MaxRAMPercentage
• □ Ingress 크기·타임아웃·/actuator 차단
• □ 롤백: 이전 digest 로 매니페스트 revert(또는 kubectl rollout undo 긴급)

적용: 빌드는 클러스터 내 Tekton, 반영 단계 결재/승인은 Jira 워크플로, 배포는 ArgoCD(GitOps) 로 분리된 엔터프라이즈 환경. 원칙 3가지: ① 클러스터 상태의 진실은 GitOps 저장소 ② CI 는 클러스터에 직접 apply 하지 않는다 ③ 승인 근거(Jira 이슈)와 배포 커밋이 1:1 로 추적된다.

E.1 전체 흐름

sequenceDiagram
  autonumber
  participant Dev as 개발자
  participant Git as 앱 저장소
  participant TK as Tekton (EventListener/Pipeline)
  participant REG as 이미지 레지스트리
  participant GO as GitOps 저장소
  participant AR as ArgoCD
  participant J as Jira
  Dev->>Git: PR 머지(develop/main)
  Git->>TK: Webhook (서명)
  TK->>TK: ongo-ci: clone → test → bootJar → image → scan
  TK->>REG: push :<sha12> (digest 획득)
  TK->>GO: overlays/dev 이미지 digest 커밋
  GO-->>AR: 변경 감지 → dev auto-sync
  AR-->>TK: (선택) 동기화/헬스 확인 태스크가 폴링
  TK->>J: 「반영요청」 이슈 생성(서비스·digest·변경요약·롤백계획)
  Note over J: 검토 → 결재자 「STG 승인」 전이
  J->>TK: Automation Webhook (issueKey, 대상 env)
  TK->>J: 이슈 상태·승인자·digest 재검증(REST)
  TK->>GO: overlays/stg 갱신 커밋(또는 PR)
  GO-->>AR: stg auto-sync
  TK->>J: 결과 코멘트 + 「STG 반영완료」
  Note over J: 운영 결재 「PROD 승인」
  J->>TK: Webhook (prod)
  TK->>GO: overlays/prod 갱신 PR → 자동/보호 머지
  AR->>AR: prod sync(수동 또는 sync window 내 자동)
  TK->>J: 헬스 결과 코멘트 + 「반영완료」/「실패」

E.2 저장소 구성

app-repo/                         gitops-repo/
├─ src/ ...                       ├─ apps/my-biz-app/
├─ docker/app/Dockerfile          │   ├─ base/ (deployment.yaml, service.yaml, configmap.yaml, pdb.yaml, kustomization.yaml)
├─ .tekton/                       │   └─ overlays/
│   ├─ pipeline-ci.yaml           │       ├─ dev/  (kustomization.yaml: images, replicas=1, profile=dev)
│   ├─ pipeline-promote.yaml      │       ├─ stg/  (replicas=2, profile=stg)
│   ├─ tasks/*.yaml               │       └─ prod/ (replicas=3, HPA, profile=prod)
│   └─ triggers/*.yaml            ├─ argocd/ (appproject.yaml, applicationset.yaml)
└─ ci/smoke.sh                    └─ secrets/ (ExternalSecret/SealedSecret 정의만, 평문 없음)

overlays/prod/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: ongo-prod
resources: [ ../../base, hpa.yaml, externalsecret.yaml ]
images:
  - name: app
    newName: registry.example.com/ongo/my-biz-app
    digest: sha256:3f1c...e9            # Tekton promote 가 갱신
replicas: [ { name: my-biz-app, count: 3 } ]
configMapGenerator:
  - name: my-biz-app-config
    behavior: merge
    literals: [ SPRING_PROFILES_ACTIVE=prod ]
commonAnnotations:
  ongo.io/jira-issue: REL-1234          # 승인 근거 추적

E.3 이미지 태그 전략

E.4 Tekton — Task 예

gradle-build Task

apiVersion: tekton.dev/v1
kind: Task
metadata: { name: gradle-build }
spec:
  params:
    - { name: module, type: string }
    - { name: jdk, type: string, default: "21" }
  workspaces: [ { name: source }, { name: gradle-cache } ]
  results: [ { name: jar-path } ]
  steps:
    - name: test-and-jar
      image: registry.example.com/mirror/eclipse-temurin:21-jdk
      workingDir: $(workspaces.source.path)
      env:
        - { name: GRADLE_USER_HOME, value: $(workspaces.gradle-cache.path) }
      computeResources: { requests: { cpu: "1", memory: 2Gi }, limits: { memory: 3Gi } }
      script: |
        #!/usr/bin/env bash
        set -euo pipefail
        ./gradlew --no-daemon test ":$(params.module):bootJar" -PongoJavaRelease=$(params.jdk)
        JAR=$(ls $(params.module)/build/libs/*.jar | grep -v -- -plain | head -1)
        mkdir -p build && cp "$JAR" build/app.jar
        printf build/app.jar | tee $(results.jar-path.path)

gitops-bump Task

apiVersion: tekton.dev/v1
kind: Task
metadata: { name: gitops-bump }
spec:
  params: [ {name: app}, {name: env}, {name: image}, {name: digest}, {name: jira-issue, default: ""} ]
  workspaces: [ { name: gitops-cred } ]     # basic-auth 또는 ssh Secret
  steps:
    - name: bump
      image: registry.example.com/mirror/kustomize-git:5
      script: |
        set -euo pipefail
        git config --global credential.helper "store --file=$(workspaces.gitops-cred.path)/.git-credentials"
        git clone --depth 1 https://git.example.com/infra/gitops.git /w && cd /w/apps/$(params.app)/overlays/$(params.env)
        kustomize edit set image app=$(params.image)@$(params.digest)
        [ -n "$(params.jira-issue)" ] && kustomize edit add annotation --force ongo.io/jira-issue:$(params.jira-issue)
        git -c user.name=tekton -c [email protected] commit -am "deploy($(params.app)/$(params.env)): $(params.digest) [$(params.jira-issue)]"
        git push origin HEAD:main

jira Task(REST 호출 공통)

apiVersion: tekton.dev/v1
kind: Task
metadata: { name: jira }
spec:
  params: [ {name: action}, {name: issue, default: ""}, {name: payload, default: "{}"} ]
  results: [ { name: issue-key } ]
  steps:
    - name: call
      image: registry.example.com/mirror/curl-jq:latest
      env:
        - { name: JIRA_URL,   valueFrom: { secretKeyRef: { name: jira-cred, key: url } } }
        - { name: JIRA_USER,  valueFrom: { secretKeyRef: { name: jira-cred, key: user } } }
        - { name: JIRA_TOKEN, valueFrom: { secretKeyRef: { name: jira-cred, key: token } } }
      script: |
        set -euo pipefail
        AUTH="-u $JIRA_USER:$JIRA_TOKEN -H Content-Type:application/json"
        case "$(params.action)" in
          create)   curl -fsS $AUTH -X POST "$JIRA_URL/rest/api/2/issue" -d '$(params.payload)' | jq -r .key | tee $(results.issue-key.path) ;;
          comment)  curl -fsS $AUTH -X POST "$JIRA_URL/rest/api/2/issue/$(params.issue)/comment" -d '$(params.payload)' ;;
          transition) curl -fsS $AUTH -X POST "$JIRA_URL/rest/api/2/issue/$(params.issue)/transitions" -d '$(params.payload)' ;;
          verify)   # 승인 상태·승인자 그룹·digest 일치 확인
            J=$(curl -fsS $AUTH "$JIRA_URL/rest/api/2/issue/$(params.issue)?fields=status,customfield_digest,customfield_approver")
            echo "$J" | jq -e '.fields.status.name == "승인"' >/dev/null || { echo "미승인 이슈"; exit 1; } ;;
        esac

Jira Cloud 는 /rest/api/3(본문 ADF 형식), Data Center 는 /rest/api/2. 커스텀 필드 ID(customfield_xxxxx)는 사이트 Jira 에서 확인.

E.5 Tekton — Pipeline 예

ongo-ci

apiVersion: tekton.dev/v1
kind: Pipeline
metadata: { name: ongo-ci }
spec:
  params:
    - { name: git-url } 
    - { name: git-rev }
    - { name: app }
    - { name: module }
    - { name: image }                 # registry.example.com/ongo/my-biz-app
    - { name: jdk, default: "21" }
  workspaces: [ {name: src}, {name: gradle-cache}, {name: docker-cred}, {name: gitops-cred} ]
  tasks:
    - name: clone
      taskRef: { resolver: hub, params: [ {name: name, value: git-clone}, {name: version, value: "0.9"} ] }
      params: [ {name: url, value: $(params.git-url)}, {name: revision, value: $(params.git-rev)} ]
      workspaces: [ {name: output, workspace: src} ]
    - name: build
      runAfter: [clone]
      taskRef: { name: gradle-build }
      params: [ {name: module, value: $(params.module)}, {name: jdk, value: $(params.jdk)} ]
      workspaces: [ {name: source, workspace: src}, {name: gradle-cache, workspace: gradle-cache} ]
    - name: image
      runAfter: [build]
      taskRef: { resolver: hub, params: [ {name: name, value: kaniko}, {name: version, value: "0.6"} ] }   # 또는 buildah
      params:
        - { name: IMAGE, value: "$(params.image):$(tasks.clone.results.commit)" }
        - { name: DOCKERFILE, value: ./ci/Dockerfile.runtime }      # §D.2 패턴 2 (build/app.jar COPY)
        - { name: CONTEXT, value: . }
      workspaces: [ {name: source, workspace: src}, {name: dockerconfig, workspace: docker-cred} ]
    - name: scan
      runAfter: [image]
      taskRef: { name: trivy-scan }
      params: [ { name: image, value: "$(params.image)@$(tasks.image.results.IMAGE_DIGEST)" } ]
    - name: bump-dev
      runAfter: [scan]
      taskRef: { name: gitops-bump }
      params:
        - { name: app, value: $(params.app) }
        - { name: env, value: dev }
        - { name: image, value: $(params.image) }
        - { name: digest, value: $(tasks.image.results.IMAGE_DIGEST) }
      workspaces: [ {name: gitops-cred, workspace: gitops-cred} ]
    - name: wait-dev
      runAfter: [bump-dev]
      taskRef: { name: argocd-wait }       # argocd app wait <app>-dev --health --timeout 300
      params: [ {name: application, value: "$(params.app)-dev"} ]
    - name: jira-request
      runAfter: [wait-dev]
      taskRef: { name: jira }
      params:
        - { name: action, value: create }
        - name: payload
          value: |
            {"fields":{"project":{"key":"REL"},"issuetype":{"name":"반영요청"},
             "summary":"[$(params.app)] $(tasks.clone.results.commit) 반영요청",
             "description":"digest=$(tasks.image.results.IMAGE_DIGEST)\nPipelineRun=$(context.pipelineRun.name)"}}
  finally:
    - name: notify
      taskRef: { name: notify-result }
      params: [ { name: status, value: "$(tasks.status)" } ]

ongo-promote (Jira 승인 Webhook 전용)

apiVersion: tekton.dev/v1
kind: Pipeline
metadata: { name: ongo-promote }
spec:
  params: [ {name: issue}, {name: app}, {name: env}, {name: image}, {name: digest} ]
  workspaces: [ {name: gitops-cred} ]
  tasks:
    - name: verify
      taskRef: { name: jira }
      params: [ {name: action, value: verify}, {name: issue, value: $(params.issue)} ]
    - name: mark-in-progress
      runAfter: [verify]
      taskRef: { name: jira }
      params: [ {name: action, value: transition}, {name: issue, value: $(params.issue)}, {name: payload, value: '{"transition":{"id":"31"}}'} ]   # 「반영중」
    - name: bump
      runAfter: [mark-in-progress]
      taskRef: { name: gitops-bump }
      params: [ {name: app, value: $(params.app)}, {name: env, value: $(params.env)}, {name: image, value: $(params.image)}, {name: digest, value: $(params.digest)}, {name: jira-issue, value: $(params.issue)} ]
      workspaces: [ {name: gitops-cred, workspace: gitops-cred} ]
    - name: wait
      runAfter: [bump]
      taskRef: { name: argocd-wait }
      params: [ {name: application, value: "$(params.app)-$(params.env)"}, {name: sync, value: "true"} ]   # prod 수동 sync 정책이면 여기서 sync 실행
      timeout: 20m
  finally:
    - name: report
      taskRef: { name: jira }
      params:
        - { name: action, value: comment }
        - { name: issue, value: $(params.issue) }
        - { name: payload, value: '{"body":"반영 결과: $(tasks.status) / env=$(params.env) / digest=$(params.digest)"}' }

Trigger (Jira Webhook)

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata: { name: jira-approval }
spec:
  serviceAccountName: tekton-triggers
  triggers:
    - name: promote
      interceptors:
        - ref: { name: cel }
          params:
            - name: filter
              value: >-
                header.match('X-Webhook-Token', '$(secret)') == false ? false :
                body.transition.to_status in ['STG 승인','PROD 승인']
        # 토큰 검증은 사이트 표준: 공유 토큰 헤더(Secret 비교), mTLS, 또는 사내 게이트웨이 서명 검증
      bindings:
        - { name: issue,  value: $(body.issue.key) }
        - { name: app,    value: $(body.issue.fields.customfield_app) }
        - { name: env,    value: "$(body.transition.to_status == 'PROD 승인' ? 'prod' : 'stg')" }
        - { name: image,  value: $(body.issue.fields.customfield_image) }
        - { name: digest, value: $(body.issue.fields.customfield_digest) }
      template: { ref: ongo-promote-template }

위 CEL 은 개념 예. Jira Automation 의 「Send web request」 본문을 사이트가 직접 정의(JSON 키)하는 편이 바인딩이 단순하다. EventListener 는 내부망 Ingress + 토큰/서명 검증 필수, Webhook 재전송에 대비해 promote 는 멱등(이미 같은 digest 면 no-op). - 공용 Tekton 운영 팁: PipelineRun TTL/pruner 로 이력 정리, gradle 캐시는 PVC 워크스페이스, 사내 미러 이미지만 사용(registry.example.com/mirror/...), Task 는 Tekton Bundles/Hub resolver 로 버전 고정.

E.6 Jira 승인 게이트 설계

stateDiagram-v2
  [*] --> 요청: Tekton 자동 생성
  요청 --> 검토: 담당 확인
  검토 --> STG승인: 결재(팀장)
  STG승인 --> STG반영중: Webhook→promote
  STG반영중 --> STG반영완료: Argo Healthy
  STG반영중 --> 실패: 헬스 실패
  STG반영완료 --> PROD승인: 결재(변경관리위원/CAB)
  PROD승인 --> PROD반영중: Webhook→promote(sync window 내)
  PROD반영중 --> 반영완료
  PROD반영중 --> 실패
  실패 --> 롤백완료: revert 커밋
  반영완료 --> [*]

E.7 ArgoCD — AppProject / Application / ApplicationSet

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata: { name: ongo, namespace: argocd }
spec:
  sourceRepos: [ https://git.example.com/infra/gitops.git ]
  destinations:
    - { server: https://kubernetes.default.svc, namespace: ongo-dev }
    - { server: https://kubernetes.default.svc, namespace: ongo-stg }
    - { server: https://prod-cluster.example.com, namespace: ongo-prod }
  clusterResourceWhitelist: []            # 클러스터 범위 리소스 생성 금지
  syncWindows:
    - { kind: allow, schedule: "0 22 * * 1-4", duration: 3h, applications: ["*-prod"], timeZone: Asia/Seoul }   # 월~목 22~01시 KST
    - { kind: deny,  schedule: "0 0 * * 5-0",  duration: 72h, applications: ["*-prod"], timeZone: Asia/Seoul, manualSync: false }
  roles:
    - name: deployer
      policies: [ "p, proj:ongo:deployer, applications, sync, ongo/*-stg, allow", "p, proj:ongo:deployer, applications, sync, ongo/*-prod, allow" ]
---
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata: { name: my-biz-app, namespace: argocd }
spec:
  goTemplate: true
  generators:
    - list:
        elements:
          - { env: dev,  cluster: https://kubernetes.default.svc, auto: true }
          - { env: stg,  cluster: https://kubernetes.default.svc, auto: true }
          - { env: prod, cluster: https://prod-cluster.example.com, auto: false }
  template:
    metadata: { name: 'my-biz-app-{{.env}}' }
    spec:
      project: ongo
      source: { repoURL: https://git.example.com/infra/gitops.git, targetRevision: main, path: 'apps/my-biz-app/overlays/{{.env}}' }
      destination: { server: '{{.cluster}}', namespace: 'ongo-{{.env}}' }
      syncPolicy:
        syncOptions: [ CreateNamespace=false, PruneLast=true, ApplyOutOfSyncOnly=true ]
        retry: { limit: 3, backoff: { duration: 10s, factor: 2, maxDuration: 2m } }
  templatePatch: |
    {{- if .auto }}
    spec:
      syncPolicy:
        automated: { prune: true, selfHeal: true }
    {{- end }}

E.8 다환경 승격(promotion) 규칙

1. dev: 머지마다 자동. 2. stg: Jira 「STG 승인」 → 같은 digest. 3. prod: stg 에서 최소 관찰 시간(예: 1영업일) 경과 + 「PROD 승인」 → 같은 digest. - 환경별 차이는 오버레이(kustomize)/values(Helm) 에만 둔다: replicas, 리소스, 프로파일, ConfigMap, ExternalSecret 경로. 이미지는 동일. - 설정 변경(ConfigMap)도 GitOps 커밋 + 같은 승인 흐름(이슈 유형 「설정변경」)을 탄다. ConfigMap 변경 시 롤링 재기동을 위해 configMapGenerator(이름 해시) 사용. | 항목 | dev | stg | prod | |---|---|---|---| | sync | auto+selfHeal | auto | 수동 + sync window | | replicas | 1 | 2 | ≥3(HPA) | | devtools/openapi | on(데모 한정) | off | 아티팩트 제외 | | 세션 저장소 | 인메모리 허용(단일) | Redis | Redis(HA) | | 승인 | 없음 | 팀장 | CAB |

E.9 시크릿 관리

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata: { name: my-biz-app-secrets }
spec:
  refreshInterval: 1h
  secretStoreRef: { name: vault-ongo, kind: ClusterSecretStore }
  target: { name: my-biz-app-secrets }
  data:
    - { secretKey: spring.datasource.password, remoteRef: { key: ongo/prod/my-biz-app, property: db_password } }
    - { secretKey: ongo.framework.crypto.key,  remoteRef: { key: ongo/prod/my-biz-app, property: crypto_key } }

• 위 Secret 을 /run/secrets/app 에 마운트하면 spring.config.import=configtree:/run/secrets/app/ 가 파일명=프로퍼티 키로 읽는다(§D.10). 프레임 CryptoKeyProvider 구현이 이 값을 사용.
• Tekton 자격증명(레지스트리·GitOps·Jira)도 같은 방식으로 생성하고, 파이프라인 ServiceAccount 에만 바인딩.

E.10 롤백(ArgoCD)

argocd app history my-biz-app-prod                 # 배포 이력(리비전·시각)
argocd app rollback my-biz-app-prod 42 --prune     # 긴급
argocd app get my-biz-app-prod --refresh           # 상태 확인

E.11 체크리스트(E)

• □ 앱/GitOps 저장소 분리, CI 의 클러스터 직접 apply 권한 없음
• □ 태그=sha, 매니페스트 digest, 같은 digest 승격
• □ Tekton Task 버전 고정·사내 미러 이미지·캐시 PVC·PipelineRun pruner
• □ EventListener 내부망 + 토큰/서명 검증, promote 멱등
• □ Jira 이슈 유형·필드·전이 조건(자기 승인 금지)·Automation Webhook
• □ promote 첫 단계 Jira 재검증
• □ AppProject 제한·sync window(KST)·prod 수동 sync
• □ ESO/Sealed Secrets, Git 평문 0
• □ PreSync 마이그레이션 하위호환, 롤백 리허설(revert → sync)
• □ argocd-notifications / Jira 결과 회신
• □ 소스 웹훅(Bitbucket 등) → Tekton 트리거 구성(E.12)

E.12 Bitbucket 저장소 웹훅 → Tekton 빌드 트리거(PaaS 표준 연계)

적용: 소스 저장소가 Bitbucket(Data Center/Server 또는 Cloud) 이고 빌드를 클러스터 내 Tekton 이 수행하는 PaaS. E.1 의 「Webhook(서명)」 단계를 Bitbucket 기준으로 구체화한 것이며, 이후 단계(이미지 push → GitOps dev 커밋 → Jira 승인 → ArgoCD 승격)는 E.5~E.10 과 동일하다. 고객사에 관계없이 쓰는 일반 패턴이다.

E.12.1 구성 요소와 흐름

flowchart LR
  BB[Bitbucket 저장소<br/>Repository Webhook] -- HTTPS POST<br/>X-Hub-Signature --> ING[Ingress/Route<br/>내부망·IP 허용]
  ING --> EL[EventListener<br/>ongo-bitbucket-listener]
  EL --> IC{Interceptors<br/>bitbucket: 서명·이벤트<br/>cel: 브랜치·경로 필터}
  IC -- 통과 --> TB[TriggerBinding<br/>payload → params]
  TB --> TT[TriggerTemplate]
  TT --> PR[PipelineRun ongo-ci-*]
  PR --> REG[(레지스트리)] --> GO[(GitOps dev overlay)]
  PR -. 빌드 상태 .-> BB

E.12.2 Bitbucket 쪽 설정(저장소 관리자)

1. 저장소 → Repository settings → Webhooks → Create webhook
2. URL: https://tekton-hooks.<내부도메인>/bitbucket/<app> (Ingress 경로별 EventListener 또는 단일 리스너 + CEL 라우팅)
3. Secret: 32바이트 이상 랜덤값(openssl rand -hex 32) → 같은 값을 클러스터 Secret 에 등록
4. 이벤트: Repository → Push(repo:refs_changed). PR 빌드(검증용)가 필요하면 Pull request → Opened/Source branch updated(pr:opened, pr:from_ref_updated) 별도 트리거로 분리
5. 「Test connection」으로 200/202 확인, Bitbucket 웹훅 「View details」에서 요청/응답 이력 확인
6. 서비스 계정 토큰(읽기 전용, HTTP access token) → Tekton git-clone 용 basic-auth Secret. 빌드 상태 회신을 쓰면 Repository write 범위 토큰 별도

폐쇄망: Bitbucket 서버 → 클러스터 Ingress 방향 방화벽(443) 개통이 필요하다. 반대 방향(클러스터 → Bitbucket 7990/443/7999)은 clone·상태 회신용.

E.12.3 웹훅 payload(Bitbucket Data Center/Server, repo:refs_changed)

{
  "eventKey": "repo:refs_changed",
  "date": "2026-10-30T12:00:00+0900",
  "actor": { "name": "dev1", "displayName": "개발자1" },
  "repository": {
    "slug": "my-biz-app",
    "project": { "key": "ONGO" },
    "links": { "clone": [ { "href": "https://bitbucket.example.com/scm/ongo/my-biz-app.git", "name": "http" },
                          { "href": "ssh://[email protected]:7999/ongo/my-biz-app.git", "name": "ssh" } ] }
  },
  "changes": [ {
    "ref": { "id": "refs/heads/develop", "displayId": "develop", "type": "BRANCH" },
    "fromHash": "1111111111111111111111111111111111111111",
    "toHash":   "9ed13f8a0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
    "type": "UPDATE"
  } ]
}

헤더: X-Event-Key: repo:refs_changed, X-Hub-Signature: sha256=<hmac>, X-Request-Id.

Cloud 는 웹훅 서명이 X-Hub-Signature(Secret 설정 시) 로 동일하나 이벤트 키가 repo:push 다. 아래 예는 Data Center 기준.

E.12.4 Tekton Triggers 매니페스트

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata: { name: ongo-bitbucket-listener, namespace: ongo-ci }
spec:
  serviceAccountName: tekton-triggers-sa
  resources:
    kubernetesResource: { replicas: 2 }
  triggers:
    - name: push-build
      interceptors:
        - ref: { name: bitbucket, kind: ClusterInterceptor }
          params:
            - name: secretRef
              value: { secretName: bitbucket-webhook-secret, secretKey: secret }
            - name: eventTypes
              value: [ "repo:refs_changed" ]
        - ref: { name: cel, kind: ClusterInterceptor }
          params:
            - name: filter
              value: >-
                body.changes[0].type != 'DELETE' &&
                body.changes[0].ref.displayId.matches('^(develop|main|release/.+)$')
            - name: overlays
              value:
                - { key: sha12,  expression: "body.changes[0].toHash.truncate(12)" }
                - { key: branch, expression: "body.changes[0].ref.displayId" }
                - { key: cloneUrl, expression: "body.repository.links.clone.filter(c, c.name == 'http')[0].href" }
      bindings: [ { ref: ongo-bitbucket-push } ]
      template: { ref: ongo-ci-template }
---
apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerBinding
metadata: { name: ongo-bitbucket-push, namespace: ongo-ci }
spec:
  params:
    - { name: git-url,  value: $(extensions.cloneUrl) }
    - { name: git-rev,  value: $(body.changes[0].toHash) }
    - { name: sha12,    value: $(extensions.sha12) }
    - { name: branch,   value: $(extensions.branch) }
    - { name: app,      value: $(body.repository.slug) }
    - { name: actor,    value: $(body.actor.name) }
---
apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata: { name: ongo-ci-template, namespace: ongo-ci }
spec:
  params: [ {name: git-url}, {name: git-rev}, {name: sha12}, {name: branch}, {name: app}, {name: actor} ]
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: PipelineRun
      metadata:
        generateName: ongo-ci-$(tt.params.app)-
        labels:
          ongo.io/app: $(tt.params.app)
          ongo.io/git-sha: $(tt.params.sha12)
          ongo.io/branch: $(tt.params.branch)
        annotations:
          ongo.io/triggered-by: $(tt.params.actor)
      spec:
        pipelineRef: { name: ongo-ci }
        params:
          - { name: git-url, value: $(tt.params.git-url) }
          - { name: git-rev, value: $(tt.params.git-rev) }
          - { name: app,     value: $(tt.params.app) }
          - { name: module,  value: "app" }
          - { name: image,   value: "registry.example.com/ongo/$(tt.params.app)" }
        taskRunTemplate: { serviceAccountName: tekton-build-sa }
        timeouts: { pipeline: 45m }
        workspaces:
          - name: src
            volumeClaimTemplate:
              spec: { accessModes: [ReadWriteOnce], resources: { requests: { storage: 2Gi } } }
          - { name: gradle-cache, persistentVolumeClaim: { claimName: gradle-cache } }
          - { name: docker-cred,  secret: { secretName: registry-push } }
          - { name: gitops-cred,  secret: { secretName: gitops-write } }

Ingress(내부망 한정):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tekton-hooks
  namespace: ongo-ci
  annotations:
    nginx.ingress.kubernetes.io/whitelist-source-range: "10.10.20.0/24"   # Bitbucket 서버 대역
spec:
  rules:
    - host: tekton-hooks.example.internal
      http:
        paths:
          - path: /bitbucket
            pathType: Prefix
            backend: { service: { name: el-ongo-bitbucket-listener, port: { number: 8080 } } }

RBAC 최소권한: tekton-triggers-sa 는 triggers.tekton.dev 리소스 get/list/watch + pipelineruns create 만. 빌드용 tekton-build-sa 와 분리한다(클러스터 apply 권한 없음 — E 원칙 ②).

E.12.5 빌드 상태 회신(선택, 권장)

ongo-ci 의 finally 에 상태 회신 Task 를 둬 Bitbucket 커밋/PR 화면에 빌드 결과를 표시한다.

finally:
  - name: bitbucket-status
    params:
      - { name: state, value: "$(tasks.status)" }      # Succeeded/Failed/Completed
    taskSpec:
      params: [ {name: state} ]
      steps:
        - name: notify
          image: registry.example.com/mirror/curl:8
          env: [ { name: TOKEN, valueFrom: { secretKeyRef: { name: bitbucket-status-token, key: token } } } ]
          script: |
            S=SUCCESSFUL; [ "$(params.state)" = "Failed" ] && S=FAILED
            curl -fsS -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
              "https://bitbucket.example.com/rest/build-status/1.0/commits/$(params.git-rev)" \
              -d "{\"state\":\"$S\",\"key\":\"ongo-ci\",\"name\":\"Tekton ongo-ci\",\"url\":\"https://tekton.example.internal/#/namespaces/ongo-ci/pipelineruns/$(context.pipelineRun.name)\"}"

(Cloud 는 POST /2.0/repositories/{ws}/{repo}/commit/{hash}/statuses/build.) Bitbucket 브랜치 권한의 「Merge checks → Minimum successful builds」 와 연결하면 PR 빌드 실패 시 머지가 막힌다.

E.12.6 기존 흐름과의 연결

E.12.7 운영 수칙·장애 대응

• 중복 실행: Bitbucket 은 재시도/수동 재전송을 한다. ongo-ci 는 sha 단위 멱등(이미 존재하는 태그면 push 스킵, GitOps 커밋은 digest 동일 시 no-op). 필요하면 CEL 에서 X-Request-Id 로그를 남겨 추적
• 동시 push: 같은 브랜치 연속 push 시 이전 PipelineRun 취소 정책(Tekton 자체 기능 없음 → 시작 Task 에서 같은 ongo.io/branch 라벨의 실행 중 Run 을 Cancelled 처리하거나 GitOps 커밋 단계에서 최신 sha 만 반영)
• 필터: 문서·설정만 바뀐 커밋은 CEL 에서 제외(DC 는 payload 에 파일 목록이 없으므로 git diff --name-only fromHash toHash 를 첫 Task 에서 검사 후 스킵)
• 태그 빌드: 릴리스 태그(refs/tags/v*, ref.type == 'TAG')는 별도 트리거로 semver 태그 추가(E.3)
• 보안: 서명 검증 없는 EventListener 금지, 외부 공개 금지, Secret 은 90일 주기 교체(Bitbucket·클러스터 동시 갱신)

E.12.8 체크리스트(Bitbucket → Tekton)

• □ 웹훅 Secret 설정 + bitbucket Interceptor 서명 검증
• □ 이벤트 repo:refs_changed(+ PR 이벤트 분리), CEL 브랜치 필터
• □ EventListener 내부망 Ingress·허용 대역, 트리거 SA/빌드 SA 분리
• □ TriggerTemplate → 기존 ongo-ci 재사용, 라벨(app·sha·branch)
• □ 빌드 상태 회신 + Merge check 연동
• □ 멱등·중복 웹훅·동시 push 정책
• □ 승격은 Jira 경로만(Bitbucket 웹훅으로 stg/prod 반영 금지)

삼카 부록: 삼카 내부 PaaS 는 위 패턴 그대로 Bitbucket 저장소 웹훅 → Tekton EventListener → ongo-ci 로 빌드하고, 이후 Jira 승인 → ArgoCD 반영으로 이어진다. 웹훅 URL·허용 대역·Bitbucket 프로젝트 키는 삼카 인프라 담당 확인 필요.

• □ 라인 확정(JDK/Boot) — §0, §B.2
• □ 아티팩트 불변·sha256·BUILD-INFO — §1.1
• □ 비밀값 외부 주입, yml 데모 사용자(auth.users) 제거 — §1.2
• □ 멀티 인스턴스 → SessionStoreService·IdempotencyStore·DistributedCacheService 공유 구현 — §1.5
• □ 채널 transport: loopback → 실제 transport, TCP 수신(EAI)은 확장 리스너 위치·포트 방화벽 확인(가이드 #extmock·#eaitcp)
• □ health/readiness·graceful shutdown·타임아웃 체인 — §1.3, §1.4
• □ 로그 경로·보관·수집(ELK 브리지)·마스킹
• □ 롤백 절차 리허설(직전 릴리스/이미지 digest)
• □ devtools·openapi 운영 제외, /actuator 외부 차단
• □ 배치 실행 방식(스케줄러/CronJob)·중복 실행 방지

docs/CUSTOMIZATION.md §17(배포), docs/MULTI-JDK-PORTING.md, docker/README.md, docs/CUSTOMIZATION-EXAMPLES.md, 코어 개발가이드 #deploy(요약·케이스별 핵심 절차).

기준일 2026-10-30. 구현: apps/demo-web/app/utils/http.ts(갱신·재시도 파이프라인) · utils/auth.ts(오류 코드 정책) · utils/auth-mock.ts(목업 인증 서버) · plugins/http.ts(결합) · 데모 /token.

1. 백엔드 확인 결과

• 인증 오류 코드: auth.unauthenticated(401) · auth.forbidden(403) · auth.bad-credentials(401) · auth.session-limit(409, 동시 세션 초과를 REJECT 로 둘 때).
• 토큰 갱신 API·강제 로그아웃 코드는 없다. 중복 로그인은 반영됨, e9e1745): 동시 세션 초과(max-per-user: 2, EXPIRE_OLDEST)로 밀려난 세션은 다음 요청에서 401 auth.duplicate-login 으로 온다(SessionStoreService.wasDisplaced 기록 → AuthenticationFilter → AuthorizationInterceptor). 로그아웃·모르는 토큰은 계속 auth.unauthenticated.
• 그래서 이 항목은 워크리스트대로 목업으로 완성하고, 실제 BE 는 설정으로 연결한다(신규 API 는 만들지 않음).

2. 오류 코드 정책 (runtimeConfig.public.auth)

• 코드 목록은 env(NUXT_PUBLIC_AUTH_REFRESH_CODES, NUXT_PUBLIC_AUTH_FORCED_LOGOUT_CODES, 쉼표)로 바꾼다. 백엔드가 401 전부를 갱신 대상으로 하려면 auth.unauthenticated 를 refresh 목록에 넣는다.
• forced 는 상태 코드와 관계없이(401·403·409) 코드로 판정한다. 일반 오류 팝업·세션 만료 처리 대신 이 안내만 한 번 띄운다.

3. 갱신·재시도 (FE-02 파이프라인)

1. 401(AUTH_ERROR)이고 코드가 refresh 목록이면 refreshAuth() 를 부른다. 로그인처럼 authEvent: false 이거나 refresh: false 인 요청은 갱신하지 않는다.
2. 동시 요청 단일 갱신: 갱신 중이면 같은 Promise 를 기다린다. 요청을 보낸 뒤 이미 다른 요청이 갱신을 끝냈다면(갱신 순번 비교) 다시 갱신하지 않고 바로 재시도한다.
3. 성공하면 request 훅을 다시 돌려(새 Authorization) 한 번만 재시도한다. 재시도도 401 이거나 갱신이 실패하면 일반 401 처리(세션 만료).
4. 실제 BE 갱신 호출 위치: plugins/http.ts 의 refreshAuth(설정 refreshPath, 기본 비움 = 실제 토큰은 갱신하지 않음). BE 에 갱신 API 가 생기면 경로만 넣는다.

4. 목업 인증 서버 (/mock-api/**, 데모 전용)

브라우저 안에서 응답한다(백엔드·네트워크 없음). 목업 로그인 토큰(mock-token-*)만 받는다.

데모 화면이 토큰 상태를 바꾸고(만료·중복·강제·갱신 실패) 동시 요청을 보내 결과를 보여 준다.

화면 PR 전 자가 점검용. 자동 정적 게이트는 apps/demo-web/tests/a11y-static.test.ts, 데모는 /a11y.

보류: axe-core 브라우저 실행(CI) — 별도 작업.

기준일 2026-10-29. 구현: apps/demo-web/app/utils/idle-session.ts(코어) · plugins/session-idle.client.ts(앱 결합) · composables/useSessionIdle.ts · 데모 /session.

1. 백엔드 확인 결과

• 세션은 슬라이딩 만료: AuthenticationFilter 가 인증 요청마다 SessionStoreService.touch() 로 만료를 미룬다.
• 만료 시간 ongo.framework.session.timeout(데모 30m), 사용자당 최대 max-per-user: 2(초과 시 EXPIRE_OLDEST — 중복 로그인은 FE-08).
• 로그인 응답(POST /api/auth/login → bearer·userId·roles)에는 만료 시각이 없다 → FE 는 같은 값을 설정으로 갖는다.
• 연장용 API 는 새로 만들지 않는다. 기존 보호 경로 GET /api/me 를 부르면 세션이 연장된다.

2. 무엇을 추적하나

FE 가 세는 것은 서버 세션 만료 시각 = 마지막 서버 갱신(lastTouch) + timeout.

3. 상태와 판정 (1초마다)

stopped(비로그인) → active → warning → expired

• active 에서
• 마지막 갱신 뒤 활동이 있었고, 갱신 후 keepAliveAfter 가 지났으면 → 조용히 연장(auto) — 쓰는 중인 사용자는 경고를 보지 않는다.
• 남은 시간 ≤ warnBefore 인데 갱신 뒤 활동이 있었으면 → 조용히 연장, 없으면 → warning(연장 다이얼로그).
• warning 에서는 활동만으로 연장하지 않는다(사용자가 연장 버튼을 눌러야 함). 다른 탭의 연장·API 응답이 오면 active 로 돌아가고 다이얼로그를 닫는다.
• 남은 시간 ≤ 0 → expired: 다이얼로그를 닫고 FE-06 terminateSession('expired', { redirect }) → 로그인 화면 + "세션이 만료되었습니다" 안내.
• 연장 실패(네트워크 등)는 경고를 유지한다. 401 이면 FE-02 auth-error 가 이미 만료 처리한다.

4. 멀티탭 동기화

BroadcastChannel('ongo-session')(없으면 FE-34 storage 이벤트로 대체)로 touch·activity(5초 스로틀)·expired 를 주고받는다. 한 탭에서 쓰고 있으면 다른 탭도 유휴로 보지 않고, 한 탭에서 연장하면 다른 탭 경고가 닫히며, 만료는 모든 탭이 함께 로그아웃한다.

5. 연장 호출

keepAlive() = GET {apiBase}{keepAlivePath}(기본 /me, 오류 팝업·전역 로딩 끔). 목업 로그인(mock-token-*)은 BE 에 없는 토큰이라 호출하지 않고 성공으로 친다(데모).

6. 설정 (runtimeConfig.public.session, env)

warnBefore 는 timeout 보다 작게, keepAliveAfter 는 timeout - warnBefore 이하로 보정한다.

7. 화면 API (useSessionIdle())

state(phase·expiresAt·remainingMs·lastTouch·lastActivity) · extend() · configure({ timeoutSec, warnBeforeSec, keepAliveAfterSec })(데모용 일시 변경) · resetConfig() · setActivityTracking(on) · events(최근 판정 로그).

기준일 2026-10-30. 구현: apps/demo-web/app/utils/action-lock.ts(버튼·작업 락) · utils/http.ts(요청 락·멱등 키) · composables/useActionLock.ts·useIdempotencyKey.ts · 목업 이체 서버 utils/transfer-mock.ts · 데모 /submit.

1. 세 겹 방어

• 버튼 락은 진행 중이면 같은 Promise 를 돌려주고 핸들러를 다시 부르지 않는다. 끝나면(성공·실패 모두) 풀린다.
• 요청 락은 화면이 여러 곳에서 같은 요청을 동시에 보낼 때(자동 저장·버튼·단축키) 한 번만 보낸다.
• 멱등 키는 논리적 제출 한 건마다 하나다. 응답이 끊겨 사용자가 다시 누르면 같은 키가 다시 가서 서버가 처음 결과를 돌려준다(이중 이체 방지). 성공하거나 사용자가 입력을 바꾸면 새 키.
• idempotent: true 는 호출마다 새 키(그 호출 안의 재시도만 같은 키) — 기존 FE-02 동작 유지.
• idempotencyKey 를 주면 그 키를 Idempotency-Key 헤더로 보내고 POST 도 retry 를 허용한다.

2. 백엔드

현재 백엔드는 Idempotency-Key 를 처리하지 않는다(신규 API·필터 만들지 않음). 데모는 브라우저 안 목업 이체 서버(/mock-api/transfer)가 키별 결과를 기억해 재전송을 재생(replayed: true)한다. 실제 적용 시 백엔드가 키를 저장·재생해야 이중 처리가 완전히 막힌다 — 그 전까지 FE 의 버튼·요청 락이 1차 방어다.

화면에 보이는 오류·안내 문구를 어디서 가져올지와 어떤 순서로 고를지를 정한다. 기준일 2026-10-29. 구현: apps/demo-web/app/utils/message-catalog.ts(코어) · plugins/message-catalog.ts(적재·설정) · composables/useMessageCatalog.ts(화면) · 데모 /messages.

1. 원천(Source)

• 같은 code 가 내장·정적 JSON 에 다 있으면 정적 JSON 이 이긴다. 제목(title)·톤(tone)은 단계와 관계없이 카탈로그 항목에서 가져온다.
• 백엔드 API 는 새로 만들지 않는다. 기존 GET /api/demo/messages/{code}?name= 응답 {code, text} 를 쓰고, text === code 면 서버에 없는 코드로 본다. Accept-Language(기본 ko-KR)를 따르고, {0} 같은 MessageFormat 자리표시는 FE 가 채운다('' → ').

2. 결정 정책(MessagePolicy)

정책 = 위 단계의 순서. 앞 단계에서 값이 나오면 멈춘다. default 는 항상 맨 끝(빠져 있으면 붙인다).

바꾸는 방법 (위에서 아래로 범위가 좁아진다)

1. 환경 프로파일별: .env.<profile> 또는 실행 시 NUXT_PUBLIC_MESSAGE_CATALOG_POLICY=catalog-first. 프리셋 이름 대신 순서를 직접 적어도 된다: override,catalog,server,default(모르는 단계는 무시).
2. 코드별: 카탈로그 JSON 항목에 "override": true — 정책에 override 단계가 있으면 그 코드만 FE 문구로 덮는다.
3. 실행 중(데모·테스트): useMessageCatalog().setPolicy('catalog-first').

3. 캐시·버전

• 백엔드(확인 결과): Refreshable + MetaLoadRunner 가 메타 적재 뒤 코드 캐시·메시지 테이블 캐시(JdbcMessageSource)·로컬 캐시를 비운다(실행: meta-load.on-startup·cron·runNow(), 데모 POST /api/demo/meta/reload). 단 데모 앱은 MetaLoadService 를 등록하지 않아 reload 가 demo.meta.not-configured 이고, 메시지 테이블(message.jdbc.enabled)도 꺼져 있다. 버전·ETag 개념은 없다.
• FE: 서버 버전이 없으므로 remote 문구는 TTL 캐시(기본 300초, 없는 코드도 같은 TTL 로 기억해 반복 호출을 막는다). reload() 가 TTL 캐시를 비우고 정적 JSON 을 다시 읽는다. 정적 JSON 의 version 은 표시용.
• 제안(이번 범위 밖): 백엔드가 메타 적재 시각이나 버전을 응답 헤더로 주면 FE 는 TTL 대신 버전이 바뀔 때만 비울 수 있다.

4. 설정 (runtimeConfig.public.messageCatalog, env)

5. 화면 API (useMessageCatalog())

• text(code, args?) — 동기. 정책대로 고른 문구 + {0} 치환. 받아 둔 remote 문구가 있으면 반영.
• fetchText(code, args?, { force? }) — 비동기. remote 를 (TTL 안이면 캐시로) 확인한 뒤 text.
• resolve({ kind, code, serverMessage }) → { message, source, entry } — 오류 팝업과 같은 판정.
• policy · setPolicy(p) · reload() · status · list() · lookup(code).

공통 HTTP 오류 팝업(FE-02)은 resolve 를 쓰고, 다이얼로그 제목·톤·필드 오류 문구도 카탈로그를 따른다.

상태: 설계(구현 전) · 추적: TODO-LAYOUT-CUSTOM.md

현재

• 래핑: ApiResponseBodyAdvice(core) — 빈 ongoApiResponseBodyAdvice, @ConditionalOnMissingBean, ongo.framework.web.envelope-enabled(기본 true)일 때만 등록.
• 필드명·레이아웃: ApiResponse(common) code/message/data/traceId 코드 고정. yml 로 못 바꾼다.
• 가능한 우회: envelope-enabled: false, @NoEnvelope, Advice 빈 교체.
• 헤더(상관ID)는 별개: ongo.framework.web.correlation-header.
• 비교: 공통코드·메시지는 yml(컬럼·from·where·query·mode)로 스키마 커스텀 가능.

목표

사이트 규격(예 resultCode/resultMsg/body/guid, 또는 성공 코드 0000)에 Advice 전체 교체 없이 맞춘다.

안 A — yml 필드 매핑(단순 이름 변경)

ongo.framework.web.envelope:
  fields: { code: resultCode, message: resultMsg, data: body, trace-id: guid }
  success-code: "0000"        # 기본 OK
  omit-null: true
  extra: { timestamp: true }   # 선택 필드

• 구현: Advice 가 ApiResponse 대신 LinkedHashMap 을 매핑 순서대로 생성(또는 Jackson PropertyNamingStrategy/MixIn).
• 장점: 대부분 사이트를 설정만으로. 단점: 중첩 구조(header{}/body{})는 표현 한계.

안 B — SPI ApiResponseWriter(가칭)

public interface ApiResponseWriter {
    Object success(Object data, String traceId);
    Object error(String code, String message, Object detail, String traceId);
}

• Advice·예외 핸들러·Idempotency 재생·Outbound unwrap-envelope(역방향 read) 가 모두 이 SPI 를 경유.
• 기본 구현 = 안 A 매핑을 읽는 MappedApiResponseWriter. 중첩 구조 사이트는 빈 교체.

권장

B 를 뼈대로, 기본 구현이 A(yml)를 읽는 2단 구조. 기본값은 현재 JSON 과 바이트 동일하게(회귀 테스트). 기본 필드 레이아웃은 확정 대기(원우) — 확정 후 기본 매핑만 바꾼다.

영향 범위

ApiResponseBodyAdvice, 전역 예외 핸들러, IdempotencyKeyFilter 재생, Outbound decoder(unwrap), 프런트 공통 응답 파서, 개발 가이드 #web.

기준일: 2026-10-30
구현 위치:
- 코어 유틸: apps/demo-web/app/utils/file-transfer.ts
- 컴포저블: apps/demo-web/app/composables/useFileTransfer.ts
- 목업 파일 API: apps/demo-web/app/utils/file-mock.ts (/mock-api/files/**)
- 데모 화면: apps/demo-web/app/pages/files.vue
- 단위 테스트: apps/demo-web/tests/file-transfer.test.ts
연동: 백엔드 공통 파일 업로드/다운로드 API 부재로 브라우저 목업 핸들러 연동, 실제 BE 예시 연계 지원

1. 요구사항 및 목표

1. 파일 검증 (Validation) - 용량 제한 (maxSizeBytes, 기본 10MB) - 허용 확장자/MIME 타입 검증 (allowedExtensions, allowedMimeTypes) - 다중 파일 개수 제한 (maxFiles) - 검증 실패 시 명확한 에러 코드/메시지 반환 (FILE_TOO_LARGE, INVALID_EXTENSION, TOO_MANY_FILES)

2. 멀티파트 업로드 (Multipart Upload) - FormData 기반 멀티파트 바디 구성 (File / Blob / 추가 폼 필드) - 실시간 업로드 진행률(progress: 0~100%) 계산 및 상태(status: idle | validating | uploading | success | error) 관리 - XHR 또는 커스텀 업로더 어댑터를 통한 진행률 이벤트 추적 - 취소(abort) 지원

3. 다운로드 (Blob Download) - Content-Disposition 헤더 파싱: filename*=UTF-8''... (RFC 5987/6266) 및 filename="..." 형식 지원, 한글 파일명 완벽 디코딩 - 브라우저 다운로드 트리거: URL.createObjectURL(blob) 임시 <a> 태그 생성 후 자동 클릭 및 메모리 해제(revokeObjectURL) - 다운로드 진행률 및 오류 처리 (오류 발생 시 FE-02 HttpError 공통 예외 체계 연동)

4. 프레임워크 규격 준수 - 코어 로직(utils/file-transfer.ts)은 DOM/Nuxt에 최소한으로 의존하며 테스트 용이성 확보 - 컴포저블(composables/useFileTransfer.ts)을 통해 반응형 상태 제공 - 프레임워크(TS) / 업무 화면(JS, pages/files.vue) 분리 원칙 준수

기능별 코드 예제(SPI 한눈에 보기 표·복붙용 Java/yml·데모 위치·흔한 실수)는 CUSTOMIZATION-EXAMPLES.md, 코드생성 화면 단계별 사용법·REST API 표·트러블슈팅은 DEVTOOLS-GUIDE.md.

프레임의 모든 기능은 같은 세 단계로 바꾼다. 위에서부터 가벼운 방법이다.

1. yml — ongo.framework.<기능>.* 값으로 on/off·순서·코드·상태·크기를 바꾼다.
2. 슬롯(SPI) 빈 추가 — 프레임이 주워 쓰는 타입의 빈을 앱에 등록한다(기본은 그대로 두고 덧붙임).
3. 기본 빈 교체 — 같은 타입(또는 같은 이름) 빈을 앱에 등록하면 프레임 기본은 @ConditionalOnMissingBean 으로 물러난다. 후보가 둘 이상이면 쓸 빈에 @Primary.

데모 앱에 모든 예제가 있다. - yml 예제: ongo-framework-sc-demo/src/main/resources/application-custom.yml - 빈 예제: ongo-framework-sc-demo/src/main/java/com/ongosoft/framework/demo/custom/DemoCustomizations.java - 앱 인터셉터 예제: .../demo/DemoChainInterceptors.java - 확인 테스트: .../demo/DemoCustomizationTest.java (custom 프로필) - 실행: ./gradlew :ongo-framework-sc-demo:bootRun --args='--spring.profiles.active=custom'

예제 값·문구는 모두 임의의 데모 값이다. 앞으로 추가되는 기능도 이 문서에 같은 표 형식(yml / 슬롯 / 교체 / 데모 위치)으로 덧붙인다.

1. JSON 공통 (envelope·상관ID) — ongo.framework.web

2. 예외·메시지 — ongo.framework.exception, ongo.framework.message

3. 트랜잭션 — ongo.framework.transaction

4. 아웃바운드 REST (Feign) — ongo.framework.outbound

5. MyBatis — ongo.framework.mybatis (+ 표준 mybatis.*)

6. 요청 체인 (Filter·HandlerInterceptor) — ongo.framework.interceptor

체인: 상관ID 필터 → 접근로그 필터 → DispatcherServlet → MDC 인터셉터(order 0) → 앱 인터셉터…

MDC 키: traceId(상관ID), handler(컨트롤러#메서드). 로그 패턴 예: %5p [%X{traceId:-}] [%X{handler:-}].

7. 마스킹·XSS — ongo.framework.masking, ongo.framework.xss

체인: 상관ID 필터(H+10) → 접근로그 필터(H+20, 쿼리 마스킹) → XSS 파라미터 필터(H+30) → DispatcherServlet → [JSON 본문 XSS 정화(읽기 컨버터)] → 컨트롤러 → [응답 마스킹(쓰기 컨버터)]. 마스킹·XSS 컨버터는 MVC 에만 붙는다. 공용 ObjectMapper 와 Feign 인코더/디코더는 그대로라 아웃바운드 본문은 가려지거나 정화되지 않는다. 접근로그는 정화 전 원본 쿼리를 마스킹해서 남긴다.

데모 엔드포인트: GET /api/demo/secure/profile(마스킹), GET /api/demo/secure/search?q=·POST /api/demo/secure/notes(XSS), /api/demo/secure/raw/**(화이트리스트). 값은 모두 임의 샘플.

8. 검증·OpenAPI·해시 — ongo.framework.validation, ongo.framework.openapi, ongo.framework.hash

검증 흐름: @Valid/@Validated(그룹) → 위반 → 공통 예외 처리(ApiExceptionHandler) → 400 VALIDATION_FAILED + errors[{field, code, message}]. 메시지 코드는 MessageService 로 다국어 문구로 바뀐다. 본문(MethodArgumentNotValidException)과 파라미터 제약(HandlerMethodValidationException, ConstraintViolationException) 모두 같은 envelope 형식으로 응답한다. OpenAPI 는 앱이 springdoc-openapi-starter-webmvc-ui 를 넣었을 때만 켜진다. 노출은 활성 프로필이 openapi.profiles(기본 local, dev)에 있을 때만이며, prod 에서는 /v3/api-docs·Swagger UI 가 404 다.

HashService 는 일반 데이터 해시·무결성용이다. 사용자 비밀번호 저장은 BCrypt/Argon2 같은 전용 해시를 HashService 빈 교체로 쓰는 것을 권장한다.

데모 엔드포인트: POST /api/demo/validation/members(Create)·PUT /api/demo/validation/members/{id}(Update)·GET /api/demo/validation/range?n=(1~100), POST /api/demo/hash, local/dev 프로필의 /swagger-ui/index.html·/v3/api-docs. 값은 모두 임의 샘플.

9. 공통 코드·메시지·메타 적재 — ongo.framework.code, ongo.framework.message.jdbc, ongo.framework.meta-load

조회 흐름: 앱 → CodeLookupService(기본 CachingCodeLookup → JdbcCodeLookup 또는 yml MapCodeLookup). 메시지: MessageSourceService(테이블 켜면 JdbcMessageSource → 없으면 yml 맵 → 번들 → 폴백 → 코드). 공통 예외 문구도 같은 서비스를 쓰므로 메시지 표에 넣은 코드는 오류 응답 문구에도 바로 반영된다. 적재: 앱(고객사 팩)이 MetaLoadService 를 등록했을 때만 MetaLoadRunner 가 켜진다. 적재가 끝나면 Refreshable 구현(코드 캐시·메시지 표 캐시)을 모두 비운다. 같은 시점에 두 번 돌지 않는다. 코드 캐시는 프로세스 내 TTL 캐시(CachingCodeLookup)다. 공유 캐시가 필요하면 §10 의 DistributedCacheService 를 쓰는 CodeLookupService 구현으로 교체한다. 메타 적재 끝에는 §10 로컬 캐시도 비워진다.

yml code.jdbc / message.jdbc 는 테이블 하나만 받는다. 표가 여러 개이거나 조인·조건이 사이트마다 다르면 그 yml 을 늘리지 않고 SPI 빈으로 바꾼다. 수신 MESSAGE 기본 코드(INB_OK 등, §12.1) 문구도 같은 MessageSourceService 를 탄다. 기간계 코드 → 채널 메시지코드는 코드 표가 아니라 §18 맵핑 → 나온 키로 다시 이 메시지 표를 찾는다.

9.x 코드·메시지 모드별 yml 샘플 (SPI 없이 JDBC 내장)

# (A) yml 모드(기본) — DB 없이 yml/번들만
ongo.framework:
  code.groups.COLOR:
    - { code: R, name: 빨강, sort-order: 1 }
  message:
    default-locale: ko
    messages:
      "[order.partial-fail]": "{0}님 {1}건 중 {2}건 실패"   # 다중 인자 {0}{1}{2} — MessageFormat
---
# (B) JDBC 단일 테이블 모드
ongo.framework:
  code:
    jdbc: { enabled: true, table: ongo_common_code, group-column: code_group, code-column: code, name-column: code_name, use-column: use_yn, use-value: Y }
    cache: { enabled: true, ttl: 10m }       # 0 = 만료 없음(refresh/메타 적재 시에만 갱신)
  message:
    jdbc: { enabled: true, table: ongo_common_message, code-column: msg_code, locale-column: locale, text-column: msg_text }
    cache: { enabled: true, ttl: 10m }       # 코드 캐시와 같은 규칙: TTL 만료·Refreshable.refresh() 시 재조회, enabled:false 면 매 조회
---
# (C) JDBC 조인/사이트 SQL 모드 (SPI 빈 없이)
ongo.framework:
  code.jdbc: { enabled: true, mode: QUERY, query: "select d.cd c_code, d.nm c_name, d.ord c_sort from cm_grp g join cm_dtl d on d.grp_id = g.grp_id where g.grp_cd = ? order by d.ord" }
  message.jdbc:
    enabled: true
    from: "msg_m m join msg_d d on d.id = m.id"
    code-column: m.msg_cd
    locale-column: d.lang
    text-column: d.txt
    use-column: m.use_yn
    # 또는 query: "select ... m_code, ... m_locale, ... m_text from ..."

다중 인자: BusinessException(code, new Object[]{a, b, c}, ...) → ApiExceptionHandler → MessageSourceService.resolve 에서 yml·번들·메시지 표 문구 모두 {0}{1}{2} 치환(데모 ?args=a&args=b 와 같은 경로). 작은따옴표는 MessageFormat 규칙대로 '' 로 쓴다.

9.y 토큰 갱신·멱등 키

ongo.framework.idempotency:
  enabled: true
  header: Idempotency-Key
  ttl: 24h
  paths: ["/api/**"]      # 비면 전체 변경 요청

• POST /api/auth/refresh (AuthSessionService.refresh): 유효 세션 → 새 토큰 발급·기존 토큰 무효화. 만료면 401 auth.token-expired.
• 같은 키 재요청 → 저장 응답 재생(Idempotent-Replayed: true), 처리 중 → 409 idempotency.in-progress, 다른 본문 → 422 idempotency.payload-mismatch. 저장소 교체: IdempotencyStore 빈(기본 메모리).

데모 엔드포인트: GET /api/demo/codes/{group}(?parent= 하위), GET /api/demo/codes/{group}/{code}(없으면 404 + 메시지 표 문구), GET /api/demo/messages/{code}?name=(Accept-Language), POST /api/demo/meta/reload(기본 프로필은 422, custom 은 적재 결과). 표·데이터: ongo-framework-sc-demo/src/main/resources/schema.sql·data.sql — 값은 모두 임의 샘플.

10. 캐시·세션 — ongo.framework.cache, ongo.framework.session

저장소(Redis 등)는 정하지 않는다. 프레임은 서비스만 고정하고 기본 구현은 프로세스 내 맵이다(단일 인스턴스·데모용). 다중 인스턴스 운영에서는 DistributedCacheService·SessionStoreService 빈을 Redis 등 구현으로 등록해 교체한다 — 프레임 코드·의존성은 그대로.

• LocalCacheService — 파드 안 캐시(TTL + 최대 개수, 오래 안 쓴 항목부터 버림). 메타 적재 뒤 비움(기본 on).
• DistributedCacheService — 인스턴스 간 공유 캐시. 계약: get/put(기본 TTL 또는 지정, 0s = 만료 없음)/evict/clear/getOrLoad. 공통코드 그룹을 이 캐시에 싣는 예는 EXAMPLES H2.4. clear() 는 캐시 전체이므로 코드 키만 evict 한다.
• SessionStoreService — 서버 세션: create(동시 세션 한도 적용)/touch(유휴 만료 연장)/find/updateAttributes/invalidate/invalidateUser(강제 로그아웃)/sessionsOf. 인증 기능은 이 서비스로 로그인 세션을 다룬다.

데모 엔드포인트: PUT|GET|DELETE /api/demo/cache/{local|distributed}/{key}(본문 {"value":...}, 없으면 404 + 메시지 표 문구, 응답 impl 에 구현 이름), POST /api/demo/sessions({"userId":..,"attributes":{..}}, 한도 초과 REJECT 시 업무 오류 — custom 409), GET /api/demo/sessions/{id}(연장, 만료면 401), DELETE /api/demo/sessions/{id}, GET|DELETE /api/demo/sessions/users/{userId}(목록·강제 로그아웃). 코드: .../demo/CacheSessionDemoController.java.

11. 인증·인가·암호 — ongo.framework.auth, ongo.framework.crypto

프레임은 서비스·필터·가드 골격과 데모 구현만 둔다. 로그인 방식·사용자 저장소·역할/권한 표·IAM/SSO 연동은 앱 몫이고, 교체는 서비스 빈으로 한다(프레임 JAR 수정 없음). Spring Security 는 강제하지 않는다.

• AuthService — 자격 확인(authenticate). IdentityService — 사용자 ID → 주체(역할·클레임) 재조회. 기본 InMemoryUserAuth(yml 사용자, 비밀번호는 기동 시 HashService 로 해시 보관) 가 둘 다 구현한다.
• AuthorizationService — 권한 코드 확인. 기본 RoleBasedAuthorization(역할 → 권한 표, * = 전체).
• AuthSessionService — 로그인 = AuthService 검증 → SessionStoreService 세션 발급(세션 ID 가 토큰). 동시 세션 거절은 409 auth.session-limit.
• 인증 필터: 헤더(기본 Authorization: Bearer <토큰>)·쿠키 → SessionStoreService.touch → IdentityService → AuthContext.current(). 차단은 하지 않는다.
• 인가 가드: protected-paths 는 로그인 필요, @RequirePermission("코드") 는 로그인 + 권한. 미로그인 401 auth.unauthenticated, 권한 없음 403 auth.forbidden, 로그인 실패 401 auth.bad-credentials — 모두 공통 예외 → 공통 응답.
• FieldCryptoService — 필드 암복호. 기본 AesGcmFieldCrypto(AES-256-GCM, 키가 있을 때만 빈 생성). ChannelCryptoService — 구간 암호, 기본 NoOpChannelCrypto(TLS 위임). 비밀번호는 HashService.

데모 엔드포인트(POC 흐름): POST /api/auth/login({"id","password"} → data.bearer), GET /api/me, GET /api/demo/auth/reports(sample.report.read), DELETE /api/demo/auth/admin/users/{userId}/sessions(sample.admin.session, 강제 로그아웃), POST /api/auth/logout, POST /api/demo/crypto/field({"value"} 암복호 왕복). 샘플 계정: sample-user / sample-admin(비밀번호는 application.yml placeholder). 코드: .../demo/AuthDemoController.java.

12. 채널·표준전문 — ongo.framework.channel

기간계·대외(MCI / EAI / FEP) 고정길이 전문 송신 골격이다. 아웃바운드 REST(Feign)와는 별도 스택이며 섞지 않는다. 업무 코드는 ChannelService.send(채널, 인터페이스ID, 값 맵) 만 호출하고, 레이아웃·코덱·전송·구간 암호는 각각 서비스라 따로 교체한다(프레임 JAR 수정 없음).

• 흐름: TelegramLayoutService(레이아웃 조회) → TelegramCodecService.encode → ChannelCryptoService.encrypt → PhysicalTransportService.exchange → decrypt → decode → ChannelResponse(값·채널 유형·전송 이름·바이트 수).
• 기본 코덱 FixedLengthTelegramCodec: CHAR 왼쪽 정렬·공백 채움, NUM 오른쪽 정렬·0 채움, 길이는 문자셋 바이트 기준(MS949 한글 = 2바이트). 넘치면 자르지 않고 400 channel.encode.
• 기본 전송: http(전문 바이트를 application/octet-stream POST — MCI HTTP 형태), loopback(받은 전문 그대로 회신, 로컬·테스트용). TCP·WebT·AnyLink 등은 PhysicalTransportService 빈을 추가하고 yml 에 name() 을 적는다.
• TCP 수신(EAI 가 tcp.port 로 밀어 넣는 방식): 코어에 TCP 서버는 없다. 앱/선택 어댑터가 소켓을 열고 받은 바이트를 InboundTelegramProcessor.process(채널, 인터페이스ID, bytes) 로 넘기면 HTTP 수신과 같은 파이프라인을 탄다. 예제: 데모 DemoEaiTcpInboundListener(custom 프로필) — docs/CUSTOMIZATION-EXAMPLES.md §M5, 개발가이드 #eaitcp.
• 오류(공통 응답): 미등록 채널 404 channel.unknown, 미등록 인터페이스 404 channel.interface.unknown, 응답 길이 부족 502 channel.decode, 전송 실패 502 channel.send-failed.

데모 엔드포인트: POST /api/demo/channel/{channel}/{interfaceId}(본문 = 값 맵). 기본 프로필은 mci/eai/fep 모두 loopback 이고 샘플 인터페이스 SAMPLE0001(요청 acctNo 12·holder 20·amount NUM 13 → 응답 balance 자리에 amount 가 그대로 돌아옴). custom 프로필은 fep 이 sample-host(잔액 임의 고정값 회신)·MS949. 응답 data.response(값·transport·requestBytes), data.codec. 코드: .../demo/ChannelDemoController.java.

12.1 동기·비동기 송신 · 공통 수신 endpoint

• 비동기 송신: ChannelService.sendAsync(채널, 인터페이스ID, 값) → CompletableFuture<ChannelResponse>. 기본 DefaultChannelService 는 채널 전용 Executor ongoChannelExecutor(고정 풀, channel.async.pool-size 기본 4)에서 송신한다. 동기 send 는 그대로.
• 공통 수신: 앱이 InboundHandlerService 빈(interfaceId(), 선택 supports(channel), handle(InboundTelegram))을 하나 이상 등록하면 프레임이 수신 endpoint 를 연다. 흐름: 구간 복호 → 요청 레이아웃 decode → 처리기 → 응답 레이아웃 encode → 암호.
• 동기(기본): POST {path}/{channel}/{interfaceId} 본문 = 전문 바이트(application/octet-stream) → 응답 전문 바이트.
• 비동기: 같은 경로에 ?mode=async 또는 헤더 X-Ongo-Channel-Mode: async → 202 + 접수(receiptId, status=ACCEPTED). 처리는 ongoChannelExecutor 에서, 결과는 GET {path}/receipts/{receiptId}(DONE·응답 값 / FAILED·오류).
• 오류(공통 응답): 레이아웃 없음 404 channel.interface.unknown, 처리기 없음 404 channel.inbound.unknown, 접수 번호 없음 404 channel.inbound.receipt-unknown.
• 고객사 전용 수신 VO·어노테이션 파싱은 확장 모듈에서 InboundHandlerService·TelegramLayoutService 구현으로 얹는다(코어 금지).

수신 응답 MESSAGE: 업무가 message.stdMsgC/message.stdMsgCn 을 안 넣으면 공통 정상 코드를 채운다. BusinessException(또는 프레임 패키지 밖 CodedException)은 그 코드·문구(문구가 있으면 테이블이 덮지 않고, 없으면 MessageSourceService)를 쓴다. 그 외는 DB·타임아웃·검증·공통 에러로 나눈다. 코드·기본 문구·결과코드(header.procsRsDvC 기본 0/1/8/9)는 시스템마다 바꾼다. 삼카 코덱은 건수가 1 이상일 때만 코드·내용 반복부(기본 10+100, samsung-card.standard-telegram.message-code-length/message-text-length)를 붙인다. 건수 0이면 기존 HEADER+MESSAGE 2바이트+BODY+@@ 길이를 유지한다.

ongo.framework.channel.inbound-message:
  enabled: true
  success-code: INB_OK          # 기본은 삼카 반복부 코드 길이(10) 안에 둔다. 더 긴 체계면 message-code-length 도 늘린다
  error-code: INB_ERR
  data-access-code: INB_DB
  timeout-code: INB_TMO
  validation-code: INB_VAL
  success-text: 정상 처리되었습니다
  error-text: 처리 중 오류가 발생했습니다
  data-access-text: 데이터 처리 중 오류가 발생했습니다
  timeout-text: 처리 시간이 초과되었습니다
  validation-text: 입력값을 확인해 주세요
  result-field: header.procsRsDvC    # 비우면 결과코드를 넣지 않음
  success-result: "0"
  business-result: "1"
  timeout-result: "8"
  error-result: "9"

데모: POST /api/demo/channel/{channel}/{interfaceId}/async(비동기 송신), POST /framework/channel/inbound/{channel}/SAMPLE0001(수신 동기·?mode=async). 테스트: ChannelAsyncInboundDemoTest.

채널별 송신 예제(MCI / EAI / FEP) — 업무 코드는 채널 이름만 바꾼다. 문자셋은 채널 설정으로 자동.

ongo.framework.channel:
  charset: UTF-8                 # mci/eai
  charset-defaults: { fep: EUC-KR }
  channels:
    mci: { type: MCI, transport: http, url: http://mci-host/gw }
    eai: { type: EAI, transport: http, url: http://eai-host/gw }
    fep: { type: FEP, transport: http, url: http://fep-host/gw }   # charset: MS949 처럼 개별 지정 가능

channel.send("mci", "SCIF0001", Map.of("cardNo", no, "header.rcvSysDvC", "MCI"));          // UTF-8
channel.send("eai", "SCIF0002", Map.of("cardNo", no, "header.rcvSysDvC", "EAI"));          // UTF-8
ScTelegramContext.with(Map.of("rcvSysDvC", "FEP", "stdIfId", "SCIF0003"), Map.of(),
        () -> channel.send("fep", "SCIF0003", Map.of("cardNo", no)));                       // EUC-KR

데모: POST /api/demo/channel/{mci|eai|fep}/{interfaceId}(응답 data.charset), 수신 시연 POST /api/demo/channel/{mci|eai|fep}/SAMPLE0001/inbound(값 → 채널 문자셋 요청 전문 → 공통 수신 처리기 → 응답 decode). 쇼케이스 화면(/) 「삼카 확장」 카드에 채널별 버튼. 테스트: ChannelPerChannelDemoTest.

채널별 수신 URL: 전용 컨트롤러 없이 공통 경로 하나로 MCI/EAI/FEP 를 받는다 — POST /framework/channel/inbound/mci/{interfaceId}, .../eai/{interfaceId}, .../fep/{interfaceId} ({channel} = InboundHandlerService.supports(channel) 판정값). 동기 응답은 인코더 byte[](application/octet-stream), ?mode=async 는 JSON 접수. TCP 수신·채널별 별도 path 는 운영 연동 스펙 확정 후.

12.2 채널·전문 규칙 레퍼런스 (2026-10-28, #115·#116 기준)

역할 분담: 이 절은 규칙·키·우선순위·케이스 를 정리한다. 복붙용 완전한 코드는 CUSTOMIZATION-EXAMPLES.md §K 에 있다.

12.2.1 방향 용어 — 「송신」과 「수신 응답」

12.2.2 채널별 문자셋(charset) — MCI / EAI / FEP

결정 순서(먼저 찾은 값): channel.channels.<이름>.charset → channel.charset-defaults.<type 소문자 또는 이름> → channel.charset.

• 같은 채널 문자셋이 송신 encode → 응답 decode, 수신 decode → 수신 응답 encode 네 단계 모두에 쓰인다(TelegramCodecService.withCharset). 수신 응답만 다른 문자셋으로 나가는 일은 없다.
• 필드 길이는 바이트 기준이다. 같은 holder 20바이트 필드에 한글 이름은 UTF-8 6자 / EUC-KR 10자까지 들어간다. 넘치면 잘리지 않고 400 channel.encode.
• 데모 응답 data.charset 으로 실제 적용 문자셋 확인.

12.2.3 HEADER/MESSAGE 값 병합 — null·"" vs 공백 " "

우선순위(위가 이김):

주의: 「값을 지우고 싶다」 는 "" 가 아니라 " " 다. "" 는 디폴트가 다시 들어간다. stdEtxtLnth(전체 길이) 는 항상 자동 계산되어 덮을 수 없다.

12.2.4 수신 응답 헤더 에코 — 「받은 값을 그대로 돌려준다」

InboundTelegramProcessor 가 응답 encode values 에 @direction=response(처리기가 이미 넣었으면 유지) 와 @request(원 요청 decode 맵)를 넣고, 표준전문 코덱이 아래를 응답 HEADER 에 복사한다.

에코는 순위 3이므로 처리기 반환 맵의 header.x(순위 1) 로 개별 필드를 다시 덮을 수 있다(특수 연동만).

12.2.5 표준전문진행번호 stdEtxtPrgNo — hop 규칙 (#116)

전문이 전문을 호출하는 중첩(nested) 호출 에서 몇 번째 hop 인지 표시한다.

예: A(송신 00) → 우리 수신 → 우리 응답 01. 우리 처리기가 안에서 또 송신하면 그 송신은 새 거래이므로 00 에서 시작한다(상위 hop 을 이어 붙이려면 ScTelegramContext.with(Map.of("stdEtxtPrgNo", …)) 로 명시).

12.2.6 실 적용 케이스

13. 로깅·관측 — ongo.framework.logging

앱 로그는 logback 기본 그대로 두고, 그 위에 슬롯 로그(접근·감사·오류·업무 등 이름 붙은 로그)와 외부 연계 브리지, 앱별 로거 레벨 관리를 얹는다. k8s(ELK/Loki/Grafana)와 IaaS(파일·콘솔)를 같은 업무 코드로 커버한다 — 업무 코드는 StructuredLogService.log(슬롯, 메시지, 필드 맵) 만 호출.

• 흐름: 슬롯 조회(미등록 404 logging.slot.unknown) → 꺼진 슬롯이면 생략 → MDC 상관ID(traceId, 1장) 첨부 → 등록된 모든 LoggingBridgeService 로 송출. 한 브리지가 실패해도 경고만 남기고 업무는 계속.
• 기본 브리지 slf4j: 로거 ongo.log.<슬롯> 에 메시지 k=v ... — logback appender(파일·콘솔·ELK 등)와 기존 %maskedMsg 마스킹(7장)이 그대로 적용.
• 기본 슬롯: access·audit·error(필수), biz(꺼짐). 필수 슬롯은 yml 로 enabled: false 를 줘도 꺼지지 않는다(고객사 필수 로그 목록 = required-slots).
• 레벨: levels 는 기동 시 적용, LogLevelService 로 재기동 없이 조회·변경(Spring Boot LoggingSystem). 잘못된 레벨 400 logging.level.invalid.

데모 엔드포인트: GET /api/demo/logging/slots, POST /api/demo/logging/slots/{slot}(본문 = 필드 맵, 응답 data.bridges = 실제 송출 브리지), GET|PUT /api/demo/logging/levels/{logger}?level=DEBUG. 운영에서는 레벨 변경 엔드포인트를 11장 인가 뒤에 둔다. 코드: .../demo/LoggingDemoController.java.

14. 개발 지원 웹툴·코드생성 — ongo.framework.devtools

모듈 ongo-framework-devtools 를 의존하면 앱 안에 /framework-devtools(화면)·/framework-devtools/api(API)가 붙는다. profiles(기본 local·dev) 중 하나가 활성일 때만 AutoConfig 가 켜지고, 화면도 정적 리소스가 아니라 컨트롤러가 내주므로 prod 에는 아무것도 노출되지 않는다.

• 흐름: 정의서 원문 → SpecParseService(유형별) → 공통 SpecModel/FieldSpec → CodeGenService → CodeGenDecorator 들이 import·클래스/필드 어노테이션 덧붙임 → 미리보기 또는 GeneratedSourceWriter 가 소비 앱 소스 트리에 쓰기.
• 기본: 유형 json(항상 남음), 생성기 = Java record(또는 getter/setter 클래스), 데코레이터 validation(required → @NotNull, 문자열 length → @Size(max)).
• 쓰기 보호: 출력 루트 밖 경로 거부, 기존 파일은 overwrite=true 일 때만 덮어씀(아니면 SKIPPED_EXISTS). 필드명·패키지는 Java 식별자 검사.
• FieldSpec.attributes/SpecModel.attributes 는 프레임이 해석하지 않는 자유 속성 — 고객사 파서가 채우고 고객사 데코레이터가 읽는다.

순수 코어만 쓰는 앱은 기본 설정(json·validation)으로, 고객사 확장 모듈을 의존하는 앱은 그 모듈이 등록한 파서·데코레이터가 함께 뜬다(앱 코드 변경 없음).

JSON 정의서 예: {"name":"SampleOrder","kind":"DTO","package":"com.example.sample","fields":[{"name":"orderNo","type":"STRING","length":12,"required":true,"description":"주문번호","attributes":{}}]} — 타입 별칭 STRING·INT·LONG·DECIMAL·NUM·BOOLEAN·DATE·DATETIME 또는 FQCN. 배열이나 {"specs":[...]} 로 여러 개.

화면 배치·버튼별 동작은 DEVTOOLS-GUIDE.md 가 정본이다(공통 I/O 정의서 카드: 입력 유형 → 불러오기·펼침·편집 → 카드 하단 덮어쓰기/스웨거/미리보기/소스에 쓰기. 업무단위 C/S/R 은 메소드 미정의 시 list·get·create 기본 뼈대 — 가이드 §8.2).

데모 엔드포인트(local/dev, 또는 custom): GET /framework-devtools(화면), GET /framework-devtools/api(유형·데코레이터·출력 위치), POST /framework-devtools/api/parse/{type}, POST /framework-devtools/api/generate/{type}?write=false&overwrite=false(본문 = 정의서 원문, 응답 data.files·data.written). 미등록 유형 404 devtools.spec.unknown, 형식 오류 400 devtools.spec.invalid/devtools.codegen.invalid. 코드: ongo-framework-devtools/.../DevtoolsController.java, 데모 .../demo/custom/DevtoolsDemoCustomizations.java.

14.1 정의서 → 동적 VO 생성·컴파일·로드 → 전문 (local/dev 전용)

hyeri_adapter 방식의 코어 파이프라인(com.ongosoft.framework.devtools.dynamic): 정의서 원문 → SpecParseService → JavaSourceGenerator(활성 데코레이터 + TelegramFieldCodeGenDecorator) → DynamicVoCompiler(JDK javax.tools javac, work-dir/<buildId>/{src,classes}, 별도 URLClassLoader) → VoLayoutResolver(VO 어노테이션 length → TelegramLayout) → TelegramCodecService 인코딩 → PhysicalTransportService 송수신 → 디코딩. 코어 기본 해석기는 @TelegramField(order, length[, num]). 고객사는 파서(SpecParseService)·데코레이터·VoLayoutResolver·코덱만 갈아끼운다(코어에 고객사 로직 없음).

• 동적 생성·컴파일·클래스로더는 운영·일반 런타임 WAS 에서 금지 — 개발툴 프로세스(local/dev)에서만. 결과는 소스로 내려받아 앱/배치에 반영한다.
• 로컬 = 코드생성 + 전문 테스트, 서버(dev WAS) = 전문 테스트만. 코드생성 쓰기는 codegen.profiles(기본 [local])에서만. 코드생성 codegen.output-dir(프로젝트 src/main/java 직접 또는 안전한 별도 경로 — 둘 다 허용)과 전문 테스트 dynamic.work-dir 은 다른 경로(겹치면 기동 실패). 서버 work-dir 은 런타임 WAS 가 쓸 수 있는 폴더.
• 기존 VO 우선(dynamic.prefer-existing-vo: true): ① 네이밍 규칙명 ② 정의서 생성 FQCN 순으로 클래스로더 로드 → 있으면 그 VO(컴파일 안 함, 응답 vos[].existing=true), 없으면 동적 생성·컴파일.
• devtools AutoConfig 와 같이 devtools.profiles 에서만 켜진다. prod 에서 런타임 컴파일은 하지 않는다(운영은 생성 소스를 커밋·빌드한 VO + 14장/16장 레이아웃).
• JDK 필요(JRE 면 동적 VO 컴파일 실패). 컴파일 classpath = java.class.path + extra-classpath — fat jar 로 띄운 개발 서버는 extra-classpath 에 프레임/고객사 jar 를 넣는다.
• 개발 서버는 앱 폴더가 읽기 전용일 수 있으므로 work-dir 을 쓰기 가능한 경로로 둔다(환경변수로 주입 권장). 빌드마다 하위 폴더가 쌓이니 주기적으로 지운다.

14.2 유연 코드생성(코어) — IN/OUT 직접 정의 · OBJECT/ARRAY · 컬럼 기본 속성

코어 JsonSpecParser·JavaSourceGenerator 가 지원한다(삼카 등 고객사는 레이아웃·파서 확장만).

{"name":"CARD01","package":"com.acme.tlg",
 "in":{"fields":[{"name":"cardNo","type":"STRING","length":16,"required":true,"encrypted":true,"masking":"CARD_NO"}]},
 "out":{"fields":[
   {"name":"owner","type":"OBJECT","fields":[{"name":"name"},{"name":"age","type":"INT"}]},
   {"name":"histories","type":"ARRAY","fields":[{"name":"amount","type":"LONG"}]},
   {"name":"tags","type":"ARRAY<STRING>"},
   {"name":"addr","type":"OBJECT","attributes":{"ref":"com.acme.Addr"}}]}}

• in/out → CARD01In·CARD01Out(direction REQUEST/RESPONSE, interfaceId=name, 네이밍 규칙과 같은 이름). attributes.className 으로 이름 직접 지정 가능.
• OBJECT+하위 fields → 중첩 static 타입, ARRAY+fields → List<중첩타입>, ARRAY<T>/T[] → List<T>, attributes.ref → 기존 타입.
• 컬럼 기본 속성: 자료형(type)·길이(length)·scale·required·encrypted(true|정책명 → @Encrypted)·masking(true|규칙명 → @Masked). 표식 어노테이션은 코어 core.security — 실제 암복호화·마스킹 연결은 앱(TypeHandler·MaskingService 등).
• 컬럼 속성 처리 SPI core.security.ColumnAttributeService(기본 no-op 빈 ongoColumnAttributeService, @ConditionalOnMissingBean → 앱 빈으로 교체): ColumnMeta.of(field|recordComponent, length) 로 자료형·길이·@Encrypted·@Masked 를 읽어 인터셉터(요청/응답 beforeResponse — 마스킹)·전문 인코더/디코더(beforeEncode 암호화 / afterDecode 복호화)가 별도 처리. 키·규칙은 앱 정책. 호출 지점·순서는 바로 아래 자동 연결 표(ColumnValues) 참고(§16.2).
• 자동 연결(코어·스타터) — 앱이 ColumnAttributeService 빈 하나만 등록하면 아래가 모두 그 빈을 호출(기본 no-op 이면 동작 불변). 공통 규칙 core.security.ColumnValues: SPI 가 값을 바꾸면 그 값 → 그대로면 @Encrypted 컬럼만 FieldCryptoService → 없으면 원값.

직접 생성 시: new FixedLengthTelegramCodec(cs, () -> cas) / .withColumns(..), new EncryptedFieldInterceptor(crypto, columns), new MaskingJacksonModule(masking, columns). - 엑셀 IN/OUT 업로드는 구현됨: 컬럼↔어노테이션 매핑 → I/O 트리 편집 → 생성 코드 미리보기 → 쓰기(§14.4).

API: POST /framework-devtools/api/dynamic/{type} 본문 {"content":"정의서 원문","interfaceId":"(생략 시 첫 VO)","values":{...},"transport":"loopback"} → data.buildId·data.dir·data.vos[].fields[](offset·length·type)·data.exchange(values 생략 시 로드·레이아웃만). 형식 오류 400 devtools.dynamic.invalid, 컴파일·통신 실패 500 devtools.dynamic.failed.

14.3 DB VO 암호화·응답 DTO 마스킹 (코어 SPI + 기본 동작)

SELECT 결과 자동 복호화: EncryptedResultInterceptor(MyBatis ResultSetHandler.handleResultSets)가 결과 VO(가변 클래스·중첩·List/Map)의 @Encrypted String 을 FieldCryptoService.decrypt. 복호화 실패(평문 레거시)는 원값 유지. 끄기 ongo.framework.mybatis.plugins.field-decryption=false.

코어(starter)만으로 동작하며, 삼카 확장 모듈은 교체·확장 예시만 둔다(데모앱은 호출·확인만).

전문 코덱 측은 §14.2 ColumnAttributeService · §16.2. 전체 요약은 §18. 예시: ongo-framework-samsung-card security.ScCardHolderRow(@Encrypted) · ScCardHolderView(@Masked) → 데모 POST /api/demo/column-security(ShowcaseDemoTest).

역할 분리: 코어 = SPI + 기본 동작(삼카 없이 동작) · 삼카 확장 = 교체/확장 기본 예시 · 데모앱 = 그 기능 호출·확인. 데모 쇼케이스 페이지 http://localhost:8080/ (코어/삼카/개발툴 카드별 ▶ 실행, 개발툴은 local 프로파일).

14.4 I/O 가져오기·펼침 — 기존 VO / Sample JSON / 정의서 / 엑셀

POST /framework-devtools/api/import/{source} → 공통 I/O 트리(편집 후 코드생성). 화면: devtools “가져오기/펼침”.

코어 기본 엑셀 양식 (헤더 행 자동 탐지, 선택 #package com.x 행):

본문: {"file":"<xlsx base64>","mapping":{"headerRow":1,"columns":{"name":"FIELD","length":"D"},"sheets":["IO*"]}} — columns 값은 헤더명 또는 열 문자, 기본 별칭보다 우선. TSV(#sheet 이름 구분)도 허용.

삼카 sc-excel (ScInterfaceExcelSpecParser extends ExcelSpecParser): 표지·문서관리정보·인터페이스정의서·소스IO정의서·타켓IO정의서 형식. IO 시트의 *** INPUT 항목 ***/*** OUTPUT 항목 *** 구간 → in/out, IO ID(SIO_APC_ISS_00026_I) → SioApcIss00026In/Out, 영문 필드명 FRG_BUR_C → frgBurC(원명은 설명에), 인터페이스ID 는 인터페이스정의서 시트에서. {ID}_IN/_OUT 시트 짝도 지원. 정의서는 BODY 만 정의한다 — 헤더/공통메시지는 코덱이 붙인다(§16.2).

데모 확장·커스텀 카탈로그: 데모의 모든 SPI 교체 예시(DemoCustomizations·DevtoolsDemoCustomizations·DemoExtensionMocks)와 Redis·MQ(Rabbit/Kafka)·ES 목업은 코어 개발가이드 /framework-devtools/guide#demoext·#extmock 및 CUSTOMIZATION-EXAMPLES §M 참고. 코어에는 SPI 계약만 있고 클라이언트 의존성은 없다(일반 공통, 삼카 비의존).

15. 공통 배치 — ongo.framework.batch

ongo-framework-batch(Spring Batch 5, Boot BatchAutoConfiguration 위). 프레임은 골격(런처·실패 정책·모니터링 훅·개발툴 화면), 잡·스텝·Reader/Writer·업무 정책은 앱.

개발툴(devtools.profiles 에서만): GET /framework-devtools/batch(화면), GET /framework-devtools/api/batch/jobs, POST .../jobs/{name}/run(본문=잡 파라미터 Map), GET .../jobs/{name}/executions?limit=. 오류: 404 batch.job.unknown, 403 batch.job.not-allowed, 409 batch.job.launch-failed.

잡 스켈레톤 생성(개발툴): POST /framework-devtools/api/generate-batch(?write=true&overwrite= 로 출력 루트에 쓰기, 화면 「배치 잡 스켈레톤 생성」). 본문 {name, packageName, chunk(100), reader: list|custom, itemType(String), outputType, channel, interfaceId} → {Name}JobConfig.java(Job {name}Job·chunk Step·policy.apply·Reader/Processor/Writer TODO). channel+interfaceId 지정 시 Processor 가 ChannelService.send 호출(확장 비의존). 생성 소스는 batch 를 의존한 앱에서 컴파일(데모 테스트가 실제 컴파일 검증). 오류 400 devtools.codegen.invalid.

배치 프로젝트 스켈레톤 생성(개발툴): POST /framework-devtools/api/generate-batch-project(?write=&overwrite=, 화면 「프로젝트 미리보기」, 수정본 저장·zip 은 /api/files/save|download 재사용). 본문 {projectName, packageName(com.example.batch), frameworkVersion(0.1.0-SNAPSHOT), repositoryUrl(사내 Nexus, 선택), samsungCard, job:{generate-batch 와 동일}} → {projectName}/ 아래 settings.gradle·build.gradle(Boot 3.5.6, Java 21 toolchain, ongo-framework-batch [+samsung-card], H2 runtime)·BatchApplication·application.yml(spring.batch.job.name, 실패정책 예)·{Job}JobConfig(패키지 .job)·README.md·.gitignore. - 한계(최소 범위): Gradle 단일 모듈만, Gradle wrapper 미포함(gradle wrapper), 프레임워크 아티팩트는 mavenLocal/사내 Nexus 가정, 채널 transport·운영 DB 는 TODO 주석. 데모 테스트는 생성 Java 소스 컴파일까지 검증(생성 프로젝트의 Gradle 빌드 실행은 미검증).

별도 배치 데모: 모듈 ongo-framework-batch-demo(비웹 Boot 배치, ongo-framework-batch + ongo-framework-samsung-card 의존, WAS 데모와 분리) — scCardLimitSyncJob(SCDEMO01 loopback), 실행 ./gradlew :ongo-framework-batch-demo:bootRun --args='--spring.batch.job.name=scCardLimitSyncJob cards=...', 모듈 README 참고. 배포(publish) 대상 아님.

OnGo DevOps 개발 배포: docker/(앱 저장소 쪽 이미지 설정) — docker/generic-demo(APP ongo-generic-demo, 제니 dev WAS 12011), docker/sc-demo(APP ongo-sc-demo, 제니 dev WAS 12012, 배치 데모는 compose profile batch 로 1회 실행). 포트·환경은 OnGoDevOps config/development/DOCKER/*.properties, docker/README.md 참고.

15.1 배치 잡에서 삼카 전문 통신

• 공통 배치는 삼카 비의존. 앱(데모)이 ongo-framework-batch + 채널(starter) + ongo-framework-samsung-card 를 함께 의존한다.
• 배치는 웹이 아니어도 같은 SPI: ChannelService.send/sendAsync + 삼카 TelegramLayoutService(@ScTelegram)·코덱.
• 데모 demo.batch.ScCardLimitSyncJobConfig: 카드번호 목록 → ChannelService.send("mci","SCDEMO01",..)(loopback) → 결과 Writer, 형식 오류는 skippable 로 건너뜀.

16. 고객사 확장 모듈(삼카) — ongo.framework.samsung-card

모듈 ongo-framework-samsung-card 는 코어·스타터 SPI 위에 삼카 전용 전문 VO 어노테이션·레이아웃·개발툴 훅만 얹는 확장(골격)이다. 코어에는 삼카 VO·레이아웃이 없다. 의존성만 추가하면 SamsungCardAutoConfiguration 이 켜지고, 데모 앱이 이 모듈을 의존한다. 어노테이션 이름·정의서 양식은 placeholder — 실제 삼카 규격은 입사 후 이 모듈 안에서만 바꾼다.

• 어노테이션 레이아웃: VO 에 @ScTelegram("인터페이스ID")(응답 VO 는 direction = RESPONSE), 필드/레코드 컴포넌트에 @ScField(order, length[, type = NUM][, name]). base-packages 를 스캔해 AnnotatedTelegramLayouts(TelegramLayoutService, 빈 samsungCardTelegramLayoutService, @Primary)를 만든다. 어노테이션에 없는 ID 는 프레임 기본 yml 레이아웃(ongoTelegramLayoutService)으로 넘긴다. 중복 VO·order 중복·응답만 있는 ID·@ScField 없는 VO 는 기동 시 실패.
• 개발툴 훅(앱이 ongo-framework-devtools 도 의존할 때만): 정의서 유형 samsung-card-io(ScIoSpecParser), 데코레이터 samsung-card(ScCodeGenDecorator) 를 추가 등록 — 기본 json·validation 은 그대로 남는다. 삼카 스펙(속성 interfaceId 있음)이면 생성 VO 에 @ScTelegram·@ScField 를 붙이고, 아니면 생성물을 건드리지 않는다(코어 기본).

samsung-card-io placeholder 양식(파이프 구분, // 주석, 블록 여러 개):

#interface|SCDEMO02|ScDemoReq|VO|com.example.sc
cardNo|STRING|16|Y|카드번호
#interface|SCDEMO02|ScDemoRes|VO|com.example.sc|RESPONSE
resultCode|STRING|2|Y|결과코드

• 코드조각 정의서(samsung-card-snippet, ScCodeSnippetSpecParser): hyeri 산출물·asis 코드에서 레이아웃을 뽑는다. 블록 헤더 // #interface|ID|Name|kind|pkg[|RESPONSE] 다음에 (A) @ChannelAnnotation(order, dataType, length, scale…)/@ScField 필드 선언(order 정렬, NUMERIC → LONG/DECIMAL) 또는 (B) x = WebtUtil.getString(buf, offset, len)(offset 정렬, 빈틈·겹침은 오류, parseInt/parseLong → LONG). ARRAY(그리드)는 아직 미지원 오류. ScFieldLayoutResolver 가 동적 VO 의 @ScField 로 레이아웃을 만든다(14.1 파이프라인). 이름 samsungCardSnippetSpecParser / samsungCardVoLayoutResolver 빈으로 교체.

데모: ScDemoCardInquiry(SCDEMO01, 요청 cardNo 16 + inquiryDate 8, 응답 cardNo 16 + limitAmount 8 NUM) — POST /api/demo/channel/mci/SCDEMO01 로 loopback 왕복, 기존 yml SAMPLE0001 도 그대로. 코드: ongo-framework-samsung-card/.../SamsungCardAutoConfiguration.java, 데모 .../demo/samsungcard/ScDemoCardInquiry.java, 테스트 SamsungCardExtensionDemoTest.

배포: 17장(OnGoSoft Nexus publish · jar 직접 전달).

16.1 인터페이스 ID → VO 파싱 → TelegramLayout (네이밍 규칙)

AnnotatedTelegramLayouts(삼카 TelegramLayoutService) 조회 순서: ① layout.base-packages 스캔한 @ScTelegram VO ② 인터페이스 ID 네이밍 규칙으로 클래스로더 로드 → @ScField 파싱(캐시) — {package}.{interfaceId}In(요청, 필수)·...Out(응답, 선택) ③ 프레임 기본 yml(fallback-to-default).

개발툴 전문 테스트의 devtools.dynamic.vo-naming 과 같은 규칙을 쓰면, 코드생성 산출물(CARD01In/Out)이 운영 레이아웃·전문 테스트 양쪽에서 그대로 잡힌다.

16.2 삼카 표준전문 코덱 — HEADER + MESSAGE + BODY (hyeri_adapter 동일)

ScStandardTelegramCodec implements TelegramCodecService — hyeri_adapter AbstractMessageBroker 조립 순서: [전문공통헤더부 850B(ChannelHeader 57필드)] + [전문공통메시지부 2B] + [개별메시지부 BODY] + "@@", 헤더 stdEtxtLnth(8) = 전체 길이. fields 인자는 BODY 레이아웃(정의서), 헤더/메시지 값은 header.이름/message.이름 키. decode 결과도 같은 접두. @Encrypted 바디 필드: codec.encrypted(ScStandardTelegramCodec.encryptedOf(Vo.class)) → encode 전 FieldCryptoService.encrypt, decode 후 decrypt. DB 저장 시 암호화는 §14.3 인터셉터 그대로.

바이트 배치 (BODY 47B 예 → 전체 901B):

빈 등록 (opt-in, 충돌 없음):

• 타입을 아는 호출: 코어 TelegramCodecService.encode(Class, fields, values)/decode(Class, fields, bytes)(기본 = 타입 무시). 삼카 코덱은 VO 클래스의 @Encrypted 필드를 자동 합산하므로 동적 전문테스트에서 따로 지정할 필요 없음.
• charset() 도 코어 인터페이스 기본 메서드(모르면 null) — 개발툴이 문자열 표시에 사용.
• 테스트: ScStandardTelegramCodecTest(901B·00000901·암호화·왕복·CAS 연동), SamsungCardAutoConfigurationTest.standardTelegramCodec.

17. 배포 — OnGoSoft Nexus publish · jar 직접 전달

게시 대상은 ongo-framework-core·ongo-framework-starter·ongo-framework-devtools·ongo-framework-samsung-card(데모 제외). 좌표 com.ongosoft.framework:<모듈>:<version>(현재 0.1.0-SNAPSHOT), 본 jar + -sources.jar + POM. POM 에는 Spring Boot/Cloud BOM 으로 정해진 의존성 버전이 실제 값으로 적힌다. 설정: 루트 build.gradle → gradle/publish.gradle.

OnGoSoft Nexus — releases https://nexus.ongosoft.com/repository/maven-releases/, snapshots https://nexus.ongosoft.com/repository/maven-snapshots/ (원우 확인 2026-10-26). OnGoDevOps CI/CD 인벤토리·기존 framework-core 와 같은 Nexus(조회용 maven-public/ 도 있음). 자격증명이 없으면 게시 태스크는 네트워크 접속 전에 안내 메시지로 실패한다.

자격증명·URL 은 저장소에 커밋하지 않는다. ~/.gradle/gradle.properties(개인) 또는 CI 환경변수만:

자격증명 두 경로(값은 어디에도 커밋하지 않음):

• 로컬 개발: 사용자 폴더 ~/.gradle/gradle.properties 에 nexusUsername / nexusPassword (아래 예시).
• 개발 빌드(Jenkins): GitHub/Jenkins credential ID nexus-credentials → 환경변수 NEXUS_USERNAME / NEXUS_PASSWORD 로 주입. 예:

// Jenkinsfile
withCredentials([usernamePassword(credentialsId: 'nexus-credentials',
                                  usernameVariable: 'NEXUS_USERNAME', passwordVariable: 'NEXUS_PASSWORD')]) {
    sh './gradlew publishAllPublicationsToOngoNexusRepository'
}

# ~/.gradle/gradle.properties (예시 — 값은 본인 것으로)
# URL 은 기본값이 있으므로 자격증명만 (framework-core 와 같은 키)
nexusUsername=<user>
nexusPassword=<token>

• 게시: ./gradlew publishAllPublicationsToOngoNexusRepository — 버전이 -SNAPSHOT 이면 snapshots, 아니면 releases URL. 자격증명이 없으면 실패(네트워크 접속 전).
• 소비 앱:

repositories {
    mavenCentral()
    maven {
        url = uri('https://nexus.ongosoft.com/repository/maven-releases/')
        credentials { username = findProperty('nexusUsername'); password = findProperty('nexusPassword') }
    }
}
dependencies {
    implementation 'com.ongosoft.framework:ongo-framework-starter:0.1.0'
    implementation 'com.ongosoft.framework:ongo-framework-samsung-card:0.1.0'   // 삼카 확장
    developmentOnly 'com.ongosoft.framework:ongo-framework-devtools:0.1.0'      // 또는 local/dev 프로필 전용
}

17.1 고객사 Nexus 가 없을 때 — jar 직접 전달

1. 권장: 파일 Maven 저장소째 전달. ./gradlew publishAllPublicationsToLocalDistRepository → build/dist-repo/ (POM 포함, 전이 의존성 유지). 이 폴더를 그대로 넘기고 앱에서:

repositories { mavenCentral(); maven { url = uri("$rootDir/libs/ongo-repo") } }   // dist-repo 를 libs/ongo-repo 로 복사
dependencies { implementation 'com.ongosoft.framework:ongo-framework-samsung-card:0.1.0-SNAPSHOT' }

2. 최후: files(...). jar 만 받는 경우(./gradlew jar → 각 모듈 build/libs/*.jar). POM 이 없어 전이 의존성이 안 따라오므로 앱이 Spring Boot 스타터 등을 직접 선언해야 한다.

dependencies {
    implementation files('libs/ongo-framework-core-0.1.0.jar', 'libs/ongo-framework-starter-0.1.0.jar',
                         'libs/ongo-framework-samsung-card-0.1.0.jar')
    implementation 'org.springframework.boot:spring-boot-starter-web'   // 프레임이 api 로 끌던 것들 직접 선언
}

데모 앱은 같은 저장소라 project(':...') 로 의존한다(위 두 방식은 별도 앱용 예시).

17.2 데모 배포 — Boot3/Boot2 · JDK 21/17/11/8 (AA12~15)

Nexus 게시와 별개로, 데모는 OnGoDevOps CI/CD 가 저장소 소스로 이미지를 빌드해 개발 서버(제니)에 올린다. 상세: docker/README.md, OnGoDevOps README 4.4·6.1.

• Boot2 데모: bootJar 대신 installDist. 로컬 ./gradlew :ongo-framework-boot2-demo:installDist 후 ongo-framework-boot2/demo/build/install/ongo-boot2-demo/bin/ongo-boot2-demo(JAVA_HOME=JDK 8).
• Boot2 프레임 jar(ongo-framework-boot2-core-web)와 공통 ongo-framework-common 은 현재 Nexus 게시 대상이 아니다(고객사 jar 분리 PoC 는 MULTI-JDK-PORTING TODO).
• 런타임은 JDK(JRE 아님) — 개발툴 동적 VO 가 javac 를 쓴다. GET /api/runtime 의 javac=true·workDir.writable=true 확인.
• 공개 도메인(OnGoDevOps #22): devfw21·devfw17·devfw8·devfw11 (+-sc) 8개 + devfw21-sc-custom. 2026-10-30 부터 컨테이너 앞단 nginx 없이 Cloudflare → NPM → WAS 포트(AA01N) 직결. FE 는 devfw-web(12003→sc) · devfw-web-custom(12004→sc-custom).

17.3 사이트별 운영 배포 가이드

케이스별 상세(IaaS 실행형 jar 멀티 인스턴스 · JEUS+WebToB WAR·Boot 버전 결정 · 중앙 관리 시스템+에이전트 쉘 배포 · Dockerfile+Jenkins/GitHub Actions/GitLab CI · Tekton+Jira 승인+ArgoCD GitOps)는 DEPLOYMENT-GUIDE.md(케이스별 운영 플레이북: 디렉터리·유닛·JVM·헬스·롤링·롤백·체크리스트, 파이프라인/YAML 스케치 포함), 요약·핵심 절차는 코어 개발가이드 #deploy.

18. 기능 총정리 기준) — 빠짐없이 한눈에

§1~§17 을 기능 축으로 다시 묶은 장이다. 각 항목의 상세 키·예시는 괄호 안의 장을 본다.

18.1 역할 분리 — 코어만으로 기본 동작, 삼카는 확장, 데모는 확인

원칙: 코어/스타터에 고객사 로직 없음. 고객사 모듈 의존을 빼면(samsung-card.enabled: false 또는 의존성 제거) 모든 기능이 코어 기본값으로 돌아간다. 확장은 빈 추가/교체 + yml 로만 한다.

18.2 삼카 전문 VO — @ScTelegram/@ScField · 인터페이스 ID 레이아웃 (§16, §16.1)

1. VO: @ScTelegram("SCDEMO01")(응답은 direction = RESPONSE), 필드 @ScField(order, length[, type = NUM][, name]).
2. 조회 순서(AnnotatedTelegramLayouts, @Primary TelegramLayoutService): ① layout.base-packages 스캔 ② 네이밍 규칙 {package}.{interfaceId}In/Out 클래스 로드·파싱(캐시) ③ 코어 yml 레이아웃(fallback-to-default).
3. 기동 검증: 중복 ID·order 중복·응답만 있는 ID·@ScField 없는 VO → 실패.
4. 개발툴 devtools.dynamic.vo-naming 을 같은 규칙으로 두면 코드생성 산출물이 운영 레이아웃·전문테스트에 그대로 잡힌다.

18.3 컬럼 보안 — @Encrypted/@Masked 와 SPI (§11, §7, §14.3)

• ColumnMeta(name, type, length, encrypted, masking) = ColumnMeta.of(Field|RecordComponent, length).
• @Encrypted 는 String 가변 필드 대상(record 는 저장 암호화 제외 — 불변).
• 마스킹 규칙명이 없으면 전체 *, @Unmasked 로 개별 제외.

18.4 DB 암·복호화 자동 처리 (§14.3)

키 접두 ongo.framework.mybatis.plugins.*. 데모: POST /api/demo/column-security(ScCardHolderRow @Encrypted · ScCardHolderView @Masked), 테스트 ColumnSecurityDefaultsTest·ShowcaseDemoTest.

18.5 코드생성 입력 — 다양한 입력 → 공통 I/O → 유형별 파서 (§14, §14.2, §14.4)

기존 VO ─┐
Sample JSON ─┤                 ┌→ I/O 트리 편집(화면) ─→ /api/generate/json → 미리보기/쓰기
정의서(json·samsung-card-io·snippet) ─┼→ SpecParseService(type) → SpecModel/FieldSpec ┤
엑셀 excel / sc-excel(멀티시트) ─┘                 └→ /api/dynamic/{type} → 동적 VO → 전문테스트

• 파서 = SpecParseService 빈, 이름 = type(). 코어 json·excel, 삼카 samsung-card-io·samsung-card-snippet·sc-excel.
• 일반 엑셀 IN/OUT 유연 매핑·미리보기(코어): ① .xlsx 선택 → [시트·컬럼 분석] = /api/excel/inspect 가 헤더 행(별칭 최다 일치, 없으면 첫 표 행)·자동 매핑 제안·미매핑 헤더·샘플 3행 반환 ② 화면에서 항목키(name·label·type·length·scale·required·encrypted·masking·maskingType·io·level·description)↔헤더 드롭다운, IN/OUT 시트 패턴, 기본 타입 → mapping JSON 자동 작성 ③ [엑셀 펼치기]/[미리보기] → 생성 코드가 파일별 편집창 ④ 수정 후 수정본 소스에 쓰기 또는 [zip 다운로드].
• 추가 매핑 키: defaults(빈 셀 기본값, 예 {"type":"STRING","length":10}) · ioSheets({"in":"*_IN","out":"*_OUT"} → ORDER_IN+ORDER_OUT 시트 = ORDERIn/ORDEROut 한 쌍). 한 시트 안 구분 컬럼(io)·level 중첩 OBJECT/ARRAY 는 기존대로. Array/Object 수동 IN/OUT 편집은 공통 I/O 문서(json)에서 그대로.
• 예시: 데모 DevtoolsExcelPreviewDemoTest(xlsx 를 테스트에서 생성 — 실제 정의서 커밋 금지).
• 코어 기본 엑셀(ExcelSpecParser): 시트 1 = VO 1, 헤더 행 자동 탐지, 별칭 표 §14.4. 마스킹여부·암호화여부·마스킹유형코드 컬럼 포함 → @Masked(규칙)·@Encrypted. mapping.columns 로 헤더명/열 문자 지정이 별칭보다 우선, sheets 와일드카드.
• 삼카 멀티시트(ScInterfaceExcelSpecParser): 인터페이스정의서 시트 = 인터페이스 ID, 소스/타켓 IO정의서 시트 *** INPUT/OUTPUT 항목 *** 구간 → In/Out, IO ID → Pascal(SioApcIss00026In), 영문 SNAKE → camel, 병합 셀 처리, _IN/_OUT 시트 짝 fallback. BODY 만 정의(헤더는 코덱).
• 실제 샘플 회귀 테스트는 환경변수 IF_SPEC_SAMPLE=<xlsx 경로> 일 때만(실명 포함 파일은 저장소에 넣지 않는다).

18.6 개발툴 실행 위치 — 코드생성/컴파일 vs 런타임 WAS (§14.1)

• work-dir 분리: dynamic.work-dir(기본 build/ongo-devtools/dynamic/<buildId>/{src,classes})와 codegen.output-dir(기본 src/main/java)가 서로 포함 관계면 기동 실패(... 다른 경로여야 합니다(겹침 금지)). 전문테스트 산출물이 소스 트리에 섞이지 않게 하기 위함.
• 동적 클래스는 별도 URLClassLoader — 운영 런타임 클래스패스에 섞이지 않음. 결과는 소스로 받아 커밋·빌드한다.
• prefer-existing-vo: 네이밍 규칙/생성 FQCN 클래스가 이미 있으면 컴파일 없이 그것 사용.

18.7 개발툴 UI · 엔드포인트

화면 GET /framework-devtools — ① 유형 선택 + 미리보기/소스에 쓰기(덮어쓰기 체크) ② 입력 불러오기: 기존 VO(className)·Sample JSON·엑셀(.xlsx 파일 + 매핑 JSON, 유형 excel/sc-excel — sc-excel 은 samsung-card 데코레이터가 있을 때만 노출, 일반 데모에는 없음)·정의서 본문 → I/O 표(필드·타입·길이·암호·마스킹) 편집 → 재생성. 배치 화면 GET /framework-devtools/batch.

(경로 접두 /framework-devtools.) 동적 전문테스트 코덱 = 기본은 컨텍스트의 TelegramCodecService(Primary).

코덱 선택: 화면 「전문 테스트」 드롭다운 또는 POST /api/dynamic/{type} 본문 "codec" / 쿼리 ?codec=(본문 우선). 후보 목록 GET /api/dynamic/codecs.

후보 추가 = DynamicCodecOption(name, label, codec) 빈(코덱 빈이 아니라 채널 by-type 주입과 충돌 없음). 모르는 codec → 400 devtools.dynamic.invalid. 응답 exchange.codec 에 사용 코덱.

표준전문 HEADER/MESSAGE 설정 (sc-standard / 삼카 표준전문 코덱) — VO 는 BODY 만. HEADER/MESSAGE 는 VO 밖에서 채운다.

우선순위(높음→낮음): ① 전문 values header.x/message.x(개발툴 HEADER·MESSAGE 입력칸) ② 업무단 ScTelegramContext(인터페이스별, 스레드 단위) ③ 설정 ongo.framework.samsung-card.standard-telegram.* ④ 인코더 내장 기본값(ScStandardHeaderDefaults, hyeri 이식).

병합 규칙: 상위 값이 null 또는 "" 이면 하위(디폴트) 값을 쓰고, length>0 이면(공백 " " 포함) 그대로 덮는다. 수신 응답(@direction=response)은 InboundTelegramProcessor 가 자동 지정(처리기가 비워 둔 경우)하고 원 요청 decode 맵을 @request 로 넘긴다 → 응답 HEADER 에 요청의 stdEtxtSn·stdEtxtCrtDt·fstAkSysDvC·fstAkDtm·stdIfId·akRcvSvId·rspRcvSvId·mciAkNodeId 에코, 응답 rcvSysDvC = 요청 sendSysDvC, 응답 stdEtxtPrgNo(표준전문진행번호) = 요청값 +1(네스티드 hop; 송신 시작은 내장 디폴트 0, stdEtxtPrgDvNo 는 기존대로)(우선순위: ③ 설정 response-header 보다 높고 ② 업무단보다 낮음).

수신 처리기 응답 맵 예시(삼카 표준전문 — BODY 키 + header./message. 접두 키, @direction 은 생략해도 자동 response):