v9에서 v10으로 올리기

이 문서는 2026-09-28에 새로 썼습니다.

이전에는 이 위키에 이관 안내서가 아예 없었습니다. 15건 사용자 문서 중 v10 계열 9개 판본을 언급한 문서가 0건이었고, 그 결과 이관이 필요한 사람이 어디서 시작해야 하는지 알 수 없었습니다.

>

한 가지 먼저: 이 문서는 10.5.1로 한 번에 오르는 길을 씁니다. 10.0.0을 거치는 경로는 쓰지 마십시오. 중간 판본은 2~5일 간격으로 연속 배포됐고(10.0.0 → 10.5.1 = 34일), 10.5.0과 10.5.1이 그 사이의 파손을 다 고쳤습니다.

1. 먼저 현재 판전을 확인하십시오

내가 지금 무슨 판본인지 모르겠다면: 배포판 루트 readme.txt 의 2행을 여십시오. ver_10.5.1 처럼 되어 있습니다. 그 숫자가 판본입니다.

⚠ readme.txt 안에 Version: 3.0.0 이라는 숫자가 하나 더 있습니다. 그건 라이선스 계약 판본이고 에디터 버전이 아닙니다. 두 숫자를 혼동하지 마십시오.

근거: readme.txt:2 ver_10.5.1 / readme.txt:11 Version: 3.0.0 / 판독 코드 editor.core.php:415-422

2. 왜 올라가야 하는가 (릴리즈 노트 인용)

2-1. 기능

2-2. ⭐ 올라가야 하는 가장 실용적인 이유 3가지

1. 9.x로 돌아갈 곳이 없습니다. 9.3.0이 마지막이고 그 이후 계열은 전부 10.x입니다.
2. 그누보드5 관리자 인증 문제가 10.5.1에서 고쳐졌습니다. 9.x 계열에서 "관리자인데 T2Editor는 로그인 필요 안내"가 나오는 증상은 10.5.1이 정면으로 고칩니다.

10.5.1 원문: "그누보드5 관리자로 로그인했는데도 T2Editor에서 그누보드5 관리자 로그인 필요 안내만 표시되는 문제가 있었습니다. 10.5.1에서는 그누보드5 관리자 정보를 정상적으로 확인할 수 있도록 인증 초기화 방식을 수정했습니다."

1. 자동 업데이트와 되돌리기가 생겼습니다. 10.4.0부터 관리자 화면에서 업데이트를 하고, 문제가 생기면 거기로 되돌립니다. 이 기능이 없는 9.x에서는 매번 수동으로 ZIP을 갈아끼우셨을 것입니다.

2-3. ⚠ 올라간다고 좋아지는 것이 아닌 것 (이 문서가important한 이유)

• 서버단 본문 필터는 v10에도 없습니다. v10.5.1에는 브라우저 안의 검사만 있고, 저장 지점에서 본문을 걸러 주는 T2Esanhtml() 같은 함수가 없습니다(트리·86개 PHP 파일 전수 검색 0건). 그 기능은 v11에 있습니다. "v10으로 올리면 안전해진다"고 읽으면 안 됩니다.
• v10 계열도 34일 만에 9판본으로 교체됐습니다. 9.x가 오래 갔던 것만큼 v10이 오래 갈다는 보장은 없습니다. 상태는 06-version-compatibility-guide.md 6절에서 확인하십시오.
• 10.0.0 릴리즈 노트에는 업그레이드 영향 요약이 없습니다. 94판본 역사 전체에서 릴리즈 노트 안에 있는 업그레이드 영향 요약은 0건입니다. 즉 공식 채널이 이관 위험을 알려주지 않습니다. 이 문서가 그 대체입니다.

3. 올라가기 전에 반드시 알아야 할 파괴적 변경

각 항목은 릴리즈 노트 원문과 10.5.1 코드 실측으로 뒷받침합니다.

3-1. ⚠ PHP 요구사항 — 가장 많이 오독되는 항목

