Skip to content

Commit 13291a0

Browse files
SOIVsisyphus-dev-ai
andcommitted
docs: 설치 가이드에 Cloudflare Tunnel 홈서버 외부 공개 섹션 추가
Docker/PM2/systemd 각 실행 방식별 cloudflared 연동 방법 및 집 IP 노출 없이 지인 공유하는 방식을 독립 섹션(7번)으로 정리 (초안/미확정) Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
1 parent dd6338c commit 13291a0

1 file changed

Lines changed: 129 additions & 2 deletions

File tree

docs/v2_FINANCIAL-LEDGER/deployment/01-installation.md

Lines changed: 129 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,12 @@ Fieldstack은 **00-overview.md**에서 정의된 4가지 실행 모델을 지원
88
## 📋 목차
99

1010
1. [Docker 버전 (권장)](#1-docker-버전-권장) - 가장 표준적이고 쉬운 방법
11-
2. [Cloudflare 버전](#2-cloudflare-버전) - 외부 접속 및 무료 SSL/TLS 자동화
11+
2. [Cloudflare 버전](#2-cloudflare-버전) - Cloudflare 클라우드(Pages + Workers + D1) 배포
1212
3. [OS Native 버전](#3-os-native-버전) - Linux 서버 운영자용 (Systemd)
1313
4. [Native (CLI) 버전](#4-native-cli-버전) - Docker 미사용 환경 (PM2)
1414
5. [기타 플랫폼](#5-기타-플랫폼) - Railway 등
1515
6. [공통 설정](#6-공통-설정) - 환경 변수, 리버스 프록시
16+
7. [[초안/미확정] Cloudflare Tunnel — 홈서버 외부 공개](#7-초안미확정-cloudflare-tunnel--홈서버-외부-공개) - 집 IP 노출 없이 지인 공유
1617

1718
---
1819

@@ -252,4 +253,130 @@ server {
252253

253254
```bash
254255
sudo certbot --nginx -d your-domain.com
255-
```
256+
```
257+
258+
---
259+
260+
## 7. [초안/미확정] Cloudflare Tunnel — 홈서버 외부 공개
261+
262+
> **⚠️ 초안/미확정:** 아이디어 검토 단계이며, 정식 기능으로 확정되지 않았습니다.
263+
264+
### 개요
265+
266+
Fieldstack은 어떤 방식(Docker, PM2, systemd)으로 실행하든 기본적으로 **로컬(집 내부 네트워크)에서만 접근 가능**합니다.
267+
268+
지인에게 공유하거나 외부에서 접근하고 싶을 경우, 가장 단순한 방법은 집 IP를 직접 알려주는 것이지만 **보안상 바람직하지 않습니다.** Cloudflare Tunnel(`cloudflared`)을 사용하면 집 IP를 노출하지 않고도 `fieldstack.내도메인.com` 형태로 안전하게 외부 공개가 가능합니다.
269+
270+
> **주의:** 이 섹션은 [2. Cloudflare 버전](#2-cloudflare-버전)(Cloudflare 클라우드 배포)과 **전혀 다른 개념**입니다.
271+
> - **2번 Cloudflare 버전**: Fieldstack 자체를 Cloudflare 클라우드(Pages + Workers + D1)에 올려서 운영하는 방식
272+
> - **이 섹션(7번)**: Fieldstack은 집/로컬 서버에서 그대로 실행하되, Tunnel을 통해 외부 접근 통로만 안전하게 여는 방식
273+
274+
| 구분 | IP 직접 공유 | Cloudflare Tunnel |
275+
|------|------------|-------------------|
276+
| 공유 주소 | `집IP:3000` | `fieldstack.내도메인.com` |
277+
| 집 IP 노출 | ✅ 노출됨 | ❌ 완전 숨김 |
278+
| 포트포워딩 | 필요 | 불필요 |
279+
| 고정 IP | 필요 | 불필요 |
280+
| SSL/HTTPS | 직접 설정 | 자동 무료 |
281+
| 유동 IP 대응 | DDNS 필요 | 자동 처리 |
282+
283+
---
284+
285+
### 실행 방식별 적용 방법
286+
287+
#### Docker로 실행 중인 경우
288+
289+
`docker-compose.yml``cloudflared` 서비스 하나만 추가하면 됩니다.
290+
291+
```yaml
292+
version: '3.8'
293+
294+
services:
295+
app:
296+
image: fieldstack/core:latest
297+
ports:
298+
- "3000:3000"
299+
volumes:
300+
- ./data:/app/data
301+
- ./modules:/app/modules
302+
environment:
303+
- NODE_ENV=production
304+
- SERVE_FRONTEND=true
305+
restart: unless-stopped
306+
307+
cloudflared:
308+
image: cloudflare/cloudflared:latest
309+
command: tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN}
310+
environment:
311+
- CLOUDFLARE_TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN}
312+
restart: unless-stopped
313+
depends_on:
314+
- app
315+
```
316+
317+
`.env`에 토큰 추가 후 재실행:
318+
319+
```bash
320+
CLOUDFLARE_TUNNEL_TOKEN=your-tunnel-token-here
321+
```
322+
323+
```bash
324+
docker-compose up -d
325+
```
326+
327+
---
328+
329+
#### PM2로 실행 중인 경우
330+
331+
`cloudflared`는 Fieldstack과 완전히 독립적으로 동작합니다. PM2로 Fieldstack을 실행 중이라면 `cloudflared`만 별도로 설치해서 실행하면 됩니다.
332+
333+
```bash
334+
# cloudflared 설치 (Linux)
335+
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
336+
chmod +x cloudflared
337+
sudo mv cloudflared /usr/local/bin/
338+
339+
# 터널 실행
340+
cloudflared tunnel run --token your-tunnel-token-here
341+
342+
# PM2로 상시 실행 등록
343+
pm2 start "cloudflared tunnel run --token your-tunnel-token-here" --name "cloudflared"
344+
pm2 save
345+
```
346+
347+
---
348+
349+
#### systemd로 실행 중인 경우
350+
351+
`cloudflared`를 별도 systemd 서비스로 등록합니다.
352+
353+
`/etc/systemd/system/cloudflared.service` 파일 생성:
354+
355+
```ini
356+
[Unit]
357+
Description=Cloudflare Tunnel
358+
After=network.target
359+
360+
[Service]
361+
Type=simple
362+
ExecStart=/usr/local/bin/cloudflared tunnel run --token your-tunnel-token-here
363+
Restart=on-failure
364+
365+
[Install]
366+
WantedBy=multi-user.target
367+
```
368+
369+
```bash
370+
sudo systemctl enable cloudflared
371+
sudo systemctl start cloudflared
372+
```
373+
374+
---
375+
376+
### 터널 토큰 발급 방법
377+
378+
1. [Cloudflare Zero Trust 대시보드](https://one.dash.cloudflare.com/) 접속
379+
2. `Networks → Tunnels → Create a tunnel`
380+
3. `Cloudflared` 선택 후 터널 이름 입력
381+
4. 토큰 복사
382+
5. `Public Hostname` 설정: `fieldstack.내도메인.com` → `http://localhost:3000`

0 commit comments

Comments
 (0)