문제 해결

화면에 보이는 증상부터 확인하세요. 도움을 요청할 때는 화면, 대략적인 발생 시간, 워크스페이스 이름, 정확한 오류 문구를 기록합니다. 비밀번호·토큰·복구 URL·기밀 자료는 화면 캡처나 제보에서 제외하세요.

브라우저와 워크스페이스

증상	확인할 내용
로컬 페이지에 접속할 수 없음	dtxwiki를 실행한 터미널을 열어 둡니다. 같은 컴퓨터에서 http://127.0.0.1:21080/을 사용합니다. 원격 설치는 실제 HTTPS 도메인으로 접속합니다. 터미널이 명령 입력 상태로 돌아왔다면 dtxWiki가 중지된 것입니다. dtxWiki 시작과 종료를 확인하세요.
dtxwiki 또는 uv 명령을 찾을 수 없음	선택한 설치 도구의 PATH 설정을 마치고 터미널을 다시 엽니다. uv는 uv --version, 필요하면 uv tool update-shell, 이어서 dtxwiki --version을 확인합니다. 첫 설치를 참고하세요.
다른 기기가 내 로컬 URL을 사용할 수 없음	127.0.0.1은 주소를 여는 기기 자신입니다. 서버의 LAN IP 또는 실제 HTTPS 주소를 사용하세요. LAN 접속을 참고하세요.
유효하지 않은·허용되지 않은 Host	접속할 호스트명·IP를 대표 URL 또는 DTXWIKI_ALLOWED_HOSTS에 맞춥니다. 0.0.0.0에서 수신한다고 모든 Host가 허용되지는 않습니다.
설정 → 배포가 없음	워크스페이스 소유자와 서버 관리자는 별개입니다. 운영자가 같은 DB의 기존 계정에 서버 관리자 권한을 부여하고 브라우저를 새로고침해야 합니다. 로컬에서는 권한 부여 명령을 실행하기 전에 앱을 중지합니다. 권한 부여를 참고하세요.
admin grant에서 사용자가 없다고 나옴	먼저 계정을 만들고 등록된 계정 이메일을 확인하거나 admin grant --user-id USER_UUID를 사용합니다. 앱과 같은 OS 사용자, 자료·DB 환경설정을 사용하세요.
회원가입을 사용할 수 없음	공유 서버는 직접 가입이 기본적으로 닫혀 있습니다. 서버 관리자에게 계정을 요청합니다.
공유 워크스페이스가 안 보임	로그인 계정과 워크스페이스 전환기를 확인합니다. 계정 → 사용자 ID → 사용자 ID 복사로 UUID를 전달하거나 등록된 계정 이메일로 추가를 요청합니다. IdP 프로필 이메일과 계정 이메일은 다를 수 있습니다. 계정 생성만으로 멤버십이 생기지 않습니다.
워크스페이스를 불러오지 못했습니다가 표시됨	서버가 30초 안에 워크스페이스 목록을 보내지 못했습니다. 페이지를 새로고침하세요. 계속 반복되면 운영자가 앱과 /health/ready 응답을 확인해야 합니다.
편집·새로 만들기 버튼이 없음	역할 또는 페이지 상태가 제한할 수 있습니다. 소유자에게 역할을 확인하세요. 뷰어는 편집 권한이 없습니다.
메뉴에 질문이나 에이전트가 없음	두 메뉴는 실험 중인 메뉴이며 기본적으로 숨겨져 있습니다. 설정 → 실험실에서 Ask 메뉴 표시 또는 Agent 메뉴 표시를 켭니다. 질문 메뉴 켜기를 참고하세요. Agent 문서 직접 링크는 열 수 있지만 브라우저 Agent 검색에는 Labs 메뉴 활성화가 필요합니다.
질문 링크를 열면 해당 페이지를 찾을 수 없습니다가 표시됨	이 브라우저에서 현재 계정의 질문 메뉴가 꺼져 있습니다. Ask 메뉴 표시를 켠 뒤 링크를 다시 엽니다. 질문 메뉴를 꺼도 질문 세션이나 저장한 답변은 삭제되지 않습니다.
실험실 설정이 사라짐	이 설정은 한 브라우저에서 현재 계정에만 저장됩니다. 다른 브라우저·기기·브라우저 프로필, 시크릿 창, 사이트 데이터를 지운 브라우저에서는 두 메뉴가 숨겨진 상태로 시작합니다. 소유자나 관리자가 대신 켜 줄 수는 없습니다.
내부 페이지 링크가 열리지 않음	같은 서버의 멤버 계정으로 로그인하세요. 내부 링크는 새 접근 권한을 주지 않습니다.
공개 페이지가 열리지 않음	발행된 버전이 없거나 웹 공유가 꺼졌을 수 있습니다. 작성자에게 확인하세요. 내부 발행과 웹 게시는 별개입니다.
수정한 내용이 나에게만 보임	브라우저 초안은 같은 공간에서 접근할 수 있는 편집자·소유자가 읽고 뷰어는 게시 버전을 읽습니다. MCP의 열린 editing은 제출 전까지 작성자 전용입니다. 상대 역할과 실제 게시 버전을 확인합니다. 컨텍스트 페이지를 참고하세요.
“더 보기”가 표시됨	목록이 나뉘어 표시됩니다. 더 보기를 눌러 나머지 항목을 확인합니다. 첫 화면이 전체 목록은 아닙니다.
이미지·파일 가져오기가 처리 중	가져오기는 백그라운드 처리에서 진행됩니다. 로컬에서는 dtxwiki 안에서 실행되므로 앱이 계속 실행 중인지, 해당 터미널에 작업 오류가 있는지 확인합니다. 서버에서는 dtxwiki-worker 서비스나 worker 컨테이너를 확인합니다. 처리가 진행되지 않으면 운영자가 설정 → 작업을 점검합니다.
첨부 파일에 삭제 버튼이 없거나 삭제가 실패함	첨부 파일은 편집자와 소유자만 삭제할 수 있으며, 사용 중이 아닌 파일만 대상입니다. 미사용 파일이나 작업 중인 초안에만 상태인 내 업로드를 삭제할 수 있고, 사용 중·이전 버전에만 상태의 파일은 보호됩니다. “목록을 열어둔 사이에 다른 사람이 이 파일을 참조하거나 변경했습니다. 새로고침 후 다시 시도하세요.” 또는 “현재 사용 중인 첨부 파일이라 삭제할 수 없습니다.”가 표시되면 그 사이 파일이 바뀌었거나, 내가 볼 수 없는 초안 등에서 사용 중이라는 뜻입니다. 목록을 새로고침하고 상태를 다시 확인하세요. 이미지, 링크와 인용 넣기를 참고하세요.
미사용 업로드가 자동으로 정리되지 않음	소유자가 미사용 파일 자동 회수를 껐거나, 업로드 시각부터 계산하는 보존 기간이 아직 지나지 않았을 수 있습니다. 정리는 이후의 백그라운드 정리 작업에서 이루어집니다. 운영자는 설정 → 작업에서 “context media orphan sweep”과 “media blob gc” 작업을 확인할 수 있습니다.
저장 중 충돌 표시	다른 편집이 기준 버전을 바꿨을 수 있습니다. 내 작업을 보존하고 현재 버전을 불러와 충돌·검토 절차를 따릅니다. 반복해서 덮어쓰지 마세요.
링크 복사가 실패함	dtxWiki는 브라우저 클립보드를 먼저 사용하고 이어서 예전 복사 방식을 시도하므로 평문 HTTP에서도 대개 복사됩니다. 브라우저가 두 방식을 모두 막으면 가능한 경우 텍스트를 선택해 두므로 Ctrl+C(macOS는 ⌘C)로 복사합니다.

