Relio 관리자 가이드

• 대상: 시스템 관리자, 인프라·보안 엔지니어, DBA — 화면을 띄워 놓고 지키는 사람
• 기준 버전: v1.11.19 (릴리즈 자산 relio-v1.11.19.tar.gz, 이미지 relio:v1.11.19)
• 함께 볼 문서: 화면 사용법은 사용자 가이드, 보안 모델의 근거는 Security Model, 구조는 Architecture, REST·MCP 명세는 REST API and MCP

이 문서의 화면은 v1.11.19 소스로 띄운 실제 Relio 관리자 콘솔을 가짜 데이터로 찍은 것입니다. 명령의 비밀값은 모두 예시입니다.

1. 구성 요소

Relio 는 컨테이너 하나와 PostgreSQL 하나로 동작합니다. Redis, 메시지 큐, 별도 런타임, 외부 네트워크가 필요 없습니다.

컨테이너 안에서 바이너리는 UID/GID 10001 로 실행되고, 이미지의 HEALTHCHECK 는 20초마다 relio healthcheck 를 호출합니다.

2. 설치

릴리즈 자산은 Docker 이미지 tar.gz 하나뿐입니다. 인터넷이 없는 서버에서도 아래 순서 그대로 됩니다.

2.1 필요한 것

2.2 이미지 적재

# 릴리즈 페이지에서 받은 자산을 서버로 옮긴 뒤
gunzip -c relio-v1.11.19.tar.gz | docker load
docker image inspect relio:v1.11.19 --format ''

2.3 PostgreSQL 준비

이미 운영 중인 PostgreSQL 이 있으면 DB 와 사용자만 만듭니다.

CREATE USER relio WITH PASSWORD '<db-password>';
CREATE DATABASE relio OWNER relio;

없으면 컨테이너로 띄웁니다.

docker network create relio-net
docker volume create relio-postgres-data
docker run -d --name relio-postgres --network relio-net \
  -e POSTGRES_DB=relio -e POSTGRES_USER=relio \
  -e POSTGRES_PASSWORD='<db-password>' \
  -v relio-postgres-data:/var/lib/postgresql/data \
  postgres:17-bookworm

2.4 Relio 기동

# 최초 1회만 생성하고 비밀번호 관리 도구에 보관합니다. 잃어버리면 SSO Client Secret 과
# 개인 연동 키를 다시 발급해야 합니다.
ENCRYPTION_KEY="$(openssl rand -hex 32)"

docker run -d --name relio --network relio-net \
  -p 8080:8080 \
  -e POSTGRES_DSN="postgres://relio:<db-password>@relio-postgres:5432/relio?sslmode=disable" \
  -e BOOTSTRAP_ADMIN="admin" \
  -e BOOTSTRAP_ADMIN_PASSWORD="<initial-admin-password, 12자 이상>" \
  -e ENCRYPTION_KEY="$ENCRYPTION_KEY" \
  -v relio-data:/var/lib/relio \
  --restart unless-stopped \
  relio:v1.11.19

기동 로그에서 마이그레이션과 키 검증이 끝나고 Relio started 가 찍히면 됩니다.

docker logs -f relio
curl -fsS http://127.0.0.1:8080/health/ready
# {"postgres":"ok","schema":{"schemaVersion":"012_personal_key_access_version.sql",...},"status":"ready"}

2.5 최초 관리자 로그인

1. 브라우저에서 http://<서버>:8080 을 엽니다.
2. BOOTSTRAP_ADMIN / BOOTSTRAP_ADMIN_PASSWORD 로 로그인합니다. 즉시 비밀번호 변경 화면으로 이동하며, 바꾸기 전에는 다른 화면을 열 수 없습니다.
3. 오른쪽 위 프로필 메뉴 → Admin Console 로 들어가 운영 현황판 을 확인합니다.

