docs: 기존 운영 중인 인스턴스용 '패치만' 가이드 추가 (patch-only/README.md)

2026-08-26 10:44:17 +09:00
parent 9029085b38
commit bd7d12255f
1 changed files with 56 additions and 0 deletions
@@ -0,0 +1,56 @@
+# TriliumNext Notes 한국어 패치만 (기존 운영 중인 인스턴스용)
+
+이미 Trilium Notes를 운영 중이고, 새 이미지를 빌드하거나 컨테이너를 새로 만들고 싶지
+않은 경우를 위한 패키지입니다. 기존 데이터/설정은 그대로 두고 파일 3개만 컨테이너에
+bind-mount로 추가하면 됩니다.
+
+전체 배포판(Dockerfile, install.sh 포함, 새로 설치하는 사람용)은
+[triliumnext-korean-patch](https://gitea.itosm.co.kr/syskiller/triliumnext-korean-patch)를 참고하세요.
+
+## 포함된 파일
+
+- `main.cjs` — 이미 패치가 적용된, 바로 쓸 수 있는 서버 번들
+  (`triliumnext/notes:latest`, 빌드일 2025-06-07, appVersion 0.95.0 기준).
+- `translation.json` — 클라이언트 UI 문자열, 1,712개 키, 100% 번역.
+- `server.json` — 서버 문자열, 283개 키, 100% 번역.
+- `patch_main_cjs.js` — `main.cjs`를 만들어낸 패치 스크립트. 다른 버전의 이미지를 쓰고
+  있다면 이 저장소의 `main.cjs`가 안 맞을 수 있으니, 이 스크립트를 직접 돌려서 본인
+  이미지에 맞는 패치 파일을 새로 만드세요.
+- `docker-compose.bind-mount.yml.example` — 기존 `docker-compose.yml`에 어떻게
+  반영하면 되는지 보여주는 예시.
+
+## 적용 방법
+
+1. 이 압축 파일을 기존 Trilium `docker-compose.yml`이 있는 폴더 옆에 풀어두거나,
+   `main.cjs`/`translation.json`/`server.json` 세 파일을 원하는 위치로 복사.
+2. 기존 `docker-compose.yml`의 `trilium` 서비스에 아래 3줄을 `volumes:` 밑에 추가
+   (`docker-compose.bind-mount.yml.example` 참고, 경로는 본인 파일 위치에 맞게 조정):
+   ```yaml
+   volumes:
+     - ./main.cjs:/usr/src/app/main.cjs:ro
+     - ./translation.json:/usr/src/app/public/translations/ko/translation.json:ro
+     - ./server.json:/usr/src/app/assets/translations/ko/server.json:ro
+   ```
+3. **주의: `docker cp`로 컨테이너 안에 파일만 직접 넣지 마세요.** 그렇게 하면 다음에
+   컨테이너를 완전히 재생성(`docker compose down && up`)할 때 파일이 통째로 사라져서,
+   나중에 "왜 갑자기 다시 영어로 나오지?" 하는 원인 불명의 문제가 생깁니다. 반드시
+   위 2번처럼 `docker-compose.yml`에 bind-mount로 등록하세요.
+4. `docker compose up -d`로 재시작 (설정만 바뀌었으므로 `--build` 불필요).
+5. 앱 안에서 **옵션 → 언어 및 지역**에서 "한국어" 선택 후 페이지 새로고침
+   (본문 텍스트까지 전부 한국어로 바뀌려면 새로고침이 한 번 필요합니다).
+
+## 이미지 버전이 다른 경우
+
+이 `main.cjs`는 위에 적은 특정 빌드용으로 패치된 파일입니다. 다른 버전을 쓰고 있어서
+안 맞으면, 컨테이너의 원본 `main.cjs`를 추출해서 `patch_main_cjs.js`를 직접 돌리세요:
+
+```bash
+docker create --name trilium-tmp triliumnext/notes:latest
+docker cp trilium-tmp:/usr/src/app/main.cjs ./main.cjs
+docker rm trilium-tmp
+node patch_main_cjs.js ./main.cjs
+node --check ./main.cjs   # 반드시 배포 전에 문법 검사
+```
+
+전체 배경 설명(왜 이렇게 복잡한지, 겪었던 문제 4가지)은 전체 배포판 저장소의
+[README](https://gitea.itosm.co.kr/syskiller/triliumnext-korean-patch)를 참고하세요.