비밀번호를 잊었다면 서버의 복구 기능을 사용하고, 없다면 서버 운영자에게 문의합니다. 워크스페이스 소유자가 자동으로 계정 복구 권한을 갖지는 않습니다. 전에 쓰던 비밀번호로 로그인할 때 현재 비밀번호는 1~128자로 입력해 주세요.가 표시되면 v0.1.2에서 허용되던 128자를 넘는 비밀번호입니다. 이 비밀번호는 더 이상 사용할 수 없으므로, 이메일 복구가 설정되어 있다면 비밀번호를 잊으셨나요?로 재설정하고 그렇지 않으면 서버 운영자에게 복구 링크를 요청하세요. 계정과 접근을 참고하세요.

일상적인 가입·위키 사용에서 SMTP는 선택 사항입니다. 이메일 확인과 메일 복구에는 메일 설정, 접속 가능한 대표 HTTPS URL, 실행 중인 백그라운드 처리가 필요합니다. 로컬 설치에서는 dtxwiki 자체가, 서버에서는 작업자 서비스가 이 처리를 맡습니다. 기본 로컬 HTTP 설치에는 복구 링크 모드가 설정되어 있지 않습니다. 메일 설정 완료 표시만으로 SMTP 인증이나 수신함 도착이 검증되지는 않습니다.

