mirror of https://github.com/NomaDamas/k-skill.git synced 2026-09-14 16:37:18 +08:00

Files

T

Jeffrey (Dongkyu) Kim d62e177a1b Prevent broken Seoul subway proxy defaults before hosted rollout

The Seoul subway proxy endpoint code is present locally, but the hosted public route is not live yet. This change turns the user-facing subway docs back into an explicit proxy configuration flow, replaces the misleading hosted default in setup examples, and keeps subway proxy examples on self-host/local URLs until rollout is verified.

Constraint: Hosted k-skill-proxy.nomadamas.org/v1/seoul-subway/arrival is not live yet
Rejected: Keep the hosted Seoul subway URL as the default path | would send default users to a 404 route
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Do not restore a hosted Seoul subway default until the public proxy route is deployed and smoke-verified
Tested: node --test scripts/skill-docs.test.js; npm run ci; local proxy smoke on 127.0.0.1:4120 with stubbed Seoul upstream (GET /health, GET /v1/seoul-subway/arrival?stationName=강남)
Not-tested: Live hosted proxy smoke after deployment

2026-03-31 11:18:00 +09:00

2.4 KiB

Raw Permalink Blame History

k-skill 프록시 서버 가이드

이 기능으로 할 수 있는 일

AirKorea 같은 무료/공공 API key를 서버에만 보관
k-skill 클라이언트는 프록시만 호출
캐시, 인증, rate limit, 로깅을 한곳에서 통제

기본 구조

client/skill -> k-skill-proxy -> upstream public API

현재 기본 엔드포인트는 아래 둘입니다.

GET /health
GET /v1/fine-dust/report
GET /v1/seoul-subway/arrival
GET /B552584/:service/:operation (허용된 AirKorea route passthrough)

권장 환경변수

클라이언트(스킬) 쪽:

KSKILL_PROXY_BASE_URL=https://your-proxy.example.com

프록시 서버 쪽:

AIR_KOREA_OPEN_API_KEY=...
SEOUL_OPEN_API_KEY=...
KSKILL_PROXY_PORT=4020

PM2 + cloudflared

pm2 start ecosystem.config.cjs
pm2 save
pm2 startup 출력대로 launchd 등록
Cloudflare Tunnel ingress 에 k-skill-proxy.nomadamas.org -> http://localhost:4020 추가

기본 공개 정책

이 프록시는 무료 API만 붙인다.
기본값은 무인증 공개 endpoint 다.
대신 read-only / allowlisted endpoint / cache / rate limit 을 유지한다.
문제가 생기면 그때 인증이나 더 강한 방어를 덧붙인다.

사용법

추가 client API 레이어는 불필요합니다. 필요한 쿼리를 그대로 프록시에 넣으면 되고, 프록시가 upstream API key 만 서버에서 주입합니다.

요약 endpoint:

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/fine-dust/report' \
  --data-urlencode 'regionHint=서울 강남구'

서울 지하철 도착정보 endpoint:

curl -fsS --get 'http://127.0.0.1:4020/v1/seoul-subway/arrival' \
  --data-urlencode 'stationName=강남'

AirKorea passthrough endpoint:

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/B552584/ArpltnInforInqireSvc/getMsrstnAcctoRltmMesureDnsty' \
  --data-urlencode 'returnType=json' \
  --data-urlencode 'numOfRows=1' \
  --data-urlencode 'pageNo=1' \
  --data-urlencode 'stationName=강남구' \
  --data-urlencode 'dataTerm=DAILY' \
  --data-urlencode 'ver=1.4'

주의할 점

upstream key는 프록시 서버에서만 관리합니다.
client 쪽에는 upstream API key를 배포하지 않습니다.
public hosted route rollout 이 끝나기 전에는 서울 지하철 예시를 local/self-host URL 로 검증합니다.

2.4 KiB Raw Permalink Blame History