T2Editor를 설치하거나 사용할 때 여러 가지 문제가 발생할 수 있습니다. 이 문서는 주요 오류의 원인을 파악하고 적절한 해결책을 제시하여 초보자부터 개발자까지 누구나 문제를 빠르게 처리할 수 있도록 돕습니다. 대부분의 문제는 파일 권한 설정, 환경 구성, 라이선스 인증 등 기본적인 점검만으로 해결할 수 있으므로, 설치 과정에서 꼼꼼하게 확인하는 것이 중요합니다.
collab/)의 권한이 적절하지 않으면 협업 기능이 동작하지 않습니다. GNUBoard5 플러그인으로 사용 시 sudo chmod 707 명령으로 collab 폴더에 전체 권한을 부여해야 합니다SIR T2Editor 8.1.2 설치 및 권한 설정 안내.fonts/와 css/ 디렉터리의 경로 및 파일 존재 여부를 확인하고, 캐시를 삭제한 후 새로고침합니다DSclub T2Editor 서비스 페이지 - 오류 해결 안내.config/upload_config.php에서 허용 확장자와 최대 용량을 확인하고, data/ 디렉터리에 쓰기 권한이 있는지 점검합니다DSclub T2Editor 서비스 페이지 - 설치·오류 안내.t2editor/collab/ 폴더의 권한을 707로 설정해야 협업 기능이 정상 동작합니다SIR T2Editor 8.1.2 설치 및 권한 설정 안내. 웹호스팅 업체에 따라 FTP 프로그램(예: FileZilla)을 사용하여 권한을 변경할 수 있습니다.t2editor/data/ 폴더의 쓰기 권한을 확인하세요. 권한이 없으면 파일 저장이 되지 않아 업로드가 실패합니다.license.txt 또는 license.dat 파일은 DSclub API 호출에 필요한 라이선스 토큰을 포함합니다. 다른 서버로 이동하거나 업데이트할 때 이 파일이 사라지면 AI 등 외부 서비스가 작동하지 않습니다DSclub T2Editor 서비스 페이지 - 설치·오류 안내.증상: 협업 버튼을 눌러도 아무런 반응이 없거나 “접속할 수 없습니다”라는 오류 메시지가 표시됩니다.
해결책:
collab/ 폴더 권한을 707로 설정했는지 확인합니다SIR T2Editor 8.1.2 설치 및 권한 설정 안내.php.ini에서 session.save_path를 확인하십시오.증상: 파일을 업로드하면 “업로드 실패” 메시지가 나타나거나, 업로드된 미리보기가 보이지 않습니다.
해결책:
config/upload_config.php에서 확장자 목록과 업로드 용량이 적절하게 설정되어 있는지 확인합니다. 필요하다면 허용 목록에 확장자를 추가하세요DSclub T2Editor 서비스 페이지 - 설치·오류 안내.data/ 폴더의 권한이 충분한지 확인합니다. 707 권한(웹 서버가 쓰기 가능)을 부여하고, Apache/Nginx 사용자 계정이 소유자로 지정되어 있는지 점검합니다.fileinfo 확장 모듈을 비활성화하여 MIME 타입을 인식하지 못할 경우 업로드가 차단될 수 있습니다. php.ini에서 fileinfo 모듈을 활성화하세요.증상: AI 버튼을 클릭해도 응답이 없거나 “라이선스 인증 실패” 오류가 표시됩니다.
해결책:
license.txt 파일이 존재하는지 확인하고, DSclub에서 발급받은 최신 라이선스를 사용합니다DSclub T2Editor 서비스 페이지 - 설치·오류 안내.증상: 글꼴이 비정상적으로 보이거나 버튼 아이콘이 표시되지 않습니다.
해결책:
css/와 fonts/ 폴더의 파일들이 모두 존재하는지 확인하고, 경로가 올바른지 index.php와 스킨 파일에서 확인합니다DSclub T2Editor 서비스 페이지 - 오류 해결 안내./var/log/php-fpm.log 또는 웹 서버 에러 로그)를 확인하여 문제의 원인을 파악하고 수정하십시오.php.ini에서 memory_limit를 늘리고, 업로드 크기 제한(upload_max_filesize, post_max_size)도 함께 조정하세요.nsfw_api_server.php 등에서 Access-Control-Allow-Origin 헤더를 추가하거나, 프록시를 사용해 해결할 수 있습니다SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의.이 섹션에서는 오류 발생의 근본 원인을 코드 레벨에서 분석하고 해결하는 방법을 제시합니다.
협업 기능은 collab 디렉터리에 저장된 JSON 파일과 editor.lib.php에서 관리하는 세션 키를 기반으로 합니다. 만약 해당 폴더에 쓰기 권한이 없으면 세션 파일이 생성되지 않고, fetch 요청이 실패합니다. 서버 로그에서는 file_put_contents(): failed to open stream과 같은 메시지가 나타날 것입니다. 이를 해결하기 위해서는 UNIX 파일 시스템의 권한 뿐만 아니라 SELinux 컨텍스트와 웹 서버 사용자 권한을 함께 고려해야 합니다.
editor.lib.php는 DSclub API와 통신할 때 X-T2Editor-License 헤더를 추가합니다. 라이선스 토큰이 없거나 만료되면 DSclub 서버가 401 오류를 반환하고, 플러그인은 이를 LicenseError로 처리합니다. 개발자는 config/t2_config.php에서 라이선스 키를 검증하는 코드를 추가하여 로컬 환경에서도 서비스가 중단되지 않도록 할 수 있습니다.
이미지 업로드는 클라이언트 측 upload.js에서 FormData를 생성해 upload.php로 전송하고, 서버에서 GD 라이브러리로 이미지를 리사이즈합니다. 업로드 실패 시에는 $_FILES 배열을 덤프하여 MIME 타입과 크기를 확인해야 합니다. 또한 upload_config.php에서 allowed_extensions와 max_file_size 변수를 변경하여 특정 파일 형식과 크기를 허용할 수 있습니다.
AI 플러그인은 ai.js에서 fetch('/api/ai/t2editor/groq/interaction/index.php')를 호출합니다. 요청 시 포함되는 헤더에는 라이선스, 시간, 도메인 정보가 포함되며, X-DSCLUB-SIGN 헤더는 API 서명을 담고 있습니다. 호출 오류가 발생하면 응답 코드와 메시지를 콘솔에서 확인하고, 필요한 경우 X-T2Editor-Verify 헤더를 재생성하는 로직을 수정해야 합니다. 대체 API를 사용할 경우 인증 방식을 바꿔주어야 합니다SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의.
license.txt, t2_config.php, upload_config.php 등 필수 파일이 존재하는지 확인합니다.이 문서는 현재 T2Editor 9.0.0 버전을 기준으로 작성되었으며, 향후 업데이트나 서버 환경 변화에 따라 수정될 수 있습니다.
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 가 필요하지 않습니다).fonts/와 css/ 디렉터리의 경로 및 파일 존재 여부를 확인하고, 캐시를 삭제한 후 새로고침합니다DSclub T2Editor 서비스 페이지 - 오류 해결 안내.config/upload_config.php에서 허용 확장자와 최대 용량을 확인하고, data/ 디렉터리에 쓰기 권한이 있는지 점검합니다DSclub T2Editor 서비스 페이지 - 설치·오류 안내.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)으로 그 폴더 하나의 권한을 변경할 수 있습니다.t2editor/data/ 폴더의 쓰기 권한을 확인하세요. 권한이 없으면 파일 저장이 되지 않아 업로드가 실패합니다.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를 보십시오.ZipArchive → 내장 zlib → 관리자 브라우저 폴백 3단, mbstring은 iconv·UTF-8 대체 경로가 있습니다. GD는 업로드를 막는 필수 판정이 아닙니다. 정확한 등급(error/warning)은 에디터 하단 정보·진단 화면의 "현재 서버 점검 결과"가 표시합니다.증상: 협업 버튼을 눌러도 아무런 반응이 없거나 “접속할 수 없습니다”라는 오류 메시지가 표시됩니다.
해결책:
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 값입니다.php.ini에서 session.save_path를 확인하십시오.증상: 파일을 업로드하면 “업로드 실패” 메시지가 나타나거나, 업로드된 미리보기가 보이지 않습니다.
해결책:
config/upload_config.php에서 확장자 목록과 업로드 용량이 적절하게 설정되어 있는지 확인합니다. 필요하다면 허용 목록에 확장자를 추가하세요DSclub T2Editor 서비스 페이지 - 설치·오류 안내.data/ 폴더의 권한이 충분한지 확인합니다. 707 권한(웹 서버가 쓰기 가능)을 부여하고, Apache/Nginx 사용자 계정이 소유자로 지정되어 있는지 점검합니다.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 버튼을 클릭해도 응답이 없거나 “라이선스 인증 실패” 오류가 표시됩니다.
해결책:
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를 보십시오.증상: 글꼴이 비정상적으로 보이거나 버튼 아이콘이 표시되지 않습니다.
해결책:
css/와 fonts/ 폴더의 파일들이 모두 존재하는지 확인하고, 경로가 올바른지 index.php와 스킨 파일에서 확인합니다DSclub T2Editor 서비스 페이지 - 오류 해결 안내./var/log/php-fpm.log 또는 웹 서버 에러 로그)를 확인하여 문제의 원인을 파악하고 수정하십시오.php.ini에서 memory_limit를 늘리고, 업로드 크기 제한(upload_max_filesize, post_max_size)도 함께 조정하세요.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을 확인하십시오.| 증상 | 해결 판본 | 근거 요약 |
|---|---|---|
| 움직이는 GIF 업로드 시 500 오류("Image upload could not be completed on this server.") | 10.5.0 | GIF87a·GIF89a·투명·애니메이션 GIF와 대문자 .GIF 지원, 원본 그대로 저장. 다른 형식을 GIF로 위장하면 올바른 형식 오류 표시 |
| 이미지·비디오·파일·표·코드를 문장 중간에 넣으면 문서 끝으로 감 | 10.5.0 | Hello와 World 사이에 넣으면 Hello, 블록, World 순서 유지 |
| 텍스트를 덮어쓴 뒤 다음 입력이 에디터 맨 아래에서 시작 | 10.5.0 | 문단 위치 + 글자 위치를 함께 기록해 가장 가까운 원래 위치로 복원 |
| 이미지·표 위아래 빈 줄에서 Enter가 안 먹힘(iPhone·iPad Safari 특히) | 10.5.0 | 빈 문단을 안정적 편집 단위로 유지, Enter 후 최종 커서 확정 |
| 플러그인 버튼이 비활성 상태로 남거나 로딩 표시가 사라지지 않음 | 10.5.0 | 플러그인별 제한 시간 적용·실패 버튼 복구·오류 격리 |
| 자동저장 초안이 다른 글로 복원됨 | 10.5.0 | 페이지·게시물 주소·에디터 ID 기준으로 분리, 저장 빈도 묶기 |
| 관리자 대시보드가 "서버의 PHP 확장과 파일 권한을 확인하고 있습니다"에서 멈춤 | 10.5.1 | 문제 문자 안전 처리로 관리자 화면 스크립트 중단 방지 |
| 오래된 게시글을 편집하면 빈 화면 | 10.5.1 | 손상 문자만 안전 대체, 나머지는 정상 로드 |
| 그누보드5 관리자로 로그인했는데 T2Editor는 "관리자 로그인 필요"만 표시 | 10.5.1 | 그누보드5 인증 초기화 방식 수정 |
이 목록은 삭제가 아니라 "해결됨" 표시를 남기는 추가입니다. 위 증상이 현재 판본에서도 보이면 ① 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 기능은 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를 보십시오.
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를 보십시오.이 문서는 현재 T2Editor 10.5.1(2026-07-27) 판본을 기준으로 작성되었습니다. 9.x 이하 계열은 EOL이며 업데이트 대상이 아닙니다. 10.5.0·10.5.1에서 이미 해결된 항목은 아래 "이미 해결된 항목" 절에 표시했으므로, 그 항목을 해결책으로 따라하지 마십시오.
| 이전 | 새 버전 | ||
|---|---|---|---|
| 1 | --- | 1 | --- |
| 2 | title: 오류 처리 및 문제 해결 가이드 | 2 | title: 오류 처리 및 문제 해결 가이드 |
| 3 | document_id: 71 | 3 | document_id: 71 |
| 4 | slug: error-handling-guide | 4 | slug: error-handling-guide |
| 5 | target_editor_version: 9.0.0 | 5 | target_editor_version: 10.5.1 |
| 6 | document_type: troubleshooting | 6 | document_type: troubleshooting |
| 7 | doc_type: troubleshooting | 7 | doc_type: troubleshooting |
| 8 | target_readers: [초보자, 웹마스터, 개발자, AI agent] | 8 | target_readers: [초보자, 웹마스터, 개발자, AI agent] |
| 9 | importance: High | 9 | importance: High |
| 10 | dependency: Medium | 10 | dependency: Medium |
| 11 | core_type: Non-Core | 11 | core_type: Non-Core |
| 12 | stability: [Version‑Bound] | 12 | stability: [Version-Bound] |
| 13 | stable_anchor: [] | 13 | stable_anchor: [] |
| 14 | version_bound: [설치 환경, 버전별 버그] | 14 | version_bound: [설치 환경, 버전별 버그] |
| 15 | related_docs: [01-installation-guide.md, 06-version-compatibility-guide.md, 67-test-points-guide.md] | 15 | related_docs: [01-installation-guide.md, 06-version-compatibility-guide.md, 67-test-points-guide.md, 72-version-issues-guide.md, 07-license-guide.md, N-02-admin-console-guide.md, N-06-server-sanitize-and-content-style.md] |
| 16 | related_files: [t2editor/config/t2_config.php, t2editor/config/upload_config.php, t2editor/collab/] | 16 | related_files: [config/t2_config.php, config/upload_config.php, data/t2editor_db/collab/] |
| 17 | related_functions: [] | 17 | related_functions: [] |
| 18 | related_classes_modules: [] | 18 | related_classes_modules: [] |
| 19 | related_features: [설치, 업로드, 협업, 라이선스] | 19 | related_features: [설치, 업로드, 협업, 라이선스] |
| 20 | related_ui: [] | 20 | related_ui: [] |
| 21 | change_risk: 환경 설정과 권한 문제로 인한 기능 중단 위험 | 21 | change_risk: 환경 설정과 권한 문제로 인한 기능 중단 위험 |
| 22 | reading_order: 71 | 22 | reading_order: 71 |
| 23 | summary: T2Editor 설치와 사용 중에 발생할 수 있는 대표적인 오류와 해결 방법을 정리한 가이드입니다. | 23 | summary: T2Editor 설치와 사용 중에 발생할 수 있는 대표적인 오류와 해결 방법을 정리한 가이드입니다. |
| 24 | description: 권한 문제, 업로드 오류, 라이선스 인증 실패 등 T2Editor에서 자주 발생하는 문제들의 원인과 해결책을 정리하였습니다. 설치 단계에서 올바른 권한 설정과 구성 파일 점검을 통해 대부분의 오류를 예방할 수 있습니다. | 24 | description: 권한 문제, 업로드 오류, 라이선스 인증 실패 등 T2Editor에서 자주 발생하는 문제들의 원인과 해결책을 정리하였습니다. 설치 단계에서 올바른 권한 설정과 구성 파일 점검을 통해 대부분의 오류를 예방할 수 있습니다. |
| 25 | tags: [T2Editor, troubleshooting, error handling, 설치, collab, 권한] | 25 | tags: [T2Editor, troubleshooting, error handling, 설치, 권한, v10] |
| 26 | version_tag: 9.0.0 | 26 | version_tag: 10.5.1 |
| 27 | maintenance_difficulty: High | 27 | maintenance_difficulty: High |
| 28 | test_requirement: High | 28 | test_requirement: High |
| 29 | ai_agent_risk: Medium | 29 | ai_agent_risk: Medium |
| 30 | source_basis: [현재 코드 분석 기반, 웹 참고 자료 기반] | 30 | source_basis: [현재 코드 분석 기반, 공식 릴리즈 노트 기반, 공식 배포판 실물 기반] |
| 31 | beginner_section_included: true | 31 | beginner_section_included: true |
| 32 | webmaster_section_included: true | 32 | webmaster_section_included: true |
| 33 | developer_section_included: true | 33 | developer_section_included: true |
| 34 | --- | 34 | --- |
| 35 | 35 | ||
| 36 | # 오류 처리 및 문제 해결 가이드 | 36 | # 오류 처리 및 문제 해결 가이드 |
| 37 | 37 | ||
| 38 | T2Editor를 설치하거나 사용할 때 여러 가지 문제가 발생할 수 있습니다. 이 문서는 주요 오류의 원인을 파악하고 적절한 해결책을 제시하여 초보자부터 개발자까지 누구나 문제를 빠르게 처리할 수 있도록 돕습니다. 대부분의 문제는 파일 권한 설정, 환경 구성, 라이선스 인증 등 기본적인 점검만으로 해결할 수 있으므로, 설치 과정에서 꼼꼼하게 확인하는 것이 중요합니다. | 38 | T2Editor를 설치하거나 사용할 때 여러 가지 문제가 발생할 수 있습니다. 이 문서는 주요 오류의 원인을 파악하고 적절한 해결책을 제시하여 초보자부터 개발자까지 누구나 문제를 빠르게 처리할 수 있도록 돕습니다. 대부분의 문제는 파일 권한 설정, 환경 구성, 라이선스 인증 등 기본적인 점검만으로 해결할 수 있으므로, 설치 과정에서 꼼꼼하게 확인하는 것이 중요합니다. |
| 39 | 39 | ||
| 40 | > 이 문서는 2026-09-28에 v10.5.1 기준으로 다시 썼습니다. 9.x 이하 계열은 EOL이며 업데이트 대상이 아닙니다. | ||
| 41 | |||
| 40 | ## 빠른 요약 | 42 | ## 빠른 요약 |
| 41 | 43 | ||
| 42 | * **파일 권한 문제** – 협업 디렉터리(`collab/`)의 권한이 적절하지 않으면 협업 기능이 동작하지 않습니다. GNUBoard5 플러그인으로 사용 시 `sudo chmod 707` 명령으로 `collab` 폴더에 전체 권한을 부여해야 합니다[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016). | 44 | * **파일 권한 문제** – 협업 데이터의 실제 위치는 `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 가 필요하지 않습니다). |
| 43 | * **라이선스 인증 오류** – 다운로드한 T2Editor 패키지에는 라이선스 파일이 포함되어 있으며, 이 파일이 없거나 손상되면 에디터가 정상적으로 동작하지 않습니다. DSclub 페이지에서 해당 버전과 일치하는 라이선스 파일을 다시 설치하세요[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). | 45 | * **라이선스 인증 오류** – 다운로드한 T2Editor 패키지에는 라이선스 파일이 포함되어 있으며, 이 파일이 없거나 손상되면 에디터가 정상적으로 동작하지 않습니다. DSclub 페이지에서 해당 버전과 일치하는 라이선스 파일을 다시 설치하세요[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). |
| 44 | * **폰트 및 스타일 오류** – 커스텀 테마나 타 사이트에서 가져온 스킨을 사용할 경우 글꼴이나 스타일이 깨질 수 있습니다. `fonts/`와 `css/` 디렉터리의 경로 및 파일 존재 여부를 확인하고, 캐시를 삭제한 후 새로고침합니다[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor). | 46 | * **폰트 및 스타일 오류** – 커스텀 테마나 타 사이트에서 가져온 스킨을 사용할 경우 글꼴이나 스타일이 깨질 수 있습니다. `fonts/`와 `css/` 디렉터리의 경로 및 파일 존재 여부를 확인하고, 캐시를 삭제한 후 새로고침합니다[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor). |
| 45 | * **업로드 오류** – 이미지나 파일 업로드가 실패할 때는 `config/upload_config.php`에서 허용 확장자와 최대 용량을 확인하고, `data/` 디렉터리에 쓰기 권한이 있는지 점검합니다[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). | 47 | * **업로드 오류** – 이미지나 파일 업로드가 실패할 때는 `config/upload_config.php`에서 허용 확장자와 최대 용량을 확인하고, `data/` 디렉터리에 쓰기 권한이 있는지 점검합니다[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). |
| 46 | * **버전 불일치 문제** – T2Editor의 코어와 플러그인 버전이 맞지 않으면 기능이 깨질 수 있습니다. 사용 중인 버전을 확인하고, DSclub 또는 SIR 커뮤니티에서 제공하는 최신 패치를 적용하세요[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor). | 48 | * **버전 불일치 문제** – T2Editor의 코어와 플러그인 버전이 맞지 않으면 기능이 깨질 수 있습니다. 사용 중인 버전을 확인하고, DSclub 또는 SIR 커뮤니티에서 제공하는 최신 패치를 적용하세요[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor). |
| 47 | 49 | ||
| 48 | ## 초보자와 웹마스터를 위한 기본 점검 목록 | 50 | ## 초보자와 웹마스터를 위한 기본 점검 목록 |
| 49 | 51 | ||
| 50 | 1. **패키지 확인**: T2Editor는 여러 버전이 존재합니다. DSclub 또는 SIR에서 다운로드한 패키지가 사이트에 맞는지 확인하세요. 버전이 맞지 않으면 에디터가 정상적으로 로드되지 않습니다[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor). | 52 | 1. **패키지 확인**: T2Editor는 여러 버전이 존재합니다. DSclub 또는 SIR에서 다운로드한 패키지가 사이트에 맞는지 확인하세요. 버전이 맞지 않으면 에디터가 정상적으로 로드되지 않습니다[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor). |
| 51 | 2. **폴더 권한 설정**: GNUBoard5 플러그인으로 설치할 경우, `t2editor/collab/` 폴더의 권한을 707로 설정해야 협업 기능이 정상 동작합니다[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016). 웹호스팅 업체에 따라 FTP 프로그램(예: FileZilla)을 사용하여 권한을 변경할 수 있습니다. | 53 | 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)으로 그 폴더 하나의 권한을 변경할 수 있습니다. |
| 52 | 3. **데이터 디렉터리 점검**: 업로드나 자동 저장 기능이 오류를 발생시킨다면 `t2editor/data/` 폴더의 쓰기 권한을 확인하세요. 권한이 없으면 파일 저장이 되지 않아 업로드가 실패합니다. | 54 | 3. **데이터 디렉터리 점검**: 업로드나 자동 저장 기능이 오류를 발생시킨다면 `t2editor/data/` 폴더의 쓰기 권한을 확인하세요. 권한이 없으면 파일 저장이 되지 않아 업로드가 실패합니다. |
| 53 | 4. **라이선스 파일 유지**: 패키지에 포함된 `license.txt` 또는 `license.dat` 파일은 DSclub API 호출에 필요한 라이선스 토큰을 포함합니다. 다른 서버로 이동하거나 업데이트할 때 이 파일이 사라지면 AI 등 외부 서비스가 작동하지 않습니다[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). | 55 | 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]]를 보십시오. |
| 54 | 5. **브라우저 캐시 삭제**: CSS나 JS 변경 후에도 화면에 반영되지 않는다면 브라우저 캐시를 삭제하거나 강제 새로고침(Ctrl+F5)을 수행하십시오. | 56 | 5. **브라우저 캐시 삭제**: CSS나 JS 변경 후에도 화면에 반영되지 않는다면 브라우저 캐시를 삭제하거나 강제 새로고침(Ctrl+F5)을 수행하십시오. |
| 55 | 6. **PHP 버전 확인**: T2Editor는 PHP 7.4 이상과 GD 라이브러리, cURL 확장 모듈을 필요로 합니다. 시스템 환경이 충족되지 않으면 일부 기능이 동작하지 않습니다[SIR T2Editor 8.1.2 소개 글](https://sir.kr/boards/g5_plugin/15016). | 57 | 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)은 에디터 하단 정보·진단 화면의 "현재 서버 점검 결과"가 표시합니다. |
| 56 | 58 | ||
| 57 | ## 자주 발생하는 오류와 해결 방법 | 59 | ## 자주 발생하는 오류와 해결 방법 |
| 58 | 60 | ||
| 59 | ### 협업 기능이 동작하지 않음 | 61 | ### 협업 기능이 동작하지 않음 |
| 60 | 62 | ||
| 61 | **증상**: 협업 버튼을 눌러도 아무런 반응이 없거나 “접속할 수 없습니다”라는 오류 메시지가 표시됩니다. | 63 | **증상**: 협업 버튼을 눌러도 아무런 반응이 없거나 “접속할 수 없습니다”라는 오류 메시지가 표시됩니다. |
| 62 | 64 | ||
| 63 | **해결책**: | 65 | **해결책**: |
| 64 | 66 | ||
| 65 | 1. `collab/` 폴더 권한을 707로 설정했는지 확인합니다[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016). | 67 | 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` 값입니다. |
| 66 | 2. 서버의 방화벽이나 SELinux 설정 때문에 웹 서버 프로세스가 해당 디렉터리에 접근하지 못할 수도 있습니다. 로그를 확인하고 적절히 해제하거나 예외 규칙을 추가합니다. | 68 | 2. 서버의 방화벽이나 SELinux 설정 때문에 웹 서버 프로세스가 해당 디렉터리에 접근하지 못할 수도 있습니다. 로그를 확인하고 적절히 해제하거나 예외 규칙을 추가합니다. |
| 67 | 3. PHP 세션 저장 경로가 제대로 설정되지 않았을 경우, 세션이 공유되지 않아 협업이 불가능합니다. `php.ini`에서 `session.save_path`를 확인하십시오. | 69 | 3. PHP 세션 저장 경로가 제대로 설정되지 않았을 경우, 세션이 공유되지 않아 협업이 불가능합니다. `php.ini`에서 `session.save_path`를 확인하십시오. |
| 68 | 70 | ||
| 69 | ### 이미지/파일 업로드 실패 | 71 | ### 이미지/파일 업로드 실패 |
| 70 | 72 | ||
| 71 | **증상**: 파일을 업로드하면 “업로드 실패” 메시지가 나타나거나, 업로드된 미리보기가 보이지 않습니다. | 73 | **증상**: 파일을 업로드하면 “업로드 실패” 메시지가 나타나거나, 업로드된 미리보기가 보이지 않습니다. |
| 72 | 74 | ||
| 73 | **해결책**: | 75 | **해결책**: |
| 74 | 76 | ||
| 75 | 1. `config/upload_config.php`에서 확장자 목록과 업로드 용량이 적절하게 설정되어 있는지 확인합니다. 필요하다면 허용 목록에 확장자를 추가하세요[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). | 77 | 1. `config/upload_config.php`에서 확장자 목록과 업로드 용량이 적절하게 설정되어 있는지 확인합니다. 필요하다면 허용 목록에 확장자를 추가하세요[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). |
| 76 | 2. `data/` 폴더의 권한이 충분한지 확인합니다. 707 권한(웹 서버가 쓰기 가능)을 부여하고, Apache/Nginx 사용자 계정이 소유자로 지정되어 있는지 점검합니다. | 78 | 2. `data/` 폴더의 권한이 충분한지 확인합니다. 707 권한(웹 서버가 쓰기 가능)을 부여하고, Apache/Nginx 사용자 계정이 소유자로 지정되어 있는지 점검합니다. |
| 77 | 3. 서버가 `fileinfo` 확장 모듈을 비활성화하여 MIME 타입을 인식하지 못할 경우 업로드가 차단될 수 있습니다. php.ini에서 `fileinfo` 모듈을 활성화하세요. | 79 | 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로 위장하면 일반 서버 오류 대신 올바른 파일 형식 오류가 표시됩니다. |
| 78 | 80 | ||
| 79 | ### AI 플러그인 호출 오류 | 81 | ### AI 플러그인 호출 오류 |
| 80 | 82 | ||
| 81 | **증상**: AI 버튼을 클릭해도 응답이 없거나 “라이선스 인증 실패” 오류가 표시됩니다. | 83 | **증상**: AI 버튼을 클릭해도 응답이 없거나 “라이선스 인증 실패” 오류가 표시됩니다. |
| 82 | 84 | ||
| 83 | **해결책**: | 85 | **해결책**: |
| 84 | 86 | ||
| 85 | 1. `license.txt` 파일이 존재하는지 확인하고, DSclub에서 발급받은 최신 라이선스를 사용합니다[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). | 87 | 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]]를 보십시오. |
| 86 | 2. 플러그인 내부에서 API 키를 재정의하지 않은 상태라면 DSclub 서버와의 통신에 실패할 수 있습니다. 플러그인 설정을 확인하여 API 키나 서버 주소를 정확하게 지정합니다[SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의](https://sir.kr/boards/g5_plugin/15016). | 88 | 2. 플러그인 내부에서 API 키를 재정의하지 않은 상태라면 DSclub 서버와의 통신에 실패할 수 있습니다. 플러그인 설정을 확인하여 API 키나 서버 주소를 정확하게 지정합니다[SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의](https://sir.kr/boards/g5_plugin/15016). |
| 87 | 3. 해당 IP나 도메인에 대한 호출 횟수가 제한(25회/일)되어 있어 거부되는 경우도 있습니다. 새 하루가 시작되기 전까지 기다리거나 Groq API 등 다른 서버를 사용하십시오[SIR T2Editor 8.1.2 AI·검색 기능 설명](https://sir.kr/boards/g5_plugin/15016). | 89 | 3. 기본 제공 AI API를 쓰는 경우 IP·서버 도메인별 사용량 한도가 있고, 화면에 남은 양과 한도가 표시됩니다. **한도 값은 서버 응답으로 정해지므로 이 문서에 수치를 적지 않습니다.** 실제 값은 편집 화면의 AI 사용량 표시에서 확인하십시오. 10.2.0부터는 LLM API를 직접 호스팅해 이 한도를 쓰지 않을 수도 있습니다. (구 인용문의 "25회/일" 수치의 유일한 출처는 EOL인 SIR 8.1.2 글이므로 현재 근거로 쓰지 않습니다.) |
| 88 | 90 | ||
| 89 | ### 스타일·폰트가 깨짐 | 91 | ### 스타일·폰트가 깨짐 |
| 90 | 92 | ||
| 91 | **증상**: 글꼴이 비정상적으로 보이거나 버튼 아이콘이 표시되지 않습니다. | 93 | **증상**: 글꼴이 비정상적으로 보이거나 버튼 아이콘이 표시되지 않습니다. |
| 92 | 94 | ||
| 93 | **해결책**: | 95 | **해결책**: |
| 94 | 96 | ||
| 95 | 1. `css/`와 `fonts/` 폴더의 파일들이 모두 존재하는지 확인하고, 경로가 올바른지 `index.php`와 스킨 파일에서 확인합니다[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor). | 97 | 1. `css/`와 `fonts/` 폴더의 파일들이 모두 존재하는지 확인하고, 경로가 올바른지 `index.php`와 스킨 파일에서 확인합니다[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor). |
| 96 | 2. 새로운 스킨을 적용한 후라면, 해당 스킨의 스타일시트가 T2Editor의 스타일을 덮어쓰지 않는지 확인합니다. CSS 우선순위를 조정하거나 클래스명을 변경하세요. | 98 | 2. 새로운 스킨을 적용한 후라면, 해당 스킨의 스타일시트가 T2Editor의 스타일을 덮어쓰지 않는지 확인합니다. CSS 우선순위를 조정하거나 클래스명을 변경하세요. |
| 97 | 3. 캐시를 비우고 강제 새로고침을 하면 로컬 브라우저 캐시로 인해 발생한 문제를 해결할 수 있습니다. | 99 | 3. 캐시를 비우고 강제 새로고침을 하면 로컬 브라우저 캐시로 인해 발생한 문제를 해결할 수 있습니다. |
| 98 | 100 | ||
| 99 | ### 기타 PHP 오류 및 백엔드 이슈 | 101 | ### 기타 PHP 오류 및 백엔드 이슈 |
| 100 | 102 | ||
| 101 | * **White Page/500 에러**: PHP 오류가 발생하면 에디터가 빈 화면만 보일 수 있습니다. 서버 로그(`/var/log/php-fpm.log` 또는 웹 서버 에러 로그)를 확인하여 문제의 원인을 파악하고 수정하십시오. | 103 | * **White Page/500 에러**: PHP 오류가 발생하면 에디터가 빈 화면만 보일 수 있습니다. 서버 로그(`/var/log/php-fpm.log` 또는 웹 서버 에러 로그)를 확인하여 문제의 원인을 파악하고 수정하십시오. |
| 102 | * **메모리 부족 오류**: 대용량 이미지를 처리하거나, AI 플러그인을 사용할 때 PHP 메모리 제한에 도달하면 오류가 발생할 수 있습니다. `php.ini`에서 `memory_limit`를 늘리고, 업로드 크기 제한(`upload_max_filesize`, `post_max_size`)도 함께 조정하세요. | 104 | * **메모리 부족 오류**: 대용량 이미지를 처리하거나, AI 플러그인을 사용할 때 PHP 메모리 제한에 도달하면 오류가 발생할 수 있습니다. `php.ini`에서 `memory_limit`를 늘리고, 업로드 크기 제한(`upload_max_filesize`, `post_max_size`)도 함께 조정하세요. |
| 103 | * **CORS 오류**: 브라우저 콘솔에 CORS 관련 오류가 나타나면 플러그인에서 외부 API 도메인을 적절히 허용하지 않은 것입니다. `nsfw_api_server.php` 등에서 `Access-Control-Allow-Origin` 헤더를 추가하거나, 프록시를 사용해 해결할 수 있습니다[SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의](https://sir.kr/boards/g5_plugin/15016). | 105 | * **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을 확인하십시오. |
| 104 | 106 | ||
| 107 | ### 이미 해결된 항목 — 아래 증상은 현재 판본(10.5.1)에서 이미 고쳐졌습니다. 해당 항목을 해결책으로 따라하지 마시고, 판본을 갱신하십시오. | ||
| 108 | |||
| 109 | | 증상 | 해결 판본 | 근거 요약 | | ||
| 110 | |---|---|---| | ||
| 111 | | 움직이는 GIF 업로드 시 500 오류("Image upload could not be completed on this server.") | 10.5.0 | GIF87a·GIF89a·투명·애니메이션 GIF와 대문자 .GIF 지원, 원본 그대로 저장. 다른 형식을 GIF로 위장하면 올바른 형식 오류 표시 | | ||
| 112 | | 이미지·비디오·파일·표·코드를 문장 중간에 넣으면 문서 끝으로 감 | 10.5.0 | Hello와 World 사이에 넣으면 Hello, 블록, World 순서 유지 | | ||
| 113 | | 텍스트를 덮어쓴 뒤 다음 입력이 에디터 맨 아래에서 시작 | 10.5.0 | 문단 위치 + 글자 위치를 함께 기록해 가장 가까운 원래 위치로 복원 | | ||
| 114 | | 이미지·표 위아래 빈 줄에서 Enter가 안 먹힘(iPhone·iPad Safari 특히) | 10.5.0 | 빈 문단을 안정적 편집 단위로 유지, Enter 후 최종 커서 확정 | | ||
| 115 | | 플러그인 버튼이 비활성 상태로 남거나 로딩 표시가 사라지지 않음 | 10.5.0 | 플러그인별 제한 시간 적용·실패 버튼 복구·오류 격리 | | ||
| 116 | | 자동저장 초안이 다른 글로 복원됨 | 10.5.0 | 페이지·게시물 주소·에디터 ID 기준으로 분리, 저장 빈도 묶기 | | ||
| 117 | | 관리자 대시보드가 "서버의 PHP 확장과 파일 권한을 확인하고 있습니다"에서 멈춤 | 10.5.1 | 문제 문자 안전 처리로 관리자 화면 스크립트 중단 방지 | | ||
| 118 | | 오래된 게시글을 편집하면 빈 화면 | 10.5.1 | 손상 문자만 안전 대체, 나머지는 정상 로드 | | ||
| 119 | | 그누보드5 관리자로 로그인했는데 T2Editor는 "관리자 로그인 필요"만 표시 | 10.5.1 | 그누보드5 인증 초기화 방식 수정 | | ||
| 120 | |||
| 121 | 이 목록은 삭제가 아니라 **"해결됨" 표시를 남기는 추가**입니다. 위 증상이 현재 판본에서도 보이면 ① 4절의 환경 점검(10.4.0 관리자 페이지의 서버 상태 자동 점검) ② 브라우저 캐시 삭제 ③ 그누보드5를 갱신했다면 CMS 데이터 경로(10.5.1의 `data/editor/t2editor_db` → `data/t2editor_db` 자동 이전) 상태를 확인하십시오. | ||
| 122 | |||
| 105 | ## 개발자를 위한 심층 분석 | 123 | ## 개발자를 위한 심층 분석 |
| 106 | 124 | ||
| 107 | 이 섹션에서는 오류 발생의 근본 원인을 코드 레벨에서 분석하고 해결하는 방법을 제시합니다. | 125 | 이 섹션에서는 오류 발생의 근본 원인을 코드 레벨에서 분석하고 해결하는 방법을 제시합니다. |
| 108 | 126 | ||
| 109 | ### 권한 오류의 구조 | 127 | ### 권한 오류의 구조 |
| 110 | 128 | ||
| 111 | 협업 기능은 `collab` 디렉터리에 저장된 JSON 파일과 `editor.lib.php`에서 관리하는 세션 키를 기반으로 합니다. 만약 해당 폴더에 쓰기 권한이 없으면 세션 파일이 생성되지 않고, `fetch` 요청이 실패합니다. 서버 로그에서는 `file_put_contents(): failed to open stream`과 같은 메시지가 나타날 것입니다. 이를 해결하기 위해서는 UNIX 파일 시스템의 권한 뿐만 아니라 SELinux 컨텍스트와 웹 서버 사용자 권한을 함께 고려해야 합니다. | 129 | 협업 기능은 10.0.0에서 JSON 파일 갱신 방식에서 **p2p + 서버 하이브리드**로 바뀌었고, 상태 파일은 `T2EDITOR_COLLAB_PATH` 아래(`data/t2editor_db/collab/`)에 저장됩니다. 세션 키를 관리하는 파일로 지목된 `editor.lib.php`는 10.5.1에서 43줄짜리 불변 부트스트랩이며 인증 로직을 담지 않습니다. 협업 인증 경로의 정확한 위치는 `plugin/collab/` 하위 구현과 어댑터 쪽 코드이므로, 파일 본문을 직접 확인하기 전에는 정확한 함수·상수명을 단정하지 마십시오. **[확인 필요]** — 협업 인증(세션 키) 실체 위치. |
| 112 | 130 | ||
| 131 | 쓰기 대상은 **공용 데이터 경로 하나**입니다(최소 권장 707). 그 경로에 쓰기 권한이 없으면 세션 파일이 생성되지 않고 `fetch` 요청이 실패하며, 서버 로그에서 `file_put_contents(): failed to open stream`이 나타납니다. 이때 확인할 것은 ① UNIX 파일 시스템 권한 ② SELinux 컨텍스트 ③ 웹 서버 사용자 권한 ④ 그누보드5라면 `G5_DIR_PERMISSION` 값입니다. 루트 `collab/` 폴더에 권한을 주는 절차는 10.5.x에서 유효하지 않습니다. | ||
| 132 | |||
| 113 | ### 라이선스 검증 로직 | 133 | ### 라이선스 검증 로직 |
| 114 | 134 | ||
| 115 | `editor.lib.php`는 DSclub API와 통신할 때 `X-T2Editor-License` 헤더를 추가합니다. 라이선스 토큰이 없거나 만료되면 DSclub 서버가 401 오류를 반환하고, 플러그인은 이를 `LicenseError`로 처리합니다. 개발자는 `config/t2_config.php`에서 라이선스 키를 검증하는 코드를 추가하여 로컬 환경에서도 서비스가 중단되지 않도록 할 수 있습니다. | 135 | 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`의 존재와 원본 일치 여부만 보십시오. |
| 116 | 136 | ||
| 117 | ### 업로드 처리 플로우 | 137 | ### 업로드 처리 플로우 |
| 118 | 138 | ||
| 119 | 이미지 업로드는 클라이언트 측 `upload.js`에서 `FormData`를 생성해 `upload.php`로 전송하고, 서버에서 GD 라이브러리로 이미지를 리사이즈합니다. 업로드 실패 시에는 $_FILES 배열을 덤프하여 MIME 타입과 크기를 확인해야 합니다. 또한 `upload_config.php`에서 `allowed_extensions`와 `max_file_size` 변수를 변경하여 특정 파일 형식과 크기를 허용할 수 있습니다. | 139 | 이미지 업로드는 `plugin/image/image.js`가 파일을 읽어 `plugin/image/image_upload.php`(서버 처리 `image_upload.core.php`)로 보내고, 파일 업로드는 `plugin/file/file_upload.php`가 담당합니다. 10.5.1은 일부 CMS의 실행 구조 안에서 업로드 설정이 잘못된 범위로 불러와져 이미지 확장자 목록을 찾지 못해 GIF 업로드가 500 오류를 내던 문제를 고쳤습니다. 업로드 실패 시에는 서버 오류 로그의 파일 형식·용량·쓰기 오류를 확인하십시오. |
| 120 | 140 | ||
| 141 | 현재 판본의 업로드 정책은 `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`가 이 값보다 작으면 서버 설정이 이깁니다. | ||
| 142 | |||
| 143 | > 이전 문서의 "서버에서 GD 라이브러리로 이미지를 리사이즈한다"는 서술은 10.5.1의 `config/upload_config.php`에서 확인되지 않아 삭제했습니다. 실제 리사이즈 여부는 **[확인 필요]** 입니다. | ||
| 144 | |||
| 121 | ### AI 및 검색 API 오류 분석 | 145 | ### AI 및 검색 API 오류 분석 |
| 122 | 146 | ||
| 123 | AI 플러그인은 `ai.js`에서 `fetch('/api/ai/t2editor/groq/interaction/index.php')`를 호출합니다. 요청 시 포함되는 헤더에는 라이선스, 시간, 도메인 정보가 포함되며, `X-DSCLUB-SIGN` 헤더는 API 서명을 담고 있습니다. 호출 오류가 발생하면 응답 코드와 메시지를 콘솔에서 확인하고, 필요한 경우 `X-T2Editor-Verify` 헤더를 재생성하는 로직을 수정해야 합니다. 대체 API를 사용할 경우 인증 방식을 바꿔주어야 합니다[SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의](https://sir.kr/boards/g5_plugin/15016). | 147 | 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]]를 보십시오. |
| 124 | 148 | ||
| 125 | ## 테스트 포인트와 예방 전략 | 149 | ## 테스트 포인트와 예방 전략 |
| 126 | 150 | ||
| 127 | 1. **설치 후 파일 검사**: `license.txt`, `t2_config.php`, `upload_config.php` 등 필수 파일이 존재하는지 확인합니다. | 151 | 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]]를 보십시오. |
| 128 | 2. **권한 테스트**: 협업 기능을 사용할 때 실제로 파일이 생성되는지 테스트합니다. 실패하면 권한을 재검토합니다. | 152 | 2. **권한 테스트**: 협업 기능을 사용할 때 실제로 파일이 생성되는지 테스트합니다. 실패하면 권한을 재검토합니다. |
| 129 | 3. **업로드 테스트**: 다양한 확장자와 크기의 파일을 업로드해보며, 에러 발생 여부를 확인합니다. | 153 | 3. **업로드 테스트**: 다양한 확장자와 크기의 파일을 업로드해보며, 에러 발생 여부를 확인합니다. |
| 130 | 4. **AI 호출 시험**: AI 기능을 테스트하여 인증 실패 메시지가 있는지 체크합니다. API 호출 로그를 분석해 문제를 조기에 발견합니다. | 154 | 4. **AI 호출 시험**: AI 기능을 테스트하여 인증 실패 메시지가 있는지 체크합니다. API 호출 로그를 분석해 문제를 조기에 발견합니다. |
| 131 | 5. **브라우저 콘솔 확인**: CORS 오류나 자바스크립트 예외는 브라우저 개발자 도구의 콘솔을 통해 빠르게 확인할 수 있습니다. | 155 | 5. **브라우저 콘솔 확인**: CORS 오류나 자바스크립트 예외는 브라우저 개발자 도구의 콘솔을 통해 빠르게 확인할 수 있습니다. |
| 132 | 156 | ||
| 133 | ## 참고 / 인용 자료 | 157 | ## 참고 / 인용 자료 |
| 134 | 158 | ||
| 135 | * DSclub에서 제공하는 설치 및 오류 처리 안내[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor)[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor) | 159 | * DSclub에서 제공하는 설치 및 오류 처리 안내[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor)[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor) |
| 136 | * SIR 커뮤니티의 설치 가이드(권한 설정 포함)[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016) | 160 | * SIR 커뮤니티의 설치 가이드(권한 설정 포함)[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016) |
| 137 | * DSclub 버전별 문제 및 수정 사항 안내[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor) | 161 | * DSclub 버전별 문제 및 수정 사항 안내[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor) |
| 138 | * AI 및 외부 API 호출 과정에서 발생할 수 있는 보안 이슈 토론[SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의](https://sir.kr/boards/g5_plugin/15016) | 162 | * AI 및 외부 API 호출 과정에서 발생할 수 있는 보안 이슈 토론[SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의](https://sir.kr/boards/g5_plugin/15016) |
| 139 | 163 | ||
| 140 | 이 문서는 현재 T2Editor 9.0.0 버전을 기준으로 작성되었으며, 향후 업데이트나 서버 환경 변화에 따라 수정될 수 있습니다. | 164 | ## 문서 관리 메모 |
| 165 | |||
| 166 | - 판본별 이슈 대응(8.x·9.x 이력 포함): [[72-version-issues-guide.md]] | ||
| 167 | - 최초 설치 게이트와 관리자 페이지: [[01-installation-guide.md]] · [[N-02-admin-console-guide.md]] | ||
| 168 | - 서버측 본문 정제 공백: [[N-06-server-sanitize-and-content-style.md]] | ||
| 169 | - 위에 남긴 "이미 해결된 항목" 표는 **삭제하지 마십시오.** 릴리즈 노트가 해결을 지칭했더라도 특정 환경에서 재현될 수 있어, 지우면 "안 보임"이 "없음"으로 읽힙니다. | ||
| 170 | |||
| 171 | 이 문서는 현재 T2Editor 10.5.1(2026-07-27) 판본을 기준으로 작성되었습니다. 9.x 이하 계열은 EOL이며 업데이트 대상이 아닙니다. 10.5.0·10.5.1에서 이미 해결된 항목은 아래 "이미 해결된 항목" 절에 표시했으므로, 그 항목을 해결책으로 따라하지 마십시오. | ||