방금 설치한 상태에서는 우선 조치에 Service URL 확인 필요 가 뜹니다. 시스템 기본정보 에서 사용자가 실제로 접속하는 주소로 바꿉니다 — SSO 콜백 주소와 MCP 가 허용하는 브라우저 Origin 이 이 값으로 만들어집니다.

Bootstrap 관리자는 삭제되지 않는 비상 계정(Break Glass) 입니다. 최초 생성 뒤에는 환경 변수를 바꿔도 계정과 비밀번호를 덮어쓰지 않으며, 로컬 로그인을 꺼도 이 계정은 계속 로그인할 수 있습니다.

2.6 개발·검증용 compose

저장소를 받을 수 있는 환경이라면 docker compose up --build 로 PostgreSQL 과 Relio 가 함께 뜹니다(compose.yaml). 초기 비밀번호와 ENCRYPTION_KEY 가 파일에 적혀 있으므로 운영에 그대로 쓰면 안 됩니다.

3. 설정

3.1 환경 변수 (전수)

애플리케이션이 읽는 환경 변수는 아래 네 개가 전부입니다(internal/config/config.go, CI 의 check-env-contract.sh 가 이 계약을 검사합니다). 그 밖의 모든 설정은 PostgreSQL 에 저장되고 관리자 콘솔에서 바꿉니다.

값을 잘못 주면 컨테이너가 바로 종료되며 로그에 invalid startup configuration 과 함께 이유(POSTGRES_DSN, BOOTSTRAP_ADMIN and BOOTSTRAP_ADMIN_PASSWORD are required, BOOTSTRAP_ADMIN_PASSWORD must contain at least 12 characters)가 찍힙니다.

리슨 주소 :8080 과 데이터 디렉터리 /var/lib/relio 는 고정이며 환경 변수로 바꿀 수 없습니다.

3.2 관리자 콘솔의 설정 (DB 저장)

관리자 콘솔 기본 설정 그룹의 화면이 아래 설정을 다룹니다. 재시작 없이 즉시 적용되고 변경은 감사 로그에 남습니다. REST 로는 GET /api/v1/admin/settings?namespace=<이름>, PUT /api/v1/admin/settings/{namespace}/{key} 로 같은 값을 다룹니다.

3.3 사내 SSO 연결 (Keycloak OIDC)

