문제 해결

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

브라우저와 워크스페이스

증상	확인할 내용
로컬 페이지에 접속할 수 없음	dtxwiki를 실행한 터미널을 열어 둡니다. 같은 컴퓨터에서 http://127.0.0.1:21080/을 사용합니다. 원격 설치는 실제 HTTPS 도메인으로 접속합니다.
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에서 사용자가 없다고 나옴	먼저 가입하거나 계정을 만들고 정확한 이메일을 확인합니다. 앱과 같은 OS 사용자, 자료·DB 환경설정을 사용하세요.
회원가입을 사용할 수 없음	공유 서버는 직접 가입이 기본적으로 닫혀 있습니다. 서버 관리자에게 계정을 요청합니다.
공유 워크스페이스가 안 보임	로그인 계정과 워크스페이스 전환기를 확인합니다. 소유자에게 정확한 이메일로 추가를 요청합니다. 계정 생성만으로 멤버십이 생기지 않습니다.
편집·새로 만들기 버튼이 없음	역할 또는 페이지 상태가 제한할 수 있습니다. 소유자에게 역할을 확인하세요. 뷰어는 편집 권한이 없습니다.
내부 페이지 링크가 열리지 않음	같은 서버의 멤버 계정으로 로그인하세요. 내부 링크는 새 접근 권한을 주지 않습니다.
공개 페이지가 열리지 않음	발행된 버전이 없거나 웹 공유가 꺼졌을 수 있습니다. 작성자에게 확인하세요. 내부 발행과 웹 게시는 별개입니다.
수정한 내용이 나에게만 보임	비공개 편집·초안 상태인지 확인합니다. 편집 저장과 검토된 버전 발행은 다른 단계입니다. 컨텍스트 페이지를 참고하세요.
“더 보기”가 표시됨	목록이 나뉘어 표시됩니다. 더 보기를 눌러 나머지 항목을 확인합니다. 첫 화면이 전체 목록은 아닙니다.
이미지·파일 가져오기가 처리 중	자료 상태와 앱의 DB를 사용하는 같은 버전 작업자가 실행 중인지 확인합니다. 처리가 진행되지 않으면 운영자가 설정 → 작업을 점검합니다.
저장 중 충돌 표시	다른 편집이 기준 버전을 바꿨을 수 있습니다. 내 작업을 보존하고 현재 버전을 불러와 충돌·검토 절차를 따릅니다. 반복해서 덮어쓰지 마세요.
링크 복사가 실패함	제공되는 텍스트 선택으로 직접 복사합니다. 브라우저가 자동 복사를 막거나 HTTPS를 요구할 수 있습니다.

비밀번호를 잊었다면 서버의 복구 기능을 사용하고, 없다면 서버 운영자에게 문의합니다. 워크스페이스 소유자가 자동으로 계정 복구 권한을 갖지는 않습니다. 계정과 접근을 참고하세요.

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

질문과 검색

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

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

AI 연결 문제

증상·코드	의미와 조치
/mcp를 직접 열면 401	인증 정보가 없으면 정상입니다. PAT를 설정하거나 OAuth 동의를 완료합니다. 만료·폐기된 자격 증명도 인증 실패를 일으킵니다.
token_workspace_denied	계정이 멤버여도 자격 증명이 해당 공간을 허용하지 않습니다. 설정 → MCP 접근에서 연결의 허용 워크스페이스를 수정합니다.
쓰기 작업 거부	멤버 역할과 자격 증명의 권한 범위를 모두 확인합니다. 읽기 전용 키나 뷰어 역할은 쓰기를 허용하지 않습니다.
OAuth 사용 불가	서버에 HTTPS issuer가 필요합니다. 평문 HTTP 평가에서는 액세스 키를 사용합니다. 내부 CA라면 브라우저와 클라이언트에 CA 신뢰를 설정합니다.
설정에 연결이 보이지만 도구 실패	등록과 성공적인 호출은 다른 검사입니다. 클라이언트에 접근 가능한 워크스페이스 목록과 아는 페이지 하나를 읽도록 요청합니다.
/mcp가 랜딩 HTML을 반환	프록시가 MCP를 웹 앱으로 보내고 있습니다. 운영자가 /mcp 경로를 확인해야 합니다.
unknown_tool	요청한 이름이 서버의 현재 도구 목록에 없습니다. 클라이언트의 도구 목록을 갱신하고 저장된 지침에서 지원되지 않는 도구 이름을 제거합니다.
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 앱 연결을 따르세요.

운영자 서버 점검

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”	업데이트·롤백·자료 이관 전 두 쓰기 프로세스를 중지합니다. systemd: sudo systemctl stop dtxwiki-worker dtxwiki. Docker: docker compose stop app worker.
migration_preflight_refused	원본 데이터베이스를 보존하고 전체 오류를 기록합니다. 변경하기 전에 실제 자료 경로와 백업을 확인하고 백업과 유지보수를 따릅니다. 무작정 stamp를 바꾸거나 데이터베이스를 지우지 않습니다.
기존 리비전 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 설정과 백업을 확인합니다. 완전한 정상 백업을 복구하거나 별도로 검증할 재구축 계획을 세웁니다.

/health/live는 프로세스가 살아 있는지 확인합니다. /health/ready는 데이터베이스와 앱 버전 동기화 등을 포함한 준비 상태를 확인합니다. 배포 검증에서는 성공한 health 응답 뒤 브라우저 로그인과 자료 읽기도 확인하세요.

도움 요청과 문제 제보

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

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

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

---

버전 근거: 운영 문제 해결·마이그레이션 판정, MCP 도구와 연결.