서문
프로덕션 환경에서 OpenClaw을 업그레이드할 때 가장 큰 리스크는 서비스 중단입니다. 사용자가 진행 중인 대화가 중단되거나, Webhook 콜백에서 메시지가 손실될 수 있습니다. 이 글에서는 사용자 경험에 영향을 주지 않으면서 버전 업데이트를 완료하기 위한 여러 가지 무중단 또는 최소 중단 시간 업그레이드 방안을 소개합니다.
1. 업그레이드 전 준비
1.1 현재 버전과 대상 버전 확인
# 현재 실행 중인 버전 확인
openclaw version
# 사용 가능한 최신 버전 확인
openclaw update check
# 출력 예시
# 현재 버전: 1.2.0
# 최신 버전: 1.3.0
# 업데이트 유형: 기능 업데이트 (minor)
# 변경 로그: https://openclaw.com/changelog/1.3.0
1.2 변경 로그 확인
업그레이드 전에 대상 버전의 변경 로그를 반드시 확인하고, 특히 다음 항목에 주의합니다:
- Breaking Changes: 호환되지 않는 설정 형식 변경이 있는지
- 데이터베이스 마이그레이션: 데이터 형식 마이그레이션이 필요한지
- 종속성 변경: Node.js 버전이나 기타 종속성 업데이트가 필요한지
- 새 설정 항목: 수동으로 추가해야 하는 새 설정이 있는지
# 버전 간 변경 요약 확인
openclaw update changelog --from 1.2.0 --to 1.3.0
1.3 업그레이드 전 백업 생성
# 전체 백업 (필수 단계)
openclaw backup create --output /backup/openclaw-pre-upgrade-$(date +%Y%m%d).tar.gz
# 백업 무결성 검증
openclaw backup verify /backup/openclaw-pre-upgrade-$(date +%Y%m%d).tar.gz
1.4 테스트 환경에서 검증
# 테스트 환경에서 먼저 업그레이드 및 검증
OPENCLAW_ENV=staging openclaw update --to 1.3.0
OPENCLAW_ENV=staging openclaw doctor
2. PM2 무중단 리로드
PM2로 OpenClaw을 관리하는 경우, PM2의 reload 기능을 활용하여 무중단 업데이트를 구현할 수 있습니다.
2.1 기본 흐름
# 단계 1: OpenClaw 패키지 업그레이드
npm install -g [email protected]
# 단계 2: PM2 reload 사용 (무중단 리로드)
pm2 reload openclaw
# 단계 3: 새 버전 확인
openclaw version
curl -s http://localhost:18789/health | jq '.version'
2.2 PM2 reload vs restart의 차이
| 작업 | 중단 시간 | 원리 |
|---|---|---|
pm2 restart |
약 5-15초 | 이전 프로세스를 먼저 중지한 후 새 프로세스를 시작 |
pm2 reload |
거의 0 | 새 프로세스를 먼저 시작하고, 준비 완료 후 이전 프로세스를 중지 |
2.3 정상적인 리로드 설정
PM2 reload가 올바르게 작동하려면 정상적인 종료를 설정해야 합니다:
// openclaw-ecosystem.config.js
module.exports = {
apps: [{
name: "openclaw",
script: "openclaw",
args: "up",
// 정상적인 종료 대기 시간 (밀리초)
kill_timeout: 15000,
// 새 프로세스 준비 대기 시간
listen_timeout: 20000,
// 준비 신호 대기
wait_ready: true,
// 리로드 시 최대 메모리
max_memory_restart: "512M"
}]
};
OpenClaw은 시작이 완료되고 헬스 체크를 통과한 후 준비 신호를 보내며, PM2가 신호를 받은 후에야 이전 프로세스를 중지합니다.
2.4 리로드 과정 모니터링
# 실시간으로 리로드 과정 관찰
pm2 logs openclaw --lines 20
# 프로세스 상태 변화 확인
watch -n 1 pm2 status
3. Systemd 정상적인 재시작
3.1 ExecReload 사용
Systemd 서비스 파일에 리로드 명령을 설정합니다:
# /etc/systemd/system/openclaw.service
[Service]
ExecStart=/usr/local/bin/openclaw up
ExecReload=/bin/kill -SIGUSR2 $MAINPID
ExecStop=/bin/kill -SIGTERM $MAINPID
# 정상적인 종료 타임아웃
TimeoutStopSec=30
Restart=always
RestartSec=5
# 업그레이드 흐름
npm install -g [email protected]
sudo systemctl daemon-reload
sudo systemctl reload openclaw
# reload가 지원되지 않는 경우, restart 사용
sudo systemctl restart openclaw
3.2 Systemd의 중단 시간
Systemd의 restart는 짧은 중단이 발생합니다. 무중단이 필요한 경우, 이중 인스턴스 방안이나 Nginx와 함께 사용하는 것을 권장합니다.
4. 블루-그린 배포 방안
블루-그린 배포는 진정한 무중단을 구현하는 고전적인 방안으로, 신구 두 버전을 동시에 실행하고 트래픽 전환으로 업그레이드를 완료합니다.
4.1 아키텍처 설명
사용자 요청 → Nginx → ┬─ Blue (이전 버전 v1.2.0) 포트 18789
└─ Green (새 버전 v1.3.0) 포트 18790
4.2 배포 단계
# 단계 1: 현재 프로덕션 환경 (Blue)이 포트 18789에서 실행 중
# 현재 상태 확인
curl -s http://localhost:18789/health
# 단계 2: 새 포트에서 새 버전 (Green) 시작
OPENCLAW_PORT=18790 openclaw up -d --name openclaw-green --config ~/.config/openclaw/openclaw.production.json5
# 단계 3: Green 환경 준비 대기
sleep 20
curl -s http://localhost:18790/health
# 단계 4: Green 환경 기능 정상 확인
openclaw doctor --port 18790
# 단계 5: Nginx 트래픽을 Green으로 전환
Nginx 설정을 수정하여 트래픽을 새 포트로 지향합니다:
upstream openclaw_backend {
# 전환 전: Blue를 지향
# server 127.0.0.1:18789;
# 전환 후: Green을 지향
server 127.0.0.1:18790;
}
server {
listen 443 ssl;
server_name openclaw.yourdomain.com;
location / {
proxy_pass http://openclaw_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
# Nginx 설정 리로드 (무중단)
sudo nginx -t && sudo nginx -s reload
# 단계 6: 트래픽 전환 확인
curl -s https://openclaw.yourdomain.com/health | jq '.version'
# "1.3.0"이 반환되어야 함
# 단계 7: 이전 버전 (Blue) 중지
openclaw stop --name openclaw-blue
4.3 빠른 롤백
새 버전에 문제가 발생하면, Nginx를 이전 포트로 전환하기만 하면 됩니다:
# Nginx upstream을 이전 버전 포트로 변경
# server 127.0.0.1:18789;
sudo nginx -s reload
5. Docker 롤링 업그레이드
5.1 Docker Compose 사용
# docker-compose.yml
version: '3.8'
services:
openclaw:
image: openclaw/openclaw:1.3.0
deploy:
update_config:
parallelism: 1
delay: 30s
order: start-first # 새 컨테이너를 먼저 시작한 후 이전 컨테이너 중지
failure_action: rollback
rollback_config:
parallelism: 1
delay: 10s
healthcheck:
test: ["CMD", "curl", "-sf", "http://localhost:18789/health"]
interval: 15s
timeout: 5s
retries: 3
start_period: 30s
ports:
- "18789:18789"
volumes:
- openclaw-data:/root/.openclaw
restart: always
# 새 이미지를 가져오고 롤링 업데이트
docker compose pull
docker compose up -d
# Docker Compose가 수행하는 작업:
# 1. 새 컨테이너 시작
# 2. 헬스 체크 통과 대기
# 3. 이전 컨테이너 중지
5.2 Docker Swarm 롤링 업그레이드
# 서비스 이미지 업데이트
docker service update --image openclaw/openclaw:1.3.0 openclaw
# 업그레이드 진행 상황 모니터링
docker service ps openclaw --format "table {{.ID}}\t{{.Image}}\t{{.CurrentState}}"
6. 데이터 마이그레이션 처리
6.1 자동 마이그레이션
OpenClaw은 버전 업그레이드 시 필요한 데이터 마이그레이션을 자동으로 감지하고 실행합니다:
# 시작 시 자동 마이그레이션
openclaw up
# [INFO] 데이터 형식 마이그레이션 필요 감지: v1.2 → v1.3
# [INFO] 현재 데이터 백업 중...
# [INFO] 마이그레이션 실행: migrate_sessions_v1.3
# [INFO] 마이그레이션 완료, 총 156개 세션 기록 처리
6.2 수동 마이그레이션
자동 마이그레이션이 실패한 경우, 수동으로 실행할 수 있습니다:
# 대기 중인 마이그레이션 확인
openclaw migrate status
# 마이그레이션 실행
openclaw migrate run
# 마이그레이션 롤백
openclaw migrate rollback --to 1.2.0
7. 업그레이드 체크리스트
매 업그레이드 전, 다음 체크리스트에 따라 실행합니다:
업그레이드 체크리스트: v1.2.0 → v1.3.0
================================
□ 변경 로그를 읽고 Breaking Changes가 없는지 확인
□ 전체 백업 생성
□ 테스트 환경에서 새 버전 검증
□ 테스트 환경 채널 연결 정상 확인
□ 테스트 환경 메시지 송수신 정상 확인
□ 테스트 환경 스킬 실행 정상 확인
□ 팀에 업그레이드 계획과 시간 창 공지
□ 트래픽이 가장 낮은 시간대에 업그레이드 실행
□ 업그레이드 실행
□ 프로덕션 환경 헬스 체크 통과 확인
□ 모든 채널이 재연결되었는지 확인
□ 테스트 메시지를 보내 기능 정상 확인
□ 30분간 모니터링하여 이상 없음 확인
□ 업그레이드 완료, 업그레이드 로그 기록
8. 롤백 방안
8.1 빠른 롤백
# 방안 1: PM2 환경 다운그레이드
npm install -g [email protected]
pm2 reload openclaw
# 방안 2: 백업에서 복원
openclaw stop
openclaw backup restore /backup/openclaw-pre-upgrade-20260314.tar.gz
npm install -g [email protected]
openclaw up -d
8.2 롤백 후 확인
# 버전 확인
openclaw version # 1.2.0이 표시되어야 함
# 진단 실행
openclaw doctor
# 데이터 무결성 확인
openclaw stats --period 1h
무중단 업그레이드는 일회성 작업이 아니라, 표준화된 프로세스와 지속적인 연습이 필요한 운영 실천입니다. 배포 규모에 맞는 업그레이드 방안을 선택하고, 매 업그레이드 전에 충분한 준비를 하면 업그레이드 리스크를 최대한 줄일 수 있습니다.