dtxWiki 시작과 종료

아래 메시지는 dtxwiki를 실행한 터미널이나 로그에 표시됩니다. dtxWiki를 시작하지 못하면 오류를 출력하고 명령 입력 상태로 돌아옵니다. 먼저 마지막 줄을 확인하고, see the preceding error로 끝나면 바로 위에 출력된 실제 원인을 읽으세요. npm 사용자는 아래 명령을 npx @dtxsuite/dtxwiki@0.2.1 … 형태로 실행합니다.

메시지 또는 증상	조치
주소·포트가 이미 사용 중이라는 오류 뒤에 dtxWiki HTTP server could not start	다른 프로그램(다른 dtxWiki일 수도 있음)이 이미 그 포트에서 수신 중입니다. dtxWiki는 백그라운드 작업자까지 다시 중지했습니다. 새로 시작하기 전에 해당 프로세스를 확인하고, 의도한 설치일 때만 중지하세요. 실행과 종료를 참고하세요.
dtxWiki is already running or storage is still active; stop the existing processes first	다른 dtxWiki 프로세스가 같은 데이터 디렉터리나 데이터베이스를 아직 사용하고 있습니다. 포트가 달라도 마찬가지이며, 다른 터미널, 백그라운드나 서비스로 실행한 인스턴스, 따로 시작한 작업자, 유지보수 명령일 수 있습니다. 해당 프로세스를 찾아 중지한 뒤 다시 시작하세요. 강제로 종료한 경우 남은 작업자는 약 10초 안에 종료됩니다. 데이터 디렉터리의 .lock 파일은 삭제하지 마세요.
마지막 줄이 could not start; see the preceding error로 끝남	실제 원인은 그 위에 출력되어 있습니다. 예를 들어 설정 검사나 거부된 데이터베이스 업그레이드입니다. 원인을 해결한 뒤 다시 시작하세요. 업그레이드 거부는 운영자 서버 점검을 확인합니다.
dtxWiki initialization did not become ready before its deadline	데이터베이스 준비가 60초를 넘겼습니다. 예를 들어 큰 데이터베이스를 업그레이드한 뒤 처음 시작할 때 생길 수 있습니다. dtxWiki는 끝나지 않은 업그레이드를 적용하지 않고 중지했습니다. 같은 터미널에서 시간 제한이 없는 dtxwiki bootstrap을 한 번 실행한 뒤 dtxwiki를 다시 시작하세요.
dtxWiki background worker did not become ready before its deadline	백그라운드 작업자가 60초 안에 시작 점검을 마치지 못해 dtxWiki가 중지되었습니다. 그 위의 오류가 있다면 확인하고 dtxWiki를 다시 시작하세요. 같은 메시지가 반복되면 터미널 출력과 함께 문제를 제보하세요.
dtxWiki background worker stopped unexpectedly (exit code N); dtxWiki has stopped	백그라운드 작업자가 종료되어 dtxWiki도 함께 중지되었습니다. 이 줄 위의 오류를 읽고 원인을 해결한 뒤 dtxwiki를 다시 실행하세요. 가져오기 하나가 실패해도 dtxWiki는 멈추지 않으며 해당 Library 항목만 실패로 표시됩니다.
명령이 stop dtxWiki (server and worker) first: …로 중단됨	dtxwiki admin …, dtxwiki users …, dtxwiki bootstrap, 입력값 복구 명령은 dtxWiki를 중지한 상태에서 실행해야 합니다. dtxwiki를 실행 중인 터미널에서 Ctrl+C를 눌러 작업자까지 중지하고, 명령을 실행한 다음 dtxwiki를 다시 시작하세요. 거부된 명령은 아무것도 바꾸지 않았습니다. 실행 중인 dtxWiki 옆에서 시작한 dtxwiki-worker run도 같은 메시지와 함께 종료 코드 4로 중단됩니다. dtxWiki가 이미 자체 작업자를 실행하므로 그 창은 닫으세요. 관리자용 다른 방법은 관리 명령 실행을 참고하세요.
managed runtime …	dtxWiki는 일반 로컬 SQLite 파일을 사용할 때만 자체 작업자를 실행합니다. 기본 데이터베이스를 사용하세요. PostgreSQL이나 SQLite URI처럼 다른 데이터베이스 구성을 의도적으로 사용한다면 external 모드로 작업자를 직접 실행합니다.
runtime SQLite database must be a regular file without hard links	managed와 external 모드 모두 하드 링크가 없는 일반 데이터베이스 파일이 필요합니다. 해당 데이터베이스를 사용하는 앱과 작업자를 모두 중지하고 백업을 확인한 뒤, 설정된 경로의 파일을 일반 복사본으로 교체하세요. 파일의 소유자와 접근 권한을 유지하고 다시 시작합니다.

