오류 처리 및 문제 해결 가이드

T2Editor를 설치하거나 사용할 때 여러 가지 문제가 발생할 수 있습니다. 이 문서는 주요 오류의 원인을 파악하고 적절한 해결책을 제시하여 초보자부터 개발자까지 누구나 문제를 빠르게 처리할 수 있도록 돕습니다. 대부분의 문제는 파일 권한 설정, 환경 구성, 라이선스 인증 등 기본적인 점검만으로 해결할 수 있으므로, 설치 과정에서 꼼꼼하게 확인하는 것이 중요합니다.

이 문서는 2026-09-28에 v10.5.1 기준으로 다시 썼습니다. 9.x 이하 계열은 EOL이며 업데이트 대상이 아닙니다.

빠른 요약

• 파일 권한 문제 – 협업 데이터의 실제 위치는 T2EDITOR_COLLAB_PATH 상수로 확인되며 그누보드5는 CMS의 data/t2editor_db/collab/, 라이믹스는 files/t2editor_db/collab/, CMS 없이는 <t2editor>/data/t2editor_db/collab/입니다. 10.5.1은 처음 실행 때 t2editor/collab/ 같은 예전 폴더가 있으면 자동으로 새 위치로 옮깁니다. t2editor/collab/에 707을 주는 절차는 10.5.x에서 유효하지 않습니다. 확인할 것은 ① 에디터 하단 정보·진단 화면 → 현재 서버 점검 결과의 공용 데이터 쓰기 검사 ② 서버 오류 로그의 file_put_contents(): failed to open stream ③ 그누보드5라면 G5_DIR_PERMISSION 값입니다. 참고로 sudo chmod 707 은 잘못된 지시입니다(707은 디렉터리의 최소 권장값이고 sudo 가 필요하지 않습니다).
• 라이선스 인증 오류 – 다운로드한 T2Editor 패키지에는 라이선스 파일이 포함되어 있으며, 이 파일이 없거나 손상되면 에디터가 정상적으로 동작하지 않습니다. DSclub 페이지에서 해당 버전과 일치하는 라이선스 파일을 다시 설치하세요DSclub T2Editor 서비스 페이지 - 설치·오류 안내.
• 폰트 및 스타일 오류 – 커스텀 테마나 타 사이트에서 가져온 스킨을 사용할 경우 글꼴이나 스타일이 깨질 수 있습니다. fonts/와 css/ 디렉터리의 경로 및 파일 존재 여부를 확인하고, 캐시를 삭제한 후 새로고침합니다DSclub T2Editor 서비스 페이지 - 오류 해결 안내.
• 업로드 오류 – 이미지나 파일 업로드가 실패할 때는 config/upload_config.php에서 허용 확장자와 최대 용량을 확인하고, data/ 디렉터리에 쓰기 권한이 있는지 점검합니다DSclub T2Editor 서비스 페이지 - 설치·오류 안내.
• 버전 불일치 문제 – T2Editor의 코어와 플러그인 버전이 맞지 않으면 기능이 깨질 수 있습니다. 사용 중인 버전을 확인하고, DSclub 또는 SIR 커뮤니티에서 제공하는 최신 패치를 적용하세요DSclub T2Editor 서비스 페이지 - 버전 변경 공지.

초보자와 웹마스터를 위한 기본 점검 목록

