백업·업데이트·그래프 유지보수
이 문서는 dtxWiki v0.2.1로 업데이트하는 0.2 계열 절차입니다. 현재 설치 방식을 확인하고 백업·감사·마이그레이션을 마친 뒤 서비스를 시작하세요. 설치·유지보수·시작에는 같은 버전의 패키지 또는 실행기를 사용합니다.
업데이트 준비
- 설치 방식·실행 버전·데이터 디렉터리·DB URL·설정·이전 패키지 또는 이미지를 기록합니다. 유지보수에도 같은 OS 계정과 환경을 사용합니다.
- 웹 서버와 모든 worker를 중지합니다. 로컬 managed 실행은 Ctrl+C로 둘 다 멈춥니다. systemd는
sudo systemctl stop dtxwiki dtxwiki-worker, Compose는 기존infra/prod에서docker compose stop app worker를 실행합니다. - 데이터 디렉터리와 설정 전체를 백업합니다. 소유권·비밀 파일·OAuth 서명 키·Library 원본·Context 미디어·배포 환경·프록시 설정을 보존합니다. Caddy 내부 CA를 사용하면
pki도 포함합니다. - 변경할 디렉터리 밖에 백업을 두고 격리 환경에서 복구해 확인합니다. SQLite WAL도 DB 상태의 일부입니다. 모든 쓰기를 멈춘 뒤 전체를 복사하거나 DB 일관성을 보장하는 백업을 사용하세요. 실행 중
.sqlite하나만 복사하지 마세요. - 공개 릴리스와 Python/npm 버전 일치를 확인합니다. 앱을 시작하지 않고 선택한 버전을 설치한 뒤 실제 DB를 감사·준비하고 접근을 재개합니다.
외부 DB는 기본 DB와 설정된 모든 워크스페이스 DB를 해당 DB 도구로 백업하고 파일·설정도 보존합니다. DB 덤프만으로 업로드 원본과 비밀 키가 복구되지는 않습니다.
감사와 마이그레이션
기존 v0.1.3·v0.1.4 설치에서는 백업과 새 릴리스 설치 후 두 서비스를 멈춘 상태로 실제 환경을 불러와 실행합니다.
dtxwiki --version
dtxwiki db revision-inventory
dtxwiki inputs audit
dtxwiki bootstrap
dtxwiki reindex
dtxwiki graph reproject --all-workspaces
dtxwiki db revision-inventory
감사가 통과한 뒤에만 bootstrap을 실행하세요. 감사 종료 코드 0은 발견 없음, 1은 발견 보고, 2는 감사 실패입니다. 현재 스칼라 값의 차단 항목을 읽고 UUID를 지정해 users set-display-name, users set-email, inputs repair-metadata 등으로 필요한 값만 고친 뒤 다시 감사합니다. 보존된 과거 이력의 발견과 현재 업그레이드 차단 항목은 다릅니다. 수정 전에 각 명령의 --help를 확인하세요.
v0.2.1의 최종 마이그레이션은 5b7e5c149279입니다. 문헌 참조 개정 c58f1d2e890a와 Chats 조회 인덱스 개정 b1d98889a4ad를 병합하며 두 개정은 앞선 그래프·함께 읽음 변경을 이어갑니다. 그래프·Inbox 병합 1d8f1c08ca36은 중간 개정입니다. 초기 워크스페이스 일반화·외부 신원·검토 결정·보존 삭제·Inbox·범위가 명시된 링크 상태도 포함합니다. inventory의 코드 최종 개정과 실제 DB 개정을 대조하고 consistency=consistent를 확인하세요.
이 참고문헌 저장은 편집기의 참고문헌 패널·주소 기반 인용·MCP cite 등록을 지원합니다. 출처 버전을 게시하면 본문 인용과 등록 문헌을 합쳐 지원하는 Agent 대상을 포함한 인용 그래프에 반영합니다. 스키마 이전이 과거 본문을 다시 쓰거나 옛 인용 키를 실제 문서로 변환하지는 않습니다. 해석되지 않은 인용 안내에 따라 오래된 표시를 참고문헌에서 선택한 문서로 교체하고 확인한 버전을 게시하세요.
참고문헌 스키마 이전으로 DB를 내리면 새 참조 데이터가 삭제되며 테이블을 다시 만들어도 등록을 복구하지 못합니다. 이전 소프트웨어로 돌아갈 때 무손실 DB downgrade를 가정하지 말고 그 버전에 맞는 이전 백업을 복원하세요.
더 오래된 v0.1.2 설치
보존된 v0.1 업그레이드 안내에서 비밀번호 한도·입력 복구·managed worker 변경을 확인하세요. v0.1.2의 128자 초과 비밀번호는 복구가 필요하며 일반 비밀번호 변경 화면으로 인증할 수 없습니다. 예전 별도 로컬 worker는 managed 실행 전에 중지합니다. 이 조건과 현재 감사를 완료하고 최종 0.2 마이그레이션·그래프 준비도 실행하세요.
지원하지 않는 초기 미리보기 DB는 해당 버전의 내보내기·새 설치 경로를 따릅니다. 인식 가능한 옛 개정 이름은 dtxwiki db rename-revisions로 미리 확인한 뒤 변환하세요. 이 작업은 스키마 확인 후 개정 식별자를 바꾸며 업그레이드나 백업을 대체하지 않습니다.
기존 개정 식별자 변환
인식 가능한 옛 개정 이름이 남아 있다면 대상 패키지 설치 후 서버·worker를 중지하고 dtxwiki db rename-revisions로 미리 확인하세요. 일치하는 스키마와 복구 가능한 백업을 확인한 뒤 같은 환경에서 dtxwiki db rename-revisions --apply를 실행합니다. 지원하지 않거나 일관되지 않은 DB는 강제로 stamp하지 마세요. 성공해도 감사·bootstrap·최종 inventory를 계속 확인해야 합니다.
설치 방식 선택
아래 명령은 v0.2.1을 설치합니다. 먼저 공통 준비를 끝내세요. Python 직접 설치는 그 환경의 dtxwiki로 앞의 감사·bootstrap·reindex·그래프 명령을 실행합니다. 실행기를 쓴다면 같은 버전을 끝까지 유지하세요.
| 현재 설치 | 이동 |
|---|---|
| uv | uv tool |
| pipx | pipx |
| 가상환경 pip | pip |
| npx | npx |
| npm 전역 실행기 | 전역 npm |
| systemd·wheel | 검증한 로컬 wheel |
| Docker Compose | 소스 재빌드 |
로컬 패키지
uv tool
uv tool install --force --python 3.12 "dtxwiki==0.2.1"
dtxwiki --version
pipx
pipx install --force --python python3.12 "dtxwiki==0.2.1"
dtxwiki --version
pip 가상환경
기존 전용 가상환경을 먼저 활성화합니다.
python -m pip install --upgrade "dtxwiki==0.2.1"
dtxwiki --version
npx
npx @dtxsuite/dtxwiki@latest는 즉시 서버를 시작할 수 있습니다. 한 버전을 검증해 준비와 시작에 같은 버전을 사용하세요.
npx @dtxsuite/dtxwiki@0.2.1 --version
npx @dtxsuite/dtxwiki@0.2.1 inputs audit
감사와 필요한 복구가 성공하면 실행합니다.
npx @dtxsuite/dtxwiki@0.2.1 bootstrap
npx @dtxsuite/dtxwiki@0.2.1 reindex
npx @dtxsuite/dtxwiki@0.2.1 graph reproject --all-workspaces
npx @dtxsuite/dtxwiki@0.2.1 db revision-inventory
확인 후 npx @dtxsuite/dtxwiki@0.2.1로 시작합니다. 복구도 같은 접두어로 실행하세요. npm 패키지는 같은 버전의 Python 앱을 실행하며 dtxwiki update로 실행기 자체를 바꾸지는 않습니다.
npm 전역 실행기
npm install --global @dtxsuite/dtxwiki@0.2.1
dtxwiki --version
그 실행기의 dtxwiki로 준비 명령을 실행한 뒤 시작하세요. PATH에 같은 이름의 경쟁하는 설치를 만들지 마세요.
systemd: 검증한 로컬 wheel
/var/lib/dtxwiki·/etc/dtxwiki·이전 wheel·서비스 설정을 보존합니다. 배포의 공개 버전 installer/wheel 절차를 따르되 기존 서비스 사용자·데이터 경로·환경 파일을 유지하세요. 환경을 불러오는 sudo dtxwiki … 래퍼로 감사·마이그레이션합니다. 별도 dtxwiki-worker 서비스를 쓸 때 DTXWIKI_WORKER_MODE=external을 유지합니다. 같은 래퍼로 reindex·reproject 후 두 서비스를 시작하세요. 소스 빌드 wheel에는 프런트엔드·그래프 자산·worker·라이선스 고지가 포함되어야 합니다.
Docker: 고정 버전 재빌드
기존 체크아웃 위치·Compose 프로젝트 이름·.env·데이터 볼륨을 유지합니다. app·worker를 멈춰 백업하고 검증된 공개 태그 v0.2.1을 선택한 뒤 infra/prod에서 docker compose build를 실행합니다. 로컬 이미지 빌드를 전제로 하며 레지스트리 이미지가 있다고 가정하지 않습니다.
docker compose run --rm --no-deps app dtxwiki inputs audit로 사전 점검하고 필요한 복구도 같은 접두어를 사용합니다. 통과 후 같은 방식으로 bootstrap·reindex·graph reproject·revision-inventory를 실행하세요. 이후 docker compose up -d로 기존 서비스를 시작합니다. 별도 worker가 있는 Compose는 external 모드를 유지합니다. 새 프로젝트로 교체해 빈 볼륨을 선택하지 마세요.
그래프 유지보수
reindex는 검색·탐색 요약과 현재 링크 투영을 갱신합니다. 그래프 reproject는 현재 Context 버전의 작성된 관계를 조정하며 빠진 인용을 만들어 내거나 완전한 과거 로그를 재구성하지 않습니다.
dtxwiki graph reproject --workspace YOUR_WORKSPACE_UUID_OR_SLUG
dtxwiki graph degree-report --workspace YOUR_WORKSPACE_UUID_OR_SLUG --json
reproject에는 --workspace 또는 --all-workspaces 중 하나를 지정합니다. 워크스페이스별 결과와 요약을 출력하고 실패한 워크스페이스는 롤백한 뒤 나머지를 계속 처리합니다. 종료 코드 1은 하나 이상 실패했다는 뜻입니다. 실패 대상을 확인한 뒤 재시도하세요. degree report는 운영 진단 표본이며 사용자의 권한별 지도나 사실 품질 점수가 아닙니다. 업그레이드와 같은 DB 설정·유지보수 시간에 실행하세요.
지도에는 여전히 Owner의 활성화와 각 사용자의 Labs 선택이 필요합니다. 지도 활성화와 데이터 복구는 별도입니다. Knowledge Map을 참고하세요.
실행 버전과 백그라운드 확인
- 기존 방식으로 서버를 시작하고 로그인·대상 워크스페이스·대표 발행 문서를 확인합니다.
- 해당 설치의
dtxwiki --version과 실제 서버의/health/live를 각각 확인합니다. 둘 다0.2.1이어야 합니다. 다르면 접근을 재개하기 전에 실행 중인 환경과 프로세스를 확인하세요. /health/ready를 확인합니다. managed는components.worker=ok, external은n/a이므로 systemd·Compose worker와 실제 가져오기 작업을 따로 점검합니다.- Library 원본·미디어·검색·참고문헌 변경을 포함한 검토·이력 비교·수신함·설정한 SSO를 확인합니다. 연습 문서에서 저장한 참고문헌과 게시된 인용을 확인하고 MCP 도구 목록·생성 스키마 캐시를 계약 개정 29로 갱신합니다.
- Knowledge Map의 두 설정과 알려진 발행 링크를 확인합니다. 기록된 관측이 없는 기간은 이력이 일부만 있을 수 있습니다.
설정 → 배포에서는 공개 패키지 인덱스를 조회하고 설치 방식별 안내를 볼 수 있습니다. 성공한 최신 조회는 공개 버전을 뜻하며 실패·오래된 조회는 업데이트가 없다는 증거가 아닙니다. 카드 자체가 업데이트를 실행하지 않습니다. 대상 버전에 맞는 매뉴얼 계열을 선택하고 앞의 설치 방식별 절차를 따르세요.
복구 연습
접근을 닫고 두 서비스를 멈춥니다. 실패한 새 상태를 따로 보존하고 이전 DB·파일·설정 전체와 그에 맞는 소프트웨어를 함께 복구한 뒤 권한·health·worker를 확인하세요. 소프트웨어만 되돌려도 DB 마이그레이션은 취소되지 않습니다. 백업 복원 대신 새 0.2 DB를 옛 코드로 열지 마세요.
내장 updater로 관리한 업데이트는 sudo dtxwiki rollback --list로 백업을 확인하고 sudo dtxwiki rollback --to-backup /var/lib/dtxwiki/backups/EXACT_BACKUP_ID로 선택한 백업과 이전 패키지를 사용합니다. 이전 패키지를 확보해 두세요. 수동 wheel·Docker는 그에 맞는 wheel·이미지·소스와 전체 백업을 함께 복구합니다.
정기 정리는 7일 지난 정리 대상 완료 점검과 만료된 재시도 영수증을 제한된 배치로 제거합니다. 실패·수동 작업·콘텐츠 처리 이력은 유지합니다. SQLite는 여유 페이지를 재사용해도 파일 크기가 줄지 않을 수 있습니다. 파일 축소는 백업과 중지 상태에서 운영 runbook의 SQLite VACUUM 절차로 수행하세요.