질문과 검색

질문 메뉴가 없거나 질문 링크에서 해당 페이지를 찾을 수 없습니다가 표시되면 설정 → 실험실에서 Ask 메뉴 표시를 켜세요. 질문 메뉴 켜기를 참고하세요.

생성된 문장 답변 없이 근거 목록만 보이는 것은 정상일 수 있습니다. LLM 제공자는 선택 사항이며 기본적으로 꺼져 있습니다. 근거와 출처를 확인하세요. MCP로 AI 앱을 연결해도 dtxWiki 자체 질문 답변기가 자동 활성화되지는 않습니다.

검색 결과가 없으면 현재 워크스페이스에 자료가 있는지, 내 계정이 읽을 수 있는지, 자료 처리가 완료되었는지 확인합니다. 정확한 제목이나 특징적인 단어로 검색해 보세요. 의미 검색은 임베딩 제공자 설정이 필요하며 키워드·탐색 검색은 제공자 없이 동작합니다. 검색과 질문을 참고하세요.

AI 연결 문제

증상·코드	의미와 조치
/mcp를 직접 열면 401	인증 정보가 없으면 정상입니다. PAT를 설정하거나 OAuth 동의를 완료합니다. 만료·폐기된 자격 증명도 인증 실패를 일으킵니다.
컴퓨터 재시작 후 연결이 끊김	터미널의 export는 임시 설정이며 MCP 등록에는 변수 이름만 남을 수 있습니다. 환경 변수 저장을 따르고, 키를 출력하지 않는 검사로 새 세션에서도 Configured인지 확인합니다.
CLI는 연결되지만 VS Code 확장은 실패	확장 자체의 MCP 설정을 확인한 뒤 변수가 준비된 상태에서 VS Code를 완전히 다시 실행합니다. WSL 확장은 Linux 환경에도 변수가 필요합니다.
token_workspace_denied	계정이 멤버여도 자격 증명이 해당 공간을 허용하지 않습니다. 설정 → MCP 접근에서 해당 액세스 키나 OAuth 앱의 워크스페이스 편집을 선택하고 워크스페이스를 고른 뒤 워크스페이스 저장을 누릅니다.
쓰기 작업 거부	멤버 역할과 자격 증명의 권한 범위를 모두 확인합니다. 읽기 전용 키나 뷰어 역할은 쓰기를 허용하지 않습니다.
OAuth 사용 불가	서버에 HTTPS issuer가 필요합니다. 평문 HTTP 평가에서는 액세스 키를 사용합니다. 내부 CA라면 브라우저와 클라이언트에 CA 신뢰를 설정합니다.
“이 설정 절차를 안전하게 표시할 수 없습니다.”	서버 주소가 평문 HTTP에서 호스트명이나 공인 주소를 사용하거나, 선택한 방식에 HTTPS가 필요합니다. HTTPS를 구성하거나, 신뢰하는 LAN에서 평가할 때는 DTXWIKI_PUBLIC_BASE_URL을 서버의 사설 IP 주소로 설정하고 액세스 키를 사용하세요. LAN 접속을 참고하세요.
설정에 연결이 보이지만 도구 실패	등록과 성공적인 호출은 다른 검사입니다. 클라이언트에 접근 가능한 워크스페이스 목록과 아는 페이지 하나를 읽도록 요청합니다. 이어서 해당 워크스페이스의 설정 → MCP 접근 → 연결된 MCP 클라이언트에서 클라이언트 상태를 확인합니다. 인증 만료는 새 액세스 키나 OAuth 재승인이 필요합니다. 인증 취소는 키나 승인이 해지되었거나, 이 워크스페이스가 허용 목록에서 빠졌거나, 소유한 사람이 더 이상 멤버가 아니라는 뜻입니다. 사용 차단은 소유자가 다시 활성화해야 합니다. 인증 상태 확인 필요는 클라이언트가 사용한 자격 증명을 dtxWiki가 알 수 없을 때(이런 기록은 클라이언트의 다음 호출 때 채워짐)나 그 자격 증명이 더 이상 없을 때 표시됩니다. 클라이언트에서 한 번 호출하거나 다시 연결하세요.
/mcp가 랜딩 HTML을 반환	프록시가 MCP를 웹 앱으로 보내고 있습니다. 운영자가 /mcp 경로를 확인해야 합니다.
unknown_tool	요청한 이름이 서버의 현재 도구 목록에 없습니다. 클라이언트의 도구 목록을 갱신하고 저장된 지침에서 지원되지 않는 도구 이름을 제거합니다.
validation_failed	256자를 넘는 제목처럼 입력값이 제한을 넘었거나 지원하지 않는 문자가 들어 있습니다. dtxWiki는 이런 입력을 줄여서 저장하지 않고 거부합니다. 값을 줄이고 클라이언트의 도구 목록을 갱신하세요.
grant_replica_missing	워크스페이스 접근 동기화 중입니다. 작업자가 재시도합니다. 계속되면 실패 작업을 확인합니다.
workspace_plane_unavailable	요청한 공간의 저장소에 접근할 수 없습니다. 운영자가 저장소·연결을 점검합니다.

