Files
dbx-main/app/integrations/cafe24/design_ftp.py
T
king bd1cc61434 fix(cafe24): 디자인 FTP 임시 파일이 확장자 제한에 걸려 적용 실패
카페24 디자인 FTP 는 허용 확장자만 받는다. 임시 이름
`product-swiper.js.cf24tmp-<tag>` 는 확장자가 바뀌어 STOR 가
`550 Operation not permitted` 로 거부돼 모바일 스와이프·PC/모바일
상품상세 적용이 모두 실패했다. 원래 확장자를 끝에 두도록
`<stem>_cf24tmp_<tag><ext>` 로 바꾼다(원본 비킴 이름도 동일).
테스트 FTP 대역에 확장자 제한을 흉내내 회귀를 막는다.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 11:01:39 +09:00

190 lines
8.7 KiB
Python

"""카페24 디자인 보관함 FTP — 스킨에 올라간 개별 파일(예: product-swiper.js) 읽기/쓰기.
Admin API(OAuth)로는 스킨 파일을 다루지 못한다(`config.py` 상단 설명 참고). 카페24가
스킨 파일에 제공하는 유일한 프로그램적 접근은 "디자인 보관함" FTP 계정이며, Admin API
와는 별개의 인증(호스트/포트/아이디/비밀번호)이다. 그래서 여기는 `Cafe24Client`
(httpx 기반)를 쓰지 않고 표준 라이브러리 `ftplib` 를 직접 쓴다.
실물 확인(스크린샷): 호스트 `{mall_id}.ftp.cafe24.com`, 포트 21, SSL/TLS 미사용
(평문 FTP). 파일은 텍스트(UTF-8)로 다룬다.
쓰기는 원본에 직접 STOR 하지 않는다 (write_text_file)
직접 STOR 는 전송 도중 끊기면 원본이 **앞부분만 남은 채** 잘린다(스킨 템플릿이면
모든 상품 페이지가 깨진다). 그래서
1) 같은 폴더의 임시 파일에 올리고 (원본은 아직 그대로)
2) 다시 받아 바이트 단위로 검증하고
3) 교체 직전 원본을 다시 읽어 편집 시작 값과 같은지 확인하고(충돌 방지)
4) RNFR/RNTO 로 이름을 바꿔 교체한다
서버가 "이미 있는 이름으로 바꾸기"를 거부하면 원본을 옆 이름으로 비킨 뒤 교체하고,
실패하면 원본을 제자리로 되돌린다. 이름 바꾸기 자체를 지원하지 않으면 **중단**한다
(직접 STOR 로 물러서지 않는다).
"""
from __future__ import annotations
import ftplib
import io
import posixpath
import uuid
from .config import Cafe24FtpConfig
from .errors import Cafe24FtpConflict, Cafe24FtpError
# 응답이 없을 때 무한 대기하지 않도록 — 관리 화면 요청 안에서 동기 호출되므로
# 너무 길면 안 되지만, 파일 하나(수십 KB) 전송에는 충분히 넉넉해야 한다.
_TIMEOUT_SECONDS = 20
def _connect(config: Cafe24FtpConfig) -> ftplib.FTP:
try:
ftp = ftplib.FTP()
ftp.connect(config.host, config.port, timeout=_TIMEOUT_SECONDS)
ftp.login(config.user, config.password)
ftp.set_pasv(True)
return ftp
except ftplib.all_errors as exc: # OSError 포함 — 연결 실패도 여기서 잡힌다
# 비밀번호가 예외 메시지에 섞여 나오지 않는다 — ftplib 오류는 서버 응답
# 문자열이며 우리가 보낸 자격증명을 되풀이하지 않는다.
raise Cafe24FtpError(f"FTP 연결/로그인에 실패했습니다: {exc}") from exc
def _close(ftp: ftplib.FTP) -> None:
try:
ftp.quit()
except Exception: # noqa: BLE001 — 정리 실패는 무시
ftp.close()
def _retr(ftp: ftplib.FTP, path: str) -> bytes:
buf = io.BytesIO()
ftp.retrbinary(f"RETR {path}", buf.write)
return buf.getvalue()
def _delete_quiet(ftp: ftplib.FTP, path: str) -> None:
try:
ftp.delete(path)
except ftplib.all_errors:
pass # 임시 파일 정리 실패는 무시(이름에 cf24tmp 가 붙어 있어 구분된다)
def read_text_file(config: Cafe24FtpConfig, path: str) -> str:
"""디자인 보관함의 파일 1개를 읽어 텍스트로 돌려준다."""
ftp = _connect(config)
try:
try:
raw = _retr(ftp, path)
except ftplib.all_errors as exc:
raise Cafe24FtpError(f"파일을 읽지 못했습니다({path}): {exc}") from exc
try:
return raw.decode("utf-8")
except UnicodeDecodeError as exc:
raise Cafe24FtpError(f"파일 인코딩을 UTF-8로 해석하지 못했습니다({path}): {exc}") from exc
finally:
_close(ftp)
def temp_names(path: str, tag: str) -> tuple[str, str]:
"""(임시 업로드 이름, 원본을 잠시 비킬 이름) — 같은 폴더, 원본 이름 + 표식.
⚠️ 원래 확장자를 **맨 끝에 그대로** 둔다. 카페24 디자인 FTP 는 허용된 확장자(.js·
.html·.css 등)만 받는다 — 예전 이름 `product-swiper.js.cf24tmp-…` 는 확장자가 바뀌어
STOR 가 `550 Operation not permitted` 로 거부됐다(실물). 그래서
`product-swiper_cf24tmp_<tag>.js` 모양으로 만든다(점·하이픈 대신 밑줄).
"""
folder, name = posixpath.split(path)
stem, ext = posixpath.splitext(name)
return (posixpath.join(folder, f"{stem}_cf24tmp_{tag}{ext}"),
posixpath.join(folder, f"{stem}_cf24old_{tag}{ext}"))
def write_text_file(
config: Cafe24FtpConfig, path: str, content: str, *, expected_current: str | None = None
) -> None:
"""디자인 보관함의 파일 1개를 안전하게 교체한다(모듈 설명 참고).
expected_current: 편집 시작(또는 백업) 때 읽은 원본. 주면 교체 직전 원본을 다시
읽어 다르면 Cafe24FtpConflict 로 멈춘다(원본 그대로).
실패 시 Cafe24FtpError — maybe_applied=True 면 원본이 이미 바뀌었을 수 있다.
"""
data = content.encode("utf-8")
tmp, aside = temp_names(path, uuid.uuid4().hex[:10])
ftp = _connect(config)
try:
# 1) 임시 파일에 올린다 — 원본은 아직 그대로다.
try:
ftp.storbinary(f"STOR {tmp}", io.BytesIO(data))
except ftplib.all_errors as exc:
_delete_quiet(ftp, tmp)
raise Cafe24FtpError(f"임시 파일을 올리지 못했습니다 — 원본은 그대로입니다({path}): {exc}") from exc
# 2) 검증 — 다시 받아 바이트 단위로 비교한다(전송이 잘렸으면 여기서 잡힌다).
try:
uploaded = _retr(ftp, tmp)
except ftplib.all_errors as exc:
_delete_quiet(ftp, tmp)
raise Cafe24FtpError(f"올린 임시 파일을 확인하지 못했습니다 — 원본은 그대로입니다: {exc}") from exc
if uploaded != data:
_delete_quiet(ftp, tmp)
raise Cafe24FtpError(
f"올린 임시 파일이 보낸 내용과 다릅니다({len(uploaded)}/{len(data)}바이트) — 원본은 그대로입니다."
)
# 3) 충돌 확인 — 교체 직전의 원본이 편집 시작 값 그대로인가.
if expected_current is not None:
try:
now = _retr(ftp, path)
except ftplib.all_errors as exc:
_delete_quiet(ftp, tmp)
raise Cafe24FtpError(f"교체 직전 원본을 다시 읽지 못했습니다 — 원본은 그대로입니다: {exc}") from exc
if now != expected_current.encode("utf-8"):
_delete_quiet(ftp, tmp)
raise Cafe24FtpConflict(
"적용하는 사이 FTP 파일이 바뀌었습니다 — 원본은 그대로입니다. 새로고침해 확인한 뒤 다시 적용하세요."
)
# 4) 교체 — 이름 바꾸기. 덮어쓰기를 거부하는 서버면 원본을 비킨 뒤 교체한다.
moved_aside = False
try:
ftp.rename(tmp, path)
except ftplib.all_errors as first:
try:
ftp.rename(path, aside)
except ftplib.all_errors as exc:
_delete_quiet(ftp, tmp)
raise Cafe24FtpError(
"이 FTP 서버가 파일 이름 바꾸기(rename)를 지원하지 않아 중단했습니다 — 원본은 그대로입니다. "
f"({first} / {exc})"
) from exc
try:
ftp.rename(tmp, path)
except ftplib.all_errors as exc:
try:
ftp.rename(aside, path)
except ftplib.all_errors as exc2:
raise Cafe24FtpError(
f"교체에 실패했고 원본 되돌리기도 실패했습니다. FTP 에서 {aside} 를 {path} 로 "
f"직접 되돌리세요: {exc} / {exc2}",
maybe_applied=True,
) from exc2
_delete_quiet(ftp, tmp)
raise Cafe24FtpError(f"교체에 실패해 원본을 되돌렸습니다: {exc}") from exc
moved_aside = True
# 5) 확인 — 교체 뒤 원본 경로가 새 내용인가.
try:
final = _retr(ftp, path)
except ftplib.all_errors as exc:
raise Cafe24FtpError(
f"교체 뒤 확인 조회에 실패했습니다 — 적용됐을 수 있으니 파일을 다시 열어 확인하세요: {exc}",
maybe_applied=True,
) from exc
if final != data:
raise Cafe24FtpError(
"교체 뒤 파일 내용이 보낸 것과 다릅니다 — 파일을 다시 열어 확인하세요.", maybe_applied=True
)
if moved_aside:
_delete_quiet(ftp, aside)
finally:
_close(ftp)