결론: PHP 7.4 서버에서 10.5.1로 바로 올라가도 됩니다. 8.0으로 올릴 필요가 없습니다. 코드 근거: admin/environment_api.core.php:219 version_compare(PHP_VERSION, '7.4.0', '>=') (error 등급) · :240-241 "신규 운영 환경은 PHP 8.1 또는 8.2를 권장합니다."

⚠ 10.0.0이나 10.0.1을 거치는 사람을 위해: 거치지 마십시오. PHP가 8.0이어야 한다고 믿고 서버를 올렸다면 그 변경은 되돌릴 수 있습니다.

3-2. ⚠ 관리자 인증 방식이 바뀌었습니다 (10.5.0)

10.5.0에서 그누보드5·라이믹스 사용자는 T2Editor 전용 관리자 비밀번호를 새로 입력하지 않고 CMS 관리자 로그인 상태로 관리자 권한을 확인하게 됩니다.

10.5.0 원문: "그누보드5와 라이믹스에서는 T2Editor 전용 관리자 비밀번호를 별도로 입력하는 대신, 현재 CMS의 관리자 로그인 상태를 이용해 T2Editor 관리자 권한을 확인하도록 변경했습니다."

10.5.0에서 문제가 생겼고 10.5.1이 고쳤습니다 — 그래서 10.5.0에 머물지 마십시오.

10.5.1 원문: "10.5.0에서는 그누보드5나 라이믹스가 감지되면 T2Editor 자체 로그인을 사용할 수 없었습니다. CMS 관리자 인증이 실패하면 관리자 페이지에 접근할 다른 방법이 없었습니다. 10.5.1에서는 CMS 환경에서도 T2Editor 자체 로그인 화면으로 이동할 수 있도록 수정했습니다."

되돌아갈 경로는 있습니다 — 자체 로그인:

10.5.1 원문: "admin/t2admin.key.txt 파일을 admin/t2admin.key로 변경하고 자체 관리자 비밀번호를 설정하면 자체 로그인을 사용할 수 있습니다."

3-3. ⚠ 데이터 경로가 재편되었습니다 (10.5.0 → 10.5.1)

10.5.1 원문: "이미지와 첨부파일은 기존처럼 data/editor 폴더에 저장됩니다. 관리자 설정, 인증 정보, 협업 데이터, 업데이트 기록, 서드파티 설치 정보는 data/t2editor_db 폴더에 별도로 저장됩니다. 기존 data/editor/t2editor_db 데이터는 새 위치로 자동 이전됩니다."

자동 이동하지만, 알아두십시오. 자동 이동이 실패하는 경우는 코드에 fallback 장치가 있습니다:

10.5.0 원문: "기존 위치에 저장된 데이터와 경로 정보는 가능한 범위에서 새 구조로 이전하거나 계속 인식합니다."

코드 근거: config/t2_storage.php:253-258(이전 중첩 위치 인식) · :345-364(실제 이전) · :427-428("이전된 설정 안에 남아 있던 과거 경로도 새 경로에 맞게 자동으로 변경")

⚠ 직접 손댄 플러그인이 data/editor/t2editor_db에 파일을 쓰고 있었다면 그 경로는 더 이상 읽히지 않을 수 있습니다. 그런 플러그인이 있다면 이관 전에 확인하십시오. [확인 필요] — v9 실물 소스가 없어 "그런 플러그인이 실제로 있었는지"는 확인하지 못했습니다.

3-4. ⚠ CMS 연결 구조가 코어에서 분리되었습니다 (10.5.0)

10.5.0 원문: "그누보드5와 라이믹스 관련 처리를 에디터 코어와 각 플러그인에 흩어 놓지 않고, CMS별 연결 계층으로 분리했습니다. … 기존 10.4.0의 공개 함수와 라이믹스 스킨 연결 구조는 계속 사용할 수 있도록 호환성을 유지했습니다."

10.4.0 공개 함수는 계속 쓸 수 있습니다. 다만 코어 파일(editor.core.php, config/)에 그누보드5·라이믹스 상수를 직접 하드코딩한custom code는 어댑터 계층으로 옮겨야 합니다. 10.2.0이 방향을 이미 껐습니다:

10.2.0 원문: "더이상 코어(editor.lib.php, /config) 하드코딩 수정없이 플러그인 순서, 반응형 메뉴바 수정, 다크모드 설정, nafw 설정, 업로드 설정 등이 가능해졌습니다."

3-5. ⚠ 최초 설치 게이트가 생겼습니다 — 통과하지 않으면 편집기가 잠깁니다

v10 계열은 최초 설정을 마치기 전까지 편집 기능이 잠깁니다. v9에서 올라온 분에게는 이 단계가 없던 일입니다.

1. admin/t2admin.key.txt → admin/t2admin.key 로 이름 변경
2. 관리자 비밀번호 설정 (CMS 관리자 로그인이면 생략 가능 — CMS 환경)
3. 공용 데이터 디렉터리 쓰기 권한 — 최소 권장 707
4. 안내를 끝까지 읽기

10.4.0 원문: "이런 필수 설정이 끝나지 않으면 잘못된 상태로 에디터가 쓰이는 걸 막기 위해 잠시 편집 기능이 잠깁니다."

10.5.0 원문: "설치 권한은 777이 아니라 707을 최소 권장값으로 명확하게 안내합니다. 실제 PHP 파일 생성·쓰기·삭제 시험이 성공하면 현재 권한을 그대로 유지하며, 숫자로 표시된 권한만 보고 불필요한 chmod 명령을 요구하지 않습니다."

코드 근거: extend/js/t2_first_run_guide.js:19(키 이름 변경) :66(707) :67(시험 우선) :307('설정 완료 전 편집 기능 잠김')

⚠ 둘 다 있으면 admin/t2admin.key.txt 를 삭제하십시오(안내 화면이 그렇게 알립니다: t2_first_run_guide.js:70).

3-6. ⚠ 설치 방식의 기본이 바뀌었습니다 — 쓰기 권한이 필요한 곳이 좁아졌습니다

권한 지침도 좁아졌습니다:

t2_first_run_guide.js:427 원문: "쓰기 권한은 감지된 T2Editor 공용 데이터 경로에만 부여합니다. T2Editor 원본 코드, plugin, extend, locales 전체를 쓰기 가능하게 만들지 마세요."

v9에서 에디터 폴더 전체에 777을 주던 습관이 있다면 그 습관 자체를 버려야 합니다.

3-7. ⚠ zip 확장이 없어도 됩니다 (10.5.0)

없어도 됩니다 — 3단 대체가 있습니다.

1. ZipArchive (php-zip)
2. 없으면 → 서버 내장 zlib(gzinflate)으로 처리
3. 그것도 없으면 → 관리자 브라우저가 ZIP을 해제, 서버가 원본 ZIP의 경로·크기·CRC를 다시 검증

10.5.0 원문: "브라우저가 해제한 파일을 그대로 신뢰하지 않고, 서버가 원본 ZIP의 파일 경로, 크기와 CRC를 다시 확인한 뒤 적용합니다."

⚠ 단, 이건 "압축 해제"의 대체입니다. ZIP을 서버로 내려받는 수송은 별개이며, 거기에는 cURL 또는 OpenSSL+allow_url_fopen이 필요합니다. 둘 다 없으면 업데이트·서드파티 설치가 막힙니다.

3-8. ⚠ mbstring이 없어도 됩니다 (10.5.0)

10.5.0 원문: "mbstring 확장이 없는 서버에서도 iconv 또는 UTF-8 대체 처리로 주요 문자열 기능을 사용할 수 있도록 보완했습니다."

코드: config/t2_compat.php:10-45(mbstring 함수를 직접 정의하는 폴리필) · config/t2_utf8.php:9-16, 30-40(mbstring → iconv → UTF-8 폴백 체인)

3-9. 낮아진 위험 (v9에 있던 문제가 v10에서 사라진 것)

따라서 "NSFW 문제를 해결하려면 8.2.0으로 내려가라"는 지시는 버리십시오. 그 증상은 10.4.0에서 끝났고 8.2.0은 EOL입니다. (72-version-issues-guide.md의 해당 지시는 2026-09-28에 교체 완료)