선택적 도우미는 서버를 독립적으로 확인합니다.

dtxwiki mcp doctor \
  --http https://wiki.example.com/mcp \
  --token-env DTXWIKI_MCP_PAT

DTXWIKI_MCP_PAT는 실행 환경에 안전하게 설정한 후 사용합니다. 서버의 인증 정보 안내와 PAT를 제공한 경우 도구 목록 요청을 검사합니다. 특정 AI 앱이 자체 연결을 완료했다는 증거는 아닙니다. AI 앱 연결을 따르세요. 신뢰하는 LAN의 HTTP 서버도 --http http://192.168.1.20:21080/mcp로 같은 방식으로 확인할 수 있습니다. 이때 TLS 검사는 설계상 실패하므로 연결 여부는 [d] list_tools 줄로 판단합니다.

운영자 서버 점검

systemd에서는:

sudo systemctl --no-pager --full status dtxwiki dtxwiki-worker caddy
sudo journalctl -u dtxwiki -n 50 --no-pager
sudo journalctl -u dtxwiki-worker -n 50 --no-pager
curl -fsS https://wiki.example.com/health/ready

Docker에서는 기존 운영 Compose 디렉터리에서 docker compose ps, docker compose logs --tail=50 app worker를 실행합니다. 로그를 공유하기 전에 비밀값과 민감한 내용을 제거하세요.