1. 패키지 확인: T2Editor는 여러 버전이 존재합니다. DSclub 또는 SIR에서 다운로드한 패키지가 사이트에 맞는지 확인하세요. 버전이 맞지 않으면 에디터가 정상적으로 로드되지 않습니다DSclub T2Editor 서비스 페이지 - 버전 변경 공지.
2. 폴더 권한 설정: 쓰기 권한이 필요한 곳은 공용 데이터 경로 하나이며 최소 권장값은 707입니다. 협업 데이터의 실제 위치는 T2EDITOR_COLLAB_PATH 상수로 확인되며 그누보드5는 CMS의 data/t2editor_db/collab/, 라이믹스는 files/t2editor_db/collab/, CMS 없이는 <t2editor>/data/t2editor_db/collab/입니다. 10.5.1은 처음 실행 때 t2editor/collab/ 같은 예전 폴더가 있으면 자동으로 새 위치로 옮깁니다. t2editor/collab/에 707을 주는 절차는 10.5.x에서 유효하지 않습니다. 확인할 것은 ① 에디터 하단 정보·진단 화면 → 현재 서버 점검 결과의 공용 데이터 쓰기 검사 ② 서버 오류 로그의 file_put_contents(): failed to open stream ③ 그누보드5라면 G5_DIR_PERMISSION 값입니다. 웹호스팅 업체에 따라 FTP 프로그램(예: FileZilla)으로 그 폴더 하나의 권한을 변경할 수 있습니다.
3. 데이터 디렉터리 점검: 업로드나 자동 저장 기능이 오류를 발생시킨다면 t2editor/data/ 폴더의 쓰기 권한을 확인하세요. 권한이 없으면 파일 저장이 되지 않아 업로드가 실패합니다.
4. 라이선스 확인: 현재 판본의 라이선스는 배포판 루트의 readme.txt 한 파일 안에 한국어(사용 권한)와 영어(Usage Rights)로 들어 있습니다. 별도의 license.txt·license.dat·license_en.txt·license_kr.txt 파일은 배포판에 없습니다. 확인 순서는 ① 배포판 루트에 readme.txt가 있는가 ② 그 내용이 원본과 같은가 ③ config/t2_config.php와 config/upload_config.php가 있는가 입니다. readme.txt를 직접 편집하거나 지운 채 재배포하면 안 됩니다(라이선스 조항 위반이고 검증이 실패합니다). AI 등 DSclub 연동 기능의 인증은 라이선스 토큰이 아니라 관리자 로그인(CMS 관리자 또는 T2Editor 자체 비밀번호)이며, 최초 설정은 admin/t2admin.key.txt → admin/t2admin.key 이름 변경 + 관리자 비밀번호 설정입니다. 07-license-guide.md를 보십시오.
5. 브라우저 캐시 삭제: CSS나 JS 변경 후에도 화면에 반영되지 않는다면 브라우저 캐시를 삭제하거나 강제 새로고침(Ctrl+F5)을 수행하십시오.
6. PHP 버전 확인: 최소 PHP 7.4.0이며 신규 운영은 8.1 또는 8.2를 권장합니다(7.4~8.4 호환 유지). 10.0.0(2026-06-24) 노트가 PHP "권장 사양"을 8.0 이상으로 올렸지만 10.1.0(2026-06-29) 노트 "php7.4 호환 추가!"로 되돌렸으므로 8.0은 필수가 아닙니다. 확장에 따라 요구가 갈립니다 — cURL은 업데이트 시 OpenSSL 스트림으로 대체되지만 확장 마켓(서드파티 설치)에 필수, ZIP 처리는 ZipArchive → 내장 zlib → 관리자 브라우저 폴백 3단, mbstring은 iconv·UTF-8 대체 경로가 있습니다. GD는 업로드를 막는 필수 판정이 아닙니다. 정확한 등급(error/warning)은 에디터 하단 정보·진단 화면의 "현재 서버 점검 결과"가 표시합니다.

자주 발생하는 오류와 해결 방법

협업 기능이 동작하지 않음

증상: 협업 버튼을 눌러도 아무런 반응이 없거나 “접속할 수 없습니다”라는 오류 메시지가 표시됩니다.

해결책:

1. 공용 데이터 경로의 쓰기 권한이 707 이상인지 확인합니다(협업 폴더를 따로 만들지 않습니다). 협업 데이터의 실제 위치는 T2EDITOR_COLLAB_PATH 상수로 확인되며 그누보드5는 CMS의 data/t2editor_db/collab/, 라이믹스는 files/t2editor_db/collab/, CMS 없이는 <t2editor>/data/t2editor_db/collab/입니다. 10.5.1은 처음 실행 때 t2editor/collab/ 같은 예전 폴더가 있으면 자동으로 새 위치로 옮깁니다. t2editor/collab/에 707을 주는 절차는 10.5.x에서 유효하지 않습니다. 확인할 것은 ① 에디터 하단 정보·진단 화면 → 현재 서버 점검 결과의 공용 데이터 쓰기 검사 ② 서버 오류 로그의 file_put_contents(): failed to open stream ③ 그누보드5라면 G5_DIR_PERMISSION 값입니다.
2. 서버의 방화벽이나 SELinux 설정 때문에 웹 서버 프로세스가 해당 디렉터리에 접근하지 못할 수도 있습니다. 로그를 확인하고 적절히 해제하거나 예외 규칙을 추가합니다.
3. PHP 세션 저장 경로가 제대로 설정되지 않았을 경우, 세션이 공유되지 않아 협업이 불가능합니다. php.ini에서 session.save_path를 확인하십시오.

이미지/파일 업로드 실패

증상: 파일을 업로드하면 “업로드 실패” 메시지가 나타나거나, 업로드된 미리보기가 보이지 않습니다.

해결책:

1. config/upload_config.php에서 확장자 목록과 업로드 용량이 적절하게 설정되어 있는지 확인합니다. 필요하다면 허용 목록에 확장자를 추가하세요DSclub T2Editor 서비스 페이지 - 설치·오류 안내.
2. data/ 폴더의 권한이 충분한지 확인합니다. 707 권한(웹 서버가 쓰기 가능)을 부여하고, Apache/Nginx 사용자 계정이 소유자로 지정되어 있는지 점검합니다.
3. 현재 판본은 업로드를 파일 시그니처로 검증하므로 PHP fileinfo 확장이 없어도 정상 동작합니다(config/upload_config.php:31-32 "server-side identification uses signatures so Fileinfo is not required"). fileinfo는 브라우저 응답 메타데이터에만 쓰입니다. php.ini를 고칠 필요가 없습니다. 업로드가 거부되면 ① 허용 확장자 목록(문서·이미지·영상·기타) ② 공용 데이터 디렉터리 쓰기 권한 ③ 이미지 픽셀 상한(기본 50MP) ④ 용량 상한(기본 50MB)과 PHP의 upload_max_filesize·post_max_size 순으로 확인하십시오. 다른 형식 파일을 GIF로 위장하면 일반 서버 오류 대신 올바른 파일 형식 오류가 표시됩니다.

AI 플러그인 호출 오류

증상: AI 버튼을 클릭해도 응답이 없거나 “라이선스 인증 실패” 오류가 표시됩니다.

해결책:

1. 현재 판본의 라이선스는 배포판 루트의 readme.txt 한 파일 안에 한국어(사용 권한)와 영어(Usage Rights)로 들어 있습니다. 별도의 license.txt·license.dat·license_en.txt·license_kr.txt 파일은 배포판에 없습니다. 확인 순서는 ① 배포판 루트에 readme.txt가 있는가 ② 그 내용이 원본과 같은가 ③ config/t2_config.php와 config/upload_config.php가 있는가 입니다. readme.txt를 직접 편집하거나 지운 채 재배포하면 안 됩니다(라이선스 조항 위반이고 검증이 실패합니다). AI 등 DSclub 연동 기능의 인증은 라이선스 토큰이 아니라 관리자 로그인(CMS 관리자 또는 T2Editor 자체 비밀번호)이며, 최초 설정은 admin/t2admin.key.txt → admin/t2admin.key 이름 변경 + 관리자 비밀번호 설정입니다. 07-license-guide.md를 보십시오.
2. 플러그인 내부에서 API 키를 재정의하지 않은 상태라면 DSclub 서버와의 통신에 실패할 수 있습니다. 플러그인 설정을 확인하여 API 키나 서버 주소를 정확하게 지정합니다SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의.
3. 기본 제공 AI API를 쓰는 경우 IP·서버 도메인별 사용량 한도가 있고, 화면에 남은 양과 한도가 표시됩니다. 한도 값은 서버 응답으로 정해지므로 이 문서에 수치를 적지 않습니다. 실제 값은 편집 화면의 AI 사용량 표시에서 확인하십시오. 10.2.0부터는 LLM API를 직접 호스팅해 이 한도를 쓰지 않을 수도 있습니다. (구 인용문의 "25회/일" 수치의 유일한 출처는 EOL인 SIR 8.1.2 글이므로 현재 근거로 쓰지 않습니다.)

