v0.71.7 — 지금 화면으로 다시 쓴 사용자·관리자 가이드

코드는 바뀌지 않았습니다. 이번 릴리즈는 문서입니다.

사용자 가이드와 관리자 가이드에 실려 있던 화면은 2026-08-21에 v0.6.0을 찍은 것
이었습니다. 그 사이 릴리즈가 120번 넘게 나갔습니다 — 오늘의 리뷰, Dream 검토, 갈래,
발표 자료 만들기, 되돌리기, 첨부, 문서 내보내기, 웹훅 상태 화면. 가이드는 그 어느
것도 보여 주지 못했고, 보여 주는 것은 지금 없는 화면이었습니다.

    가이드가 보여 주던 것              지금 화면
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    v0.6.0 (2026-08-21 캡처)         v0.71.6 (1440x900, 가짜 데이터)
    23장, 번호 이름                   27장, 화면 이름
    Dream 은 가짜 응답을 끼워 찍음     실제로 만들어진 Dream
    관리자 비밀번호가 스크립트에 박힘   캡처 전용 환경 변수, 없으면 거부

두 가이드를 처음부터 다시 썼습니다

docs/user-guide.md · docs/admin-guide.md가 docs/USER_GUIDE.md ·
docs/ADMIN_GUIDE.md로 바뀝니다. 이름만 바뀐 것이 아니라 차례가 바뀝니다.
aidev의 공통 가이드 규격(GUIDE-STANDARD.md)을 따르므로, 다른 프로젝트의 가이드를
읽어 본 사람은 같은 자리에서 같은 것을 찾습니다.

사용자 가이드 — 이 제품이 하는 일 · 처음 5분(로그인 → 오늘의 리뷰 → 첫 생각
→ 첫 연결) · 화면별 사용법(오늘의 리뷰, 캔버스와 단축키, Dreams, 결정 기록,
검토·승인, 개인 설정) · 자주 하는 작업(발표 자료 만들기, 백업과 되돌리기, 갈래,
의견만 받기, 오프라인, API·MCP 키) · 막혔을 때 · 용어.

관리자 가이드 — 구성 요소 · 릴리즈 자산에서 설치(umm-v*.tar.gz 반입,
compose, 최초 관리자) · 환경 변수 전수 표 · 계정과 권한 · 운영(상태 점검, 로그,
백업과 복구, 업그레이드와 되돌리기, 감사 로그, 웹훅) · 장애 대응 · 보안.
Keycloak, Dream Layer, AI Gateway, 임베딩 품질, Ptium처럼 전에 있던 화면별 상세는
버리지 않고 부록으로 내려갑니다.

표는 코드에서 읽었습니다

환경 변수 표는 기억이 아니라 internal/config/config.go와
internal/observability/observability.go가 실제로 읽는 이름 전부입니다. 아홉 개 —
필수 넷(POSTGRES_DSN BOOTSTRAP_ADMIN BOOTSTRAP_ADMIN_PASSWORD ENCRYPTION_KEY)과
선택 다섯. 표에 없는 이름은 umm이 읽지 않는 이름입니다.

장애 대응 표의 증상은 로그가 실제로 찍는 문자열입니다.

    로그에 보이는 것                           확인할 곳
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━    ━━━━━━━━━━━━━━━━━━━━━━━━━━
    invalid startup configuration            필수 환경 변수 넷
    database unavailable                     POSTGRES_DSN · /readyz
    migration failed                         extension 생성 권한
    collaboration listener disconnected      pool_max_conns
    dream generation failed                  AI Gateway 연결 테스트

grep으로 로그를 잡고 그 줄로 표를 찾으면 됩니다.

캡처 스크립트가 남의 서버를 건드리지 못하게 했습니다

화면을 찍는 scripts/capture_all.js는 목록이 비지 않도록 가짜 데이터를 심습니다.
그래서 버려도 되는 배포에만 겨눠야 합니다. 전에는 주소가 기본값으로 있었고 관리자
비밀번호가 스크립트 안에 적혀 있었습니다.

const BASE_URL = required('UMM_CAPTURE_BASE_URL');
const ADMIN = required('UMM_CAPTURE_ADMIN');
const ADMIN_PASSWORD = required('UMM_CAPTURE_ADMIN_PASSWORD');

대상과 계정은 캡처 전용 환경 변수에서만 옵니다. 하나라도 비면 시작하지 않습니다.
대상이 loopback이 아니면 UMM_CAPTURE_ALLOW_REMOTE=1을 따로 요구합니다.
아무것도 흉내 내지 않습니다. 전에는 Dream 화면을 page.route로 가짜 응답을
끼워 찍었습니다. 지금은 실제로 만들어진 것을 찍습니다.
관리자 화면은 열기만 하고 저장하지 않습니다. 전역 설정이 바뀌는 일이 없습니다.

따라온 것

PDF는 공통 md2pdf 도구로 만듭니다. generate_pdf.js는 두 가이드를 따로 그리지 않고
종합 매뉴얼에만 넣습니다.
README, 문서 허브(docs/README.md), 쇼케이스 페이지, compose.yaml의 주석이 새
파일을 가리킵니다. docs/pdf/ 아래 중복으로 있던 두 PDF도 치웠습니다.
문서 허브의 "현재 문서 기준"이 v0.8.1에서 v0.71.6으로 올라갑니다. 가이드의
화면은 v0.71.6을 띄워 찍은 것이라 그 버전을 그대로 적습니다.

검증

바뀐 것은 문서·화면·캡처 스크립트뿐이고 서버와 웹 코드는 그대로입니다.
go vet ./... · go test -p 1 ./...(실제 PostgreSQL 17에 대한 통합 시험 포함) ·
gofmt · tsc · oxlint/Prettier · i18n 994키 · vitest 158개 ·
scripts/check-version.sh 통과.

What's Changed

auto-improve: Let a thought keep a name the export also uses by @hkjang in #148
auto-improve: Rewrite the user and admin guides around real screens of v0.71.6 by @hkjang in #151

Full Changelog: v0.71.5...v0.71.7

Navigation Menu

umm v0.71.7

Choose a tag to compare

Sorry, something went wrong.