실행·유지보수 오류	다음 조치
세션 비밀값·운영 설정 검사 오류	구체적인 안내와 운영 환경을 확인하고 지원되는 CLI로 수정합니다. 검사를 끄지 않습니다.
oauth_jwk=ephemeral_unsafe	운영 OAuth 서명 키 경로가 없거나 잘못되었습니다. 유지되는 키 경로·파일 소유자·권한을 확인합니다. 일반 재시작에서 새 키를 만들면 안 됩니다. 로컬 설치는 데이터 디렉터리에 자체 키를 보관하므로 이 상태는 서버 설정 문제를 가리킵니다.
app_version=unsynced 또는 bootstrap 필요	앱·작업자를 중지하고 저장된 자료가 있다면 백업한 뒤 운영 래퍼의 sudo dtxwiki bootstrap을 실행합니다. 성공한 후에만 서비스를 시작합니다.
“stop dtxWiki (server and worker) first”	다른 dtxWiki 프로세스가 아직 자료를 사용하고 있습니다. 업데이트·롤백·자료 이관, dtxwiki bootstrap, 입력값 복구 전에는 두 쓰기 프로세스를 중지합니다. systemd: sudo systemctl stop dtxwiki-worker dtxwiki. Docker: docker compose stop app worker. 로컬: dtxwiki를 실행 중인 터미널에서 Ctrl+C.
input restrictions preflight failed; use inputs audit and explicit UUID maintenance repairs before upgrading: …	기존 계정 이름·이메일·제목 등의 값이 v0.2.1의 입력 규칙에 맞지 않아 업그레이드가 거부되었고, 아무것도 바뀌지 않았습니다. dtxWiki를 중지한 상태로 두고 백업을 보관합니다. dtxwiki inputs audit을 실행하고 표시된 ID를 하나씩 복구한 뒤, 감사가 종료 코드 0으로 끝날 때까지 반복하고 다시 시작합니다(systemd는 서비스를 시작하기 전에 sudo dtxwiki bootstrap 실행). v0.1.2에서 업그레이드를 따르세요. 데이터베이스를 stamp하거나 삭제하지 마세요.
input audit refused: unsupported or inconsistent database	감사 명령이 설정된 데이터베이스를 검사하지 못했습니다(종료 코드 2). 서버와 같은 설정과 데이터베이스로 실행하세요. 이전 형식의 리비전 식별자가 남아 있는 데이터베이스는 먼저 리비전 식별자 변환이 필요합니다.
input repair refused: … 또는 input repair failed: database conflict; no changes applied	복구 명령은 아무것도 바꾸지 않았습니다. 메시지가 dtxWiki 중지를 요구하면 먼저 중지합니다. 그렇지 않다면 메시지에 나온 ID·필드·값 제한을 확인한 뒤 다시 실행하세요.
migration_preflight_refused	원본 데이터베이스를 보존하고 전체 오류를 기록합니다. 변경하기 전에 실제 자료 경로와 백업을 확인하고 백업과 유지보수를 따릅니다. 무작정 stamp를 바꾸거나 데이터베이스를 지우지 않습니다.
v0.1.2로 되돌린 뒤 DB version … > code version … 또는 migration_preflight_refused와 unknown_revision	v0.2.1이 이미 업그레이드한 데이터베이스는 v0.1.2에서 열 수 없습니다. 메시지가 재구축을 안내하더라도 재구축하거나 stamp하지 마세요. v0.2.1을 다시 실행하거나, 업그레이드 전에 만든 백업을 v0.1.2와 함께 복원합니다. v0.1.2에서 업그레이드를 참고하세요.
기존 리비전 0001_initial_release 또는 0002_epic1이 거부됨	재사용하는 DB에는 명시적인 식별자 변환이 필요할 수 있습니다. 쓰기 프로세스를 중지한 상태로 기존 리비전 식별자 변환을 따릅니다. 백업·실제 DB 확인·미리 보기를 완료한 뒤 --apply를 판단합니다. 처음 설치할 때는 필요하지 않습니다.
revision_rename_refused	변환 명령이 지원되는 스키마·리비전을 확인하지 못했습니다. DB와 백업을 보존하고 운영자에게 정확한 오류를 확인하도록 요청하세요. 강제 stamp나 기존 DB를 덮어쓰는 재생성을 사용하지 않습니다.
unversioned_populated, partial_schema, stamp_marker_conflict, invalid_alembic_revision, probe_error	파일·경로·스키마의 안전한 변경이 증명되지 않았습니다. 실제 DB 설정과 백업을 확인합니다. 완전한 정상 백업을 복구하거나 별도로 검증할 재구축 계획을 세웁니다.
systemd: 패키지를 직접 업그레이드한 뒤 dtxwiki-worker가 종료 코드 4로 계속 재시작하거나 dtxwiki 서비스가 이미 실행 중이라고 보고함	/etc/dtxwiki/dtxwiki.env에 DTXWIKI_WORKER_MODE=external이 없어 앱 서비스가 dtxwiki-worker 옆에서 자체 작업자를 시작했습니다. 두 서비스를 중지하고 sudo dtxwiki config set DTXWIKI_WORKER_MODE=external을 실행한 뒤 둘 다 시작합니다. v0.1.2에는 이 설정을 추가하지 마세요.
sudo dtxwiki update 중 systemd env-file discovery failed … 또는 finalize-bootstrap refused: …	업데이트가 멈췄고 서비스는 중지된 상태로 남습니다. 서비스를 계속 중지해 두고 메시지를 따르세요. 출력된 명령을 실제 env 파일 경로로 실행하거나 안내된 원인을 해결한 뒤, 업데이트를 마무리하거나 롤백합니다. v0.1.2에서 업그레이드를 참고하세요.
unknown DTXWIKI_ env detected: DTXWIKI_WORKER_MODE	v0.1.2 설치가 v0.2.1용으로 기록된 설정을 읽고 있습니다. 업데이트 전에 백업한 env 파일을 복원하거나 해당 줄을 지우세요. 검사를 우회하려고 development 모드로 바꾸지 마세요.