스타일·폰트가 깨짐

증상: 글꼴이 비정상적으로 보이거나 버튼 아이콘이 표시되지 않습니다.

해결책:

1. css/와 fonts/ 폴더의 파일들이 모두 존재하는지 확인하고, 경로가 올바른지 index.php와 스킨 파일에서 확인합니다DSclub T2Editor 서비스 페이지 - 오류 해결 안내.
2. 새로운 스킨을 적용한 후라면, 해당 스킨의 스타일시트가 T2Editor의 스타일을 덮어쓰지 않는지 확인합니다. CSS 우선순위를 조정하거나 클래스명을 변경하세요.
3. 캐시를 비우고 강제 새로고침을 하면 로컬 브라우저 캐시로 인해 발생한 문제를 해결할 수 있습니다.

기타 PHP 오류 및 백엔드 이슈

• White Page/500 에러: PHP 오류가 발생하면 에디터가 빈 화면만 보일 수 있습니다. 서버 로그(/var/log/php-fpm.log 또는 웹 서버 에러 로그)를 확인하여 문제의 원인을 파악하고 수정하십시오.
• 메모리 부족 오류: 대용량 이미지를 처리하거나, AI 플러그인을 사용할 때 PHP 메모리 제한에 도달하면 오류가 발생할 수 있습니다. php.ini에서 memory_limit를 늘리고, 업로드 크기 제한(upload_max_filesize, post_max_size)도 함께 조정하세요.
• CORS 오류: 10.4.0부터 부적절한 이미지 필터는 배포판에 포함된 파일(vendor/nsfwjs/ + config/nsfw_api_browser.js)로 브라우저에서 직접 구동하므로 서버 엔드포인트에 Access-Control-Allow-Origin을 추가할 대상이 없습니다(해당 파일 nsfw_api_server.php는 10.5.1에 존재하지 않습니다 — core-nsfw_api_server-php.md 참고). AI·검색·ClipURL·링크 미리보기 카드처럼 외부 API를 호출하는 기능에서 CORS 오류가 나면 ① 요청 대상 도메인과 config/remote_proxy.php 경유 여부 ② 관리자 환경 정보의 외부 접속 점검 ③ 브라우저 콘솔의 요청 URL을 확인하십시오.

이미 해결된 항목 — 아래 증상은 현재 판본(10.5.1)에서 이미 고쳐졌습니다. 해당 항목을 해결책으로 따라하지 마시고, 판본을 갱신하십시오.

이 목록은 삭제가 아니라 "해결됨" 표시를 남기는 추가입니다. 위 증상이 현재 판본에서도 보이면 ① 4절의 환경 점검(10.4.0 관리자 페이지의 서버 상태 자동 점검) ② 브라우저 캐시 삭제 ③ 그누보드5를 갱신했다면 CMS 데이터 경로(10.5.1의 data/editor/t2editor_db → data/t2editor_db 자동 이전) 상태를 확인하십시오.

개발자를 위한 심층 분석

이 섹션에서는 오류 발생의 근본 원인을 코드 레벨에서 분석하고 해결하는 방법을 제시합니다.

권한 오류의 구조