4. 사라지거나 바뀐 것 목록

4-1. 위치가 바뀐 것

4-2. 파일이 없는 것 (알려진 혼동 — "이 파일이 없어요"가 정상입니다)

4-3. ⚠ 사라졌다고 믿으면 오판하는 것 (실제로는 없음)

4-4. CMS 고유 계약이 바뀐 곳

워드프레스에 대해 확정된 것과 그렇지 않은 것:

• 확정: 환경 감지에서 워드프레스는 한 번도 선택되지 않습니다(adapters/wordpress.php:93 validate_context => function () { return false; })
• 확정: 제공 = 워드프레스 미디어 라이브러리 업로드, nonce 검증, upload_files 권한 검사(wordpress.php:33-60)
• [확인 필요]: 워드프레스 최소 지원 판본

5. 이관 절차

5-0. 이관 전 체크리스트

• 백업을 받았습니다. 글 데이터와 data/ 폴더를 전부
• 그누보드5 data/editor/ (미디어) 와 data/editor/t2editor_db/ (내부 데이터) 를 따로 백업했습니다
• 라이믹스 files/ 를 백업했습니다
• 테스트 환경에서 먼저 올려봤습니다
• 서버 PHP가 7.4 이상임을 확인했습니다(php -v)
• 쓰기 권한이 필요한 곳이 공용 데이터 경로 하나임을 알고 있습니다

5-1. 공통 절차 (4가지 CMS 모두)

1. 백업. 글을 담는 파일과 data/ 폴더를 전부 복사해 두십시오. 자동 업데이트의 백업 기능은 10.4.0부터지만, 첫 이관 전 백업은 직접 받으십시오.
2. 현재 판전을 기록해 두십시오. 나중에 되돌릴 때 필요합니다. readme.txt 2행.
3. v10.5.1 배포판을 받아 t2editor 폴더를 덮어씁니다. data/ 는 건드리지 마십시오.
4. 설치 자리가 올바른지 확인합니다 (5-2).
5. 최초 설치 게이트를 통과합니다 (3-5). 관리자 키 활성화 → 비밀번호 → 쓰기 시험 → 안내 완독.
6. 관리자 페이지를 엽니다 — 자동 업데이트가 뜨면 먼저 "되돌리기" 경로가 있는지 확인한 뒤 진행하십시오.
7. 기존 글 몇 개를 열어 편집해 봅니다. 과거 글이 빈 화면으로 뜨지 않는지, 영상이 재생되는지, 표가 깨지지 않는지 확인.

5-2. CMS별 설치 자리 확인

5-3. 그누보드5

1. 관리자 → 환경설정 → 기본환경설정 → 에디터 선택에서 t2editor 선택. 게시판마다 다르게 쓰려면 게시판 관리에서 지정.
2. 관리자 로그인으로 T2Editor 관리자 페이지에 들어갑니다(CMS 연동). CMS 인증이 안 되면 자체 로그인 경로를 씁니다(3-2).
3. data/t2editor_db 가 자동으로 만들어지는지 확인합니다. 쓰기 시험이 실패하면 data/ 에 707을 적용하고 다시 시험합니다. 성공하면 그 권한을 그대로 둡니다.
4. 이전 위치 data/editor/t2editor_db 에 파일이 남아 있는지 확인하십시오. 남아 있으면 자동 이관이 실패했을 수 있습니다. 관리자 업데이트로 재시도하거나, 파일을 새 위치로 옮긴 뒤 관리자 화면을 다시 엽니다.

5-4. 라이믹스

1. 스킨을 rhymix/modules/editor/skins/t2editor/ 에 둡니다. 폴더 이름이 t2editor 여야 합니다. 다른 이름이면 관리자 에디터 목록에 안 나옵니다.
2. 라이믹스 관리자 → 고급 설정 → 에디터 → 에디터 스킨에서 T2Editor 선택.
3. 업로드는 T2Editor가 직접 파일을 두지 않고 라이믹스 파일 모듈을 거칩니다. 그래서 첨부파일 목록·용량 계산·삭제가 라이믹스와 어긋나지 않습니다. 이건 10.3.0 이후의 동작입니다.
4. CMS 관리자 인증이 안 될 때: admin/t2admin.key 활성화 + 자체 비밀번호.