/health/live는 프로세스가 살아 있는지 확인합니다. /health/ready는 데이터베이스, 앱 버전 동기화, 백그라운드 작업자를 포함한 준비 상태를 확인합니다. worker 항목은 로컬 dtxwiki처럼 dtxWiki가 자체 작업자를 실행할 때 ok입니다. systemd와 Docker는 작업자를 별도 서비스로 실행하며 /health/ready가 이를 검사하지 않으므로 n/a를 표시합니다. 해당 서비스나 컨테이너는 위 명령으로 확인하세요. 설정 → 배포의 상태가 준비됨이 아니면 서버 관리자는 백그라운드 처리를 포함한 각 구성 요소를 확인할 수 있습니다. 배포 검증에서는 성공한 health 응답 뒤 브라우저 로그인과 자료 읽기도 확인하세요.

도움 요청과 문제 제보

공유 서버의 계정·워크스페이스·배포 문제는 먼저 서버 운영자에게 문의하세요. 실제 설치 환경과 로그를 확인할 수 있습니다. 재현 가능한 제품 오류나 기능 제안은 dtxWiki GitHub 이슈를 이용합니다.

설치된 dtxWiki 버전, 설치 방법, 운영체제, 브라우저 또는 AI 클라이언트 버전, 재현 단계, 예상 결과, 정확한 오류나 요청 ID를 정리하세요. 필요하면 가상 예시 자료와 민감한 내용을 제거한 화면을 첨부합니다. 공개 제보에는 토큰, 비밀번호, 복구 링크, 비공개 문서, 설정의 비밀값을 넣지 않습니다.

