백업과 유지보수
백업은 내 지식과 그 지식을 사용하는 데 필요한 파일을 복구할 수 있게 복사한 것입니다. 페이지 이력은 내용 변경을 되돌리는 데 도움을 주지만 서버 백업을 대신하지 않습니다.
설치 안내를 따라 v0.1.2을 새로 설치해 시작하세요. 이 문서는 설치 이후 만든 자료의 백업, 복구 연습, 설치 환경의 유지보수를 다룹니다. 이후 소프트웨어 버전으로 바꾸기 전에는 해당 버전의 업데이트 안내를 확인하세요.
함께 보관할 자료
| 설치 방식 | 데이터와 설정 |
|---|---|
| 기본 로컬 설치 | 데이터베이스·업로드·라이브러리 파일·세션 비밀값을 포함한 ~/.dtxwiki 전체 |
| 기본 systemd 설치 | /var/lib/dtxwiki, /etc/dtxwiki, 실행 중인 버전의 wheel |
| 기본 Docker 설치 | /var/lib/dtxwiki에 연결된 data volume, Compose 설정과 .env |
| 내부 CA 사용 | Caddy의 pki 데이터 또는 Docker caddy_data volume. 클라이언트가 같은 인증 기관을 계속 신뢰하도록 보존 |
별도 경로를 설정했다면 실제 설정 경로를 따릅니다. 백업에는 비공개 페이지, 자격 증명, 서명 키가 있으므로 접근 권한을 제한하고 서버 밖에도 복사본을 두세요.
로컬 백업
dtxWiki를 Ctrl+C로 종료하고 별도로 실행한 작업자가 있다면 함께 중지합니다. 기본 로컬 경로의 예시입니다.
BACKUP_DIR="$HOME/dtxwiki-backups/$(date -u +%Y%m%dT%H%M%SZ)"
umask 077
mkdir -p "$BACKUP_DIR"
cp -a "$HOME/.dtxwiki" "$BACKUP_DIR/data"
백업이 자신을 다시 복사하지 않도록 ~/.dtxwiki 밖에 저장합니다. -wal/-shm이 남아 있으면 함께 보관하세요. dtxwiki --version 결과와 설치한 wheel 또는 패키지 버전도 기록합니다.
복사가 성공하면 한 터미널에서 dtxwiki로 앱을 다시 실행하고, 다른 터미널에서 dtxwiki-worker run으로 작업자도 다시 실행하세요. npm 설치는 설치 안내의 실행기와 같은 버전의 uvx·pipx 작업자 명령을 사용합니다. 두 프로세스 모두 백업 전과 같은 계정, 설치한 패키지, 데이터·데이터베이스 설정을 사용합니다. 앱을 실행해도 작업자가 함께 시작되지는 않습니다. 가져오기 등 대기 중인 백그라운드 작업이 다시 진행되려면 작업자가 필요합니다.
systemd 백업
백업 중에는 쓰기가 없도록 짧은 점검 시간을 공지합니다. 아래 명령에는 서버의 sqlite3 도구가 필요합니다.
BACKUP_STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
BACKUP_DIR="/var/backups/dtxwiki/$BACKUP_STAMP"
if sudo install -d -o dtxwiki -g dtxwiki -m 0700 "$BACKUP_DIR" &&
sudo systemctl stop dtxwiki-worker dtxwiki &&
sudo -u dtxwiki sqlite3 /var/lib/dtxwiki/dtxwiki.sqlite \
".backup '$BACKUP_DIR/dtxwiki.sqlite'" &&
sudo install -d -o root -g root -m 0700 "$BACKUP_DIR/data" &&
sudo cp -a /var/lib/dtxwiki/. "$BACKUP_DIR/data/" &&
sudo cp -a /etc/dtxwiki "$BACKUP_DIR/etc-dtxwiki" &&
sudo chown -R root:root "$BACKUP_DIR" &&
sudo chmod -R go-rwx "$BACKUP_DIR" &&
sudo sha256sum "$BACKUP_DIR/dtxwiki.sqlite"; then
sudo systemctl start dtxwiki dtxwiki-worker
else
printf '%s\n' '백업 미완료. 재시작·업그레이드 전에 오류를 확인하세요.'
fi
백업 단계가 실패하면 해결하기 전까지 업그레이드하지 않습니다. 내부 TLS에서는 Caddy CA 경로가 /var/lib/caddy/.local/share/caddy/pki라면 함께 보관하세요. .backup으로 만든 최상위 dtxwiki.sqlite를 복구용 데이터베이스로 사용합니다. data/ 안의 사본은 전체 원본 디렉터리를 보존하기 위해 포함한 것입니다.
Docker 백업
설치할 때 사용한 infra/prod 디렉터리에서 실행합니다. 압축 파일에 비밀값이 있으므로 디렉터리와 파일 접근 권한이 중요합니다.
BACKUP_DIR="$HOME/dtxwiki-backups"
if docker compose stop app worker &&
APP_CONTAINER="$(docker compose ps --all --quiet app)" &&
test -n "$APP_CONTAINER" &&
(umask 077 && mkdir -p "$BACKUP_DIR") &&
docker run --rm --volumes-from "$APP_CONTAINER" \
-v "$BACKUP_DIR:/backup" alpine \
sh -c 'umask 077; tar czf "/backup/dtxwiki-$(date -u +%Y%m%dT%H%M%SZ).tgz" -C /var/lib/dtxwiki .'; then
docker compose start app worker
else
printf '%s\n' '백업 미완료. 재시작·업그레이드 전에 오류를 확인하세요.'
fi
.env와 Compose 설정도 보호된 복사본으로 보관합니다. 내부 TLS에서는 CA가 있는 Caddy volume을 함께 백업하세요. down -v, data volume 삭제, volume prune을 사용하지 마세요. 업데이트 중 Compose 프로젝트 이름과 데이터베이스·데이터 경로를 유지합니다.
유지보수 전 데이터베이스 상태 확인
실행 중인 systemd 배포본에서 서비스를 중지하기 전 읽기 전용 revision 정보를 수집합니다.
sudo dtxwiki db revision-inventory --configured prod
이 명령은 증거를 수집하며 마이그레이션을 승인하지는 않습니다. 지원되는 리비전 순서는 bd62193d5cf6 → efcbcf724889이며, 현재 head는 efcbcf724889입니다. 인식 가능한 리비전이라도 consistency=consistent를 확인해야 합니다. 실제 유지보수 명령은 별도로 사전 검사를 수행합니다.
현재 이 정보 수집 명령은 SQLite의 WAL 부속 파일(-wal/-shm)을 요구합니다. 정상 종료되어 checkpoint된 데이터베이스는 sqlite_wal_sidecars_required를 반환할 수 있습니다. 이 결과만으로 손상되었다고 판단하지 마세요. 실행 중 수집한 정보를 보관하고 최종 판단은 지원되는 사전 검사를 따릅니다.
데이터베이스 검사가 진행을 거부하면 원본과 백업을 보존하고 문제 해결을 따르세요. 검사를 우회하려고 무작정 revision stamp를 바꾸거나 데이터베이스를 지우지 마세요. DB에 0001_initial_release 또는 0002_epic1이 기록되어 있다면 아래의 명시적인 스키마 검사·변환 절차를 사용합니다.
기존 리비전 식별자 변환
0001_initial_release 또는 0002_epic1이 기록된 데이터베이스를 재사용할 때만 필요한 관리자 작업입니다. 처음 설치할 때는 필요하지 않습니다. 지원되는 변환은 다음과 같습니다.
| 기록된 식별자 | 지원되는 식별자 |
|---|---|
0001_initial_release | bd62193d5cf6 |
0002_epic1 | efcbcf724889 |
서버·작업자를 중지하고 복구 가능한 백업을 확인한 뒤, 앱을 실행하지 않은 상태로 v0.1.2 코드를 설치합니다. 실제 사용할 DB의 설정을 로드하세요. 변환은 스키마를 확인한 후 리비전 기록만 바꾸며 테이블 변경이나 데이터 변환을 다시 실행하지 않습니다. 지원되지 않는 스키마는 거부합니다. 앱 시작 과정이 이 변환을 자동 처리하지는 않습니다.
로컬 Python 패키지 설치라면 처음 사용한 도구로 버전을 고정해 다시 설치한 뒤 미리 확인합니다.
# pipx
pipx install --force --python python3.12 'dtxwiki==0.1.2'
# 또는 uv: uv tool install --force --python python3.12 'dtxwiki==0.1.2'
dtxwiki db rename-revisions
npm 설치에서는 같은 버전의 실행기로 서버를 시작하지 않고 미리 확인할 수 있습니다.
npx @dtxsuite/dtxwiki@0.1.2 db rename-revisions
실제 DB 설정과 출력된 변환 내용을 확인한 후 적용합니다.
# 로컬 Python 패키지 설치
dtxwiki db rename-revisions --apply
# npm 설치
npx @dtxsuite/dtxwiki@0.1.2 db rename-revisions --apply
변환에 성공한 뒤에만 설치 안내에 따라 앱과 같은 버전의 작업자를 실행합니다. 명령이 DB를 거부하면 쓰기 프로세스를 중지한 채 원래 백업을 보존하세요.
systemd
팀 서버 설치의 v0.1.2 wheel을 사용합니다. 서비스를 중지하고 wheel을 설치한 뒤 /etc/dtxwiki/dtxwiki.env를 읽는 래퍼로 미리 확인합니다.
chmod 0644 /tmp/dtxwiki-0.1.2-py3-none-any.whl
sudo systemctl stop dtxwiki-worker dtxwiki &&
sudo -u dtxwiki /opt/dtxwiki/.venv/bin/pip install --upgrade --force-reinstall \
/tmp/dtxwiki-0.1.2-py3-none-any.whl &&
sudo dtxwiki db rename-revisions
미리 보기와 백업을 확인한 후 적용합니다.
sudo dtxwiki db rename-revisions --apply &&
sudo dtxwiki bootstrap &&
sudo systemctl start dtxwiki dtxwiki-worker &&
curl -fsS https://wiki.example.com/health/ready
일반적인 패키지 저장소 업데이트 명령은 이 식별자 변환을 자동 수행하지 않습니다.
Docker
기존 checkout 위치, Compose 프로젝트 이름, 환경 설정과 data volume을 유지합니다. 먼저 app·worker를 중지하고 백업을 완료하세요. 해당 checkout에서 v0.1.2 태그를 선택한 뒤 infra/prod 디렉터리에서 실행합니다.
docker compose build &&
docker compose run --rm --no-deps app dtxwiki db rename-revisions
--no-deps는 식별자 변환 전에 init 서비스가 DB 마이그레이션을 시도하지 않도록 합니다. app 서비스의 실제 DB와 SKIP_BOOTSTRAP=1 환경을 사용합니다. 미리 확인한 뒤 적용합니다.
docker compose run --rm --no-deps app dtxwiki db rename-revisions --apply &&
docker compose run --rm --no-deps app dtxwiki bootstrap &&
docker compose up -d
docker compose ps, /health/ready, 로그인과 자료 읽기를 확인하세요. 리비전 오류를 해결하려고 data volume을 삭제하지 않습니다.
v0.1.2 유지보수와 재설치
아래 예시는 설치 환경을 복구하기 위해 같은 v0.1.2을 다시 설치하는 방법입니다. 첫 설치는 설치 안내를 따르세요. 이후 릴리스에는 해당 버전의 안내와 맞는 패키지·소스 태그를 사용합니다.
로컬 패키지
백업한 뒤 로컬 앱·작업자를 종료하고 처음 사용한 설치 도구로 v0.1.2을 다시 설치합니다.
pipx install --force --python python3.12 'dtxwiki==0.1.2'
소스로 만든 패키지는 설치 안내의 정확한 wheel과 해당 설치 도구의 로컬 wheel 설치·재설치 방법을 사용하세요. pipx upgrade dtxwiki는 사용 가능한 최신 패키지를 선택하므로 사용할 버전을 직접 지정하세요.
처음 uv로 설치했다면 uv tool install --force --python python3.12 'dtxwiki==0.1.2'를 사용합니다. npm 설치는 실행기의 버전이 Python 애플리케이션 버전을 결정합니다. 앱·작업자를 중지하고 백업한 뒤 npx @dtxsuite/dtxwiki@0.1.2를 사용하거나 npm install --global @dtxsuite/dtxwiki@0.1.2로 전역 실행기를 다시 설치하세요. npm 설치의 dtxwiki update·dtxwiki rollback은 npm 절차를 안내하며 앱을 변경하지 않습니다. 설치 안내의 같은 버전 작업자 명령을 별도로 사용합니다.
systemd: 검증한 로컬 wheel
팀 서버 설치 절차로 만든 wheel을 사용합니다. 먼저 이전 wheel을 보관하고 백업을 완료하세요.
chmod 0644 /tmp/dtxwiki-0.1.2-py3-none-any.whl
if sudo systemctl stop dtxwiki-worker dtxwiki &&
sudo -u dtxwiki /opt/dtxwiki/.venv/bin/pip install --upgrade --force-reinstall \
/tmp/dtxwiki-0.1.2-py3-none-any.whl &&
sudo dtxwiki bootstrap; then
sudo systemctl start dtxwiki dtxwiki-worker &&
curl -fsS https://wiki.example.com/health/ready
else
printf '%s\n' '업데이트 실패. 서비스를 중지한 상태로 오류를 확인하고 필요한 경우 복구하세요.'
fi
bootstrap이 실패하면 해결하거나 백업을 복구할 때까지 서비스를 중지한 상태로 두세요.
이후 패키지 저장소 업데이트는 해당 릴리스 안내와 systemd 래퍼의 sudo dtxwiki update --help를 확인하세요. 업데이트 명령은 백업·패키지 설치·마이그레이션·재시작·준비 상태 확인을 처리합니다. 실패하면 복구 방법을 출력하며 자동으로 롤백하지 않습니다. 마이그레이션 단계의 실패는 부분 적용된 데이터베이스를 서비스하지 않도록 서비스를 멈춘 채 둘 수 있습니다.
Docker: 고정 버전에서 재빌드
백업 후 설치에 사용한 checkout에서 git checkout --detach v0.1.2로 v0.1.2 태그를 선택해 같은 버전을 다시 빌드합니다. infra/prod에서 docker compose build, docker compose up -d 순서로 실행합니다. init 서비스가 데이터베이스를 준비합니다. 접근을 다시 열기 전에 docker compose ps와 /health/ready를 확인하세요.
복구 연습
별도 컴퓨터에서 같은 앱 버전과 데이터·업로드·설정·키를 복원합니다. /health/ready, 로그인, 공개된 컨텍스트 버전, 이미지·첨부 파일 읽기를 확인하세요. 복구 연습 환경이 실제 복구 메일을 보내거나 실제 클라이언트 요청을 받지 않도록 분리합니다.
systemd의 패키지 저장소 업데이트에서는 sudo dtxwiki rollback --list로 관리 백업을 보고 sudo dtxwiki rollback --to-backup /var/lib/dtxwiki/backups/EXACT_BACKUP_ID로 선택한 백업을 복구할 수 있습니다. 이전 wheel이 패키지 저장소에 남아 있어야 합니다. 직접 전달한 wheel 설치는 같은 이전 wheel과 데이터·설정 백업을 보관하고 함께 복구해야 합니다. 코드와 데이터베이스를 함께 되돌리세요.
migration_preflight_refused와 실행 잠금 오류는 문제 해결을 참고하세요.
버전 근거: 백업·업데이트 운영 안내, 거부되는 데이터베이스 처리, pipx 버전 고정 설치 명령, 스키마를 확인하는 리비전 변환.