사내 SSO 연결 화면에 Issuer URL(예: https://sso.company.internal/realms/enterprise), Client ID, Client Secret 을 저장합니다. Client Secret 은 Instance Data Key 로 암호화되어 저장됩니다. 연결 테스트 는 Discovery, TLS, JWKS, Callback 을 확인합니다(POST /api/v1/admin/oidc/test).

• Keycloak 클라이언트의 Redirect URI 는 <system.service_url>/api/v1/auth/oidc/callback 입니다.
• SSO 로 처음 로그인한 사용자는 권한 · 데이터 범위 에서 기본으로 지정한 Role(영업 담당자)을 자동으로 받습니다. 클레임 → Role/조직 매핑은 GET/PUT /api/v1/admin/oidc/mappings 로 다룹니다.

3.4 영업 정책

영업 단계 설정(단계·성공확률·전망 분류), 영업 실행 정책(단계별 Playbook 과 전환 조건 OFF/WARNING/BLOCK, Deal Health 규칙과 배점), 승인 절차, 사용자 정의 항목, 상품 카탈로그, 고객 요청 유형 · SLA 가 여기 있습니다. 모두 코드 변경 없이 화면에서 바꾸고 즉시 반영됩니다.

승인 절차는 정책이 하나도 없으면 검토·승인 메뉴와 버튼이 서비스 전체에서 사라집니다. 사용자가 “승인 메뉴가 없다”고 하면 정상입니다.

4. 계정과 권한

권한은 세 겹의 교집합입니다: 기능 권한(Role 의 customer:read 같은 항목) ∩ 데이터 범위(Role 의 본인/팀/부서/본부/전사) ∩ 개인 연동 키 범위(API·MCP 로 올 때). 화면, REST, MCP 어디서 오든 같은 규칙을 탑니다.

4.1 기본 제공 Role

기능 권한 목록: activity, contact, customer, lead, opportunity, quotation, notification 의 :read/:write, contract·product·sales·target·forecast·intelligence 의 :read/:write, report:read, approval:request/:approve, voice:read/:write/:manage, analytics:manage, mcp:use, customer:delete, admin:read/admin:write.

4.2 사용자 · 조직

• ＋ 사용자 생성: 로컬 계정을 만듭니다. 초기 비밀번호를 지정하면 첫 로그인에서 변경이 강제됩니다.
• 권한: Role 을 부여합니다. Role 이 하나도 없는 사용자는 로그인은 되지만 “아직 사용 권한이 없습니다” 만 봅니다.
• 비밀번호: 로컬 계정 재설정. SSO 계정에는 비밀번호가 없습니다.
• 비활성화: 즉시 로그인이 막히고 세션이 끝납니다. Bootstrap 관리자는 비활성화·삭제할 수 없습니다.
• 조직 탭에서 조직 트리를 만들고 사용자를 배치합니다. 데이터 범위(팀/부서/본부)는 이 트리를 기준으로 계산됩니다.

4.3 개인 연동 키 관리

사용자는 자기 키를 발급·회전·폐기하고, 관리자는 연동 키 · API · MCP 에서 전체 키를 보고 POST /api/v1/admin/users/{id}/keys/revoke-all 로 한 사용자의 키를 모두 회수할 수 있습니다. 서버는 Secret 의 HMAC Digest 만 저장하므로 DB 가 유출되어도 키가 복원되지 않습니다.

5. 운영

5.1 상태 점검

Support Bundle(GET /api/v1/admin/operations/support-bundle)은 진단 결과·버전·설정을 JSON 하나로 내려받습니다. 비밀번호, SSO Secret, 키 Digest 는 들어가지 않으며 다운로드 자체가 감사 로그에 SUPPORT_BUNDLE_EXPORT 로 남습니다. 문제를 보고할 때 이 파일을 첨부하세요.

5.2 로그

로그는 JSON 한 줄 형식으로 표준 출력에 나갑니다. 파일로 쓰지 않으므로 docker logs 나 컨테이너 런타임의 로그 드라이버로 수집합니다.

docker logs --since 1h relio | jq -r 'select(.level=="ERROR") | "\(.time) \(.msg) \(.error // "")"'

모든 API 응답 오류에는 requestId 가 있고, 같은 값이 서버 로그의 requestId 와 감사 로그에 찍힙니다. 사용자가 전달한 ID 로 세 곳을 이어 봅니다.

5.3 감사 로그

감사 로그 화면은 Web·REST·MCP·Admin·Login·Key 채널의 작업을 검색하고 변경 전후를 비교합니다(GET /api/v1/admin/audit?channel=&q=&limit=). 감사 행은 PostgreSQL 에 남으므로 보관 기간은 DB 백업 정책을 따릅니다.

5.4 백업

백업할 것은 두 가지이고, 같은 시점으로 맞춰야 합니다.

1. PostgreSQL — 모든 데이터.
2. 암호화 키 — ENCRYPTION_KEY 를 쓰고 있다면 그 값(비밀번호 관리 도구에 이미 있어야 합니다). 쓰지 않는다면 /var/lib/relio/secrets/master.key. 이 키 없이 DB 만 복원하면 개인 연동 키와 SSO Client Secret 을 열 수 없어 다시 발급해야 합니다.

# DB
docker exec relio-postgres pg_dump -U relio -d relio -F c > relio-$(date +%Y%m%d).dump
# 볼륨 (ENCRYPTION_KEY 를 쓰지 않을 때 필수, 쓸 때도 uploads/exports 를 위해 권장)
docker run --rm -v relio-data:/data -v "$PWD":/backup debian:bookworm-slim \
  tar czf /backup/relio-data-$(date +%Y%m%d).tar.gz -C /data .

5.5 복구

docker stop relio
docker exec -i relio-postgres psql -U relio -d postgres -c 'DROP DATABASE relio' -c 'CREATE DATABASE relio OWNER relio'
docker exec -i relio-postgres pg_restore -U relio -d relio < relio-20260911.dump
docker run --rm -v relio-data:/data -v "$PWD":/backup debian:bookworm-slim \
  tar xzf /backup/relio-data-20260911.tar.gz -C /data      # master.key 를 쓰는 경우
docker start relio

복구 후 기동 로그에 instance encryption key verified 가 찍혀야 합니다. instance encryption key integrity check failed 가 나오면 DB 와 키가 서로 다른 시점의 것입니다 — Relio 는 데이터 손상을 막기 위해 새 키를 만들지 않고 기동을 멈춥니다. 원래 ENCRYPTION_KEY 를 넣거나 같은 시점의 master.key 를 복원하세요.

5.6 업그레이드

마이그레이션은 새 버전이 기동하면서 자동으로 적용됩니다. 되돌릴 수 없으므로 업그레이드 직전 백업(5.4) 이 곧 롤백 수단입니다.

gunzip -c relio-v1.11.19.tar.gz | docker load
docker stop relio && docker rename relio relio-old
docker run -d --name relio --network relio-net -p 8080:8080 \
  -e POSTGRES_DSN="..." -e BOOTSTRAP_ADMIN="admin" -e BOOTSTRAP_ADMIN_PASSWORD="..." \
  -e ENCRYPTION_KEY="$ENCRYPTION_KEY" -v relio-data:/var/lib/relio \
  --restart unless-stopped relio:v1.11.19
docker logs -f relio            # "Relio started" 확인
curl -fsS http://127.0.0.1:8080/health/ready | jq .schema.schemaVersion
docker rm relio-old             # 확인 뒤

• 같은 볼륨·같은 ENCRYPTION_KEY 를 넘겨야 합니다. 이전 버전에서 ENCRYPTION_KEY 없이 운영하다가 이번에 처음 주면, 기동 시 instance data key re-wrapped with the new wrapping key 로그와 함께 기존 자격증명이 그대로 새 키로 감싸집니다.
• 롤백: 새 컨테이너를 멈추고 → 업그레이드 직전 DB 덤프를 복원(5.5)하고 → 이전 이미지로 다시 기동합니다. 스키마가 올라간 DB 에 이전 이미지를 붙이지 마세요.
• 릴리즈 파이프라인은 직전 발행 릴리즈 이미지에서 새 이미지로 올리는 업그레이드 테스트(scripts/run-upgrade-container-test.sh <old> <new>)를 통과해야 발행되므로, 한 버전씩 순서대로 올리는 경로는 검증되어 있습니다.

5.7 데이터 품질과 설정 이관

데이터 품질 · 설정 이관 화면은 고객·담당자·영업기회의 완성도를 0~100 점수와 표본으로 진단하고(GET /api/v1/admin/data-quality), 영업 정책·Role·설정을 비밀값 없이 JSON 번들로 내보내(GET /api/v1/admin/configuration/export) 다른 환경에 적용합니다. 적용은 두 단계입니다: POST /api/v1/admin/configuration/preview 로 생성·갱신·변경 없음 Diff 를 보고, POST /api/v1/admin/configuration/apply 에 {"confirmation":"APPLY","bundle":…} 로 비파괴 Upsert 합니다. 업무 데이터는 번들에 포함되지 않습니다.

6. 장애 대응

7. 보안

설치 직후 바꿀 것

• BOOTSTRAP_ADMIN_PASSWORD 는 첫 로그인에서 강제로 바뀌지만, 환경 변수에 남은 초기값도 예시가 아닌 강한 값으로 두고 배포 파일을 비밀로 관리합니다.
• system.service_url 을 실제 주소로. 기본값 http://localhost:8080 은 SSO 콜백을 깨뜨립니다.
• ENCRYPTION_KEY 를 지정하고 비밀번호 관리 도구에 보관합니다.
• 일상 관리자 계정을 따로 만들고 Bootstrap 계정은 비상용으로만 씁니다. Bootstrap 은 삭제·비활성화가 불가능하므로 비밀번호 보관을 특히 신경 씁니다.
• 사내 SSO 를 연결한 뒤에는 일반 로컬 로그인 허용 을 끄는 것을 검토합니다.

외부에 열면 안 되는 것

• PostgreSQL 포트. Relio 컨테이너만 접근해야 합니다.
• /var/lib/relio 볼륨. secrets/master.key 가 있습니다.
• 8080 을 인터넷에 직접 노출하지 말고 TLS 를 종단하는 리버스 프록시 뒤에 둡니다. 단, Relio 는 X-Forwarded-For 를 읽지 않고 TCP 피어 주소만 기록하므로 프록시 뒤에서는 감사 로그의 IP 와 로그인 시도 제한이 프록시 주소 기준이 됩니다 — 로그인 경로(POST /api/v1/auth/login)의 요청 제한은 프록시에서도 걸어 두세요.

기본 보호 장치 (보안 · 파일 · 접속 화면 하단에 요약되어 있습니다)

• 비밀번호는 argon2id 로 저장하며 원문을 보관하지 않습니다. 존재하지 않는 계정·비활성 계정도 같은 시간을 들여 거절해 아이디 열거를 막습니다.
• 세션 쿠키는 HttpOnly·SameSite, 상태 변경 요청은 CSRF 토큰, 응답에는 CSP 가 붙습니다. 기본 상태에서 외부 CDN·폰트·분석 스크립트가 없고, 방문자 분석은 방문자 분석 · CSP 에서 출처별로 명시적으로 허용한 것만 CSP 에 추가됩니다.
• SSO Client Secret 은 AES-256-GCM 으로, 개인 연동 키는 HMAC Digest 로만 저장됩니다.
• MCP 는 Origin 검사, 개인 연동 키 인증, 도구 허용 목록, 감사 로그를 거칩니다.
• 주요 보안 설정 변경은 모두 감사 로그에 남습니다.

자세한 위협 모델과 근거는 Security Model 을 보세요.

부록. 이 가이드의 화면 캡처 다시 찍기

캡처는 scripts/guide/screenshots.mjs 가 만듭니다. 버려도 되는 배포에 가짜 데이터를 채우고 headless Chrome 으로 1440×900 화면을 docs/assets/guide/ 에 저장합니다. 대상 주소·계정은 전용 환경 변수로만 받고, RELIO_GUIDE_DISPOSABLE=1 이 없으면 시작하지 않습니다. 실행 중 API 요청 한도를 잠시 올렸다가 끝나면 원래 값으로 되돌리며, 그 밖의 전역 설정은 건드리지 않습니다.

docker compose -p relio-guide up --build -d          # 개발 compose 로 임시 배포
cd scripts/guide && npm install --no-audit --no-fund
RELIO_GUIDE_URL=http://127.0.0.1:8080 RELIO_GUIDE_DISPOSABLE=1 \
RELIO_GUIDE_ADMIN=admin RELIO_GUIDE_PASSWORD='<compose 의 초기 비밀번호>' \
RELIO_GUIDE_NEW_PASSWORD='<첫 로그인에서 바꿀 비밀번호>' \
RELIO_GUIDE_SEED_PASSWORD='<데모 동료 계정 비밀번호>' \
node screenshots.mjs
docker compose -p relio-guide down -v                # 끝나면 폐기

PDF 는 저장소 밖의 공용 가이드 도구(md2pdf.mjs)로 굽습니다. 저장소 안에 별도 변환기를 두지 않습니다.