5-5. 독립 실행

1. data/ 가 없으면 첫 요청에서 자동 생성됩니다.
2. 최초 요청이 리다이렉트·경로 오류로 보이면, 배포판 안의 진단 화면을 먼저 여십시오. 자동 감지가 빗나간 경우입니다.
3. 최소 권장 권한은 707 입니다(777이 아님). 그리고 숫자보다 실제 쓰기 시험입니다.

5-6. 업그레이드 후 확인할 것

• 과거 글을 열어도 빈 화면이 아니다 (10.5.1에서 손상문자 문제 수정됨)
• 이미지가 깨지지 않는다
• 표가 원래 모양이다
• 영상이 재생된다
• 협업이 동작한다
• 자동 저장이 되고 지난 자동 저장 데이터가 읽힌다
• 관리자 페이지에 무한 로딩이 없다
• 에디터 하단 버전 정보에 10.5.1 이 표시된다

6. 되돌리는 법

6-1. 되돌리기 전에 알아야 할 것 — 되돌려도 되는가?

v10.5.1로 올린 뒤 관리자에서 글을 썼다면, 되돌리면 그 글의 서식이 깨질 수 있습니다. 10.0.0이 아키텍처를 바꿨고(hook 분산화), 10.5.0이 편집 기본 동작을 정비했습니다. 되돌릴 때는 데이터 이관이 되돌려지지 않는다는 점을 먼저 기억하십시오.

데이터 경로 이관(3-3)은 한 방향입니다. 10.5.1이 data/editor/t2editor_db → data/t2editor_db 로 옮겼다면, 9.x로 되돌렸을 때 9.x는 새 위치를 모릅니다. 코드에는 새 경로를 다시 이전 경로로 되돌리는 로직이 없습니다.

그래서 순서를 지킵니다:

1. 되돌리기 전에 새 위치의 데이터를 따로 복사해 둡니다(data/t2editor_db 전체).
2. 그 뒤에 9.x 배포판을 덮어씁니다.
3. 9.x가 이전 경로를 찾지 못하면, 복사해 둔 데이터로 9.x가 기대하는 경로(data/editor/t2editor_db)에 되돌려 놓습니다.

6-2. 방법 A — 관리자 자동 업데이트 되돌리기 (10.4.0 이상)

10.4.0부터 관리자 페이지에서 업데이트를 되돌릴 수 있습니다. 업데이트 전에 파일이 자동 백업되고, 비밀번호를 다시 확인한 뒤 적용됩니다.

10.4.0 원문: "안전을 위해 기본적으로는 원래 파일을 직접 건드리지 않고 별도 공간에 새 버전을 설치한 뒤 전환하는 방식을 씁니다. 이렇게 하면 문제가 생겨도 이전 상태로 바로 되돌릴 수 있습니다."

⚠ 이건 10.x 계열 안에서의 되돌리기입니다. 9.x로 되돌리는 데는 이 경로를 쓸 수 없습니다.

6-3. 방법 B — 수동 되돌리기 (9.x로)

1. 쓰기를 멈추십시오(게시·편집 중이 아니게).
2. 백업 — data/ 전체, CMS가 있다면 data/editor/(그누보드5) 또는 files/(라이믹스).
3. 9.x 배포판으로 t2editor 폴더를 덮어씁니다. 9.x 판본을 처음 받아야 한다면 72-version-issues-guide.md의 EOL 안내를 보십시오. 그 계열은 더 이상 배포 대상이 아닙니다.
4. 데이터 경로를 6-1 순서로 되돌립니다.
5. 관리자 페이지를 엽니다. admin/t2admin.key 가 남아 있으면 CMS 로그인이 아닌 자체 로그인 경로로 들어갈 수 있습니다(9.x에 이 기능이 있는지는 [확인 필요]).

