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를 설치하거나 사용할 때 여러 가지 문제가 발생할 수 있습니다. 이 문서는 주요 오류의 원인을 파악하고 적절한 해결책을 제시하여 초보자부터 개발자까지 누구나 문제를 빠르게 처리할 수 있도록 돕습니다. 대부분의 문제는 파일 권한 설정, 환경 구성, 라이선스 인증 등 기본적인 점검만으로 해결할 수 있으므로, 설치 과정에서 꼼꼼하게 확인하는 것이 중요합니다.
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 버전을 기준으로 작성되었으며, 향후 업데이트나 서버 환경 변화에 따라 수정될 수 있습니다.
| 이전 | 새 버전 | ||
|---|---|---|---|
| 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: 9.0.0 |
| 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] |
| 16 | related_files: [t2editor/config/t2_config.php, t2editor/config/upload_config.php, t2editor/collab/] | 16 | related_files: [t2editor/config/t2_config.php, t2editor/config/upload_config.php, t2editor/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, 설치, collab, 권한] |
| 26 | version_tag: 9.0.0 | 26 | version_tag: 9.0.0 |
| 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 | ## 빠른 요약 | 40 | ## 빠른 요약 |
| 41 | 41 | ||
| 42 | * **파일 권한 문제** – 협업 디렉터리(`collab/`)의 권한이 적절하지 않으면 협업 기능이 동작하지 않습니다. GNUBoard5 플러그인으로 사용 시 `sudo chmod 707` 명령으로 `collab` 폴더에 전체 권한을 부여해야 합니다[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016). | 42 | * **파일 권한 문제** – 협업 디렉터리(`collab/`)의 권한이 적절하지 않으면 협업 기능이 동작하지 않습니다. GNUBoard5 플러그인으로 사용 시 `sudo chmod 707` 명령으로 `collab` 폴더에 전체 권한을 부여해야 합니다[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016). |
| 43 | * **라이선스 인증 오류** – 다운로드한 T2Editor 패키지에는 라이선스 파일이 포함되어 있으며, 이 파일이 없거나 손상되면 에디터가 정상적으로 동작하지 않습니다. DSclub 페이지에서 해당 버전과 일치하는 라이선스 파일을 다시 설치하세요[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). | 43 | * **라이선스 인증 오류** – 다운로드한 T2Editor 패키지에는 라이선스 파일이 포함되어 있으며, 이 파일이 없거나 손상되면 에디터가 정상적으로 동작하지 않습니다. DSclub 페이지에서 해당 버전과 일치하는 라이선스 파일을 다시 설치하세요[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). |
| 44 | * **폰트 및 스타일 오류** – 커스텀 테마나 타 사이트에서 가져온 스킨을 사용할 경우 글꼴이나 스타일이 깨질 수 있습니다. `fonts/`와 `css/` 디렉터리의 경로 및 파일 존재 여부를 확인하고, 캐시를 삭제한 후 새로고침합니다[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor). | 44 | * **폰트 및 스타일 오류** – 커스텀 테마나 타 사이트에서 가져온 스킨을 사용할 경우 글꼴이나 스타일이 깨질 수 있습니다. `fonts/`와 `css/` 디렉터리의 경로 및 파일 존재 여부를 확인하고, 캐시를 삭제한 후 새로고침합니다[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor). |
| 45 | * **업로드 오류** – 이미지나 파일 업로드가 실패할 때는 `config/upload_config.php`에서 허용 확장자와 최대 용량을 확인하고, `data/` 디렉터리에 쓰기 권한이 있는지 점검합니다[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). | 45 | * **업로드 오류** – 이미지나 파일 업로드가 실패할 때는 `config/upload_config.php`에서 허용 확장자와 최대 용량을 확인하고, `data/` 디렉터리에 쓰기 권한이 있는지 점검합니다[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). |
| 46 | * **버전 불일치 문제** – T2Editor의 코어와 플러그인 버전이 맞지 않으면 기능이 깨질 수 있습니다. 사용 중인 버전을 확인하고, DSclub 또는 SIR 커뮤니티에서 제공하는 최신 패치를 적용하세요[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor). | 46 | * **버전 불일치 문제** – T2Editor의 코어와 플러그인 버전이 맞지 않으면 기능이 깨질 수 있습니다. 사용 중인 버전을 확인하고, DSclub 또는 SIR 커뮤니티에서 제공하는 최신 패치를 적용하세요[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor). |
| 47 | 47 | ||
| 48 | ## 초보자와 웹마스터를 위한 기본 점검 목록 | 48 | ## 초보자와 웹마스터를 위한 기본 점검 목록 |
| 49 | 49 | ||
| 50 | 1. **패키지 확인**: T2Editor는 여러 버전이 존재합니다. DSclub 또는 SIR에서 다운로드한 패키지가 사이트에 맞는지 확인하세요. 버전이 맞지 않으면 에디터가 정상적으로 로드되지 않습니다[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor). | 50 | 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)을 사용하여 권한을 변경할 수 있습니다. | 51 | 2. **폴더 권한 설정**: GNUBoard5 플러그인으로 설치할 경우, `t2editor/collab/` 폴더의 권한을 707로 설정해야 협업 기능이 정상 동작합니다[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016). 웹호스팅 업체에 따라 FTP 프로그램(예: FileZilla)을 사용하여 권한을 변경할 수 있습니다. |
| 52 | 3. **데이터 디렉터리 점검**: 업로드나 자동 저장 기능이 오류를 발생시킨다면 `t2editor/data/` 폴더의 쓰기 권한을 확인하세요. 권한이 없으면 파일 저장이 되지 않아 업로드가 실패합니다. | 52 | 3. **데이터 디렉터리 점검**: 업로드나 자동 저장 기능이 오류를 발생시킨다면 `t2editor/data/` 폴더의 쓰기 권한을 확인하세요. 권한이 없으면 파일 저장이 되지 않아 업로드가 실패합니다. |
| 53 | 4. **라이선스 파일 유지**: 패키지에 포함된 `license.txt` 또는 `license.dat` 파일은 DSclub API 호출에 필요한 라이선스 토큰을 포함합니다. 다른 서버로 이동하거나 업데이트할 때 이 파일이 사라지면 AI 등 외부 서비스가 작동하지 않습니다[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). | 53 | 4. **라이선스 파일 유지**: 패키지에 포함된 `license.txt` 또는 `license.dat` 파일은 DSclub API 호출에 필요한 라이선스 토큰을 포함합니다. 다른 서버로 이동하거나 업데이트할 때 이 파일이 사라지면 AI 등 외부 서비스가 작동하지 않습니다[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). |
| 54 | 5. **브라우저 캐시 삭제**: CSS나 JS 변경 후에도 화면에 반영되지 않는다면 브라우저 캐시를 삭제하거나 강제 새로고침(Ctrl+F5)을 수행하십시오. | 54 | 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). | 55 | 6. **PHP 버전 확인**: T2Editor는 PHP 7.4 이상과 GD 라이브러리, cURL 확장 모듈을 필요로 합니다. 시스템 환경이 충족되지 않으면 일부 기능이 동작하지 않습니다[SIR T2Editor 8.1.2 소개 글](https://sir.kr/boards/g5_plugin/15016). |
| 56 | 56 | ||
| 57 | ## 자주 발생하는 오류와 해결 방법 | 57 | ## 자주 발생하는 오류와 해결 방법 |
| 58 | 58 | ||
| 59 | ### 협업 기능이 동작하지 않음 | 59 | ### 협업 기능이 동작하지 않음 |
| 60 | 60 | ||
| 61 | **증상**: 협업 버튼을 눌러도 아무런 반응이 없거나 “접속할 수 없습니다”라는 오류 메시지가 표시됩니다. | 61 | **증상**: 협업 버튼을 눌러도 아무런 반응이 없거나 “접속할 수 없습니다”라는 오류 메시지가 표시됩니다. |
| 62 | 62 | ||
| 63 | **해결책**: | 63 | **해결책**: |
| 64 | 64 | ||
| 65 | 1. `collab/` 폴더 권한을 707로 설정했는지 확인합니다[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016). | 65 | 1. `collab/` 폴더 권한을 707로 설정했는지 확인합니다[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016). |
| 66 | 2. 서버의 방화벽이나 SELinux 설정 때문에 웹 서버 프로세스가 해당 디렉터리에 접근하지 못할 수도 있습니다. 로그를 확인하고 적절히 해제하거나 예외 규칙을 추가합니다. | 66 | 2. 서버의 방화벽이나 SELinux 설정 때문에 웹 서버 프로세스가 해당 디렉터리에 접근하지 못할 수도 있습니다. 로그를 확인하고 적절히 해제하거나 예외 규칙을 추가합니다. |
| 67 | 3. PHP 세션 저장 경로가 제대로 설정되지 않았을 경우, 세션이 공유되지 않아 협업이 불가능합니다. `php.ini`에서 `session.save_path`를 확인하십시오. | 67 | 3. PHP 세션 저장 경로가 제대로 설정되지 않았을 경우, 세션이 공유되지 않아 협업이 불가능합니다. `php.ini`에서 `session.save_path`를 확인하십시오. |
| 68 | 68 | ||
| 69 | ### 이미지/파일 업로드 실패 | 69 | ### 이미지/파일 업로드 실패 |
| 70 | 70 | ||
| 71 | **증상**: 파일을 업로드하면 “업로드 실패” 메시지가 나타나거나, 업로드된 미리보기가 보이지 않습니다. | 71 | **증상**: 파일을 업로드하면 “업로드 실패” 메시지가 나타나거나, 업로드된 미리보기가 보이지 않습니다. |
| 72 | 72 | ||
| 73 | **해결책**: | 73 | **해결책**: |
| 74 | 74 | ||
| 75 | 1. `config/upload_config.php`에서 확장자 목록과 업로드 용량이 적절하게 설정되어 있는지 확인합니다. 필요하다면 허용 목록에 확장자를 추가하세요[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). | 75 | 1. `config/upload_config.php`에서 확장자 목록과 업로드 용량이 적절하게 설정되어 있는지 확인합니다. 필요하다면 허용 목록에 확장자를 추가하세요[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). |
| 76 | 2. `data/` 폴더의 권한이 충분한지 확인합니다. 707 권한(웹 서버가 쓰기 가능)을 부여하고, Apache/Nginx 사용자 계정이 소유자로 지정되어 있는지 점검합니다. | 76 | 2. `data/` 폴더의 권한이 충분한지 확인합니다. 707 권한(웹 서버가 쓰기 가능)을 부여하고, Apache/Nginx 사용자 계정이 소유자로 지정되어 있는지 점검합니다. |
| 77 | 3. 서버가 `fileinfo` 확장 모듈을 비활성화하여 MIME 타입을 인식하지 못할 경우 업로드가 차단될 수 있습니다. php.ini에서 `fileinfo` 모듈을 활성화하세요. | 77 | 3. 서버가 `fileinfo` 확장 모듈을 비활성화하여 MIME 타입을 인식하지 못할 경우 업로드가 차단될 수 있습니다. php.ini에서 `fileinfo` 모듈을 활성화하세요. |
| 78 | 78 | ||
| 79 | ### AI 플러그인 호출 오류 | 79 | ### AI 플러그인 호출 오류 |
| 80 | 80 | ||
| 81 | **증상**: AI 버튼을 클릭해도 응답이 없거나 “라이선스 인증 실패” 오류가 표시됩니다. | 81 | **증상**: AI 버튼을 클릭해도 응답이 없거나 “라이선스 인증 실패” 오류가 표시됩니다. |
| 82 | 82 | ||
| 83 | **해결책**: | 83 | **해결책**: |
| 84 | 84 | ||
| 85 | 1. `license.txt` 파일이 존재하는지 확인하고, DSclub에서 발급받은 최신 라이선스를 사용합니다[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). | 85 | 1. `license.txt` 파일이 존재하는지 확인하고, DSclub에서 발급받은 최신 라이선스를 사용합니다[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor). |
| 86 | 2. 플러그인 내부에서 API 키를 재정의하지 않은 상태라면 DSclub 서버와의 통신에 실패할 수 있습니다. 플러그인 설정을 확인하여 API 키나 서버 주소를 정확하게 지정합니다[SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의](https://sir.kr/boards/g5_plugin/15016). | 86 | 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). | 87 | 3. 해당 IP나 도메인에 대한 호출 횟수가 제한(25회/일)되어 있어 거부되는 경우도 있습니다. 새 하루가 시작되기 전까지 기다리거나 Groq API 등 다른 서버를 사용하십시오[SIR T2Editor 8.1.2 AI·검색 기능 설명](https://sir.kr/boards/g5_plugin/15016). |
| 88 | 88 | ||
| 89 | ### 스타일·폰트가 깨짐 | 89 | ### 스타일·폰트가 깨짐 |
| 90 | 90 | ||
| 91 | **증상**: 글꼴이 비정상적으로 보이거나 버튼 아이콘이 표시되지 않습니다. | 91 | **증상**: 글꼴이 비정상적으로 보이거나 버튼 아이콘이 표시되지 않습니다. |
| 92 | 92 | ||
| 93 | **해결책**: | 93 | **해결책**: |
| 94 | 94 | ||
| 95 | 1. `css/`와 `fonts/` 폴더의 파일들이 모두 존재하는지 확인하고, 경로가 올바른지 `index.php`와 스킨 파일에서 확인합니다[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor). | 95 | 1. `css/`와 `fonts/` 폴더의 파일들이 모두 존재하는지 확인하고, 경로가 올바른지 `index.php`와 스킨 파일에서 확인합니다[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor). |
| 96 | 2. 새로운 스킨을 적용한 후라면, 해당 스킨의 스타일시트가 T2Editor의 스타일을 덮어쓰지 않는지 확인합니다. CSS 우선순위를 조정하거나 클래스명을 변경하세요. | 96 | 2. 새로운 스킨을 적용한 후라면, 해당 스킨의 스타일시트가 T2Editor의 스타일을 덮어쓰지 않는지 확인합니다. CSS 우선순위를 조정하거나 클래스명을 변경하세요. |
| 97 | 3. 캐시를 비우고 강제 새로고침을 하면 로컬 브라우저 캐시로 인해 발생한 문제를 해결할 수 있습니다. | 97 | 3. 캐시를 비우고 강제 새로고침을 하면 로컬 브라우저 캐시로 인해 발생한 문제를 해결할 수 있습니다. |
| 98 | 98 | ||
| 99 | ### 기타 PHP 오류 및 백엔드 이슈 | 99 | ### 기타 PHP 오류 및 백엔드 이슈 |
| 100 | 100 | ||
| 101 | * **White Page/500 에러**: PHP 오류가 발생하면 에디터가 빈 화면만 보일 수 있습니다. 서버 로그(`/var/log/php-fpm.log` 또는 웹 서버 에러 로그)를 확인하여 문제의 원인을 파악하고 수정하십시오. | 101 | * **White Page/500 에러**: PHP 오류가 발생하면 에디터가 빈 화면만 보일 수 있습니다. 서버 로그(`/var/log/php-fpm.log` 또는 웹 서버 에러 로그)를 확인하여 문제의 원인을 파악하고 수정하십시오. |
| 102 | * **메모리 부족 오류**: 대용량 이미지를 처리하거나, AI 플러그인을 사용할 때 PHP 메모리 제한에 도달하면 오류가 발생할 수 있습니다. `php.ini`에서 `memory_limit`를 늘리고, 업로드 크기 제한(`upload_max_filesize`, `post_max_size`)도 함께 조정하세요. | 102 | * **메모리 부족 오류**: 대용량 이미지를 처리하거나, 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). | 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). |
| 104 | 104 | ||
| 105 | ## 개발자를 위한 심층 분석 | 105 | ## 개발자를 위한 심층 분석 |
| 106 | 106 | ||
| 107 | 이 섹션에서는 오류 발생의 근본 원인을 코드 레벨에서 분석하고 해결하는 방법을 제시합니다. | 107 | 이 섹션에서는 오류 발생의 근본 원인을 코드 레벨에서 분석하고 해결하는 방법을 제시합니다. |
| 108 | 108 | ||
| 109 | ### 권한 오류의 구조 | 109 | ### 권한 오류의 구조 |
| 110 | 110 | ||
| 111 | 협업 기능은 `collab` 디렉터리에 저장된 JSON 파일과 `editor.lib.php`에서 관리하는 세션 키를 기반으로 합니다. 만약 해당 폴더에 쓰기 권한이 없으면 세션 파일이 생성되지 않고, `fetch` 요청이 실패합니다. 서버 로그에서는 `file_put_contents(): failed to open stream`과 같은 메시지가 나타날 것입니다. 이를 해결하기 위해서는 UNIX 파일 시스템의 권한 뿐만 아니라 SELinux 컨텍스트와 웹 서버 사용자 권한을 함께 고려해야 합니다. | 111 | 협업 기능은 `collab` 디렉터리에 저장된 JSON 파일과 `editor.lib.php`에서 관리하는 세션 키를 기반으로 합니다. 만약 해당 폴더에 쓰기 권한이 없으면 세션 파일이 생성되지 않고, `fetch` 요청이 실패합니다. 서버 로그에서는 `file_put_contents(): failed to open stream`과 같은 메시지가 나타날 것입니다. 이를 해결하기 위해서는 UNIX 파일 시스템의 권한 뿐만 아니라 SELinux 컨텍스트와 웹 서버 사용자 권한을 함께 고려해야 합니다. |
| 112 | 112 | ||
| 113 | ### 라이선스 검증 로직 | 113 | ### 라이선스 검증 로직 |
| 114 | 114 | ||
| 115 | `editor.lib.php`는 DSclub API와 통신할 때 `X-T2Editor-License` 헤더를 추가합니다. 라이선스 토큰이 없거나 만료되면 DSclub 서버가 401 오류를 반환하고, 플러그인은 이를 `LicenseError`로 처리합니다. 개발자는 `config/t2_config.php`에서 라이선스 키를 검증하는 코드를 추가하여 로컬 환경에서도 서비스가 중단되지 않도록 할 수 있습니다. | 115 | `editor.lib.php`는 DSclub API와 통신할 때 `X-T2Editor-License` 헤더를 추가합니다. 라이선스 토큰이 없거나 만료되면 DSclub 서버가 401 오류를 반환하고, 플러그인은 이를 `LicenseError`로 처리합니다. 개발자는 `config/t2_config.php`에서 라이선스 키를 검증하는 코드를 추가하여 로컬 환경에서도 서비스가 중단되지 않도록 할 수 있습니다. |
| 116 | 116 | ||
| 117 | ### 업로드 처리 플로우 | 117 | ### 업로드 처리 플로우 |
| 118 | 118 | ||
| 119 | 이미지 업로드는 클라이언트 측 `upload.js`에서 `FormData`를 생성해 `upload.php`로 전송하고, 서버에서 GD 라이브러리로 이미지를 리사이즈합니다. 업로드 실패 시에는 $_FILES 배열을 덤프하여 MIME 타입과 크기를 확인해야 합니다. 또한 `upload_config.php`에서 `allowed_extensions`와 `max_file_size` 변수를 변경하여 특정 파일 형식과 크기를 허용할 수 있습니다. | 119 | 이미지 업로드는 클라이언트 측 `upload.js`에서 `FormData`를 생성해 `upload.php`로 전송하고, 서버에서 GD 라이브러리로 이미지를 리사이즈합니다. 업로드 실패 시에는 $_FILES 배열을 덤프하여 MIME 타입과 크기를 확인해야 합니다. 또한 `upload_config.php`에서 `allowed_extensions`와 `max_file_size` 변수를 변경하여 특정 파일 형식과 크기를 허용할 수 있습니다. |
| 120 | 120 | ||
| 121 | ### AI 및 검색 API 오류 분석 | 121 | ### AI 및 검색 API 오류 분석 |
| 122 | 122 | ||
| 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). | 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). |
| 124 | 124 | ||
| 125 | ## 테스트 포인트와 예방 전략 | 125 | ## 테스트 포인트와 예방 전략 |
| 126 | 126 | ||
| 127 | 1. **설치 후 파일 검사**: `license.txt`, `t2_config.php`, `upload_config.php` 등 필수 파일이 존재하는지 확인합니다. | 127 | 1. **설치 후 파일 검사**: `license.txt`, `t2_config.php`, `upload_config.php` 등 필수 파일이 존재하는지 확인합니다. |
| 128 | 2. **권한 테스트**: 협업 기능을 사용할 때 실제로 파일이 생성되는지 테스트합니다. 실패하면 권한을 재검토합니다. | 128 | 2. **권한 테스트**: 협업 기능을 사용할 때 실제로 파일이 생성되는지 테스트합니다. 실패하면 권한을 재검토합니다. |
| 129 | 3. **업로드 테스트**: 다양한 확장자와 크기의 파일을 업로드해보며, 에러 발생 여부를 확인합니다. | 129 | 3. **업로드 테스트**: 다양한 확장자와 크기의 파일을 업로드해보며, 에러 발생 여부를 확인합니다. |
| 130 | 4. **AI 호출 시험**: AI 기능을 테스트하여 인증 실패 메시지가 있는지 체크합니다. API 호출 로그를 분석해 문제를 조기에 발견합니다. | 130 | 4. **AI 호출 시험**: AI 기능을 테스트하여 인증 실패 메시지가 있는지 체크합니다. API 호출 로그를 분석해 문제를 조기에 발견합니다. |
| 131 | 5. **브라우저 콘솔 확인**: CORS 오류나 자바스크립트 예외는 브라우저 개발자 도구의 콘솔을 통해 빠르게 확인할 수 있습니다. | 131 | 5. **브라우저 콘솔 확인**: CORS 오류나 자바스크립트 예외는 브라우저 개발자 도구의 콘솔을 통해 빠르게 확인할 수 있습니다. |
| 132 | 132 | ||
| 133 | ## 참고 / 인용 자료 | 133 | ## 참고 / 인용 자료 |
| 134 | 134 | ||
| 135 | * DSclub에서 제공하는 설치 및 오류 처리 안내[DSclub T2Editor 서비스 페이지 - 설치·오류 안내](https://dsclub.kr/service/editor)[DSclub T2Editor 서비스 페이지 - 오류 해결 안내](https://dsclub.kr/service/editor) | 135 | * 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) | 136 | * SIR 커뮤니티의 설치 가이드(권한 설정 포함)[SIR T2Editor 8.1.2 설치 및 권한 설정 안내](https://sir.kr/boards/g5_plugin/15016) |
| 137 | * DSclub 버전별 문제 및 수정 사항 안내[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor) | 137 | * DSclub 버전별 문제 및 수정 사항 안내[DSclub T2Editor 서비스 페이지 - 버전 변경 공지](https://dsclub.kr/service/editor) |
| 138 | * AI 및 외부 API 호출 과정에서 발생할 수 있는 보안 이슈 토론[SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의](https://sir.kr/boards/g5_plugin/15016) | 138 | * AI 및 외부 API 호출 과정에서 발생할 수 있는 보안 이슈 토론[SIR T2Editor 8.1.2 댓글 - 외부 API 연동 주의](https://sir.kr/boards/g5_plugin/15016) |
| 139 | 139 | ||
| 140 | 이 문서는 현재 T2Editor 9.0.0 버전을 기준으로 작성되었으며, 향후 업데이트나 서버 환경 변화에 따라 수정될 수 있습니다. | 140 | 이 문서는 현재 T2Editor 9.0.0 버전을 기준으로 작성되었으며, 향후 업데이트나 서버 환경 변화에 따라 수정될 수 있습니다. |