# 발행 토큰 운영 가이드

## 역할

발행 토큰은 옵시디언 플러그인이 홈페이지의 `POST /api/publish` API를 호출할 때 사용하는 비밀 인증값이다. 토큰을 가진 요청만 문서를 발행할 수 있으므로 홈페이지 주소와 함께 외부에 공개하지 않는다.

## 1. 토큰 생성

충분히 긴 무작위 토큰을 생성한다. Node.js가 설치된 환경에서 다음 명령을 사용한다.

```powershell
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

생성된 값을 비밀번호처럼 취급한다. 채팅, 문서 본문, Git 저장소, 화면 캡처에 남기지 않는다.

## 2. 로컬 개발 환경 등록

`Pros_on/.env.local` 파일을 만들고 다음처럼 기록한다.

```env
PUBLISH_TOKEN=생성한_토큰
```

`.env.local`은 커밋하지 않는다. 개발 서버를 실행 중이었다면 토큰을 읽도록 서버를 재시작한다.

```powershell
cd C:\Obsidian\LUCKY\Pros_on
npm.cmd run dev
```

## 3. 옵시디언 플러그인 등록

1. 옵시디언을 재시작하거나 커뮤니티 플러그인 목록을 새로고침한다.
2. `PROS·ON Publisher`를 활성화한다.
3. 플러그인 설정에서 홈페이지 API 주소를 입력한다.
   - 로컬: `http://localhost:3000`
   - 운영: `https://실제-도메인`
4. 발행 토큰에 `.env.local`의 값과 동일한 토큰을 입력한다.
5. frontmatter가 있는 문서를 열고 명령 팔레트에서 `PROS·ON Publisher: 현재 문서 발행`을 실행한다.

플러그인은 토큰을 발행 요청의 다음 헤더로 전송한다.

```http
Authorization: Bearer <발행 토큰>
```

## 4. 토큰 보관 원칙

- 홈페이지 서버: 환경변수 `PUBLISH_TOKEN`으로만 보관한다.
- 옵시디언: 플러그인 설정에 저장한다.
- 토큰을 Markdown frontmatter나 문서 본문에 작성하지 않는다.
- 토큰을 JavaScript, CSS, GitHub, 이미지, 로그에 하드코딩하지 않는다.
- 운영 서버와 로컬 개발 환경은 서로 다른 토큰을 사용한다.
- 여러 운영자가 사용하게 되면 사용자별 토큰으로 분리하는 것을 권장한다.

## 5. 토큰 교체

토큰이 노출되었거나 담당자가 변경되면 즉시 교체한다.

1. 새 토큰을 생성한다.
2. 서버의 `PUBLISH_TOKEN`을 새 값으로 변경한다.
3. 서버를 재시작하거나 배포한다.
4. 옵시디언 플러그인 설정의 토큰도 새 값으로 변경한다.
5. 이전 토큰으로 발행 요청이 거부되는지 확인한다.

현재 API는 단일 `PUBLISH_TOKEN`을 사용하므로, 교체 시 기존 토큰이 즉시 폐기된다.

## 6. 오류 확인

| 증상 | 확인할 내용 |
|---|---|
| 발행 토큰을 입력하라는 알림 | 플러그인 설정에 토큰이 저장되어 있는지 확인 |
| 인증 실패 | 서버 환경변수와 플러그인 토큰이 정확히 같은지 확인 |
| 서버 주소 오류 | API 주소 끝의 `/`를 제외하고 입력했는지 확인 |
| slug 중복 오류 | 기존 문서의 `slug`를 변경하거나 수정 발행 기능을 사용 |
| frontmatter 오류 | `title`, `slug`, `description`, `published`, `publishedAt` 확인 |

## 운영 전 점검

- [ ] 운영 토큰이 로컬·운영 환경에서 분리되어 있는가
- [ ] `.env.local`이 Git에 포함되지 않는가
- [ ] 플러그인 설정에 올바른 운영 API 주소가 입력되어 있는가
- [ ] 테스트 문서 발행 후 `/blog/[slug]`에서 확인되는가
- [ ] 토큰 교체 절차를 운영자가 알고 있는가