6-4. 되돌리면 안 되는 경우

⚠ 현실적인 조언: 되돌리기보다 앞으로 가지 않는 편이 낫습니다. EOL 계열로 내려가는 길은 돌아오기 어렵습니다.

7. 데이터 이관 체크리스트 (10.5.0 / 10.5.1)

8. 파이프라인 업그레이드 (개발자용)

9. 이 문서가 답하지 못한 것 (미확인)

| # | 항목 | 왜 | |:-:|---|---| | 1 | v9 → v10 커스텀 플러그인 hook API 1:1 대응표 | v9 판본 실물 소스 미확보 | | 2 | v9의 collab 폴더 구조·권한 계약 | v9 실물 소스 미확보 | | 3 | data/editor/t2editor_db 에 직접 쓰던 플러그인이 실제로 있었는지 | v9 실물 소스 미확보 | | 4 | 9.x에 admin/t2admin.key 자체 로그인 경로가 있었는지 | v9 실물 소스 미확보 | | 5 | 10.0.0~10.0.1에서 8.0+ 전용 API 사용 여부 | 해당 판본 실물 미확보 | | 6 | ext-dom이 없으면 링크 미리보기 카드가 어떻게 실패하는지 | 폴백 코드 0건은 확인, 런타임 재현 안 함 | | 7 | mbstring+iconv 동시 부재 시 문자열 처리 정확도 | 대체 경로 존재는 확인, 결과 동일성 미측정 | | 8 | 9.x 배포판을 어디서 받아야 하는지 | 제3자 배포 채널 정보를 이 문서에서 판정하지 않습니다 | | 9 | 10.0.0의 자동 이관 성공률·실패 조건 | 이전 경로 인식 코드는 존재하나 실패 조건은 미측정 |

이 목록은 지우지 마십시오. 지우면 "알려지지 않았다"가 "문제가 없다"로 읽힙니다.

N-xx 번호 체계 메모 (2026-09-28 확정)

이 위키의 N- 번호는 2026-09-28에 등록부를 확정하면서 붙였습니다. 확정된 신규 문서는 4건입니다.

N-01 · N-04 · N-07은 비어 있습니다. 번호를 미리 예약하면 그 번호가 "예정된 문서가 있다"는 뜻으로 읽히고, 실제로 그런 문서가 생기지 않으면 독자가 찾다 포기합니다. 필요해지는 시점에 그때 번호를 쓰십시오. 이전 문안에서 [[N-02-admin-console-guide.md]]·[[N-05-cms-adapter-and-data-paths.md]]처럼 가리키던 링크는 이 등록부 기준으로 교정되었습니다(N-08 → N-02, 라이믹스 경로는 N-05에 포함).

10. 참고 자료

• 판본 목록 94건 · 릴리즈 노트 전문: 이 위키 내부 데이터
• 배포판 실물: tak2-08/T2Editor-v10 · 브랜치 releases/v10.5.1
• 호환 매트릭스(PHP·CMS·확장): 06-version-compatibility-guide.md
• 판본별 이슈 대응: 72-version-issues-guide.md
• 최초 설치 절차: 01-installation-guide.md
• 오류 대응: 71-error-handling-guide.md
• 업로드·미디어 파이프라인: 75-upload-and-media-pipeline-guide.md

11. 문서 관리 메모

• 이 문서는 10.x 계열이 끝나면 새 판본을 추가해야만 유효합니다. v10이 EOL이 되면 v11로 같은 형식으로 다시 써야 합니다.
• 3절(파괴적 변경)은 "릴리즈 노트 원문 + 10.5.1 코드 실측" 두 겹을 요구합니다. 한쪽만으로 채우지 마십시오.
• 4-3절("사라졌다고 믿으면 오판하는 것")을 지우면 안 됩니다. 9.x 사용자가 가장 많이 하는 오독입니다.
• 6절(되돌리기)의 6-1은 데이터 이관이 단방향이라는 실제 제약을 적는 자리입니다. 이 문장을 줄이면 안 됩니다.