1. 무엇을 하는가
릴리스는 releases/ 아래 나란히 놓이고 current 가 그중 하나를 가리키는 심볼릭 링크라서, 배포는 링크를 옮기는 것이고 롤백은 도로 옮긴 뒤 인계만 다시 하는 것이다:
ssh <host> "sudo -n -u ahawiki ln -sfn /opt/ahawiki/releases/<previous> /opt/ahawiki/current" AHAWIKI_RESTART_ONLY=1 AHAWIKI_DEPLOY_HOST=… AHAWIKI_HEALTH_HOST=… AHAWIKI_PROXY_RELOAD=… bash deploy.sh
손으로 하는 재시작 순서를 여기 따로 적지 않는다. 2026-10-11 까지는 이 자리에 인스턴스마다 재시작하고 기다리는 for 루프가 있었고, 그것은 배포 경로와 따로 낡았다 — 2026-08-16 까지 sleep 20 이라고 적혀 있었다, 배포 경로가 초 세기를 그만둔 지 한참 뒤까지. 롤백은 이미 무언가 잘못됐을 때 도는데, 그때가 손 절차의 낡음을 발견하기에 최악의 순간이다.
cache/ 와 logs/ 는 shared/ 에 살고 각 릴리스에 링크로 들어간다. 어느 릴리스보다도 오래 살기 때문이다.
2. 평소에는 한 대, 배포 때만 두 대
systemd 인스턴스(ahawiki@<port>)는 평소 10000 하나만 리버스 프록시 뒤에서 돈다. 10001 은 대기 인스턴스로, 배포 동안만 뜬다. 프록시는 그것을 backup 으로 둬서, 10000 이 답하지 않는 동안에만 요청을 보낸다. 배포는 이렇다:
10001을 새 릴리스로 띄워 확인한다.10000은 그대로 옛 릴리스로 서비스한다. 여기서 실패하면current를 되돌리고10001을 내린 뒤 멈춘다 — 독자에게는 아무 일도 없다.- 프록시가 실패 기억을 잊게 하고(
AHAWIKI_PROXY_RELOAD),10000을 재시작한다. 그동안10001이 답한다. 10000이 답하고 그려지면 프록시가 다시 잊게 한 뒤10001을 내린다.
왜 한 대인가 — 메모리. 2026-10-11 까지는 둘이 늘 같이 돌며 둘 다 요청을 받았다(2026-09-10 에 [[Uptime]] 을 여덟 번 렌더링하니 JVM 시작 시각 둘이 5:3 으로 번갈아 나왔다). 인스턴스 하나가 상자 메모리의 4분의 1 안팎을 쓴다 — 숫자와 그 분해는 운영 저장소 ahawiki/README.md. 두 대를 둔 이유는 둘이었다: 무중단 배포와, -XX:+ExitOnOutOfMemoryError 로 JVM 이 스스로 죽을 때 다른 대가 받아 주는 것. 앞의 것은 위 순서가 그대로 지킨다. 뒤의 것은 일어난 적이 없었다(2026-10-11 에 셌다): 남은 앱 로그(9-26 부터)에서 JVM 이 시작된 46번이 모두 배포였고 — 10000 의 시작마다 15분 안에 10001 의 시작이 앞섰다 — OutOfMemoryError 는 남은 로그 전체에 0건, old 세대 사용량은 64~138MB 로 -Xmx512m 의 3분의 1 아래였다.
대가. 평소의 한 대가 죽으면 다시 뜰 때까지 프록시가 보낼 곳이 없다. systemd 가 5초 뒤 다시 띄우고 JVM 기동이 약 9초라(2026-10-07 배포의 로그), 그동안 약 15초 502 다. 죽지 않고 멈춘(응답 없는) 경우는 사람이 볼 때까지다 — 두 대일 때도 프록시가 그 대를 시간 초과로 걸러 낼 때까지 절반의 요청이 묶였다.
고르지 않은 것:
- 두 대를 그대로. 위 대가를 피하는 값으로 상자 메모리의 4분의 1을 늘 쓴다.
- 두 포트를 번갈아. 배포마다 새 릴리스를 쉬던 쪽에 띄우고 돌던 쪽을 내리면 배포 때 JVM 기동이 한 번 준다. 대신 «지금 어느 쪽이 서비스하는가» 가 배포마다 바뀌어, 운영 명령·표본기·문서가 모두 그것을 따라가야 한다.
되돌리려면 이 변경의 deploy.sh 를 되돌리고(두 대를 차례로 재시작하던 모양), 프록시에서 10001 의 backup 표시를 빼고, 10001 을 다시 enable 해서 띄운다. 인스턴스 사이 장치 — 캐시 무효화의 짧은 만료(Dev Cache «인스턴스가 둘이다»), page.updated 의 Redis 전달(Dev WebSocket) — 는 그대로 두었다. 배포 동안 둘이 함께 뜨고, 되돌릴 때 다시 필요하다.
어느 인스턴스가 답하는지는 지금도 이렇게 본다. /w/ 를 연달아 부르면 봇 차단에 걸리므로 /w/ 밖의 경로로 잰다:
for i in 1 2 3 4 5 6 7 8; do curl -s -X POST -H 'content-type: application/json' -d '{"comment":"[[Uptime]]"}' https://ahawiki.net/api/renderAhaMark/FrontPage; echo; sleep 1; done | sort | uniq -c
AHAWIKI_KEEP_RELEASES 를 넘는 옛 릴리스는 마지막에 지워진다. current 가 가리키는 것은 건너뛴다. 스크립트의 모든 원격 블록은 set -e 로 시작하고, 지우는 블록이 그것이 여전히 그런지 확인해야 하는 이유다. 없으면 releases/ 로의 cd 가 실패해도 아무것도 멈추지 않는다: 루프는 로그인 사용자의 홈 디렉터리를 목록하며 계속 돌고, 거기서는 "이것이 current 인가" 검사에 아무것도 걸리지 않아, 눈에 띄는 가장 오래된 항목들에 sudo rm -rf 를 돌린다. 실패가 아무도 종료코드를 읽지 않는 명령 안에 있어서, 배포는 어느 쪽이든 성공을 보고한다.
3. 대기 인스턴스로 먼저 대조하기
렌더링에 닿는 배포는 대기 인스턴스만 새 릴리스로 띄워 둔다. 그 페이지를 옛 릴리스로 도는 10000 과 대조한 뒤에 인계한다.
AHAWIKI_CANARY=1 AHAWIKI_DEPLOY_HOST=… AHAWIKI_HEALTH_HOST=… AHAWIKI_PROXY_RELOAD=… bash deploy.sh AHAWIKI_DEPLOY_HOST=… bash scripts/compare-instances.sh 10000 10001 AHAWIKI_RESTART_ONLY=1 AHAWIKI_DEPLOY_HOST=… AHAWIKI_HEALTH_HOST=… AHAWIKI_PROXY_RELOAD=… bash deploy.sh
- 첫 줄은 평소 배포와 같고,
10001을 띄워 확인한 데서 멈춘다.current는 새 릴리스로 옮겨 가지만10000은 떠 있던 옛 릴리스에서 계속 돌고 독자는 모두 그쪽으로 간다 — 프록시가10001을 backup 으로 두기 때문이다. 2026-10-11 까지는 canary 가 독자의 절반을 받았다. 태그도 이때 붙는다 — 태그는 «서버에 닿아 답했다» 는 뜻이고, 한 대가 답했다. - 둘째 줄이 두 대에서 사이트의 모든 페이지를 보기·히스토리로 그려 비교한다. 바뀐 것은 무엇이 바뀌었는지로 묶어 보여 주므로, 모든 페이지에 들어간 템플릿 변경은 한 번만 나온다. 의도한 변경만 나오면 된다. 무엇을 빼고 비교하는지와 결과를 읽는 법은 스크립트 머리말에 있다.
첫 줄이 성공했다는 것은 확인 URL 몇 개가 그려진다는 뜻이지 사이트 전체가 멀쩡하다는 뜻은 아니다. 이 둘째 줄을 건너뛰지 않는다. 2026-10-01 에 첫 줄은 전부 통과했는데 canary 는 모든 페이지에 500 을 답하고 있었다 — 원인은 Dev Resources 의 «운영에서는 jar 안에서 읽는다». 그때 배포가 본 것은 /hc 와 프록시를 거친 확인뿐이었고, 프록시 너머에서는 옛 대가 답했다. 그래서 띄운 대가 확인 URL 을 직접 그리는 확인이 5단계에 들어갔다(아래 그려지는지는 띄운 그 대에서 본다).
- 괜찮으면 셋째 줄로 인계한다.
current는 이미 새 릴리스이므로 빌드 없이 인계만 한다 —10001을 같은 릴리스로 다시 띄우고,10000을 재시작하고,10001을 내린다. 문제가 있으면 첫 줄이 찍어 준 대로current를 되돌리고10001을 내린 뒤 태그를 지우고 배포 잠금을 지운다.10000은 건드린 적이 없다.
첫 줄부터 셋째 줄까지가 배포 하나다. 그래서 첫 줄은 배포 잠금을 놓지 않고 canary 라고 적어 둔 채 끝나고, 그 잠금을 이어받는 것은 AHAWIKI_RESTART_ONLY 뿐이다(아래 배포는 한 번에 하나).
비교는 서버 안에서 루프백으로 돈다. 인스턴스는 루프백에서만 답하고, 루프백은 화이트리스트라 수백 번 불러도 봇 차단에 걸리지 않는다. 두 대가 같은 릴리스면 비교할 것이 없으므로 스크립트가 거부한다(exit 2) — 어느 릴리스인지는 각 프로세스의 작업 디렉터리로 안다.
2026-09 에는 이 대조를 배포마다 손으로 다시 짰다. 2026-09-26 에는 첫 대조가 231개 중 226개를 «다름» 으로 냈는데, 인접 페이지 그래프가 그릴 때마다 새 UUID 를 쓰기 때문이었다. 그래서 스크립트로 만들었다.
이 대조는 서버가 보내는 HTML 만 본다. 브라우저에서 생기는 일 — 스크립트 예외, 404 를 받는 이미지·요청 — 은 scripts/browser-sweep.mjs 가 본다. 모든 페이지를 헤드리스 Chrome 으로 열어 페이지마다 적는다. 템플릿이나 JS 를 바꾼 배포 뒤에 다 올리고 돌린다. 2026-10-03 에 대조로는 다 «같음» 이던 114개 중 4개에서 이것이 사이트 목록 아이콘의 404 를 찾았다. 쓰는 법과 주의(화이트리스트 주소에서 돌릴 것)는 scripts/README.md.
4. 왜 이런 모양인가
각각이 한 번씩 배포를 부순 값이다.
- 대기 인스턴스가 먼저 뜨고, 프록시는 잊게 한다. 하나뿐인 인스턴스를 재시작하면 JVM 이 뜨는 동안 받을 곳이 없다. 그래서 대기 인스턴스가 먼저 새 릴리스로 떠서 확인을 통과해야
10000이 내려간다. 띄울 수 없거나 그려지지 않는 릴리스·설정은 거기서 멈추고,10000은 자기가 시작할 때 읽은 것으로 계속 돈다. 설정이 깨져 기동이 실패한 날(2026-08-19, 운영 저장소의 키 교체 기록) 사이트를 지킨 것이 이 «먼저 한 대» 였다.
자기 답만으로는 부족하다. 죽은 upstream 을 떨어뜨리는 프록시는 정해진 간격 동안 그것을 빼놓으므로, 인스턴스가 loopback 에서는 서비스 중인데 프록시는 여전히 아무것도 보내 주지 않을 수 있다 — 그 틈에 다른 대를 내리면 보낼 곳이 남지 않는다. 2026-08-12 배포에서 1초쯤의 502 로 값을 치렀다. 그 뒤로는 «프록시를 거친 요청이 200 이 될 때까지» 기다렸는데, 그 요청은 내리지 않은 다른 대가 답해도 200 이라 실제로는 아무것도 기다리지 않았다. 간격에 맞춘 수를 자면 그 간격이 두 곳에 적힌다. 그래서 프록시를 reload 해 실패 기억을 지운다 — 기다릴 조건을 참으로 만든다. 10000 을 내리기 전에 한 번(대기 인스턴스가 예전 실패로 빠져 있지 않게), 10000 이 돌아온 뒤 대기 인스턴스를 내리기 전에 한 번. 설정 reload 라 진행 중인 요청은 옛 워커에서 끝난다. reload 가 실패하면 떠 있는 것을 다 둔 채 멈춘다.
프록시는 503 도 대기 인스턴스로 넘겨야 한다. 내려가는 Play 는 이미 열려 있던 연결로 들어온 요청에 503 으로 답하는데, 프록시의 기본 재시도는 연결 실패와 시간 초과뿐이다. 2026-10-12 첫 인계에서 10000 이 내려가는 7초에 503 한 건이 샜고, 운영 쪽 프록시 설정에 503 재시도를 더한 뒤의 인계에서는 프록시를 거친 /hc 72건이 모두 200 이었다. 앱은 503 을 스스로 내지 않으므로 이 재시도가 다른 응답을 다시 보내지는 않는다. 남은 틈은 반대쪽 끝이다 — 대기 인스턴스를 내릴 때 그것이 종료 대기(5초)보다 오래 붙잡고 있던 요청은 503 을 받는다. 지금 그런 것은 tarpit 중인 차단 주소의 요청뿐이다(Dev BotDetection). 이 틈은 두기로 했다(2026-10-12). 끊기지 않았어도 그 요청은 어차피 403 을 받았다. 막으려면 deploy.sh 가 대기 인스턴스의 연결이 빠지기를 기다려야 하는데, tarpit 이 최대 55초라 배포마다 그만큼 길어지고, 웹소켓은 스스로 끊기지 않으니 독자가 붙어 있으면 늘 끝까지 기다린다. 다시 볼 때: 정상 요청이 5초 넘게 걸리는 경로가 생기면. 인계 직후 접근 로그에서 «대기 인스턴스를 내린 시각의 503» 을 세면 알 수 있다.
10000 이 새 릴리스에서 실패하면 대기 인스턴스가 대신 받는 채로 두지 않는다. 프록시는 10000 이 무엇이든 답하는 순간 그쪽으로 돌아가므로, 500 을 그리는 10000 이 독자를 받게 된다. 그래서 current 를 이전 릴리스로 되돌려 10000 을 다시 띄우고 대기 인스턴스를 내린다 — 배포 전 그대로다. 그것도 안 되거나 되돌릴 릴리스가 없으면(AHAWIKI_RESTART_ONLY) 10000 을 내리고, 같은 확인을 통과한 대기 인스턴스가 혼자 받게 둔다. 그 상태에서 다시 돌리면 스크립트가 알아보고 대기 인스턴스를 재시작하지 않은 채 10000 부터 띄운다.
- 배포는 한 번에 하나. 시작하자마자 서버에
/opt/ahawiki/deploy.lock디렉터리를 만든다.mkdir는 이미 있으면 실패하므로 그것이 잠금이다. 안의holder파일에 상태·배포한 사람@기계·커밋·시각을 적는다. 이미 있으면 그 줄을 보여 주고 빌드 전에 멈춘다(exit 2). 끝나면 성공이든 실패든 지운다.
2026-11-04 에 다른 체크아웃의 배포가 canary 가 대조를 기다리는 동안 인계를 해, canary 의 릴리스를 자기 것으로 바꿔 놓았다. 대조가 엉뚱한 릴리스를 읽고서야 알았다. 잠금이 서버에 있는 것은 그래서다 — 체크아웃·기계가 달라도 같은 것을 본다.
canary 는 잠금을 canary 로 바꿔 둔 채 끝나고, 그것을 이어받는 것은 AHAWIKI_RESTART_ONLY 뿐이다. 이어받을 때 holder 를 옆으로 옮기므로, 둘이 동시에 이어받으려 해도 한쪽만 된다. 실행 중인(deploying) 잠금은 AHAWIKI_RESTART_ONLY 도 넘지 않는다 — 롤백도 진행 중인 배포를 기다린다.
잠금을 쥔 배포가 지우지 못하고 죽으면(ssh 가 끊기는 등) 잠금이 남는다. 멈춤 메시지가 누구의 것인지 보여 주므로, 그 배포가 없다는 것을 확인한 뒤 ssh <host> sudo -n rm -rf /opt/ahawiki/deploy.lock 으로 지운다. 오래된 잠금을 저절로 푸는 시한은 두지 않았다 — 대조는 몇 분이 걸릴지 정해져 있지 않고, 시한이 지나 풀린 canary 잠금은 이번 사고를 그대로 되풀이한다.
- 헬스체크는
/hc를 찌른다. 위키 페이지가 아니다./hc는SELECT 1로 DB 를, 그리고 디스크 여유를 확인하고OK를 답한다 — 재시작이 깨뜨릴 수 있는 것들이다. 사이트 매칭을 타지 않으니Host헤더도 필요 없다.
그리고 /w/ 밖에 있어야 한다. IpRateLimiter 는 /w/ 아래를 페이지 조회로, 나머지를 사람 신호로 세고, 짧은 창 안에서 페이지만 여러 번 요청한 주소를 차단한다(임계값과 그 이름은 Dev BotDetection). deploy.sh 의 폴링 간격(sleep 3)으로 /w/FrontPage 만 부르는 것이 정확히 그 정의다. 2026-09-04 에 이 루프가 다섯 번째 폴링에서 자기를 차단했다 — 남은 폴링은 403 과 tarpit 을 받았고, 인스턴스가 독자에게 정상 서비스하는 동안 배포는 never became healthy 로 죽었다. 차단은 IpDeny 에 행으로 남고 두 인스턴스가 그 테이블을 공유하므로, 고치지 않았다면 보관 기간 내내 모든 배포가 같은 자리에서 실패했다.
기동이 15초 안에 끝나면 네 번으로 통과한다. 그래서 몇 달간 멀쩡했고, 릴리스가 무거워지자 걸렸다. 폴링 창은 AHAWIKI_HEALTH_TRIES(기본 60 × 3초 = 180초)다. 2026-09-15 에는 두 인스턴스가 같이 뜨며 CPU 를 다투자 차가운 JVM+Play 기동이 첫 대에서 90초(옛 30회 고정)를 넘겨, 멀쩡한 기동을 배포가 실패로 보고하고 한 대를 옛 릴리스에 남긴 채 멈췄다 — 그때는 current 가 이미 새 릴리스를 가리키므로, 남은 한 대를 손으로 재시작해(새 릴리스를 집는다) 마쳤다. 더 느린 장비는 이 값을 올린다. 사이트가 실제로 그려지는지는 /hc 가 통과한 뒤 따로 본다(바로 아래) — /hc 폴링이 넓게 볼 이유가 없다. 7단계는 태그일 뿐 아무것도 확인하지 않는다.
- 그려지는지는 띄운 그 대에서 본다.
/hc가 통과하면 그 포트에 루프백으로AHAWIKI_VERIFY_URLS를 하나씩 그려 본다(Host헤더는 URL 의 호스트). 프록시를 거치면 다른 대가 대신 답할 수 있다 — 2026-10-01 에 모든 페이지가 500 인 canary 를 배포가 성공으로 보고한 이유다. 대기 인스턴스가 하나라도 200 이 아니면current를 이전 릴리스로 되돌리고 그것을 내린 뒤 멈춘다.10000이 그러면 위 대기 인스턴스가 먼저 뜨고, 프록시는 잊게 한다 의 마지막 문단대로다. 루프백은 화이트리스트라 이 요청들은 봇 차단에 세지 않는다. 확인 URL 몇 개만 보므로 렌더링에 닿는 배포의 대조(위 대기 인스턴스로 먼저 대조하기)를 대신하지는 않는다. 되돌리는 길은 운영 인스턴스에 그 함수만 돌려 본 것(정상 URL 은 통과, 403·404 는 잡힌다)이고, 실제 배포에서 돈 적은 아직 없다. - 외부 확인은 리다이렉트를 따라간다. 303 을 답하는 첫 페이지는 그것이 어디로 가는지에 대해 아무 말도 하지 않는다. 뒤의 모든 페이지가 500 인 동안 303 으로 통과한 배포가 있었다.
- 외부 확인은 재시도한다. 처음에는 프록시의 «빼놓는 간격» 을 기다리려는 것이었다 — 마지막 재시작이 헬스체크를 통과한 순간에 확인하면 멀쩡한 배포에서 502 를 읽었고, 좋은 릴리스의 태그 하나를 값으로 치렀다. 이제 5단계가 프록시를 reload 하므로 그 이유는 사라졌고, 첫 시도가 통과하면 비용이 없어 그대로 둔다. canary 에서는 외부 확인을 하지 않는다 — 프록시가 독자를 옛 릴리스로 보내고 있으니 새 릴리스에 대해 말해 주는 것이 없다.
- 업로드는 rsync 가 아니라
tarover ssh 다. Git Bash 에서 MSYS2 rsync 를 부르면 두 MSYS 런타임을 건너느라 인자가 뭉개져 도착하고, 아무것도 복사하기 전에 죽는다. - 태그는 맨 마지막에 쓴다. 검증 뒤에 써서, "이것이 빌드됐다" 가 아니라 "이것이 서버에 닿아 답했다" 를 뜻하게 한다.
conf/evolutions가 바뀐 배포는 백업을 먼저 본다. 스크립트는 이것을 하지 않는다 — 어느 데이터베이스인지가 운영 쪽 사실이라서다. 확인 명령과 멈춰야 할 값은 운영 저장소ahawiki/README.md에 있고, 읽기 전용 한 줄이다. 2026-09-02 에 evolution 둘이 이것 없이 나갔다. 안전망은 있었지만 그것을 안 것은 배포 뒤였고, 그날 두 번째 배포는 실제로 실패해 되돌려야 했다(Dev Database).
5. CSS·JS 주소에는 내용 해시가 붙는다
/public/ 아래 파일은 Play 기본값 그대로 Cache-Control: public, max-age=3600 으로 나간다. 2026-09-27 까지는 템플릿이 그 파일들을 고정 주소(/public/wiki.css)로 불러서, 배포 전 한 시간 안에 사이트를 연 브라우저는 새 HTML 을 옛 CSS·JS 로 그렸다. 2026-09-26 배포 직후 옛 리비전 안내 상자(Dev Page)가 이렇게 색 없이 보였다 — 서버는 이미 새 CSS 를 주고 있었다. HTML 과 JS 를 같이 바꾼 배포라면 그 한 시간 동안 새 HTML 이 옛 JS 를 불렀다.
이제 템플릿은 위키 자신의 CSS·JS 를 PublicAsset.url 로 부르고, 그것이 주소 뒤에 파일 내용의 해시를 붙인다(/public/wiki.css?v=…). 내용이 바뀐 파일은 어느 브라우저도 캐시한 적 없는 새 주소가 되고, 안 바뀐 파일은 주소도 캐시도 그대로다. 파일은 여전히 Play 의 Assets 가 보낸다 — 캐시 헤더만 PublicAssets 가 바꾼다. v 가 맞지 않으면 no-cache(아래 남은 틈), 맞으면 1년 immutable 이다(2026-11-02 부터). 그 주소는 그 내용만 뜻하므로 다시 물을 이유가 없다.
- 해시는 인스턴스마다 파일당 한 번, 실제로 서비스되는 파일(classpath 의
public/…)에서 계산한다. 릴리스는 새 디렉터리와 재시작이라 도는 중에는 파일이 바뀌지 않는다. 배포가admin.js를 다시 빌드해도 해시는 실제로 나가는 쪽을 따른다. dev 모드(sbt run)에서는 파일을 고쳐도 해시가 다음 reload 까지 그대로인데, dev 모드는 자산을no-cache로 내보내므로 브라우저가 매번 다시 묻는다. - 템플릿에 CSS·JS 를 새로 넣을 때도
PublicAsset.url로 부른다. 맨 주소로 쓰면 그 파일은 예전처럼 배포 뒤 최대 한 시간 늦게 닿는다.test/templates.public-assets.test.mjs가 맨 주소와 없는 파일 이름을 잡고,PublicAssetVersionSpec은 렌더된 페이지의 해시가 그 주소에서 실제로 받는 내용의 해시인지 본다. - 관리 화면의 import map 값도 같다(2026-10-31 부터).
_baseAdmin.scala.html이 React·Mantine 등을public/js/babel/vendor/의 파일로 가리키는데, 그 값은 속성이 아니라 JSON 문자열이라PublicAssetVersionSpec의 정규식이 그 모양도 읽는다. vendor 파일끼리 서로 부르는 청크(chunk-<hash>.js)에는?v=가 없다 — 이름에 내용 해시가 있어 다시 빌드되면 다른 주소가 되므로 같은 효과다. 왜 esm.sh 에서 여기로 왔는지는scripts/README.md. - 서드파티 CSS·JS 도 같다(2026-10-31 부터). jQuery·MathJax·mermaid 같은 것을 페이지가 CDN 대신
public/vendor/에서 받는데(scripts/vendor.mjs가 node_modules 에서 복사, 왜는scripts/README.md«Vendored page assets»), 템플릿이 그 파일을 부르는 자리도PublicAsset.url이다. MathJax 가 자기 밑에서 더 불러오는 글꼴·jax 와 Font Awesome·Pretendard 의 웹폰트에는?v=가 없고 한 시간 캐시를 그대로 받는다 — 버전을 올리면 MathJax 는 제?V=버전을 붙이고 글꼴은 이름이 같아도 내용이 거의 안 바뀐다. - 이미지·파비콘과 CSS 안의
url(…)에는 붙이지 않았다. 배포에서 HTML 과 맞물려 바뀌는 일이 없어서, 한 시간 늦어도 깨지는 것이 없다. - 앞단 리버스 프록시가 query string 을 그대로 넘기고 캐시하지 않아야 이것이 듣는다. 2026-09-27 운영에서
/public/wiki.css와?v=를 붙인 주소가 같은 파일을 같은Cache-Control로 돌려줬고, 캐시 헤더(Age같은)는 없었다. 앞단에 query 를 캐시 키에서 빼는 캐시를 두면 이 방식은 소리 없이 무력해진다.
고르지 않은 것:
- sbt-digest 와
routes.Assets.versioned— 파일 이름에 해시를 넣고 1년 캐시한다. 플러그인과 파이프라인 단계가 늘고, 해시는sbt stage에서만 생겨sbt run·sbt test에서는 볼 수 없다. 배포 중 두 인스턴스가 섞인 동안 한쪽에 없는 이름을 받으면 404 라 그 화면은 스타일 없이 그려진다. - 릴리스나 커밋을 query 에 — 빌드나 배포가 그 값을 앱에 따로 넣어 줘야 하고, 배포마다 안 바뀐 파일까지 전부 다시 받게 한다.
/public/전체의max-age늘리기 — 맨 주소는 3600 그대로다. 전체에 걸리는 값이라 해시가 없는 이미지까지 길어진다. 해시가 맞는 주소만 늘린 것은 이 문제가 없고, 아래 남은 틈도 넓히지 않는다 — 어긋난 응답은no-cache라 1년이 붙지 않는다.
남은 틈 — 릴리스가 바뀌는 순간. 새 HTML 이 부른 ?v=<새 해시> 가 옛 릴리스로 도는 인스턴스로 가면, 옛 인스턴스는 옛 파일을 준다. 그대로 두면 그 브라우저는 옛 파일을 새 주소로 최대 한 시간 캐시한다 — 배포가 끝난 뒤에도. 2026-10-11 까지는 새 인스턴스와 옛 인스턴스가 같이 요청을 받는 동안이 배포마다 있었다 — 보통 배포는 몇 초, canary 는 대조를 마칠 때까지. 이제 독자를 받는 쪽은 한 번에 하나라(위 평소에는 한 대, 배포 때만 두 대) 그 동안은 10000 이 내려가는 순간 진행 중이던 요청 정도로 줄었다. 옛 HTML 을 들고 있는 브라우저가 새 인스턴스에 옛 v 를 묻는 반대 경우는 배포마다 그대로 생긴다.
그래서 /public/ 은 PublicAssets 컨트롤러가 받는다. 파일은 Assets 가 그대로 보내고, v 가 그 인스턴스가 가진 파일의 해시와 다르면 max-age 대신 no-cache 를 붙인다. 섞인 동안 받은 파일은 다음 페이지에서 다시 물어 바로잡힌다. 옛 HTML 의 v 를 새 인스턴스가 받는 반대 경우도 같다. PublicAssetCacheSpec 이 확인하는데, Prod 모드로 띄운다 — Assets 는 Prod 에서만 max-age 를 붙이고 Dev·Test 에서는 아무것도 안 붙여, 다른 모드에서는 이 검사가 컨트롤러가 없어도 통과한다.
이것은 옛 인스턴스 쪽에 있어야 듣는다. 그래서 이 코드가 들어간 배포(2026-10-02) 자체는 아직 막지 못하고, 그다음 배포부터 막는다.
그러니 배포 직후 눈으로 본 화면이 이상하면 여전히 강력 새로고침부터 해 본다. HTML 과 맞물려야 하는 JS 변경도 그동안은 어긋날 수 있다. CSS·JS 를 바꾼 배포는 대조에서 모든 페이지의 그 ?v= 가 바뀐 것으로 나온다 — 의도한 변경이다.
6. JDK 를 갈면 재시작 전까지 프로세스 실행이 막힌다
돌고 있는 JVM 아래에서 JDK 패키지가 갈리면, 그 프로세스는 자식 프로세스를 하나도 띄우지 못한다. 예외는 IOException: Cannot run program "sh": error=0, Failed to exec spawn helper 이고, 까닭은 JVM 이 fork 할 때 쓰는 jspawnhelper 가 제가 떠 있는 JDK 의 것이라야 하는데 그 파일이 이미 다른 것으로 갈려 있기 때문이다. 돌고 있는 프로세스의 /proc/<pid>/exe 가 (deleted) 로 보이는 것이 신호다.
ssh <host> "sudo -n readlink -f /proc/\$(systemctl show ahawiki@10000 -p MainPID --value)/exe"
2026-09-25 에 실제로 그 상태였다. 인스턴스는 9-20 19:06 부터 돌고 있었고, JDK 는 9-23 06:29 에 unattended-upgrade 가 갈았다(/var/log/apt/history.log: openjdk-17 17.0.20+8 → 17.0.20.1+1). 즉 사람이 한 일이 아니고, 다음 JDK 보안 업데이트에도 같은 일이 난다. AhaWiki 에서 자식 프로세스를 띄우는 곳은 InterpreterVim 의 vi 하나뿐이라, 증상은 캐시에 없는 Vim 블록을 그리는 문서가 전부 500 이었다 — 이미 캐시에 있는 블록은 멀쩡해서 사이트는 정상으로 보였다. 3일간 아무도 몰랐다.
고치는 방법은 재시작뿐이다. 배포는 어차피 재시작하므로 배포 한 번이 곧 치료다. 다시 나지 않게 하려면 둘 중 하나인데 아직 어느 쪽도 하지 않았다.
- 서버 쪽: apt 가 openjdk 를 올리면
ahawiki@*를 재시작하는 hook(DPkg::Post-Invoke). 운영 저장소의 일이다. - 앱 쪽: JVM 을
-Djdk.lang.Process.launchMechanism=VFORK로 띄운다.jspawnhelper를 안 쓰므로 JDK 가 갈려도 프로세스를 띄울 수 있다. 이 앱이 띄우는 프로세스는vi하나뿐이라 부담이 없다. systemd unit 의 한 줄이라 이것도 운영 쪽이다.
그 사이에는 InterpreterVim 이 강조 없이 본문을 보여 주는 것으로 버틴다(InterpreterVim).
7. 비밀이 든 설정을 conf/ 밖에
sbt stage 는 conf/ 아래 모든 파일을 릴리스에 복사한다. gitignore 는 거기 관여하지 못한다 — git 이 무엇을 추적하는지를 다스릴 뿐, 빌드가 무엇을 패키징하는지는 아니다 — 그래서 거기 둔 로컬 설정은 배포마다 서버로 따라간다.
가정이 아니다. 개발 DB 비밀번호와 play.http.secret.key 가 릴리스 세 개에, world readable 로, 앱이 열지도 않는 파일에 앉아 있었다: 앱은 릴리스 밖을 가리키는 절대 경로 -Dconfig.file 로 시작된다. 지금 구조가 시작된 뒤로 배포마다 나가고 있었다.
build.sbt 는 이제 git 에게 conf/ 아래 무엇을 추적하는지 물어 그것만 패키징한다. ignore 된 파일은 실리지 않는다 — 모두가 이미 그런 줄 알았던 바로 그것이다. 무엇을 뺐는지도 말한다:
[info] conf/: not packaged (untracked): conf/something.local.conf
파일명 패턴을 먼저 시도했고, git 이 없는 빌드의 폴백으로만 남겼다. 패턴은 누군가 떠올린 모양들을 잡는데, 이 일의 발단이 된 파일은 그중 어느 모양도 아니었다: 호스트명을 따서 지은 이름이었다.
그 폴백은 2026-08-15 에 처음 실제로 돌려 봤다 — git 을 PATH 에서 빼고, 미끼 파일 둘을 심어서: 하나는 *.local.*, 하나는 호스트명을 딴 이름. 설계대로 동작했고 한계도 위에 적은 그대로다: 첫째는 빠졌고 둘째는 실렸다. 그래서 폴백은 경고하고, 이제 패키징하려는 conf/ 최상위 목록도 찍는다. "릴리스를 확인하라" 는 뺀 것의 목록으로는 답할 수 없기 때문이다 — 걱정할 파일은 정의상 패턴이 알아보지 못한 그 파일이다.
[warn] conf/: git unavailable, falling back to name patterns. Check the release for local configs. [warn] conf/: packaged on the name rule alone: conf/application.conf [warn] conf/: packaged on the name rule alone: conf/base.conf ...
여섯 줄쯤이고, 낯선 설정 하나는 거기 끼면 눈에 띈다. 하위 디렉터리는 그 목록에서 뺐다 — 기본 페이지와 evolution 전부는 하나를 숨기기에 충분히 길다. git 이 있으면 이것들은 하나도 나타나지 않는다. 보통의 빌드가 전부 그쪽이다.
배포 설정이 conf/ 에 살아야 할 이유는 아무것도 없다 — 서버는 절대 경로로 설정 위치를 받는다 — 그러니 가장 안전한 자리는 여전히 아예 다른 곳이다.
8. 앞단 nginx 는 경로를 풀지 않는다
위키로 가는 proxy_pass 끝에는 / 를 붙이지 않는다(2026-10-04 소유자 결정). 붙이면 nginx 가 경로의 %22·%5B·%3C 를 "·[·< 로 풀어서 넘기고, Play 는 그런 경로를 읽지 못해 400 을 낸다("Cannot parse path from URI") — Tip "T.I." Harris 같은 이름의 링크가 그랬다. 바꾼 곳과 되돌릴 백업은 운영 저장소 ahawiki/README.md «앞단 nginx».
대가가 둘 있다.
- nginx 가 더는
//를 하나로 합쳐 주지 않는다 —//public/less.css는 404 다. 위키가 만드는 주소에//가 생기면 안 된다. 페이지 대표 이미지의 주소는Api.pageImageUrl한 곳에서 만든다(전에는 그래프용 사본이/로 시작하는 이미지를https://<host>//…로 만들었다). 검사는PageImageUrlSpec. - 퍼센트 인코딩 없이 UTF-8 바이트 그대로 온 경로는 Pekko 가 400 으로 거절한다. 받아 주려면 nginx 가 다시 인코딩하게 해야 하는데 이 결정과 부딪힌다. 브라우저는 늘 인코딩해 보내므로 봇만 걸린다(Dev Logs «2026-10-31 에 나온 것»).
9. 전에 여기 있던 것
2026-08-12 까지 이 저장소에는 다른 배포 장치 둘이 실려 있었고 둘 다 더는 서버와 맞지 않았다: 옛 경로에 빌드를 덮어 복사하는 스크립트 하나, 서버에서 빌드해 pm2 로 띄우는 GitHub Actions 워크플로 하나. 운영은 current 에서 도는 systemd 서비스로 옮겨 간 뒤라, 스크립트는 아무도 읽지 않는 디렉터리에 썼고 워크플로는 돌고 있는 서비스와 포트를 두고 경합했을 것이다. 둘 다, 의존하던 pm2 launch 스크립트·process 파일과 함께 제거했다.
10. See Also
10.2. Similar Pages
Similar pages by cosine similarity. Words after page name are term frequency.