RIDM Apps 배포 가이드
RIDM Apps는 깃흐름으로 코드를 올리면 빌드·배포하고 <이름>.ridm.ai 로 공개하는 호스팅이에요(깃허브도 사용가능). 신청은 콘솔의 내 앱에서, 요금은 요금 페이지에서 확인하세요. 이용 조건은 이용약관 제3장이 정해요. 무엇이 들어 있는지 한눈에 보려면 앱 호스팅 소개를 보세요.
깃흐름 — 코드 보관·배포 (깃허브도 사용가능)
깃흐름은 흐름이 앱마다 코드 보관함(git 저장소)을 하나씩 주는 기능이에요. GitHub 계정이 없어도 돼요. 컴퓨터에 깃흐름 프로그램(명령어 hrum)을 깔고 hrum save로 저장, hrum push로 올리면 빌드되고 <이름>.ridm.ai에 공개돼요. 빌드·검사·첫 배포 규칙은 GitHub로 올릴 때와 같아요.
- 저장은 지금 바뀐 파일을 한 번에 기록해 두는 거예요. 언제든 그 시점으로 되돌릴 수 있어요.
- 올리기는 저장한 것을 흐름에 보내는 거예요.
main에 올리면 배포가 시작돼요. - 앱 하나는 깃흐름과 GitHub 중 하나만 써요. 앱 화면에서 「깃허브 연결 없이 시작하기」를 고르면 깃흐름이에요.
- 만든 폴더는 보통 git 폴더예요. git을 아는 사람이나 VS Code·Cursor의 git 기능도 같은 주소로 그대로 써요.
- Dockerfile 필요 (hrum init이 기본 파일을 만들어 줘요) — 빌드는 저장소 루트의
Dockerfile로 해요. 없으면hrum init이public/폴더를 그대로 서비스하는 정적 사이트 Dockerfile을 넣고, 빈 폴더라면public/index.html도 만들어요. 이미 있는Dockerfile은 건드리지 않아요.package.json이 있는 프로젝트는 기본 파일을 넣지 않으니 Dockerfile 요구사항대로 직접 넣어요. - 큰 파일은 나눠서 push — 한 번에 올리는 양은 100MB까지예요. 업로드가 느리면 중간 연결(Cloudflare)에서 그보다 먼저 끊길 수 있어요. 큰 이미지·모델은 여러 번에 나눠 저장하고 올리거나, 큰 바이너리는 git에 넣지 말고 빌드할 때 내려받게 해요.
프로그램 내려받기와 짧은 설명은 깃흐름 프로그램 페이지에도 있어요.
설치
따로 깔 것은 없어요(Node.js 없이 도는 실행 파일이에요). 설치 스크립트는 내려받은 파일의 SHA-256이 맞을 때만 설치해요.
| 컴퓨터 | 터미널에 붙여 넣을 줄 | 설치되는 곳 |
|---|---|---|
| macOS · Linux | curl -fsSL https://console.hrum.ai/git/install.sh | sh | ~/.local/bin/hrum |
| Windows (PowerShell) | irm https://console.hrum.ai/git/install.ps1 | iex | %LOCALAPPDATA%\Programs\HRUM\bin (사용자 PATH에 추가돼요) |
| 설치 없이 (Node만) | npx -y <npx 주소> <명령> | 설치하지 않아요. 지금 버전의 npx 주소는 latest.json에 있어요 |
설치가 끝나면 새 터미널을 열고 hrum help로 확인해요. 메시지는 컴퓨터 언어에 맞춰 한국어나 영어로 나와요. hrum config lang ko로 바꾸거나 명령마다 --lang en을 붙여요. 새 버전은 hrum update로 확인해요.
로그인 (hrum login)
- 프로젝트 폴더에서
hrum login <앱이름>을 실행해요. 터미널에XXXX-XXXX모양의 코드가 나오고, 브라우저에 콘솔 승인 화면이 열려요. - 콘솔에 로그인한 채로 터미널의 코드를 직접 입력하고 「확인」을 눌러요.
- 요청 시각·기기 이름·앱을 보고, 방금 내가 실행한 게 맞으면 「허용」을 눌러요. 누가 보내 준 코드나 링크라면 「거절」을 눌러요.
허용하면 이 컴퓨터에 그 앱 전용 토큰이 저장돼요(macOS 키체인, Windows 자격 증명 관리자, Linux libsecret, 없으면 나만 읽을 수 있는 파일). 토큰은 화면이나 로그에 나오지 않아요. 브라우저를 쓸 수 없는 컴퓨터는 아래 기기와 토큰을 보세요.
명령
괄호 안 한국어 이름도 같은 명령이에요. 모든 명령에 --json, --lang ko|en, --app <앱이름>을 붙일 수 있어요.
| 명령 | 하는 일 |
|---|---|
hrum init [앱] (새프로젝트) | 이 폴더를 앱 저장소에 연결해요. .gitignore·.gitattributes·AGENTS.md 안내 블록을 넣고, Dockerfile이 없으면 기본 파일을 넣어요. 앱에 이미 코드가 있으면 내려받아요 |
hrum clone <앱> (가져오기) | 다른 컴퓨터에서 앱 코드를 새 폴더로 받아요 |
hrum save "메모" (저장) | 바뀐 파일을 한 번에 저장해요. 환경 파일이나 비밀값 모양이 보이면 저장하지 않아요 |
hrum push (올리기) | 흐름에 올리고 배포가 끝날 때까지 진행을 보여 줘요. 기다리지 않으려면 --no-wait |
hrum pull (받기) | 다른 컴퓨터나 AI가 올린 것을 받아요. 같은 곳을 양쪽에서 고쳤으면 두 내용을 다 남기고 알려 줘요 |
hrum deploy (배포) | main의 최신 저장을 다시 배포해요. 콘솔의 「지금 배포」와 같아요 |
hrum status (상태) · hrum history (이력) | 안 올린 변경, 저장 목록, 각 저장의 배포 결과 |
hrum logs (로그) | 돌고 있는 앱이 찍은 기록 |
hrum undo (되돌리기) | 서비스를 바로 전에 잘 돌던 버전으로 돌려요. 코드는 그대로예요 |
hrum restore <번호> (복원) | 코드를 그 저장 시점 내용으로 되살려 새 저장으로 남겨요. 이력은 지우지 않아요. 그다음 hrum push |
hrum url (주소) | 앱 주소와 저장소 주소 |
저장·올리기·받기·배포·로그·되돌리기는 hrum login만으로 돼요(배포·되돌리기는 읽기·쓰기 기기만, 로그는 읽기 전용 기기도 돼요). hrum devices만 콘솔 계정 로그인이 필요해요. hrum login --email <내 이메일>으로 한 번 로그인하거나, 콘솔 앱 화면에서 해요.
AI 도구로 쓰기
Claude Code·Cursor·Codex 같은 AI 도구에 아래 한 줄을 붙여 넣으면 연결부터 배포까지 해요. <앱이름>만 바꿔요.
이 폴더를 흐름 앱 <앱이름>에 연결하고 배포해 줘: hrum login <앱이름> (브라우저가 열리면 터미널의 코드를 내가 입력하고 「허용」을 누를게) 후 hrum init <앱이름>, 그다음 hrum save · hrum push --json
hrum init이 프로젝트의AGENTS.md에<!-- hrum:start -->…<!-- hrum:end -->안내 블록을 넣어요. AI 도구는 이 파일을 읽고 저장은hrum save, 배포는hrum push --json으로 해요.--json을 붙이면 한 줄 JSON{"ok", "code", "message", "data"}로 답해요.hrum push --json은 기다리는 동안 진행을 JSON Lines로 내보내고, 마지막 줄이 결과예요.- 배포가 실패하면 결과의
failMessage(고치는 법 링크failHelpUrl)·failReason·logTail을 보고 고친 뒤 다시 저장하고 올려요. - 종료 코드:
0성공,1고칠 수 있는 문제,2서버·네트워크,3로그인 필요. --json이거나 터미널이 아니면 묻지 않고 오류 코드로 끝내요. AI가 멈춰서 기다리지 않아요.- HRUM MCP에도
hrum_git_connect(이 폴더를 앱에 연결)·hrum_git_status도구가 있어요. 저장·올리기는 AI가hrum명령을 불러서 해요.
기기와 토큰
- 컴퓨터 한 대에 토큰 하나예요. 앱 하나에 10대까지 연결돼요. 한 대를 끊어도 나머지는 그대로예요.
hrum login으로 받은 토큰은 30일 동안 쓸 수 있고, 쓸 때마다 연장돼요.- 콘솔 앱 화면 「새 토큰 만들기」로 만든 토큰은 90일 동안 쓸 수 있어요. 값은 한 번만 보여요. 브라우저가 없는 컴퓨터에서는
hrum token add <앱이름>을 실행하고 그 값을 붙여 넣어요. - 끊기: 콘솔 앱 화면 「연결된 기기」의 「끊기」, 또는
hrum devices revoke <이름>. 이 컴퓨터의 토큰을 모두 지우려면hrum logout. - 프로그램 없이 git만 쓸 때: 저장소 주소는
https://git.hrum.ai/<앱이름>.git이에요. 사용자 이름은 아무거나, 비밀번호 칸에 토큰을 넣으면 git이 기억해요.hrum init으로 만든 폴더는 비밀번호를 묻지 않아요.
GitHub와 오가기
- GitHub에서 깃흐름으로: GitHub를 연결한 앱 화면에서 「깃흐름으로 옮기기」를 눌러요. 연결된 브랜치의 이력이 한 번 복사되고 GitHub 연결은 풀려요. 그다음부터는
hrum push로 올려요. - 깃흐름에서 GitHub로: 깃흐름 앱 화면에서 「깃허브로 옮기기」를 눌러 GitHub 저장소를 연결해요. 깃흐름 저장소는 30일 동안 받기만 되고, 그 뒤 지워져요. 그 안에
hrum pull이나git clone으로 받아 두세요. - 옮기는 동안에도 지금 서비스 중인 버전은 그대로 돌아요.
깃흐름 한도
앱 하나 기준이에요. 플랜을 바꾸면 다음 올리기부터 새 한도가 적용돼요. 하루 횟수는 한국 시간 0시에 새로 세요.
| 한도 | 무료 | 베이직 | 프로 |
|---|---|---|---|
| 저장소 전체 | 500MB | 2GB | 5GB |
| 한 번에 올리는 양 | 100MB | 100MB | 100MB |
| 파일 하나 | 50MB | 100MB | 100MB |
| 하루 올리기 횟수 | 50번 | 300번 | 1,000번 |
저장소가 가득 차도 받기(hrum pull, git clone)는 돼요. 강제 올리기(force push)와 main 지우기는 막혀 있어요. main이 아닌 가지에 올리면 저장만 되고 배포되지 않아요.
깃흐름 오류
오류 코드는 언어와 상관없이 같아요. --json 결과의 code, 또는 git이 보여 주는 remote: [HRUM_E_…] 줄에서 봐요.
| 코드 | 뜻 | 할 일 |
|---|---|---|
HRUM_E_NOT_LOGGED_IN | 로그인이 필요해요 | hrum login |
HRUM_E_NO_TOKEN | 이 컴퓨터가 그 앱에 연결되지 않았어요 | hrum login <앱이름> |
HRUM_E_TOKEN_REVOKED · HRUM_E_TOKEN_EXPIRED | 연결이 끊겼거나 만료됐어요 | hrum login으로 다시 연결 |
HRUM_E_LOGIN_DENIED · HRUM_E_LOGIN_EXPIRED | 「거절」을 눌렀거나 10분이 지났어요 | hrum login 다시 |
HRUM_E_APP_NOT_FOUND | 그 이름의 앱이 내 계정에 없어요 | 앱 이름 확인, 콘솔에서 앱 만들기 |
HRUM_E_APP_NOT_HRUM | GitHub에 연결된 앱이에요 | 앱 화면 「깃흐름으로 옮기기」 |
HRUM_E_NOT_A_REPO | 이 폴더가 아직 앱에 연결되지 않았어요 | hrum init <앱이름> |
HRUM_E_UNCOMMITTED | 저장하지 않은 변경이 있어요 | hrum save "메모" 뒤 다시 올리기 |
HRUM_E_BEHIND | 흐름에 이 컴퓨터에 없는 저장이 있어요 | hrum pull 뒤 다시 올리기 |
HRUM_E_CONFLICT | 같은 파일을 양쪽에서 고쳤어요 | 알려 준 파일을 고치고 hrum save |
HRUM_E_SECRET_FOUND · HRUM_E_ENV_FILE | 비밀값이나 환경 파일이 보여요 | 파일에서 빼고 값은 환경변수로 |
HRUM_E_CRLF_DOCKERFILE | Windows 줄바꿈이라 빌드가 실패해요 | hrum save --fix-crlf |
HRUM_E_CASE_COLLISION | 대소문자만 다른 파일 이름이 있어요 | 하나만 남기기 |
HRUM_E_READ_ONLY_TOKEN | 읽기 전용 토큰이에요 | 쓰기 토큰으로 다시 연결 |
HRUM_E_REPO_MOVED | GitHub로 옮긴 앱이라 받기만 돼요 | GitHub에 올리기 |
HRUM_E_APP_NOT_WRITABLE | 앱이 멈췄거나 해지 중이라 올릴 수 없어요 | 받기는 돼요. 콘솔에서 앱 상태 확인 |
HRUM_E_DAILY_LIMIT | 오늘 올리기 횟수를 다 썼어요 | 내일 다시 |
HRUM_E_REPO_FULL · HRUM_E_PUSH_TOO_BIG · HRUM_E_FILE_TOO_BIG | 한도를 넘었어요 | 큰 파일을 빼거나 나눠서 올리기 |
HRUM_E_FORCE_PUSH · HRUM_E_DELETE_DENIED | 강제 올리기·지우기는 막혀 있어요 | hrum pull 뒤 다시 올리기 |
HRUM_E_PUSH_BUSY | 다른 곳에서 올리는 중이에요 | 잠시 뒤 다시 |
HRUM_E_BUILD_FAILED · HRUM_E_START_FAILED | 빌드나 시작이 실패했어요 | 메시지의 이유를 보고 고친 뒤 다시 올리기 |
HRUM_E_DEPLOY_TIMEOUT | 배포가 아직 안 끝났어요 | hrum status로 확인 |
HRUM_E_NETWORK · HRUM_E_RATE_LIMITED | 연결이 안 되거나 요청이 너무 많아요 | 잠시 뒤 다시 |
배포 흐름
- 신청 — 내 앱에서 플랜과 주소(서브도메인)를 골라요. 주소는 나중에 바꿀 수 없어요.
- 코드 연결 — 앱 화면에서 「깃허브 연결 없이 시작하기」를 고르고 깃흐름 프로그램을 깔아
hrum login으로 연결해요. (깃허브도 사용가능: 앱 화면에서 GitHub Appridm-apps-builder를 설치하고 저장소와 브랜치를 골라요. 권한은 저장소 읽기뿐이에요.) - 올리기 —
hrum push로main에 올릴 때마다(깃허브는 연결한 브랜치에 푸시할 때마다) 빌드가 시작돼요. 빌드 기록과 실패 로그는 앱 화면에 표시돼요. - 첫 배포 — 빌드가 성공하면 자동 검사를 거쳐 바로 공개돼요(아래). 그 뒤의 푸시도 자동으로 반영돼요.
Dockerfile 요구사항
- 저장소 루트에
Dockerfile이 있어야 해요. 없으면 빌드가 실패해요. - 앱은 포트 3000에서 HTTP로 응답해야 해요.
PORT=3000,HOSTNAME=0.0.0.0이 강제로 설정돼요. 컨테이너가 시작되고 30초 안에/요청에 응답해야 해요(상태 코드는 상관없음). 그 안에 응답하지 않으면 시작 실패로 처리되고, 새 버전이면 이전 버전이 계속 서비스돼요. - 상태 확인 경로(앱 화면 「상태 확인 경로」, 예:
/api/health)를 정하면/대신 그 경로가 200번대·300번대·404로 답해야 시작 성공이에요(500번대나 그 밖의 400번대면 실패). DB까지 확인하는 경로를 쓰면 포트만 열고 제대로 못 도는 버전은 올라가지 않아요. 비워 두면 위 규칙 그대로예요. - 새 버전이 공개된 뒤 5분 안에 3번 이상 다시 시작되면(프로세스가 계속 죽으면) 이전에 정상으로 돌던 버전으로 한 번 자동으로 되돌리고 메일로 알려 드려요(앱이 마지막으로 남긴 로그 포함). 되돌린 버전도 계속 죽으면 더 되돌리지 않고 그대로 두니 코드를 고쳐 다시 푸시해 주세요.
- 컨테이너는 사용자 1000:1000으로 실행돼요. 앱 파일은 이 사용자가 읽을 수 있어야 해요(
node:*-alpine이미지의node사용자가 1000이에요). - 파일 시스템은 읽기 전용이에요. 쓸 수 있는 곳은
/tmp와/app/.next/cache(둘 다 메모리 기반, 재시작 시 사라짐)뿐이에요. 영구 데이터는 DB에 저장하세요. - 빌드는 x86_64(amd64)로 해요. 빌드 시간 한도는 20분이에요.
- 저장소에 비밀값이 보이면 빌드를 멈춰요: AWS 액세스 키, GitHub 토큰, Stripe 라이브 키, 개인 키 블록, 비밀번호가 들어간 PostgreSQL URL. 비밀값은 환경변수로 넣으세요.
Next.js 스타터
next.config.js에 output: 'standalone'을 넣고 아래 Dockerfile을 저장소 루트에 두세요. public 폴더가 없으면 그 줄은 지워요.
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build --chown=1000:1000 /app/public ./public
COPY --from=build --chown=1000:1000 /app/.next/standalone ./
COPY --from=build --chown=1000:1000 /app/.next/static ./.next/static
USER 1000
EXPOSE 3000
CMD ["node", "server.js"]
Next.js가 아니어도 돼요. 포트 3000에서 응답하는 컨테이너면 어떤 스택이든 동작해요.
실행 환경
- 무료 플랜은 방문이 있을 때 켜지고 15분 동안 요청이 없으면 멈춰요. 멈춘 뒤 첫 방문은 몇 초 늦을 수 있어요. 검색 로봇·모니터링 요청·HEAD 요청은 앱을 깨우지 않아요.
- 유료 플랜은 상시 실행돼요. 앱이 죽으면 자동으로 다시 시작해요.
- 메모리를 넘기면 앱이 강제 종료돼요. Node.js 힙 한도는 플랜 메모리의 75%로 설정돼요.
- WebSocket은 유료 플랜에서 써요(무료 플랜은 업그레이드 요청이
403). 앱은 포트 3000에서 평소처럼Upgrade: websocket을 받으면 돼요(경로·서브프로토콜·Origin·X-Forwarded-For·CF-Connecting-IP가 그대로 전달되고, 앱이 업그레이드 대신 보낸 403·429 같은 응답도 그대로 방문자에게 가요). 한도:- 앱당 동시 연결 120개. 넘으면 새 연결이
503(Retry-After: 10)으로 거절돼요. - 메시지 하나(조각 합계) 64KB. 넘으면 그 연결이
1009로 닫혀요. 압축 확장(permessage-deflate)은 쓰지 않아요. - 메시지 수는 앱당 방향별 초당 2,000개, 방문자 연결 하나가 보내는 건 초당 60개까지예요. 넘으면 버리지 않고 늦춰서 전달해요.
- 프레임 없이 100초가 지나면 중간 구간(Cloudflare)이 연결을 끊어요. 앱이나 클라이언트가 그보다 자주 ping을 보내세요.
- 같은 앱 Origin만 허용: 브라우저 연결은
Origin이 그 앱의 주소(앱이름.ridm.ai또는 그 앱에 연결한 도메인)일 때만 열려요. 다른 앱이나 다른 사이트에서 오는 연결은 같은 파트너의 앱이어도403이에요. 다른 앱끼리 WebSocket으로 직접 붙을 수 없어요. - 브라우저가 아닌 클라이언트(서버·앱·CLI)는
Origin없이 연결할 수 있지만, 그때Cookie는 앱에 전달되지 않아요. 쿠키 대신 토큰을 헤더(Authorization)나 쿼리로 보내 인증하세요. - 연결이 열려 있는 동안 앱은 잠들지 않아요. 새 버전 배포나 플랫폼 재시작 때는 연결이
1001로 닫히니 클라이언트는 다시 연결하게 만들어 두세요.
- 앱당 동시 연결 120개. 넘으면 새 연결이
- 외부로 나가는 HTTPS 요청은 가능해요. 메일 발송 포트(SMTP)와 내부망은 막혀 있어요. 안내 메일은 앱 메일 발송 API에
HRUM_API_KEY로 보내거나, HTTPS API 방식의 메일 서비스를 쓰세요. - 보안을 위해 앱이 밖으로 연결한 곳을 앱별로 기록해요: 연결한 주소·포트, 앱이 조회한 도메인 이름, 처음·마지막으로 본 시각, 연결 횟수예요. 요청·응답 내용과 전체 URL은 기록하지 않아요. 이 기록은 3개월 동안 보관한 뒤 지워요. 침해 사고나 금지 행위(약관 제26조) 조사, 법령에 따른 요청이 있을 때만 열람해요.
- 앱 로그(stdout·stderr)는 장애 대응 때 운영자가 조회할 수 있으며, 호스트를 떠나기 전에 환경변수 값·DB 비밀번호·토큰·이메일 등이 가려져요(약관 제20조).
쿠키
여러 파트너 앱이 ridm.ai 아래에 있으므로, 게이트웨이가 쿠키를 앱 주소에만 묶어요. 앱 코드는 평소처럼 쿠키를 쓰면 돼요. 다만:
- 쿠키는 항상
Secure,Path=/이고Domain속성은 무시돼요. - 쿠키 이름은 57자 이하여야 해요. 더 긴 이름의 쿠키는 버려져요.
- 브라우저 자바스크립트(
document.cookie)로 만든 쿠키는 서버로 전달되지 않아요. 서버가 읽어야 하는 쿠키는 서버 응답의Set-Cookie로 만드세요.
데이터베이스
앱마다 전용 PostgreSQL DB가 만들어지고, 접속 정보가 환경변수로 들어와요: DATABASE_URL(SSL 필수)과 PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD, PGSSLMODE. 용량 한도는 플랜마다 다르며 앱 화면에 사용량이 표시돼요.
DB 연결은 인증서까지 검증하는 TLS예요. 인증서 발급 기관(Amazon RDS)은 컨테이너에 미리 설치되어 있어서(NODE_EXTRA_CA_CERTS·PGSSLROOTCERT) 코드에 SSL 옵션을 따로 넣지 않아도 돼요 — new Pool({ connectionString: process.env.DATABASE_URL, max: 2 })면 돼요. 연결은 앱당 3개까지라 풀 크기는 2 이하로 두세요.
- 연결은 앱당 동시 3개까지, 쿼리 하나는 10초, 트랜잭션 안에서 60초 넘게 쉬면 끊겨요.
- 사용량이 80%를 넘거나 용량을 넘으면 이메일로 알려 드려요.
- 용량을 넘은 상태가 24시간 이어지면(150%를 넘으면 즉시) DB가 읽기 전용이 돼요. 데이터를 지우려면 연결에서
SET default_transaction_read_only = off를 먼저 실행하세요. - 읽기 전용 상태에서 110%를 넘으면 DB 연결을 끊어요. 데이터는 지우지 않으며 백업은 계속 만들 수 있어요.
- 용량의 90% 아래로 줄이거나 더 큰 플랜으로 바꾸면 5분 안에 풀려요.
환경변수
- 앱 화면의 "환경변수"에서 추가·삭제해요. 저장한 값은 암호화되어 보관되고 다시 볼 수 없어요(이름만 표시). 바꾸려면 새 값으로 덮어쓰세요.
- 저장하면 앱이 새 값으로 다시 시작돼요.
- 이름은 대문자·숫자·밑줄만(숫자로 시작 불가, 64자 이하), 값은 한 줄 3,000바이트 이하, 앱당 60개까지, 앱 전체 합계 64KB까지(80%를 넘으면 저장할 때 경고).
- 플랫폼이 쓰는 이름은 설정할 수 없어요:
PORT,HOSTNAME,NODE_OPTIONS,DATABASE_URL,RIDM_·PG로 시작하는 이름. - 플랫폼이 넣어 주는 값:
RIDM_COMMIT(배포한 커밋 전체 SHA),RIDM_COMMIT_SHORT(앞 7자),RIDM_DEPLOYED_AT(그 버전을 배포한 시각, ISO UTC) — 예를 들어/api/health에서 지금 도는 버전을 보여 줄 때 쓰세요. 이전 버전으로 되돌리면 그 버전의 값이 들어가요. HRUM_API_KEY: 콘솔 「API 키」에서 발급한 키를 넣어요. 「AI 연결」을 켠 앱은 플랫폼이 자동으로 넣어서 직접 넣을 수 없고, 직접 넣은 값이 있으면 「AI 연결」을 켜기 전에 지워야 해요. 다른 계정의 키나 앱 전용 키는 넣을 수 없어요.- 해지한 앱은 환경변수를 바꿀 수 없어요.
- 값은 어떤 화면·API로도 다시 읽을 수 없어요. 목록과 API 응답에는 이름만 나와요. 값을 잃어버렸다면 원래 발급처(결제사·외부 서비스 콘솔 등)에서 새로 받아 같은 이름으로 다시 저장하세요.
콘솔에서 비밀키 넣기 (사람)
어떤 이름이든 사람이 콘솔에서 넣을 수 있어요. AI 도구가 넣을 수 없는 이름(아래)도 이 방법으로 넣어요.
- console.hrum.ai에 로그인하고 왼쪽 메뉴의 내 앱을 열어요.
- 앱 카드를 아래로 내려 환경변수 칸을 찾아요. 지금 저장된 이름이 값 대신
••••••••로 보여요. - 첫 칸 이름 (예: STRIPE_SECRET_KEY)에 이름을 적어요. 소문자나 다른 글자는 입력하는 대로 대문자·밑줄로 바뀌어요.
- 둘째 칸 값에 값을 붙여 넣어요. 입력란은 비밀번호처럼 가려져요.
- 저장을 누르면 「환경변수를 저장했어요: 이름. 앱이 곧 다시 시작돼요.」가 나와요. 같은 이름으로 다시 저장하면 값이 바뀌어요.
- 지울 때는 그 줄의 삭제 → 확인 창의 삭제를 눌러요. 지우면 앱이 다시 시작되고 값은 되살릴 수 없어요.
값을 옮기는 동안 지킬 것:
- 값은 비밀번호 관리자나 macOS 키체인 접근에서 복사해 바로 붙여 넣어요. 메모장·채팅·메일·문서에 한 번 적었다 옮기지 마세요.
- 붙여 넣은 뒤에는 클립보드를 비워요(macOS 터미널:
pbcopy < /dev/null, 또는 아무 글자나 한 번 복사). - 브라우저가 값을 비밀번호로 저장하겠냐고 물으면 거절해요.
- 화면 공유·녹화 중에는 넣지 마세요.
AI로 비밀키 넣기 (AI 운영 토큰)
AI 코딩 도구가 사람 대신 환경변수를 넣으려면 AI 운영 토큰이 있어야 해요. 콘솔 관리 토큰(hrum_cm_…, AI로 콘솔 관리하기)을 발급할 때 사람이 hosting_ops 권한을 체크한 토큰이에요. 이 권한이 있으면 작업마다 동의를 다시 받지 않아요. 환경변수 넣기는 값이 AI 모델을 거치지 않도록 HRUM MCP에 두지 않았으니 아래 HTTP 경로를 써요.
AI 경로로 넣을 수 있는 이름은 _KEY·_SECRET·_TOKEN·_PASSWORD·_PASSWD·_PASS·_SALT·_CLIENT_ID로 끝나는 이름뿐이에요(예: STRIPE_SECRET_KEY, MASTER_KEY). 그중에서도 실행 환경이나 접속 주소를 바꾸는 이름은 거절돼요: _URL·_URI·_ENDPOINT·_HOST·_PROXY로 끝나는 이름, NODE_·LD_·DYLD_·PYTHON·JAVA_·_JAVA_·JDK_·RUBY·PERL·GIT_·NPM_CONFIG_·GLOBAL_AGENT_·AWS_ENDPOINT_URL로 시작하는 이름, 그리고 HTTP_PROXY·HTTPS_PROXY·NODE_TLS_REJECT_UNAUTHORIZED·SSL_CERT_FILE·PATH·OPENAI_API_BASE 같은 이름. 다른 이름(예: ADMIN_PATH, SMTP_HOST)은 사람이 콘솔에서 넣어요. 지우기는 AI 경로로도 할 수 있어요(예약 이름 제외).
토큰 받기 — 30일 동안 써요.
- AI가 인증 없이
POST https://api.hrum.ai/api/v1/partners/v1/console-ai/consents에{"action":"token_issue","payload":{"scopes":["hosting_ops"],"label":"내 앱 운영"}}을 보내요. 응답data에consentUrl·userCode(8자리)·code·pollSecret이 와요. - AI는 사용자에게
consentUrl과 8자리 코드만 보여 줘요.pollSecret은 보여 주지 않아요. - 사람이 콘솔에 로그인한 브라우저로 링크를 열고(10분 안에), 확인 코드 칸에 AI 도구 화면의 8자리 코드를 넣고,
hosting_ops를 체크한 뒤 동의를 눌러요. 체크 아래 경고(새면 환경변수 덮어쓰기·배포·재시작이 가능하다는 내용)를 읽고 눌러요. - AI가
GET …/console-ai/consents/{code}를 헤더X-Consent-Poll-Secret과 함께 부르면, 승인 뒤 첫 응답의data.token.value로 토큰을 딱 한 번 받아요. 화면에 찍지 말고 바로 비밀 저장소(키체인, 권한 600 파일 등)에 넣어요. - 필요 없어지면 콘솔 API 키 화면의 「AI 콘솔 관리 토큰」에서 취소를 눌러요. 그 즉시 막혀요. 계정당 살아 있는 토큰은 10개까지예요.
호출 — 기본 주소 https://api.hrum.ai, 헤더 Authorization: Bearer hrum_cm_…. 앱 id는 GET /api/v1/partners/v1/console-ai/hosting 응답의 data.apps[].id(UUID)예요.
| 할 일 | 요청 | 응답 |
|---|---|---|
| 이름 목록 | GET /api/v1/partners/v1/console-ai/hosting/apps/{appId}/env | {"success":true,"data":{"env":{"names":[…]}}} — 값 없음 |
| 넣기·바꾸기 | PUT …/hosting/apps/{appId}/env/{NAME} 본문 {"value":"…"} | 바뀐 이름 목록. 앱이 다시 시작돼요 |
| 지우기 | DELETE …/hosting/apps/{appId}/env/{NAME} | 바뀐 이름 목록. 앱이 다시 시작돼요 |
예시(bash·zsh). 값과 토큰을 명령줄 인자로 넘기지 않고, 값은 표준 입력으로 보내요. $APP_ID, 키체인 항목 이름은 자기 것으로 바꿔요.
# 1) Read secrets into shell variables (nothing is printed)
HRUM_CM_TOKEN=$(security find-generic-password -s hrum-console-ops -w)
VALUE=$(security find-generic-password -s myapp-STRIPE_SECRET_KEY -w)
# 2) Value goes through stdin, token through a header file: neither shows up in ps or shell history
printf '%s' "$VALUE" | jq -Rs '{value: .}' | curl -s -X PUT \
-H @<(printf 'Authorization: Bearer %s' "$HRUM_CM_TOKEN") \
-H 'Content-Type: application/json' --data-binary @- \
"https://api.hrum.ai/api/v1/partners/v1/console-ai/hosting/apps/$APP_ID/env/STRIPE_SECRET_KEY" \
| jq '.data.env.names // .'
# 3) Forget the value
unset VALUE
저장이 끝나면 응답에 이름 목록만 나와요. 앱이 새 값으로 다시 시작됐는지는 앱 주소를 열어 확인해요.
AI로 배포하고 로그 보기 (AI 운영 토큰)
같은 AI 운영 토큰(hosting_ops)으로 배포를 시작하고, 배포 상태와 앱이 찍는 로그를 볼 수 있어요. 사이트에 들어가지 않아도 돼요.
HRUM MCP 0.3.3부터는 MCP 도구로도 같은 일을 해요: hrum_hosting_deploy(배포 시작)·hrum_hosting_deploys(배포 상태)·hrum_hosting_logs(런타임 로그). hrum_ai_connect로 hosting_ops 권한 토큰을 받은 뒤 부르면 되고, 앱 id는 hrum_hosting_status에서 봐요. MCP를 쓰지 않는 도구는 아래 HTTP 경로를 써요.
| 할 일 | 요청 | 응답 |
|---|---|---|
| 배포 시작 | POST …/hosting/apps/{appId}/deploy 본문 {} 또는 {"commit":"40자 sha"} | {"deployId","commitSha","retried","status":"queued"}. 콘솔 「지금 배포」와 똑같이 연결 브랜치의 최신 커밋을 빌드해요(첫 배포 검토·요금제 규칙도 같아요). commit은 그 최신 커밋일 때만 받아요 — 예전 커밋은 아직 안 돼요(400 COMMIT_NOT_BRANCH_HEAD). 1분에 2번까지 |
| 배포 상태 | GET …/hosting/apps/{appId}/deploys?limit=20 | 최신순 id·commitSha·status·queuedAt·startedAt·finishedAt·liveAt·failReason·scanFindings(비밀값 검사에 걸린 파일·줄·규칙만)·logTail(빌드 로그 끝)·startFailReason·startFailLog |
| 로그 요청 | POST …/hosting/apps/{appId}/logs 본문 {"lines":100}(1~200) | 202 {"requestId"} |
| 로그 받기 | GET …/hosting/apps/{appId}/logs/{requestId} | status가 pending이면 2~3초 뒤 다시, delivered면 lines. 3분 지나면 expired |
로그와 실패 사유는 내보내기 전에 가려요: 그 앱에 저장된 환경변수 값, 그리고 sk-…·AKIA…·Bearer …·JWT·…_live_… 같은 키 모양은 [redacted]로 바뀌어요. 그래도 앱이 비밀값을 로그에 찍지 않게 만드는 게 먼저예요. 모든 호출(거절 포함)은 토큰·앱·결과와 함께 기록돼요.
콘솔 로그인 세션이나 HRUM MCP 로그인 세션으로도 같은 경로가 있어요: POST …/console/hosting/apps/{appId}/deploy-now(MCP는 가입으로 만든 세션만), GET …/console/hosting/apps/{appId}/deploys, POST …/console/hosting/apps/{appId}/logs 본문 {"lines":100}(1~200, MCP는 가입으로 만든 세션만) → GET …/logs/{requestId}. 자기 앱만 되고, 로그 줄은 같은 규칙으로 가려져요. 가져온 로그 내용은 전달(또는 요청)한 때부터 24시간 뒤 지워져요(2026-12-01부터 7일, 이용약관 제20조 제5항).
HRUM_CM_TOKEN=$(security find-generic-password -s hrum-console-ops -w)
API=https://api.hrum.ai/api/v1/partners/v1/console-ai/hosting/apps/$APP_ID
git push origin main
curl -s -X POST -H @<(printf 'Authorization: Bearer %s' "$HRUM_CM_TOKEN") \
-H 'Content-Type: application/json' -d '{}' "$API/deploy" | jq '.data // .'
curl -s -H @<(printf 'Authorization: Bearer %s' "$HRUM_CM_TOKEN") \
"$API/deploys?limit=3" | jq '.data.deploys[] | {id, commitSha, status, liveAt, failReason}'
비밀키 안전 규칙 (AI 도구가 지킬 것)
- 사용자에게 값을 채팅에 붙여 달라고 하지 않아요. 키체인·비밀번호 관리자에 넣어 달라고 하고, 항목 이름만 물어요.
- 사용자가 채팅에 값을 붙여 넣었더라도 다시 출력하지 않아요. 그 값은 이미 대화 기록에 남았으니, 사용자에게 발급처에서 새로 발급받아 바꾸기를 권해요.
- 값은 셸 변수로 읽어 표준 입력으로 넘겨요.
curl -d "값",echo 값,set -x처럼 값이 명령줄·로그에 남는 방법은 쓰지 않아요. - 값을 코드·
.env커밋·PROGRESS.md·로그·화면 출력에 적지 않아요. 보고는 "이름 + 저장 여부"만 해요. - AI 경로가 거절하는 이름(위)은 우회하지 말고 사람에게 콘솔에서 넣어 달라고 넘겨요.
- 운영 토큰(
hrum_cm_…)도 값과 똑같이 다뤄요. 쓰고 나면 콘솔에서 취소하라고 알려 줘요.
실제 있었던 일: 판매 관리 앱을 만들던 AI 도구가 앱의 마스터 키를 환경변수로 넣으려 했는데, 그때는 AI가 쓸 운영 경로가 없어 거기서 멈췄어요. 지금은 MASTER_KEY처럼 _KEY로 끝나는 이름은 AI 운영 토큰으로 넣을 수 있고, 그 밖의 이름은 사람이 콘솔에서 넣어요. 어느 쪽이든 값이 채팅으로 오가지 않게 해요.
환경변수 오류
오류 본문은 {"success":false,"statusCode":…,"message":"…"}이에요. 환경변수 오류에는 code가 없으니 상태 코드와 아래 문구 앞부분으로 구분해요. 원문 전체는 llms.txt에 있어요.
| 상태 | 메시지 앞부분 | 원인 → 해결 |
|---|---|---|
| 400 | 이름은 대문자·숫자·밑줄만 | 이름 규칙 위반 → 대문자·숫자·밑줄, 숫자로 시작 안 함, 64자 이하 |
| 400 | 플랫폼이 쓰는 이름이라 | PORT·HOSTNAME·NODE_OPTIONS·DATABASE_URL, RIDM_·PG 접두 → 다른 이름으로 |
| 400 | AI 연결이 자동으로 넣는 이름이라 | HRUM_API_KEY → 이 앱은 「AI 연결」이 켜져 있어 플랫폼이 넣어요. 직접 넣으려면 「AI 연결」을 꺼요 |
| 400 | 이 계정에서 발급한 API 키만 넣을 수 있어요 | 내 콘솔 「API 키」의 키를 넣어요 |
| 400 | AI 연결이 앱마다 만든 키는 넣을 수 없어요 | 콘솔 「API 키」에서 발급한 키를 넣어요 |
| 400 | 값을 입력해 주세요 | 값이 비었어요 |
| 400 | 값에 줄바꿈을 넣을 수 없 | 여러 줄 값(PEM 개인 키 등) → base64 한 줄로 바꿔 넣고 앱에서 풀어 써요 |
| 400 | 값은 3000바이트까지 | 값이 3,000바이트를 넘어요 → 큰 값은 DB나 외부 비밀 저장소에 |
| 400 | 환경변수 전체 크기가 한도를 넘어 | 앱 전체 합계가 64KB를 넘어요 → 안 쓰는 환경변수를 지우거나 값을 줄여요 |
| 400 | 실행 환경을 바꾸는 이름이라 AI 경로 | AI 경로 거절 이름 → 사람이 콘솔에서 |
| 400 | AI 경로(AI 운영 토큰·MCP)로는 _KEY | 비밀 이름 접미가 아님 → 이름을 바꾸거나 사람이 콘솔에서 |
| 400 | Validation failed (uuid is expected) | 앱 id가 UUID가 아님 → GET /console-ai/hosting의 apps[].id |
| 401 | MGMT_TOKEN_INVALID | 토큰이 없거나 만료·취소 → 새로 발급 |
| 403 | MGMT_SCOPE_DENIED (scope: "hosting_ops") | 토큰에 hosting_ops가 없어요 → 체크해서 새로 발급 |
| 404 | 앱을 찾을 수 없 | 다른 계정의 앱이거나 삭제된 앱 → 앱 id 확인 |
| 404 | 없는 환경변수 | 지우려는 이름이 없어요 → 이름 목록 확인 |
| 409 | 해지된 앱은 환경변수를 바꿀 수 없 | 해지 진행 중인 앱 → 바꿀 수 없어요 |
| 409 | 환경변수는 앱당 60개까지 | 안 쓰는 이름을 지우고 다시 |
| 429 | — | 넣기·지우기는 1분에 30번까지 → 잠시 뒤 다시 |
| 503 | 환경변수 저장소가 준비되지 않 | 서버 쪽 문제 → 잠시 뒤 다시, 계속되면 문의 |
AI 연결
앱에서 사주·AI API를 부를 수 있게 이 앱만 쓰는 API 키를 플랫폼이 넣어 주는 기능이에요. 모든 계정에서 쓸 수 있어요.
- 켜기 — 콘솔 앱에서 앱 상세를 열고 「AI 연결 사용」을 켜요. 앱 전용 키가 만들어져 환경변수
HRUM_API_KEY로 들어가고, 앱이 다시 시작돼요. - 부르기 — 앱 서버 코드에서
process.env.HRUM_API_KEY를 읽어X-Partner-Api-Key헤더에 담아요. 키 값은 콘솔에도 보이지 않아요. 브라우저로 보내는 코드에는 넣지 마세요.
켜 둔 동안에는 HRUM_API_KEY를 직접 넣을 수 없어요. 직접 넣은 값이 있으면 켜기 전에 지워요(안 지우면 「기존 HRUM_API_KEY 환경변수를 먼저 지워 주세요」가 떠요). 이 키로 쓴 요금은 내 크레딧에서 나가고, 앱 상세에서 정한 하루 사용 한도에 닿으면 그날은 멈춰요. 끄면 키가 바로 끊기고, 다시 켜면 새 키가 만들어져요. 이 키로는 결제 API를 부를 수 없어요 — 앱에서 결제 받기는 콘솔에서 발급한 키로 해요.
앱에서 결제 받기
앱 이용자의 결제를 흐름 결제 페이지로 받을 수 있어요. 판매는 판매자(개인·개인사업자·법인)로 등록하고 승인된 뒤에 열려요. 판매자 등록은 콘솔의 정산에서 해요. 조건은 이용약관 제32조~제39조가 정해요. 무료 플랜 앱도 판매할 수 있어요. 다만 월 전송 한도에 이르거나 정지되어 앱 공개가 멈춘 동안에는 새 결제 열기가 409 APP_NOT_SERVING으로 거절돼요. 이미 연 결제와 주문 확인·환불은 그대로 돼요.
- API 키 넣기 — 콘솔 API 키에서 발급한 키를 환경변수(예:
HRUM_PARTNER_KEY)로 넣어요. 「AI 연결」이 넣어 주는HRUM_API_KEY로는 결제 API를 부를 수 없어요. 키는 서버 코드에서만 쓰고 브라우저로 보내지 마세요. - 상품 등록 —
POST /api/v1/partners/v1/storefront/skus본문{"appId","name","priceWon"}. 가격은 여기 등록한 값으로만 결제돼요. 30일 이용권처럼 한 번 결제하고 자동 갱신 없이 앱이 기간을 관리하는 상품은"accessDays"(이용 기간, 1~30일)를 같이 넣어요. 환불 기준은"refundPolicy"(1,000자까지)에 넣어요. 둘 다 선택이고, 넣으면 결제 화면에 그대로 보여요. 자동 갱신(정기결제) 상품은 받지 않아요. - 결제 열기 — 서버에서
POST /api/v1/partners/v1/storefront/checkouts본문{"appId","skuId","qty","returnUrl"}을 보내고, 응답의checkoutUrl로 이용자를 보내요.returnUrl은 이 앱 주소(<이름>.ridm.ai또는 연결한 도메인)의 https 주소만 돼요. - 결과 확인 — 결제가 끝나면 이용자가
returnUrl?orderId=…로 돌아와요. 서버에서GET /api/v1/partners/v1/storefront/orders/{orderId}로status가paid인지 확인한 뒤 상품을 주세요. 주소에 붙은 값만 믿으면 안 돼요.
모든 요청에는 X-Partner-Api-Key 헤더가 필요해요. 환불이 필요하면 주문번호와 함께 [email protected]로 알려 주세요. 환불되면 주문 status가 canceled 또는 partial_canceled로 바뀌어요.
결제·환불 시험 — 시험용 결제 모드는 따로 없어요. 가장 싼 상품을 실제 카드로 결제한 뒤, 결제일부터 7일 안에 결제 화면의 「환불 요청」이나 [email protected]로 그 주문의 전액 환불을 요청해요. 전액 환불된 시험 결제는 정산되지 않아 자기 거래로 보지 않고, 남는 비용도 없어요(이용약관 제44조 제5항). 개인 제작자 상품은 내 콘솔에 로그인한 브라우저에서는 결제가 막혀요.
자체 결제와 흐름 결제는 혼용할 수 없어요 — 흐름 결제로 판매하는 앱은 상품·서비스 대금(포인트 충전 포함)을 흐름 결제로만 받아요. 내 명의로 계약한 결제대행사(자체 결제)를 쓰려면 그 앱에서는 흐름 판매를 쓰지 않아요. 자체 결제의 운영 조건은 자유롭게 정할 수 있고, 그 매출과 환불은 내가 직접 처리해요(이용약관 제44조 제7항).
const res = await fetch("https://api.hrum.ai/api/v1/partners/v1/storefront/checkouts", {
method: "POST",
headers: { "Content-Type": "application/json", "X-Partner-Api-Key": process.env.HRUM_PARTNER_KEY },
body: JSON.stringify({ appId, skuId, qty: 1, returnUrl: "https://myapp.ridm.ai/paid" }),
});
const { checkoutUrl } = (await res.json()).data;
키 권한별로 부를 수 있는 것
키를 만들 때 권한을 고를 수 있어요. 고른 권한 밖의 경로를 부르면 403 KEY_SCOPE_MISSING이에요. 권한을 고르지 않은 기존 키는 모든 경로를 그대로 불러요. 경로 전체는 OpenAPI 문서에 있어요.
payments— 상품 등록POST /storefront/skus, 결제 열기POST /storefront/checkoutsorders.read— 주문 확인GET /storefront/orders/{orderId}refunds— 환불 결과는 주문status와 웹훅order.refunded로 받아요settlement.read— 정산 데이터GET /settlement/sales·/settlement/payouts·/settlement/summarywebhooks— 판매자 웹훅 주소 등록·전송 기록
정산 데이터 API
콘솔 「정산」 화면과 같은 숫자를 서버에서 받아요. 내 키의 내 데이터만 보여요. 기간 from·to는 한국 날짜(YYYY-MM-DD, 양끝 포함)이고, 비우면 이번 달이에요. 한 번에 366일까지 돼요.
GET /api/v1/partners/v1/settlement/sales?from=&to=&skuId=&limit=&cursor=— 판매 한 건마다 결제액(paidWon), HRUM 판매 수수료(salesCommissionWon, 부가세 포함), 결제 건당 수수료(perOrderFeeWon), 카드 수수료(pgFeeWon), 지급될 금액(sellerWon), 환불(refundedWon). 모두 환불을 뺀 값이에요.totals는 이 페이지가 아니라 기간 전체 합계예요.GET /api/v1/partners/v1/settlement/payouts?from=&to=&status=scheduled|completed|unpaid— 지급마다grossWon= 보낸 돈(amountWon) + 지급 수수료(feeWon) + 그 부가세(feeVatWon) + 개인 판매자 원천징수 3.3%(withholdingWon). 기간은 지급일 기준이에요.GET /api/v1/partners/v1/settlement/summary?from=&to=— 판매 합계와 지급 예정·완료 합계, 지금 지급 수수료를 한 번에.
const res = await fetch("https://api.hrum.ai/api/v1/partners/v1/settlement/summary?from=2026-11-01&to=2026-11-30", {
headers: { "X-Partner-Api-Key": process.env.HRUM_PARTNER_KEY },
});
const { sales, payouts, payoutFee } = (await res.json()).data;
판매자 웹훅
결제 완료·환불·지급이 생기면 내 서버로 알려 드려요. 주소는 https://만 되고(포트 443·8443), 사설·내부 주소는 등록할 수 없어요.
- 주소 등록 —
PUT /api/v1/partners/v1/webhooks/endpoint본문{"url":"https://myapp.ridm.ai/hrum/webhook"}. 응답의secret(whsec_…)은 이때 한 번만 보여요. 바로 서버 환경변수HRUM_WEBHOOK_SECRET에 넣으세요. 새로 받으려면{"url": …, "rotateSecret": true}. - 이벤트 —
order.paid(결제 완료),order.refunded(환불 한 건),payout.scheduled(지급 예정),payout.completed(지급 완료),webhook.test(POST /webhooks/test). 본문은{"id","type","created","data"}이고 구매자 정보는 들어 있지 않아요. 같은 일은 같은id로 한 번만 만들어지니id로 중복을 걸러 주세요. - 플랫폼 사본 — 플랫폼 키로 주소를 등록하면 그 플랫폼에서 열린 판매자 주문의
order.paid·order.refunded사본도 와요. 헤더·서명은 같고id는 판매자 쪽과 달라요.data에sellerId·spaceId가 더 들어 있어요. - 서명 확인 — 헤더
Hrum-Signature: t=<unix초>,v1=<hex>.v1은 비밀값으로 만든 HMAC-SHA256(t + "." + 받은 본문 그대로)예요. 5분보다 오래된t는 버리세요. - 다시 보내기 — 10초 안에 2xx로 답하지 않으면 1분·5분·30분·2시간·12시간 뒤 다시 보내요(최대 6번). 전송 기록은
GET /webhooks/deliveries, 다시 보내기는POST /webhooks/deliveries/{eventId}/redeliver.
const crypto = require("node:crypto");
function verifyHrumWebhook(rawBody, header, secret, toleranceSec = 300) {
const parts = Object.fromEntries(String(header || "").split(",").map((p) => p.trim().split("=")));
const t = Number(parts.t);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const want = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
const got = Buffer.from(parts.v1 || "", "hex");
return got.length === want.length && crypto.timingSafeEqual(got, want);
}
// Express: 본문을 JSON으로 바꾸기 전에 원본 그대로 확인해요
app.post("/hrum/webhook", express.raw({ type: "application/json" }), (req, res) => {
const raw = req.body.toString("utf8");
if (!verifyHrumWebhook(raw, req.get("Hrum-Signature"), process.env.HRUM_WEBHOOK_SECRET)) return res.sendStatus(400);
const event = JSON.parse(raw); // event.id 를 이미 처리했으면 200만 돌려줘요
res.sendStatus(200);
});
첫 배포와 자동 검사
첫 빌드가 성공하면 자동 검사를 거쳐 자동으로 승인되고, 바로 주소가 공개돼요. 첫 배포가 공개되기 전에는 유료 요금이 차감되지 않아요. 저장소에 비밀값(키·토큰·비밀번호)이 들어 있으면 빌드가 실패해요. 새 외부 접속 대상·새 위험 패턴이 발견되거나 저장소 소유자가 바뀌어도 배포는 자동으로 반영되며, 그 내용은 기록돼요. 모든 자동 승인과 검사 결과는 기록되고 운영자가 사후에 확인하며, 문제가 있으면 공개를 중지할 수 있어요. 공개가 중지되면 사유를 이메일과 앱 화면으로 알려 드려요. 금지 행위는 약관 제26조를 보세요.
요금·한도
앱 종류: 일반 앱 / 메타버스 — 호스팅은 하나이고, 콘솔 「내 호스팅」에서 신청할 때 앱 종류를 골라요. 일반 앱 플랜은 앱마다, 메타버스 플랜은 계정 하나에 걸려요. 이 문서의 나머지는 일반 앱 기준이에요.
- 메타버스 한도(계정 하나에 걸리고, 모든 공간 합계) — 무료: 공간 1개·동시 접속 50명·월 전송 10GB·저장 100MB·내 도메인 연결 없음(
<이름>.ridm.ai). 베이직: 공간 5개·동시 접속 200명·월 전송 40GB·저장 3GB·내 도메인 2개. 프로: 공간 20개·동시 접속 500명·월 전송 100GB·저장 10GB·내 도메인 5개. 무료는 전송 한도에 이르면 같이 접속만 멈추고 공간은 열려 있어요. 요금은 요금 페이지, 만드는 법은 메타버스 만들기 책에 있어요.
플랜별 요금·메모리·DB·월 전송은 요금 페이지에 있어요. 유료 플랜 요금은 충전한 크레딧에서 매월 차감돼요. 결제일에 잔액이 부족하면 앱이 멈추고, 충전하면 자동으로 재개돼요. 월 전송량은 방문자에게 보낸 응답과 앱이 밖으로 보낸 트래픽(외부 API 호출·업로드·DB 쓰기 포함)을 합한 양이에요. WebSocket은 주고받은 프레임 양쪽 방향이 모두 들어가요. 한도에 이르면 열린 WebSocket도 1008로 닫혀요. 한도에 이르면 공개와 앱 실행이 함께 멈추며(다음 달 1일에 재개), 유료 플랜은 앱 화면에서 전송 블록을 사면 몇 분 안에 다시 켜져요. 80%와 한도 도달 때 이메일로 알려 드려요.
백업·해지
- 앱 화면의 "데이터베이스 백업"으로 DB 덤프를 만들 수 있어요. 1시간 동안 유효한 내려받기 주소가 나오며, 하루 3번까지 만들 수 있어요.
- 해지하면 유료 플랜은 이미 결제한 기간이 끝나는 날 멈추고, 그 뒤 30일 동안 데이터를 내려받거나 되돌릴 수 있어요. 30일이 지나면 앱과 DB가 삭제되어 복구할 수 없어요. 차감된 요금은 환불되지 않습니다.
문의: contact@float.do