협업 기능은 10.0.0에서 JSON 파일 갱신 방식에서 p2p + 서버 하이브리드로 바뀌었고, 상태 파일은 T2EDITOR_COLLAB_PATH 아래(data/t2editor_db/collab/)에 저장됩니다. 세션 키를 관리하는 파일로 지목된 editor.lib.php는 10.5.1에서 43줄짜리 불변 부트스트랩이며 인증 로직을 담지 않습니다. 협업 인증 경로의 정확한 위치는 plugin/collab/ 하위 구현과 어댑터 쪽 코드이므로, 파일 본문을 직접 확인하기 전에는 정확한 함수·상수명을 단정하지 마십시오. [확인 필요] — 협업 인증(세션 키) 실체 위치.

쓰기 대상은 공용 데이터 경로 하나입니다(최소 권장 707). 그 경로에 쓰기 권한이 없으면 세션 파일이 생성되지 않고 fetch 요청이 실패하며, 서버 로그에서 file_put_contents(): failed to open stream이 나타납니다. 이때 확인할 것은 ① UNIX 파일 시스템 권한 ② SELinux 컨텍스트 ③ 웹 서버 사용자 권한 ④ 그누보드5라면 G5_DIR_PERMISSION 값입니다. 루트 collab/ 폴더에 권한을 주는 절차는 10.5.x에서 유효하지 않습니다.

라이선스 검증 로직

10.5.1의 라이선스 검증은 editor.core.php의 _t2e_validate_readme()가 수행합니다. readme.txt에서 한국어 사용 권한·영어 Usage Rights 블록과 라이선스 파일 참조 줄을 뽑아 sha256 해시를 내장 기대값과 hash_equals로 비교합니다. X-T2Editor-License·X-DSCLUB-SIGN·X-T2Editor-Verify 헤더는 AI 플러그인(plugin/ai_complex/ai_complex.js)이 외부 API 호출 시 붙입니다. 검증 코드를 추가하거나 우회하는 코드를 작성하지 마십시오 — readme.txt를 원본 그대로 두는 것이 유일하게 올바른 상태입니다. 로컬에서 확인하고 싶으면 readme.txt의 존재와 원본 일치 여부만 보십시오.

업로드 처리 플로우

이미지 업로드는 plugin/image/image.js가 파일을 읽어 plugin/image/image_upload.php(서버 처리 image_upload.core.php)로 보내고, 파일 업로드는 plugin/file/file_upload.php가 담당합니다. 10.5.1은 일부 CMS의 실행 구조 안에서 업로드 설정이 잘못된 범위로 불러와져 이미지 확장자 목록을 찾지 못해 GIF 업로드가 500 오류를 내던 문제를 고쳤습니다. 업로드 실패 시에는 서버 오류 로그의 파일 형식·용량·쓰기 오류를 확인하십시오.

현재 판본의 업로드 정책은 config/upload_config.php의 상수와 정책 함수로 정의되어 있습니다. ① 최대 용량 = 상수 T2EDITOR_MAX_UPLOAD_SIZE(기본 50MB) ② 허용 확장자 = t2editor_default_upload_extensions()가 document·image·video·other 네 묶음으로 정의하며, SVG(액티브 콘텐츠·XSS 위험)와 ICO(GD·MIME 처리 불일치)는 의도적으로 제외되어 있습니다 ③ 조회는 $GLOBALS['t2editor_allowed_extensions']와 헬퍼를 거칩니다. allowed_extensions나 max_file_size 같은 변수는 존재하지 않습니다. 권장 변경 경로는 관리자 페이지의 업로드 설정 화면입니다(10.4.0 통합 관리 페이지에 편입 — N-02-admin-console-guide.md). 단, PHP·웹서버의 upload_max_filesize·post_max_size가 이 값보다 작으면 서버 설정이 이깁니다.

이전 문서의 "서버에서 GD 라이브러리로 이미지를 리사이즈한다"는 서술은 10.5.1의 config/upload_config.php에서 확인되지 않아 삭제했습니다. 실제 리사이즈 여부는 [확인 필요] 입니다.

AI 및 검색 API 오류 분석

