Cloudwiki/설정

# 시작하는법
## 준비

PC에 아래 프로그램들을 설치합니다.
[node.js(필수)](https://nodejs.org/ko/download)
[git(권장)](https://git-scm.com/install/windows)

아래 웹사이트들에서 계정을 생성합니다.

https://cloudflare.com 에 가입하고, 도메인을 구입 또는 등록합니다. (도메인 등록은 생략이 가능합니다.)
https://cloud.google.com 또는 https://discord.com/developers 에 가입합니다.
https://github.com 에서 계정을 생성합니다.


## 레포지토리 복제

```bash
git clone https://github.com/eoeoe22/cloudwiki-public.git
```
git을 사용해 이 레포지토리를 복제하고, 깃허브에 **프라이빗 레포지토리**를 생성한 뒤 파일 전체를 업로드합니다.
git이 설치되어있지 않다면 https://github.com/eoeoe22/cloudwiki-public 에서 직접 코드를 다운로드합니다.

## Oauth 설정

회원가입 / 로그인 Oauth 제공자를 고릅니다. 현재는 Google과 Discord를 지원하며, 최소 1개를 선택해 이용해야 합니다. 
두가지 Oauth 제공자를 모두 이용할수도 있습니다.


> 도메인을 구입하지 않은 경우, 이후 생성될 Worker이름.Cloudflare유저네임.workers.dev 리디렉션 주소에 사용합니다.


### Google
https://console.cloud.google.com 에 접속해 프로젝트를 생성하고, Google 인증 플랫폼 / 클라이언트에 접속해 Oauth 클라이언트를 생성합니다.
**승인된 JavaScript 원본**, **승인된 리디렉션 URI** 에는 `https://사용할 도메인/auth/google/callback` 을 입력한 뒤, 저장 후 클라이언트 ID와 시크릿 키를 복사해둡니다.


### Discord
https://discord.com/developers/applications 에 접속해 애플리케이션을 생성하고, Oauth 탭에 접속해 **리디렉션** 탭의 URI에 `https://사용할 도메인/auth/discord/callback`을 입력하고, 클라이언트 아이디(숫자), 클라이언트 시크릿(랜덤 문자열, 최초 1회 재설정 필요) 를 발급받아 복사해둡니다.

## Cloudflare 및 wrangler.toml 설정

먼저 `wrangler example.toml` 파일의 이름을 wrangler.toml로 변경합니다.

https://dash.cloudflare.com 에 접속해 스토리지 및 데이터베이스를 클릭하고, R2 Object Storage, Workers KV, D1 SQL Database를 각각 하나씩 생성하고, 각 스토리지들의 UID와 이름을 wrangler.toml에 붙여넣습니다.
wrangler.toml에 적힌 주석을 참고해 나머지 설정값들도 적절히 설정합니다.

앞서 선택한 Oauth 클라이언트, 시크릿키는 각각 `Oauth제공자_CLIENT_ID`, `Oauth제공자_CLIENT_SECRET` 으로 저장합니다. 
클라이언트 시크릿은 꼭 Cloudflare Workers 대시보드에서 **비밀 변수** 로 주입해야 합니다.  



Turnstile 설정
dash.cloudflare.com 의 사이드바에서
`보호 및 연결` -> `응용 프로그램 보안` -> `Turnstile` -> `위젯 추가` 경로로 접속 후, `호스트 이름 추가`에 도메인을 입력하고 생성합니다.

이후 제공된 시크릿 키, 사이트 키를 저장해둔 뒤, Workers 배포 단계를 마치고 나서 `Workers 설정` -> `변수 및 암호` 에서 `비밀` 암호로 등록합니다.

> 참고 : `사이트 키` 는 wrangler.toml에 직접 입력해도 무방하나, 보안을 위해 `시크릿 키` 는 꼭 비밀 암호로 등록해야 합니다.

Analstics Engine 설정
[[Cloudwiki/설정/Analytics Engine]] 문서를 참고하세요.



> 참고 : wrangler.toml 의 관리자 잡 러너 Durable Object 바인딩 블록은 기본적으로 주석 처리돼 있다.
> 그대로 두면 위키의 모든 기능이 정상 동작하며, 관리자 잡 러너(역링크 재인덱싱 · 대량 이동/삭제 ·
> RAG 백필)만 비활성화된다. 사용하려면 아래 **관리자 잡 러너 설정 (선택)** 단계를 진행하세요.




## Cloudflare Workers 배포

Cloudflare 대시보드에서 Compute > Workers 및 Pages > 응용 프로그램 생성을 클릭한 뒤, **Continue with GitHub**를 클릭해 깃허브 계정을 연동한 후, 만들어둔 프라이빗 레포지토리를 선택해 Workers에 배포합니다.

> 참고 : 연결된 깃허브 레포지토리의 main 브랜치에 수정사항이 발생시, 1~2분 내 자동으로 업데이트된 내용이 배포됩니다.
> wrangler.toml의 내용은 언제든 수정이 가능합니다.

## Workers Secrets 주입

생성된 Workers의 설정에 들어가 변수 및 암호 탭에서 **+추가** 버튼을 클릭한 뒤, 유형은 **비밀**, 이름은 **GOOGLE_CLIENT_SECRET**, 값은 조금 전 복사해둔 구글 Oauth 클라이언트 시크릿 키로 설정한 뒤 저장합니다.

## 도메인 연결

Workers 설정에서 도메인 및 경로 탭의 **+추가** 버튼, **사용자 설정 도메인** 버튼을 클릭한 뒤, Cloudflare 계정에 연결된 도메인을 입력후 저장합니다.

도메인이 없는 경우, workers에서 발급된 임시 즈소를 사용합니다.
임시 주소는 `https://앱이름.유저네임.workers.dev` 형식입니다.

## D1 데이터베이스 설정
앞서 생성했던 D1 데이터베이스의 설정으로 이동해 Explore Data 버튼을 클릭하고, **Query** 탭의 입력창에 **migrations/schema.sql** 파일의 내용을 붙여넣은 뒤, 실행 버튼의 ** 드롭다운 메뉴** 를 클릭하고 **Run all statement** 로 모든 설정 명령어를 실행합니다.

## 관리자 잡 러너 설정 (선택)

역링크 전수 재인덱싱, 문서 대량 이동/삭제, RAG 백필 같은 관리자 대량 작업은 별도의 DO(Durable Object) 전용 Worker(`cloudwiki-do`)가 처리합니다. Cloudflare 정책상 DO 클래스를 구현하는 Worker에는 프리뷰 URL이 생성되지 않기 때문에, 본체와 분리된 전용 Worker로 배포하는 구조입니다.

이 단계를 건너뛰어도 위키는 정상 동작합니다 — 해당 관리자 기능만 비활성화됩니다(호출 시 503).

1. 저장소의 `do-worker/wrangler example.toml`을 참고해 같은 위치에 `do-worker/wrangler.toml`을 만들고 값을 채웁니다. D1/R2 리소스는 **본체와 같은 것**을 바인딩합니다.
2. `ENABLED_EXTENSIONS`, `RAG_SEARCH_ENABLED`, `WIKI_PUBLIC_BASE_URL`, `SUPER_ADMIN_EMAILS` 는 본체 wrangler.toml의 같은 이름 값과 **반드시 일치**시킵니다. 특히 `ENABLED_EXTENSIONS`가 어긋나면 역링크 재인덱싱 잡이 익스텐션 문서의 링크 데이터를 손상시킬 수 있습니다.
3. `do-worker` 디렉터리에서 아래 명령으로 **본체보다 먼저** 배포합니다. (wrangler 로그인이 필요합니다)

```bash
cd do-worker
npx wrangler deploy
```

4. 본체 `wrangler.toml`의 `[[durable_objects.bindings]]` 블록 주석을 해제합니다. `script_name = "cloudwiki-do"` 가 1번에서 배포한 Worker 이름과 일치하는지 확인한 뒤(이름을 바꿨다면 함께 수정), 본체를 다시 배포합니다. script_name이 가리키는 Worker가 없으면 본체 배포가 실패하므로 3번이 먼저입니다.

> 기존 설치 업그레이드 (2026-09 이전 버전에서 관리자 잡 러너를 사용했던 경우에만) :
> **2단계 배포가 필요합니다.** 본체 wrangler.toml의 `ADMIN_JOB_DO` 바인딩 블록과
> `v4-move-admin-job-to-do-worker` 마이그레이션 블록 주석을 **동시에** 해제한 채 배포하면
> 실패합니다("Cannot apply --delete-class migration to class 'AdminJobDO' without also removing
> the binding that references it" — code 10061). ① 바인딩+마이그레이션 주석을 모두 해제하고
> 1회 배포(기존 네임스페이스 삭제) → ② 마이그레이션은 다시 주석 처리하고 바인딩만 해제한 뒤
> 재배포(script_name 연결). 잡이 실행 중일 때는 배포하지 마세요(진행 상태만 초기화되며 문서
> 데이터에는 영향이 없습니다).

> 참고 : cloudwiki-do 에는 시크릿 변수가 필요 없습니다. 배포는 Workers 대시보드의 GitHub 연결이
> 아니라 위 명령(로컬 wrangler)으로 수행합니다.

자세한 배경과 절차는 저장소의 `docs/durable-object-worker.md` 문서를 참고하세요.


## robots.txt 커스터마이징
크롤러 접근 정책은 `src/robots-txt.ts` 파일을 직접 수정하여 원하는 형태로 변경할 수 있습니다.
`Sitemap:` 항목은 배포된 사이트의 URL을 기반으로 자동 삽입되므로 별도로 작성하지 않아도 됩니다.

## 기타
유저를 위한 문법 가이드 문서를 생성하려면 [[Cloudwiki/위키 문법 가이드]]의 내용을 그대로 복사해서 사용하세요.
MIT 라이센스에 따라 자유로운 사용이 가능하지만, 사용하실때 eoe@vialinks.xyz로 쓴다고 한마디만 보내주시면 감사하겠습니다.


# 기타 설정

기초 설정 완료 후 사용할 수 있는 커스터마이징 옵션은 `Cloudwiki/설정` 의 하위 문서들을 참고하세요.


[[Cloudwiki]]
├── [[Cloudwiki/개인정보처리방침|개인정보처리방침]]
├── [[Cloudwiki/메인|메인]]
├── [[Cloudwiki/이용약관|이용약관]]
├── [[Cloudwiki/Pricing|Pricing]]
├── 기타
│   └── [[Cloudwiki/기타/문서 내용 일괄 수정|문서 내용 일괄 수정]]
├── [[Cloudwiki/관리자|관리자]]
│   ├── [[Cloudwiki/관리자/블로그 및 공지|블로그 및 공지]]
│   └── [[Cloudwiki/관리자/삭제|삭제]]
├── [[Cloudwiki/확장 기능|확장 기능]]
│   ├── [[Cloudwiki/확장 기능/freq|freq]]
│   └── [[Cloudwiki/확장 기능/stock|stock]]
├── [[Cloudwiki/위키 문법 가이드|위키 문법 가이드]]
│   ├── [[Cloudwiki/위키 문법 가이드/요약본-AI용|요약본-AI용]]
│   ├── [[Cloudwiki/위키 문법 가이드/컴포넌트|컴포넌트]]
│   └── [[Cloudwiki/위키 문법 가이드/차트|mermaid]]
├── [[Cloudwiki/에디터|에디터]]
│   ├── [[Cloudwiki/에디터/단축키|단축키]]
│   ├── [[Cloudwiki/에디터/이미지 업로드|이미지 업로드]]
│   ├── [[Cloudwiki/에디터/자동완성|자동완성]]
│   ├── [[Cloudwiki/에디터/툴바|툴바]]
│   ├── [[Cloudwiki/에디터/편집 요약|편집 요약]]
│   ├── [[Cloudwiki/에디터/편집 충돌|편집 충돌]]
│   └── [[Cloudwiki/에디터/표|표]]
├── 기능
│   ├── [[Cloudwiki/기능/검색|검색]]
│   ├── [[Cloudwiki/기능/맵 및 그래프|맵 및 그래프]]
│   ├── [[Cloudwiki/기능/문서|문서]]
│   ├── [[Cloudwiki/기능/문서 주시|문서 주시]]
│   ├── [[Cloudwiki/기능/카테고리|카테고리]]
│   ├── [[Cloudwiki/기능/커맨드 팔레트|커맨드 팔레트]]
│   ├── [[Cloudwiki/기능/템플릿|템플릿]]
│   ├── [[Cloudwiki/기능/토론|토론]]
│   ├── [[Cloudwiki/기능/틀|틀]]
│   ├── [[Cloudwiki/기능/편집 요청|편집 요청]]
│   ├── [[Cloudwiki/기능/프레젠테이션|프레젠테이션]]
│   └── [[Cloudwiki/기능/ACL|ACL]]
└── [[Cloudwiki/설정|설정]]
    ├── [[Cloudwiki/설정/동시편집 감지|동시편집 감지]]
    ├── [[Cloudwiki/설정/레이아웃 모드|레이아웃 모드]]
    ├── [[Cloudwiki/설정/로그인페이지|로그인페이지]]
    ├── [[Cloudwiki/설정/사이드바 푸터 커스터마이징|사이드바 푸터 커스터마이징]]
    ├── [[Cloudwiki/설정/스크립트 삽입|스크립트 삽입]]
    ├── [[Cloudwiki/설정/아이콘 커스터마이징|아이콘 커스터마이징]]
    ├── [[Cloudwiki/설정/웹훅|웹훅]]
    ├── [[Cloudwiki/설정/위키 공개설정|위키 공개설정]]
    ├── [[Cloudwiki/설정/컬러 팔레트|컬러 팔레트]]
    ├── [[Cloudwiki/설정/크롤링|크롤링]]
    ├── [[Cloudwiki/설정/푸시알림|푸시알림]]
    ├── [[Cloudwiki/설정/회원가입 정책|회원가입 정책]]
    ├── [[Cloudwiki/설정/Analytics Engine|Analytics Engine]]
    ├── [[Cloudwiki/설정/MCP서버|MCP서버]]
    └── [[Cloudwiki/설정/테마|테마]]
        ├── [[Cloudwiki/설정/테마/벡터|벡터]]
        ├── [[Cloudwiki/설정/테마/Astro|Astro]]
        ├── [[Cloudwiki/설정/테마/Cloudwiki|Cloudwiki]]
        └── [[Cloudwiki/설정/테마/VIA|VIA]]