LINKRIGHTS (링크라이츠)
이주배경청소년이 자신의 권리를 알고 → 할 수 있는 행동을 찾고 → 실제 도움을 받을 기관까지 연결되도록 돕는 권리정보 웹사이트입니다.
이 문서는 개발을 전공하지 않은 분이 사이트를 직접 운영·수정할 수 있도록 쓴 안내서입니다.
모르는 단어가 나오면 그 자리에서 쉬운 설명을 함께 적어두었습니다.
목차
- 이 사이트는 무엇으로 만들어졌나요
- 처음 한 번만 하는 준비 (설치)
- 내 컴퓨터에서 사이트 실행하기
- 환경변수와 OpenAI API 키 설정
- 콘텐츠 수정 방법 (가장 자주 하는 일)
- 권리정보 새로 추가하기
- 기관 정보 수정하기
- 이미지 넣고 바꾸기
- 인터넷에 배포하기
- AI 비용 관리와 모니터링
- 안전 규칙 — 반드시 지켜주세요
- 자주 생기는 문제 해결
- 폴더 구조
1. 이 사이트는 무엇으로 만들어졌나요
| 항목 | 사용한 것 | 왜 이것을 골랐나요 |
|---|
| 웹사이트 뼈대 | Next.js (넥스트제이에스) | 검색(구글)에 잘 노출되고, 무료 배포가 쉽고, 자료가 가장 많습니다. |
| 디자인 | Tailwind CSS | 색·글자 크기를 한 곳에서 관리할 수 있어 나중에 바꾸기 쉽습니다. |
| 콘텐츠 저장 | JSON 파일 (content 폴더) | 데이터베이스 서버가 없어 월 고정비 0원이고, 파일 하나만 고치면 내용이 바뀝니다. |
| 배포(인터넷 공개) | Vercel | 이 프로젝트 규모에서는 무료로 쓸 수 있고, 파일을 올리면 자동으로 사이트가 갱신됩니다. |
| AI | OpenAI API | 질문에 맞는 안내를 만들 때만 사용합니다. |
JSON이란? 컴퓨터가 읽기 쉬운 형태로 정보를 적어둔 텍스트 파일입니다.
메모장으로 열 수 있고, "제목": "내용" 처럼 생겼습니다.
중요한 설계 원칙
- 회원가입·로그인·데이터베이스가 없습니다. 그래서 개인정보 사고 위험과 운영 비용이 매우 낮습니다.
- AI는 등록된 자료만 근거로 답합니다. 기관 이름과 전화번호를 스스로 만들어내지 못하도록 서버에서 한 번 더 걸러냅니다.
2. 처음 한 번만 하는 준비 (설치)
(1) Node.js 설치
Node.js는 이 사이트를 내 컴퓨터에서 실행하기 위해 필요한 프로그램입니다.
- https://nodejs.org 에 접속합니다.
- LTS라고 적힌 초록색 버튼을 눌러 내려받습니다. (버전 20 이상)
- 내려받은 파일을 실행하고 "다음"만 계속 누르면 설치가 끝납니다.
- 설치가 잘 됐는지 확인합니다. PowerShell(윈도우 시작 메뉴에서 "powershell" 검색)을 열고 아래를 입력하세요.
node -v
v20.x.x 처럼 숫자가 나오면 성공입니다.
(2) 프로젝트 폴더에서 필요한 파일 내려받기
PowerShell에서 이 프로젝트 폴더로 이동한 뒤 아래를 입력합니다. (1~3분 걸립니다)
npm install
npm install 은 사이트를 만드는 데 필요한 부품들을 인터넷에서 내려받는 명령입니다.
딱 한 번만 하면 되고, 나중에 부품이 바뀔 때만 다시 하면 됩니다.
3. 내 컴퓨터에서 사이트 실행하기
npm run dev
실행하면 화면에 http://localhost:3000 이라는 주소가 나옵니다.
그 주소를 브라우저에 붙여넣으면 사이트가 보입니다.
- 파일을 수정하고 저장하면 브라우저가 자동으로 새로고침됩니다.
- 종료하려면 PowerShell에서
Ctrl + C 를 누릅니다.
콘텐츠만 고친 뒤 문제가 없는지 확인하고 싶다면:
npm run check
✅ 콘텐츠 점검 완료 가 나오면 정상입니다.
❌ 가 나오면 어떤 파일의 무엇이 잘못됐는지 한국어로 알려주므로, 그 부분만 고치면 됩니다.
4. 환경변수와 OpenAI API 키 설정
환경변수란? 비밀번호처럼 코드 안에 직접 적으면 안 되는 값을 따로 보관하는 방법입니다.
(1) 파일 만들기
프로젝트 폴더에 있는 .env.example 파일을 복사하고, 이름을 .env.local 로 바꿉니다.
(2) OpenAI API 키 발급받기
- https://platform.openai.com 에 로그인합니다.
- 오른쪽 위 → API keys → Create new secret key
- 만들어진 키(
sk- 로 시작하는 긴 글자)를 복사합니다. 이 화면을 닫으면 다시 볼 수 없으니 바로 붙여넣으세요.
(3) .env.local 파일에 붙여넣기
OPENAI_API_KEY=sk-여기에_복사한_키
OPENAI_MODEL=gpt-4o-mini
DAILY_REQUEST_LIMIT=500
RATE_LIMIT_PER_WINDOW=6
NEXT_PUBLIC_SITE_URL=https://실제-사이트-주소
| 이름 | 뜻 | 권장값 |
|---|
OPENAI_API_KEY | OpenAI 비밀 키 | 필수 |
OPENAI_MODEL | 사용할 AI 모델 | gpt-4o-mini (가장 저렴) |
DAILY_REQUEST_LIMIT | 하루 전체 AI 질문 허용 횟수 | 처음에는 300~500 |
RATE_LIMIT_PER_WINDOW | 한 사람이 5분 동안 물을 수 있는 횟수 | 6 |
NEXT_PUBLIC_SITE_URL | 실제 사이트 주소 (검색 노출에 사용) | 배포 후 입력 |
DATABASE_URL | 관리자 페이지용 데이터베이스 (Vercel 마켓플레이스에서 Neon 을 연결하면 자동으로 들어옵니다) | 관리자 페이지를 쓸 때만 |
ADMIN_PASSWORD | 관리자 페이지 비밀번호 (8자 이상) | 관리자 페이지를 쓸 때만 |
관리자 페이지(/admin)를 쓰려면 DATABASE_URL 과 ADMIN_PASSWORD 가 필요합니다. 자세한 설정 방법은
docs/관리자-페이지-설정.md 에 있습니다. 두 값이 없으면 사이트는 예전처럼
문의 메일 주소를 보여주고, 그 밖의 기능은 모두 그대로 동작합니다.
⚠️ .env.local 파일은 절대로 다른 사람에게 보내거나 GitHub에 올리지 마세요.
이 프로젝트는 이미 .gitignore 설정으로 자동 제외되도록 되어 있습니다.
키가 유출된 것 같으면 OpenAI 사이트에서 그 키를 삭제(Revoke)하고 새로 만드세요.
5. 콘텐츠 수정 방법 (가장 자주 하는 일)
모든 글은 content 폴더 안에 있습니다. 코드를 건드릴 필요가 없습니다.
| 바꾸고 싶은 것 | 열어야 할 파일 |
|---|
| 문의 이메일, 사이트 소개 문구, 예시 질문 | content/site.json |
| 소개 페이지 전체 글 | content/about.json |
| 프로그램·활동 카드 | content/programs.json |
| 자주 묻는 질문 | content/faq.json |
| 기관 목록 (전화번호 등) | content/organizations.json |
| 긴급상황 안내문과 감지 키워드 | content/emergency.json |
| 분야(카테고리) 이름 | content/categories.json |
| 권리정보 글 | content/rights/파일이름.json |
| 버튼·메뉴 같은 짧은 화면 문구 | messages/ko.json (영어는 en.json, 중국어 zh.json, 베트남어 vi.json) |
수정할 때 지켜야 할 3가지 규칙
- 따옴표
" 를 지우지 마세요. 글자는 항상 " 와 " 사이에 있어야 합니다.
- 줄 끝의 쉼표
, 를 지우지 마세요. 단, 목록의 마지막 줄에는 쉼표가 없어야 합니다.
- 글 안에 큰따옴표를 쓰고 싶으면
\" 처럼 앞에 \ 를 붙이세요.
수정한 뒤에는 반드시 npm run check 로 확인하세요.
예시: 문의 이메일 바꾸기
content/site.json 을 열고
"contactEmail": "[email protected]",
이 줄의 이메일만 바꾸면 사이트 아래쪽과 개인정보 페이지의 이메일이 한꺼번에 바뀝니다.
6. 권리정보 새로 추가하기
content/rights 폴더 안의 기존 파일(예: labor-unpaid-wages.json)을 복사합니다.- 파일 이름을 새 이름으로 바꿉니다. 예:
labor-overtime.json
- 영어 소문자와
- 만 사용하세요. 한글·띄어쓰기는 안 됩니다.
- 이 파일 이름이 인터넷 주소가 됩니다.
- 파일을 열어 아래 항목을 채웁니다.
{
"id": "labor-overtime", // 파일 이름과 반드시 똑같이!
"category": "labor", // categories.json 에 있는 분야 id
"status": "published", // published = 공개 / draft = 숨김
"featured": false, // true 면 홈 화면에 먼저 보입니다
"owner": "운영팀", // 이 글을 책임지는 사람
"reviewed_at": "2026-10-01", // 내용을 확인한 날짜
"keywords": ["야근", "연장근로", "overtime"], // 검색·AI 매칭에 쓰입니다
"organizations": ["moel-1350"], // organizations.json 에 있는 기관 id 만!
"related": ["labor-contract"], // 함께 보면 좋은 다른 글의 id
"sources": [
{ "title": "고용노동부", "url": "https://www.moel.go.kr", "publisher": "고용노동부" }
],
"i18n": {
"ko": {
"title": "제목",
"summary": "한두 문장 요약",
"situations": ["이런 상황인가요? 1", "이런 상황인가요? 2"],
"rights": [{ "title": "권리 제목", "body": "쉬운 설명" }],
"actions": [{ "title": "행동 제목", "body": "구체적으로 무엇을 하면 되는지" }],
"note": "확인이 필요한 부분 (없으면 이 줄을 지우세요)"
}
}
}
- 저장하고
npm run check 실행 → ✅ 가 나오면 완료입니다.
- 메뉴, 목록, 사이트맵(검색엔진용 목록)에 자동으로 추가됩니다. 다른 파일은 손대지 않아도 됩니다.
다른 언어 번역을 추가하려면
"i18n" 안에 "ko" 와 같은 모양으로 "en", "zh", "vi" 를 추가하면 됩니다.
번역이 없어도 괜찮습니다. 그 언어로 볼 때 한국어 원문과 함께
"이 내용은 아직 이 언어로 번역되지 않았습니다" 안내가 자동으로 표시됩니다.
7. 기관 정보 수정하기
content/organizations.json 을 엽니다. 기관 하나는 아래와 같이 생겼습니다.
{
"id": "moel-1350",
"category": "public", // emergency / public / youth / migrant / legal 중 하나
"emergency": false, // true 면 긴급 연락처로 강조됩니다
"name": { "ko": "...", "en": "...", "zh": "...", "vi": "..." },
"description": { "ko": "...", "en": "...", "zh": "...", "vi": "..." },
"phone": "1350",
"website": "https://www.moel.go.kr",
"languages": ["ko", "en", "zh", "vi"],
"region": "전국",
"hours": { "ko": "평일 09:00~18:00" },
"status": "published", // draft 로 바꾸면 사이트에서 사라집니다
"owner": "운영팀",
"reviewed_at": "2026-09-06",
"source_url": "https://www.moel.go.kr"
}
🔒 여기에 없는 기관·전화번호는 사이트 어디에도 나오지 않습니다.
AI 답변에 등록되지 않은 번호가 섞여 있으면 서버가 자동으로 지웁니다.
반대로 말하면, 여기에 잘못된 번호를 적으면 그대로 노출됩니다. 등록 전에 꼭 공식 홈페이지에서 확인하세요.
기관을 지우고 싶다면 삭제하지 말고 "status": "draft" 로 바꾸세요.
그 기관을 참조하던 권리정보가 오류를 내지 않게 됩니다.
긴급 기관의 공식 사이트 (report_url, 선택)
긴급 도움 페이지에서 휴대폰은 전화 버튼(tel:)을, PC에서는 공식 사이트 링크를 함께 보여줍니다.
신고·안내 전용 공식 페이지가 있다면 "report_url": "https://..." 로 적으세요. 비워 두면 website 를 쓰고, 둘 다 없으면 전화 버튼만 보입니다.
공식 기관 누리집에서 직접 확인한 주소만 적고, 추측한 주소나 검색 결과 주소는 적지 마세요.
8. 이미지 넣고 바꾸기
- 사진을
public/images 폴더에 넣습니다. (파일 이름은 영어 소문자로, 예: mentoring-2026.jpg)
content/programs.json 에서 해당 항목의 "image" 값에 파일 이름을 적습니다.
"image": "mentoring-2026.jpg"
- 사진이 없으면
"image": "" 로 두세요. 빈 자리에 색 배경이 자동으로 들어갑니다.
사진 가이드
- 가로가 긴 사진(가로:세로 = 3:2 정도)이 가장 잘 보입니다.
- 용량은 한 장에 500KB 이하를 권장합니다. (너무 크면 휴대폰에서 느려집니다)
- 청소년의 적극적이고 주체적인 모습(활동·발표·배움)을 담아주세요.
- 얼굴이 나오는 사진은 반드시 본인과 보호자의 동의를 받은 뒤 사용하세요.
9. 인터넷에 배포하기
아래 과정은 처음 한 번만 설정하면, 이후에는 파일을 올릴 때마다 사이트가 자동으로 갱신됩니다.
(1) GitHub에 프로젝트 올리기
- https://github.com 에서 계정을 만듭니다.
- New repository → 이름을
linkrights 로 만들고 Private(비공개)로 만듭니다.
- 화면에 나오는 안내대로 이 폴더를 올립니다. (GitHub Desktop 프로그램을 쓰면 클릭만으로 가능합니다)
(2) Vercel에 연결하기
- https://vercel.com 에 GitHub 계정으로 로그인합니다.
- Add New → Project → 방금 만든
linkrights 저장소를 선택합니다.
- Environment Variables(환경변수) 칸에 아래를 하나씩 입력합니다.
OPENAI_API_KEY → 발급받은 키OPENAI_MODEL → gpt-4o-miniDAILY_REQUEST_LIMIT → 500NEXT_PUBLIC_SITE_URL → Vercel이 알려준 주소 (예: https://linkrights.vercel.app)
- Deploy 를 누릅니다. 2~3분 뒤 사이트 주소가 나옵니다.
(3) 이후 수정하는 방법
파일을 고쳐서 GitHub에 올리면(= commit & push) Vercel이 자동으로 사이트를 새로 만듭니다.
GitHub 웹사이트에서 파일을 직접 열어 연필 아이콘을 눌러 고치는 것도 가능합니다.
(4) 도메인 연결 (선택)
직접 구매한 주소(예: linkrights.org)가 있다면 Vercel → Settings → Domains 에서 연결할 수 있습니다.
연결한 뒤에는 NEXT_PUBLIC_SITE_URL 값도 그 주소로 바꿔주세요.
계정 소유자를 정해두세요. GitHub·Vercel·OpenAI 계정은 프로젝트가 끝난 뒤에도
사이트를 유지할 사람(또는 단체 공용 계정)의 이름으로 만드는 것을 권장합니다.
10. AI 비용 관리와 모니터링
비용을 줄이기 위해 이미 적용된 것
- 일반적인 정보 탐색은 AI 없이 정적 페이지로 제공합니다. (비용 0원)
- 긴급 키워드가 감지되면 AI를 호출하지 않고 검토된 안내만 보여줍니다. (비용 0원)
- 질문 길이를 500자로 제한합니다.
- 질문과 가장 관련 있는 권리정보 4건만 AI에게 전달합니다.
- 답변 길이를 제한하고, 정해진 형식(JSON)으로만 받습니다.
- 한 사람이 5분에 6번, 하루 전체 500번까지만 물을 수 있습니다.
예산 기준 (프로젝트 기준: OpenAI 월 최대 약 100만 원)
| 단계 | 기준 | 해야 할 일 |
|---|
| 🟢 정상 | 월 사용액 30만 원 미만 | 그대로 운영 |
| 🟡 주의 | 월 사용액 50만 원 도달 | DAILY_REQUEST_LIMIT 을 300 이하로 낮춤 |
| 🟠 경고 | 월 사용액 70만 원 도달 | 더 저렴한 모델로 변경, 홍보 일정 조정 |
| 🔴 정지 | 월 사용액 90만 원 도달 | OpenAI 하드 리밋으로 자동 정지 (아래 설정) |
반드시 해두어야 할 설정
- OpenAI → Settings → Limits 에서
- Hard limit(하드 리밋)을 설정하세요. 이 금액을 넘으면 API가 자동으로 멈춥니다.
- Soft limit(알림 기준)을 그보다 낮게 설정해 이메일 알림을 받으세요.
- 매주 월요일 OpenAI → Usage 화면에서 사용액을 확인하고 기록하세요.
- Vercel → Analytics 에서 방문자 수와
/api/ask 호출 수를 함께 확인하면 원인을 알기 쉽습니다.
💡 서버가 여러 대로 나뉘어 실행되는 환경에서는 사이트 안의 하루 제한이 대략적인 상한으로 동작합니다.
그래서 OpenAI 쪽 하드 리밋 설정이 가장 확실한 안전장치입니다. 반드시 설정해 주세요.
11. 안전 규칙 — 반드시 지켜주세요
이 사이트는 청소년이 법률·의료·체류 정보를 찾는 곳입니다. 아래는 선택이 아니라 필수입니다.
- 기관 정보는 반드시 공식 홈페이지에서 확인한 뒤 등록하세요.
전화번호·운영시간은 바뀝니다. 최소 6개월에 한 번 다시 확인하고
reviewed_at 날짜를 갱신하세요.
- AI가 만든 문장을 그대로 권리정보 페이지에 붙여넣지 마세요.
권리정보는 공식 자료를 근거로 사람이 작성하고 검토한 뒤 올립니다.
- 최저임금처럼 매년 바뀌는 숫자는 1월에 반드시 갱신하세요.
(
content/rights/labor-minimum-wage.json)
- 개인정보를 받지 마세요. 이 사이트에는 회원가입도, 개인정보를 저장하는 곳도 없습니다.
문의는 이메일로만 받고, 상담이 필요한 사람은 등록된 공식 상담기관으로 안내하세요.
- 긴급 연락처를 임의로 바꾸지 마세요.
content/emergency.json 수정은 담당자 확인 후에만 하세요.
- 1년 이상 검토되지 않은 정보는 화면에 "검토가 필요한 정보입니다" 라고 표시되고,
AI가 근거로 사용하지 않습니다. 이 표시가 보이면 내용을 다시 확인해 주세요.
- 공개 전에는
docs/데이터-검증-체크리스트.md 를 처음부터 끝까지 확인하세요.
12. 자주 생기는 문제 해결
| 증상 | 원인과 해결 방법 |
|---|
npm 명령이 없다고 나옴 | Node.js가 설치되지 않았습니다. 2번 참고. |
npm run check 에서 ❌ JSON 형식 오류 | 쉼표나 따옴표가 빠졌습니다. 오류 메시지에 적힌 파일 이름을 열어 그 부분만 고치세요. |
등록되지 않은 기관 id 오류 | 권리정보의 organizations 에 적은 id가 organizations.json 에 없습니다. 철자를 확인하세요. |
| 사이트는 뜨는데 AI가 답을 못 함 | .env.local 의 OPENAI_API_KEY 가 없거나 틀렸습니다. 또는 OpenAI 잔액이 부족합니다. |
| "오늘 사용할 수 있는 AI 질문 수를 모두 사용했습니다" | 하루 한도에 도달했습니다. DAILY_REQUEST_LIMIT 값을 조정하거나 다음 날 다시 시도하세요. |
| 글을 고쳤는데 사이트에 안 보임 | "status" 가 draft 로 되어 있는지 확인하세요. 배포 사이트라면 GitHub에 올렸는지 확인하세요. |
| 화면이 이상하게 깨져 보임 | npm install 을 다시 실행한 뒤 npm run dev 를 다시 시작해 보세요. |
13. 폴더 구조
linkrights/
├─ content/ ← 📝 글과 데이터 (여기만 고치면 됩니다)
│ ├─ site.json 사이트 기본 정보, 문의 이메일
│ ├─ categories.json 분야(일·알바, 학교 등)
│ ├─ organizations.json 기관 목록 (전화번호·홈페이지)
│ ├─ emergency.json 긴급 안내문과 감지 키워드
│ ├─ about.json 소개 페이지 글
│ ├─ programs.json 프로그램·활동 카드
│ ├─ faq.json 자주 묻는 질문
│ └─ rights/ 권리정보 글 (파일 1개 = 페이지 1개)
│
├─ messages/ ← 🌐 버튼·메뉴 같은 짧은 문구 (ko / en / zh / vi)
├─ public/images/ ← 🖼️ 사진 파일
├─ docs/ ← 📚 설계 문서와 운영 체크리스트
├─ scripts/check-content.mjs ← 🔍 콘텐츠 점검 프로그램
│
└─ src/ ← ⚙️ 화면을 그리는 코드 (평소에는 건드리지 않습니다)
├─ app/ 페이지 (주소 하나 = 폴더 하나)
│ ├─ [locale]/ 언어별 페이지
│ └─ api/ask/ AI 질문을 처리하는 서버 코드
├─ components/ 반복해서 쓰는 화면 부품
└─ lib/ 데이터 읽기, 검색, AI 연결 등
문의
이 사이트에 대한 문의는 content/site.json 의 contactEmail 에 적힌 주소로 받습니다.
정보 오류를 발견하면 알려주세요. 확인 후 수정하고 검토일을 갱신합니다.