AI 기능은 10.2.0부터 plugin/ai_complex/(클라이언트 ai_complex.js, 서버 api.php·api.core.php)가 담당합니다. 10.2.0에서 AI는 단순 플러그인이 아니라 공통 베이스 시스템(t2llm.js·t2ai_core.js)으로 진화했고, 기존의 단일 외부 경유를 전제로 한 호출 구조도 함께 바뀌었습니다. 따라서 이전 문서가 지목한 plugin/ai/ai.js 와 고정 경로 ?action=... 호출은 10.5.1에 없습니다. 대체 LLM을 쓸 때는 10.2.0부터 제공되는 LLM API 셀프 호스팅 경로를 사용하십시오. 도구(Tool)를 추가·삭제하려면 플러그인 모듈화를 따라야 하므로 헤더 재생성 로직을 직접 고치는 것은 권장되지 않습니다. plugin-ai.md를 보십시오.

테스트 포인트와 예방 전략

1. 설치 후 파일 검사: 현재 판본의 라이선스는 배포판 루트의 readme.txt 한 파일 안에 한국어(사용 권한)와 영어(Usage Rights)로 들어 있습니다. 별도의 license.txt·license.dat·license_en.txt·license_kr.txt 파일은 배포판에 없습니다. 확인 순서는 ① 배포판 루트에 readme.txt가 있는가 ② 그 내용이 원본과 같은가 ③ config/t2_config.php와 config/upload_config.php가 있는가 입니다. readme.txt를 직접 편집하거나 지운 채 재배포하면 안 됩니다(라이선스 조항 위반이고 검증이 실패합니다). AI 등 DSclub 연동 기능의 인증은 라이선스 토큰이 아니라 관리자 로그인(CMS 관리자 또는 T2Editor 자체 비밀번호)이며, 최초 설정은 admin/t2admin.key.txt → admin/t2admin.key 이름 변경 + 관리자 비밀번호 설정입니다. 07-license-guide.md를 보십시오.
2. 권한 테스트: 협업 기능을 사용할 때 실제로 파일이 생성되는지 테스트합니다. 실패하면 권한을 재검토합니다.
3. 업로드 테스트: 다양한 확장자와 크기의 파일을 업로드해보며, 에러 발생 여부를 확인합니다.
4. AI 호출 시험: AI 기능을 테스트하여 인증 실패 메시지가 있는지 체크합니다. API 호출 로그를 분석해 문제를 조기에 발견합니다.
5. 브라우저 콘솔 확인: CORS 오류나 자바스크립트 예외는 브라우저 개발자 도구의 콘솔을 통해 빠르게 확인할 수 있습니다.

참고 / 인용 자료

• DSclub에서 제공하는 설치 및 오류 처리 안내DSclub T2Editor 서비스 페이지 - 설치·오류 안내DSclub T2Editor 서비스 페이지 - 오류 해결 안내
• SIR 커뮤니티의 설치 가이드(권한 설정 포함)SIR T2Editor 8.1.2 설치 및 권한 설정 안내
• DSclub 버전별 문제 및 수정 사항 안내DSclub T2Editor 서비스 페이지 - 버전 변경 공지
• AI 및 외부 API 호출 과정에서 발생할 수 있는 보안 이슈 토론SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의

문서 관리 메모

• 판본별 이슈 대응(8.x·9.x 이력 포함): 72-version-issues-guide.md
• 최초 설치 게이트와 관리자 페이지: 01-installation-guide.md · N-02-admin-console-guide.md
• 서버측 본문 정제 공백: N-06-server-sanitize-and-content-style.md
• 위에 남긴 "이미 해결된 항목" 표는 삭제하지 마십시오. 릴리즈 노트가 해결을 지칭했더라도 특정 환경에서 재현될 수 있어, 지우면 "안 보임"이 "없음"으로 읽힙니다.

이 문서는 현재 T2Editor 10.5.1(2026-07-27) 판본을 기준으로 작성되었습니다. 9.x 이하 계열은 EOL이며 업데이트 대상이 아닙니다. 10.5.0·10.5.1에서 이미 해결된 항목은 아래 "이미 해결된 항목" 절에 표시했으므로, 그 항목을 해결책으로 따라하지 마십시오.