보안 취약점이 의심되면 비공개로 제보하세요. 보안 제보 정책에 따라 저장소의 Security → Report a vulnerability 또는 dtxwiki.ai@gmail.com을 이용합니다. 실제 자격 증명이나 개인정보를 제외하고, 영향을 받는 버전·배포 방법·재현 단계·확인한 영향을 설명하세요.

참고문헌 저장·인용 문제

증상	확인
해석되지 않은 인용 경고	옛 키나 빈 @cite{}를 그대로 두지 말고 편집기의 인용 선택기에서 읽을 수 있는 Context·Library·Agent 문서를 다시 선택합니다.
참고문헌 변경이 저장되지 않음	열린 편집의 버전과 최신 편집 개정 번호를 확인합니다. 참고문헌은 최대 500개입니다. 충돌 시 다시 읽고 대상과 메모를 확인하세요.
읽기 화면이나 그래프에 인용이 안 보임	참고문헌이 포함된 버전을 게시했는지 확인합니다. 저장된 초안과 현재 게시 버전은 다릅니다.
공개 페이지에서 참고문헌이 사용 불가로 표시	익명 독자에게 허용되지 않은 대상은 제목 없이 사용 불가로 표시됩니다. 익명 독자에게는 별도로 웹 공개한 적격 Context 문서만 열립니다. Library·Agent 참고문헌은 공개 페이지에서 계속 접근할 수 없는 문서로 표시됩니다.
인용 관계에 보존된 근거가 없음	문서 사이의 인용 관계와 보존된 버전·자료 근거는 별개입니다. 근거 없음만으로 문서 관계가 잘못됐다고 판단하지 마세요. 그래프 근거 안내를 참고하세요.

MCP 연동은 cite에 version_id, 최신 expected_editing_revision, idempotency_key와 추가·제거 대상을 전달합니다. 예전 주장 검색용 입력은 사용할 수 없습니다. 참고문헌 작성, API·MCP 계약을 참고하세요.

0.2 새 흐름 문제 해결

증상	확인
지식 지도 링크가 접근 불가 화면을 표시	실험실의 개인 설정을 먼저 켜고 Owner에게 워크스페이스 지도를 요청합니다. 서버 전체 차단이 우선합니다. 지도.
아는 링크·인용이 그래프에 없음	본문 인용이나 등록한 참고문헌이 포함된 버전을 게시한 뒤 필터와 현재 게시 대상을 확인합니다. 미게시 초안 저장만으로 그래프 선이 생기지는 않습니다. 링크.
새로고침 후 Inbox 항목이 줄어듦	자격·작업 점유·권한·결정에 따라 현재 항목이 사라집니다. 읽음은 검토 결정이 아닙니다. 수신함.
SSO가 기존 계정 연결을 요구	기존 계정으로 로그인한 뒤 연결합니다. 미확인 이메일 충돌은 관리자 요청을 이용합니다. 계정.
Context 결정 취소 불가	기록된 결과가 바뀌었거나 대상 결정이 아닐 수 있습니다. 이력과 실제 발행 버전을 확인하세요. 검토.
업데이트 후 옛 MCP 연동 실패	workspace_id 명시, 도구·스키마 갱신, 간결한 응답·생략 기본값 처리가 필요합니다. 계약 29.
그래프·Inbox 병합 개정이지만 최종 head가 아님	쓰기를 멈추고 백업 후 감사·bootstrap·reproject를 따릅니다. 강제로 stamp하지 마세요.

---

버전 근거: 운영 문제 해결·마이그레이션 판정, 시작·종료 메시지, 저장소 보호 잠금, 입력값 감사·복구, 준비 상태 확인, 실험실 메뉴, MCP 인증 상태, MCP 도구와 연결.