From 8136db858b81a8f1e6d9bd1ab00334682275a1ce Mon Sep 17 00:00:00 2001
From: andy-sg <andy.sg@kakaoent.com>
Date: Thu, 5 Mar 2026 19:33:20 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20Gitea=20Actions=20=E2=86=92=20Synology?=
 =?UTF-8?q?=20=EB=B0=B0=ED=8F=AC=20=EC=A3=BC=EC=9D=98=EC=82=AC=ED=95=AD=20?=
 =?UTF-8?q?=EC=A0=95=EB=A6=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/README.md b/README.md
index 18bc70e..2c38e02 100644
--- a/README.md
+++ b/README.md
@@ -14,3 +14,49 @@ The React Compiler is not enabled on this template because of its impact on dev
 ## Expanding the ESLint configuration
 
 If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project.
+
+---
+
+## 배포 (Gitea Actions → Synology NAS)
+
+`main` 브랜치에 푸시하면 Gitea Actions가 빌드 후 Synology NAS(Web Station)로 자동 배포합니다.
+
+### 인프라 구성
+
+| 구성요소 | 환경 |
+|---------|------|
+| Gitea | Proxmox LXC |
+| Gitea Actions Runner | LXC 내 Docker Compose |
+| 배포 대상 | Synology NAS (10.0.0.19) Web Station |
+| 배포 경로 | `/volume1/web/app` |
+| 접속 URL | `http://10.0.0.19:8080` |
+
+### 주의사항
+
+#### 1. Runner 컨테이너 ≠ Job 실행 환경
+- Runner 자체는 Alpine이지만, `runs-on: ubuntu-latest`로 실행되는 Job은 **별도 Ubuntu 컨테이너**에서 동작
+- Runner 컨테이너에 들어가서 테스트하면 환경이 다르므로 의미 없음
+- 디버깅은 **워크플로우 스텝에서 직접** 해야 정확
+
+#### 2. Ubuntu 24.04의 scp는 Synology와 호환 문제 있음
+- OpenSSH 9.0+부터 scp가 기본적으로 **SFTP 프로토콜**을 사용
+- Synology가 이를 제대로 지원하지 못해 `dest open: No such file or directory` 에러 발생
+- **해결**: scp 대신 `tar | ssh` 파이프 사용
+  ```bash
+  tar -czf - -C dist . | ssh user@host "tar -xzf - -C /path/"
+  ```
+
+#### 3. Job 컨테이너의 패키지 제한
+- `rsync` 없음 → scp 또는 tar+ssh 사용
+- `apk` 없음 → Ubuntu이므로 `apt-get` (하지만 ssh/scp는 기본 포함)
+
+#### 4. Gitea Secrets 등록 시 주의
+- 공백, 개행 문자가 들어가지 않도록 주의
+- 디버깅 시 `echo "[$VAR]"`, `${#VAR}` (길이 출력)로 확인
+
+#### 5. 배포 디렉토리 관리
+- `rm -rf /path/*` 후 전송하면 타이밍에 따라 디렉토리가 사라질 수 있음
+- **안전한 패턴**: `mkdir -p`로 보장 후 전송
+  ```bash
+  ssh user@host "mkdir -p /path && rm -rf /path/*"
+  ```