timothepoznanski/poznote

1단계: 사전 준비

Docker Desktop을 설치하고 실행하세요.

2단계: Poznote 배포

새 디렉터리를 만드세요.

mkdir poznote

Poznote 디렉터리로 이동하세요.

cd poznote

환경 파일을 만드세요.

curl -o .env https://raw.githubusercontent.com/timothepoznanski/poznote/main/.env.template

.env 파일을 편집하세요.

notepad .env

Docker Compose 설정 파일을 내려받으세요.

curl -o docker-compose.yml https://raw.githubusercontent.com/timothepoznanski/poznote/main/docker-compose.yml

최신 Poznote 웹 서버와 MCP 이미지를 내려받으세요.

docker compose pull

Poznote 컨테이너를 시작하세요.

docker compose up -d

1단계: 사전 준비

1. Docker 엔진 설치
2. Docker Compose 설치

2단계: Poznote 설치

새 디렉터리를 만드세요.

mkdir poznote

Poznote 디렉터리로 이동하세요.

cd poznote

환경 파일을 만드세요.

curl -o .env https://raw.githubusercontent.com/timothepoznanski/poznote/main/.env.template

.env 파일을 편집하세요.

vi .env

Docker Compose 설정 파일을 내려받으세요.

curl -o docker-compose.yml https://raw.githubusercontent.com/timothepoznanski/poznote/main/docker-compose.yml

최신 Poznote 웹 서버와 MCP 이미지를 내려받으세요.

docker compose pull

Poznote 컨테이너를 시작하세요.

docker compose up -d

1단계: 사전 준비

Docker Desktop을 설치하고 실행하세요.

2단계: Poznote 배포

새 디렉터리를 만드세요.

mkdir poznote

Poznote 디렉터리로 이동하세요.

cd poznote

환경 파일을 내려받으세요.

curl -o .env https://raw.githubusercontent.com/timothepoznanski/poznote/main/.env.template

.env 파일을 편집하세요.

vi .env

Docker Compose 설정 파일을 내려받으세요.

curl -o docker-compose.yml https://raw.githubusercontent.com/timothepoznanski/poznote/main/docker-compose.yml

최신 Poznote 웹 서버와 MCP 이미지를 내려받으세요.

docker compose pull

Poznote 컨테이너를 시작하세요.

docker compose up -d

서버를 직접 관리하고 싶지 않다면 호스팅 업체에 Poznote 운영을 맡길 수 있습니다. 지원 업체와 선택 방법은 여기를 참고하세요.

Proxmox VE Community Scripts는 Docker 없이 명령 하나로 Poznote 전용 컨테이너를 설치합니다. 기본 1 vCPU, RAM 512 MB, 디스크 4 GB인 비특권 Debian 13 LXC를 생성하고 내부 nginx와 PHP로 제공합니다.

Proxmox 호스트 셸에서 실행하세요.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/poznote.sh)"

설치 후 http://<container-ip>:8040에 접속하며 기본 로그인 정보는 다른 설치와 같습니다. 업데이트하려면 컨테이너 콘솔에서 update를 실행하세요.

이 스크립트는 Poznote가 아닌 커뮤니티가 작성·관리합니다. 옵션과 참고 사항은 Poznote 스크립트 페이지를 확인하세요.

1단계: 사전 준비

Helm을 설치하고 Kubernetes 컨텍스트가 배포할 클러스터를 가리키는지 확인하세요.

2단계: Poznote 배포

HelmForge 차트 저장소를 추가하세요.

helm repo add helmforge https://repo.helmforge.dev

로컬 차트 목록을 갱신하세요.

helm repo update

Poznote를 설치하세요.

helm install poznote helmforge/poznote --namespace poznote --create-namespace

Poznote Helm 차트는 HelmForge 커뮤니티가 관리하는 Kubernetes 설치 옵션입니다. 값, 영구 저장, 서비스 공개, 상태 검사, 보안 컨텍스트, 운영 설정은 HelmForge Poznote 차트 문서를 참고하세요.

Poznote는 root 대신 일반 사용자(uid/gid 1000)로 실행되는 rootless 이미지도 제공합니다. Kubernetes 제한 PodSecurityStandard, rootless Podman, docker run --user 등 root가 금지된 환경용입니다. 기본 이미지와 같지만 내부 포트가 8080이고 시작 시 데이터 디렉터리의 소유권을 수정하지 못합니다.

1단계: 사전 준비

1. Docker 엔진 설치
2. Docker Compose 설치

2단계: Poznote 배포

새 디렉터리를 만드세요.

mkdir poznote

Poznote 디렉터리로 이동하세요.

cd poznote

데이터 디렉터리를 만들고 uid/gid 1000의 소유로 설정하세요. 필수: rootless 컨테이너는 기본 이미지와 달리 시작 시 이를 자동 수정하지 못합니다.

mkdir -p data
sudo chown -R 1000:1000 data

대개 sudo는 필요하지 않습니다. 사용자 uid가 1000이면 chown을 생략할 수 있으며 rootless Podman/Docker에서는 root 없이 수행할 수 있습니다. rootless 실행을 참고하세요.

환경 파일을 만드세요.

curl -o .env https://raw.githubusercontent.com/timothepoznanski/poznote/main/.env.template

.env 파일을 편집하세요.

vi .env

rootless Docker Compose 설정 파일을 내려받으세요.

curl -o docker-compose.rootless.yml https://raw.githubusercontent.com/timothepoznanski/poznote/main/docker-compose.rootless.yml

최신 rootless Poznote 웹 서버와 MCP 이미지를 내려받으세요.

docker compose -f docker-compose.rootless.yml pull

Poznote 컨테이너를 시작하세요.

docker compose -f docker-compose.rootless.yml up -d

기존 인스턴스의 전환 및 상세 설명은 문제 해결 문서의 rootless 실행을 참고하세요.

• HTTP_WEB_PORT
• POZNOTE_OIDC_CLIENT_ID
• POZNOTE_OIDC_CLIENT_SECRET
• POZNOTE_OIDC_DISABLE_NORMAL_LOGIN
• POZNOTE_MCP_PORT, POZNOTE_DEBUG 등 선택적 실행 설정
• POZNOTE_PHP_FPM_MAX_CHILDREN: 동시 PHP 요청 수 변경(기본 10). 문제 해결 참고
• POZNOTE_PHP_MEMORY_LIMIT: 요청당 PHP 메모리 상한, MB 단위(기본 512). 문제 해결 참고
• POZNOTE_LISTEN_PORT: 컨테이너 내부 웹 서버 포트(기본 80). network_mode: host에서 필요. 문제 해결 참고
• POZNOTE_SETTINGS_PASSWORD: 설정 페이지를 열기 전에 추가 비밀번호 요청. 기본은 빈 값
• POZNOTE_MCP_AUTH_TOKEN: MCP 클라이언트에 Bearer 토큰 요구. MCP 서버 참고

• 관리자·전역 설정: OIDC 제공업체, Git 동기화 활성화, 가져오기 한도, 사용자 CSS 업로드 등
• 사용자·프로필 설정: 계정 비밀번호, 테마, 글꼴 크기, 노트 정렬, 작업 공간 배경, UI 요소 숨김 등

프로필의 사용자 이름 또는 이메일과 비밀번호로 인증합니다.

기본 계정

새 설치에서는 활성 관리자 프로필 하나를 생성합니다.

• 사용자 이름: admin_change_me
• 비밀번호: admin

첫 로그인 후 기본 비밀번호와 계정 이름을 변경하세요.

비밀번호 관리

비밀번호는 .env가 아닌 Poznote 웹 화면에서 관리합니다.

• 사용자는 설정 > 비밀번호 변경에서 본인 비밀번호 변경
• 관리자는 설정 > 관리자 도구 > 사용자 관리에서 비밀번호 지정 또는 기본값으로 초기화
• 로그인 유지는 30일 동안 유지
• 비밀번호 변경 시 기존 로그인 유지 쿠키 무효화

2단계 인증

각 사용자는 설정 > 2단계 인증에서 TOTP를 켤 수 있습니다. 비밀번호 입력 후 인증 앱(Aegis, Google Authenticator, 1Password, Bitwarden 등)의 6자리 코드를 요청합니다.

• 설정 시 브라우저에서 생성한 QR 코드와 휴대폰 분실에 대비한 일회용 복구 코드 10개 제공
• 비밀번호 로그인 보호. SSO 로그인은 제공업체 자체의 2단계 인증 사용
• 활성화하면 REST API는 계정 비밀번호만으로 인증하지 않음. 클라이언트에 앱 비밀번호를 주거나 X-Poznote-OTP 헤더로 현재 코드 전달
• 기기와 복구 코드를 모두 분실하면 관리자가 설정 > 관리자 도구 > 사용자 관리의 비밀번호 창에서 해제 가능
• 관리자는 설정 > 관리자 도구 > 2단계 인증 필수에서 비밀번호로 로그인하는 모든 계정에 필수로 지정 가능. 미설정 계정은 다음 로그인 때 로그인 페이지에서 설정(QR 코드와 첫 코드), 2단계 인증 없이 열린 세션은 종료, 사용자가 직접 해제 불가. SSO 로그인은 해당 없음
• 활성화 또는 해제 시 기존 로그인 유지 쿠키 무효화

기본 비밀번호

• 관리자 계정: admin
• 일반 사용자 계정: user

변경 전에는 위 기본값을 사용합니다. 화면에서 변경하면 안전한 bcrypt 해시를 DB에 저장하고 우선 사용합니다.

OpenID Connect(인증 코드 + PKCE)로 통합 로그인을 지원합니다. Auth0, Keycloak, Azure AD, Google Identity 등 외부 제공업체를 사용할 수 있습니다.

동작 방식

1. OIDC를 활성화하면 Continue with [Provider Name] 버튼 표시
2. PKCE로 보호된 OIDC 인증 코드 흐름으로 사용자 인증
3. 허용 그룹 및 필요 시 기존 허용 사용자 목록으로 접근 제한
4. 인증 후 sub(oidc_subject), 그다음 검증된 이메일(관리자가 설정했거나 공급자에서 동기화된 이메일, 대소문자 구분 없음) 순서로 계정 연결. 기존 프로필은 사용자 이름으로 연결되지 않습니다. 첫 SSO 로그인에서 연결하려면 Settings > Admin Tools > User Management에서 공급자가 보내는 이메일을 입력하거나 OIDC subject를 붙여 넣으세요. 첫 로그인이 거부되면 붙여 넣을 subject가 로그에 기록됩니다.
5. 자동 사용자 생성이 켜져 있고 일치하는 프로필이 없으면 새 프로필 생성. 이 프로필은 비밀번호가 전혀 없습니다. 관리자가 계정을 만들 때의 초기 인증 정보 전달 절차가 없으므로 기본 비밀번호도 작동하지 않습니다. 제공업체로 로그인하거나 관리자가 설정 > 관리자 도구 > 사용자 관리에서 명시적으로 비밀번호를 설정해야 합니다.
6. POZNOTE_OIDC_DISABLE_NORMAL_LOGIN=true이면 비밀번호 양식을 숨기고 SSO 전용으로 전환
7. OIDC 활성화 시 REST API에서 Authorization: Bearer <OIDC JWT> 인증 가능. JWKS, 발급자, 만료, 대상, 접근 제어 검증
8. OIDC 흐름을 지원하지 않는 확장 프로그램·모바일 앱·스크립트는 각 사용자 설정에서 만든 앱 비밀번호 사용
9. 2단계 인증은 비밀번호 양식만 보호합니다. SSO는 Poznote 코드를 요구하지 않으므로 제공업체에서 2단계 인증을 적용하세요. 비밀번호와 SSO가 모두 있으면 두 경로를 사용할 수 있으며 SSO의 보안 수준은 제공업체 정책에 따릅니다.

설정

관리자 화면의 설정 > 관리자 도구 > OIDC / SSO에서 설정합니다.

활성화, 발급자, 제공업체 이름, 범위, 접근 제어, 허용 그룹·사용자, 자동 생성, HTTP Basic Auth 동작 등은 여기서 관리하고 DB에 저장합니다.

제공업체가 전용 API 대상의 액세스 토큰을 발급한다면 API JWT audience를 설정하세요. 비우면 설정한 OIDC Client ID를 JWT 대상으로 허용합니다.

다음 설정은 .env에 남아 있습니다.

POZNOTE_OIDC_CLIENT_ID=your_client_id
POZNOTE_OIDC_CLIENT_SECRET=your_client_secret
POZNOTE_OIDC_DISABLE_NORMAL_LOGIN=false

로컬 비밀번호 양식을 숨기고 SSO만 강제하려면 POZNOTE_OIDC_DISABLE_NORMAL_LOGIN=true를 사용하세요. 비밀번호 인증을 차단하는 유일한 스위치로 양식을 제거하고 서버의 비밀번호 POST를 거부하며 “비밀번호 변경” 설정도 숨깁니다.

인증 제공업체 장애 복구. POZNOTE_OIDC_DISABLE_NORMAL_LOGIN=true이면 관리자도 비밀번호로 로그인할 수 없으며 브라우저의 우회 경로가 없습니다. 침해된 관리자 계정이 비밀번호 로그인을 다시 켜 지속적인 접근을 확보하지 못하도록 의도된 동작입니다. 복구에는 서버 접근이 필요합니다. .env에서 POZNOTE_OIDC_DISABLE_NORMAL_LOGIN=false로 바꾸고 컨테이너를 다시 시작한 뒤 로컬 비밀번호로 로그인하세요. 활성화 전에 최소 관리자 한 명에게 설정 > 관리자 도구 > 사용자 관리에서 비밀번호를 명시적으로 설정하세요. OIDC가 자동 생성한 관리자는 설정 전 비밀번호가 없습니다.

호환성 변경: .env의 기존 OIDC 설정은 POZNOTE_OIDC_CLIENT_ID, POZNOTE_OIDC_CLIENT_SECRET, POZNOTE_OIDC_DISABLE_NORMAL_LOGIN 외에는 읽지 않습니다. 업데이트 후 나머지는 관리자 페이지에서 다시 입력하세요.

인증 제공업체에 등록할 URL

인증 제공업체에서 애플리케이션(클라이언트)을 만들 때 아래 첫 번째 URL을 리디렉션 URI(콜백 URL)로 등록하고, 제공업체가 요구하면 두 번째 URL을 로그아웃 후 리디렉션 URI로 등록하세요.

https://YOUR_SERVER/oidc_callback.php
https://YOUR_SERVER/login.php

Poznote는 요청이 들어온 호스트 이름으로 두 URL을 만들며 항상 https://를 사용합니다. 제공업체에 다른 값이 필요하면 OIDC 관리 페이지의 고급 섹션에서 리디렉션 URI 또는 로그아웃 후 리디렉션 URI를 설정하고 정확히 그 값을 등록하세요.

디스커버리 URL은 보통 입력할 필요가 없습니다. Poznote가 발급자 URL 뒤에 /.well-known/openid-configuration을 붙입니다. 예를 들어 Authentik의 발급자는 https://AUTHENTIK_HOST/application/o/APPLICATION_SLUG/입니다. 제공업체가 이 문서를 다른 위치에 게시할 때만 디스커버리 URL을 설정하세요.

접근 제어 예시(그룹 + 자동 생성)

OIDC 관리자 페이지에서 다음을 설정하세요.

• 그룹 클레임: groups
• 허용 그룹: poznote
• 사용자 자동 생성: 활성화

자동 생성 시 OIDC 클레임(preferred_username, nickname, 이메일의 @ 앞부분, name, sub 순)으로 이름을 만들고 프로필에 OIDC subject를 저장합니다. SSO로 로그인한 적이 없는 기존 프로필이 이미 같은 preferred_username을 쓰고 있으면, 옆에 두 번째 프로필을 만드는 대신 로그인이 거부됩니다. 해당 프로필에 공급자가 보내는 이메일이나 OIDC subject를 입력하면 연결됩니다.

• 편집기: 결과를 바로 보며 편집하는 WYSIWYG 방식
• 저장: 사용자 데이터 디렉터리의 .html 파일. 표준 HTML이므로 웹 브라우저로 직접 열 수 있음
• 전용 기능:
  • 세부 서식: 글자색, 강조, 표준 HTML 요소 지원
  • 직접 조작: 편집기에서 요소를 바로 조작

• 편집기: 실시간 미리보기가 있는 마크다운 문법 편집기
• 저장: 사용자 데이터 디렉터리의 .md 파일
• 전용 기능:
  • Mermaid 다이어그램: ```mermaid 코드 블록으로 흐름도, 시퀀스 등 생성
  • 수식: $ inline $, $$ block $$ 문법의 LaTeX 수식 지원
  • 호환성: 외부 편집기와 정적 사이트 생성기에 호환되는 표준 마크다운

• 용도: 대화형 체크리스트로 할 일과 프로젝트 관리
• 진행 관리: 편집기나 노트 목록에서 체크박스를 직접 선택·해제하며 목록마다 진행률 표시
• 할 일 옵션: 날짜와 선택적 시간, 마감 시 알림, 우선순위(높음·보통·낮음, 빨강·주황·초록) 설정 및 다른 목록으로 이동
• 할 일 페이지: 왼쪽 아이콘 모음에서 열며 할 일 목록과 선택적으로 일반 노트의 체크박스를 모아 보여줍니다. 상태(미완료, 우선순위, 기한 지남, 마감일 있음, 완료)·텍스트 필터와 날짜가 있는 항목의 달력을 지원합니다. 제목의 눈 버튼으로 목록을 숨기고 숨긴 목록 표시로 다시 보일 수 있습니다. 설정은 계정에 저장되어 기기 간 유지됩니다.
• 공개 협업: 공개 URL로 공유하고 편집 권한을 주면 Poznote 계정 없이도 외부 사용자가 완료 표시 가능

• 기능: 다른 위치에 기존 노트의 참조 생성
• 용도: 한 노트를 두 위치에서 동시에 참조합니다. 분류 폴더에 보관하면서 칸반 보드에 바로가기를 두고 진행 상황을 관리할 수 있습니다.

• 기능: 전체 노트부터 짧은 문구까지 미리 작성한 내용을 재사용해 문서 형식 통일
• 설정: Templates 폴더나 하위 폴더에 재사용할 노트를 넣으세요. Templates라는 이름의 작업 공간도 지원하며 모든 공간에서 사용할 수 있습니다. UI 언어별 이름도 인식합니다(Modèles, Vorlagen, Plantillas, Modelos, Шаблоны, 模板, 템플릿, テンプレート).
• 노트에 삽입: 서식 있는 텍스트나 마크다운 노트에 /template 또는 / 뒤 템플릿 제목을 입력하고 선택하세요. 커서에 붙여 넣으며 형식이 다르면 변환합니다.
• 템플릿으로 새 노트: 템플릿 노트를 복제하거나 Templates 폴더 전체를 복제해 준비된 구조로 프로젝트 시작

• 용도: 전용 일기 보드에서 하루 한 노트 작성
• 작성 방식: “오늘 일기 작성”은 현재 날짜 제목의 노트를 Diary/YYYY/MM 구조에 자동 저장합니다. 이미 있으면 “오늘 일기로 이동”으로 바뀝니다.
• 다른 날: 보기 설정 옆의 달력 버튼으로 휴대폰에서도 원하는 날을 고를 수 있습니다. 이미 항목이 있는 날에는 점이 표시되며, 그날을 고르면 항목이 열리고 다른 날을 고르면 그 날짜의 항목이 만들어집니다.
• 보드 보기: 월별 카드로 최신순 표시하며 필터로 과거 항목 검색
• 일기 보기: 보기 설정 옆 스크롤 버튼으로 본문 전체를 한 열에 최신순 표시합니다. 스크롤하며 추가 항목을 불러오고 필터도 적용됩니다. 항목이나 연필을 누르면 즉시 편집하며 입력 중 자동 저장됩니다. 연필 옆 태그 버튼을 누르면 노트를 열지 않고도 항목의 태그를 추가하거나 제거할 수 있습니다.
• 형식: 설정 > 일기의 “일기 항목 형식”에 따라 서식 있는 텍스트 또는 마크다운으로 생성

• 이력: 왼쪽 열에는 수정 이력이 날짜별로 묶여 표시되며, 각 항목에 자동, 수동, AI 편집 전 또는 MCP 편집 전이라는 표시가 붙습니다. 현재 노트와 동일한 이력에는 “현재와 같음”, 바로 이전 이력과 동일한 이력에는 “변경 없음” 배지가 표시됩니다. 두 배지는 본문뿐 아니라 제목과 태그도 같아야 표시됩니다.
• 본문: 페이지를 열면 선택한 수정 이력을 렌더링한 본문 탭이 표시됩니다. Markdown 노트는 탭 옆의 미리 보기/원본 전환 버튼을 사용할 수 있습니다.
• 변경 사항: 두 번째 탭에서는 현재 버전, 이전 수정 이력 또는 다른 수정 이력과 줄 단위로 비교하고 변경된 단어를 강조합니다. 한 화면에서 비교하거나 나란히 비교할 수 있습니다. 변경 없는 줄은 접혀 있으며 클릭하면 펼쳐집니다. 이전/다음 변경 사항 버튼으로 이동할 수 있고 추가·삭제된 줄 수도 표시됩니다. Markdown 노트는 원본을, 서식 있는 텍스트 노트는 텍스트를 비교하므로 서식만 바뀐 경우에는 차이가 표시되지 않습니다. 비교 내용 위에는 제목 변경(이전 → 이후)과 두 버전 사이에 추가·제거된 태그가 표시됩니다.
• 작업: “작업” 메뉴에는 “이 수정 이력 복원”, “수정 이력 저장”, “본문 복사”, “이 수정 이력 삭제”가 있습니다. “수정 이력 저장”은 현재 본문을 즉시 저장하며 나머지는 선택한 이력에 적용됩니다.
• 복원: 해당 이력의 본문, 제목, 태그로 노트를 되돌립니다. 덮어쓰는 현재 상태는 저장되지 않으므로 보관하려면 먼저 작업 메뉴의 “수정 이력 저장”이나 Ctrl + Alt + S를 사용하세요. 복원된 제목에도 이름 변경 규칙이 적용되어 같은 폴더에 동일한 제목이 있으면 “(1)”과 같은 접미사가 붙습니다. 태그 기록 기능이 추가되기 전에 저장한 이력에는 태그가 없으며, 이를 복원해도 현재 태그는 유지됩니다.

• 자동: 노트를 열 때가 아니라 수정할 때 저장합니다. 본문·제목·태그 변경을 저장할 때마다(편집기의 자동 저장, 할 일 체크, 그림 저장, REST API, 공개 공유 링크에서의 편집) 변경 직전의 상태를 먼저 보관합니다. 단, 같은 노트의 이력을 지난 10분 안에 저장했다면 건너뜁니다. 따라서 편집 중에는 10분마다 최대 하나의 자동 이력이 생성되며 항상 변경 전의 상태를 담습니다. 열거나 읽기만 해서는 생성되지 않습니다. 빈 노트이거나 최신 이력의 본문·제목·태그가 현재 상태와 정확히 같으면 저장하지 않아 중복을 방지합니다. 이력에는 “자동”으로 표시되며, 이전 Poznote 버전에서 노트를 열 때 생성한 이력에도 같은 규칙이 적용됩니다.
• 예시: 9:00부터 9:35까지 편집하면 약 9:00(편집 시작 전 상태), 9:10, 9:20, 9:30의 이력이 생깁니다. 14:00에 돌아와 단어 하나를 바꾸면 14:00 이력은 9:35에 마친 상태를 보관합니다.
• 되돌릴 수 있는 상태: 편집을 마친 상태는 당시 노트 자체에 있으므로 그 순간 별도 이력으로 저장되지 않습니다. 다음 편집이 시작될 때, 시간이 얼마나 지났든 첫 변경이 그 상태를 보관합니다. 따라서 오늘 편집을 시작하기 전의 상태와 긴 편집 중 약 10분 이하 간격의 상태로 돌아갈 수 있습니다. 최신 상태는 항상 노트 자체이며, 이력을 “현재 버전”과 비교하면 이후 변경 내용을 볼 수 있습니다.
• 자동 이력 보관 기간: 최근 24시간의 자동 이력은 모두 보관합니다. 24시간이 지나면 날짜별로 가장 최근의 자동 이력 하나만 남기며 기본 30일 동안 보관합니다. 설정 > 작업 > 수정 이력에서 보관 일수를 1~30일로 변경할 수 있습니다. 이전 버전에서 보관 개수를 바꿨다면 값은 유지되지만 이제는 일수를 의미합니다.
• 수동: “수정 이력 저장”이나 열린 노트에서 Ctrl + Alt + S(Mac은 Cmd + Alt + S)로 언제든 저장할 수 있습니다. 수동 이력에는 개수 제한이 없고 하루 하나로 줄이지 않습니다. 30일 후 만료될 때만 삭제됩니다.
• AI 편집 전: AI 어시스턴트나 MCP 서버가 본문을 변경하기 직전에 저장합니다. 자동 이력이 10분 이내에 생성되었더라도 저장하므로 잘못된 재작성을 쉽게 복원할 수 있습니다. “AI 편집 전” 또는 “MCP 편집 전”으로 표시되며 최신 이력의 본문·제목·태그가 같으면 건너뜁니다.
• 편집 보호 이력: “AI 편집 전”과 “MCP 편집 전” 이력은 같은 한도를 공유하며 노트당 최근 20개를 보관합니다. AI나 MCP를 통한 편집이 많으면 설정 > 작업 > 수정 이력에서 1~200개로 변경할 수 있습니다.
• 만료: 종류와 관계없이 저장한 지 30일이 지나면 삭제됩니다. 수정 이력 페이지에서 직접 삭제할 수도 있습니다.
• 첨부 파일과 이미지: 본문·제목·태그만 저장하며 파일은 복사하지 않습니다. 여러 이력이 참조해도 디스크에는 파일 하나만 있습니다. 노트에서 제거한 파일은 이를 포함한 이력이 남아 있는 동안 숨긴 상태로 보관하므로 해당 이력을 복원하면 다시 나타납니다. 마지막 참조 이력이 만료·삭제되거나 노트가 영구 삭제되면 파일도 영구 삭제됩니다. 이력을 더 보관해도 파일은 복제되지 않으며 제거된 파일을 최대 30일 동안 더 보관할 뿐입니다.
• API와 MCP: REST API와 MCP 서버 도구에서는 수정 이력을 여전히 “snapshots”라고 부릅니다(/notes/{id}/snapshots, list_snapshots, get_snapshot, restore_snapshot).

설정 > 화면 표시의 항목:

• 앱 글꼴: UI 전체 글꼴 선택
• 글꼴 크기: 노트·사이드바·코드 블록·설정 페이지의 크기 조절
• 인덱스 아이콘 크기 조정: 노트 목록의 아이콘 크기 조절
• 아이콘 사이드바 아이콘 크기: 왼쪽 아이콘 사이드바의 아이콘 크기 조절
• 노트 색상: 노트에 사용할 색상표 선택
• 로그인 페이지 제목: 표시 제목 변경 (관리자 전용)

설정 > 사이드바의 항목:

• 현재 폴더 트리 강조 표시: 작업 중인 폴더 계층 밖의 노트·폴더를 흐리게 표시
• 아이콘 사이드바 레이아웃: 왼쪽 버튼 순서와 색상 변경 (오른쪽 클릭으로 색상 선택 가능)
• 노트 날짜 필터: 지정한 일수 안에 갱신된 노트만 표시
• 폴더 뒤에 노트 표시: 폴더 없는 노트를 폴더 목록 아래에 표시
• 폴더 아이콘으로 칸반 보기 열기: 폴더 아이콘 클릭 시 아이콘 선택기 대신 칸반 보기 열기
• 오프라인 점 표시: 오프라인으로 사용 가능한 노트 옆에 작은 점 표시

설정 > 노트 내용의 항목:

• 노트 내용 폭: 편집 영역 최대 너비 지정
• 노트 아래 여백: 텍스트 끝을 화면 중앙까지 스크롤할 수 있게 마지막 줄 아래 여백 추가
• 백링크를 하단에 표시: 노트 상단 대신 하단에 백링크 표시
• 기본 이미지 테두리: 추가 여백 없이 삽입 이미지에 테두리 표시
• 맞춤법 검사: 서식 있는 텍스트 노트에서 브라우저 맞춤법 검사 활성화
• 명령 메뉴 바로가기(컴퓨터): 컴퓨터에서 슬래시(/) 명령 메뉴를 여는 키보드 입력 방식 설정
• 명령 메뉴 바로가기(모바일): 모바일에서 명령 메뉴를 여는 키보드 입력 방식 설정. 설정과 관계없이 키보드 위 도구 모음의 + 버튼으로도 열 수 있음
• 서식 도구 모음: 텍스트 선택 시 서식 버튼이 표시될 위치(노트 도구 모음 또는 선택 영역 위 플로팅 메뉴) 선택
• 할 일 추가 위치: 새 할 일을 넣을 위치(맨 위 또는 맨 아래)
• 첨부 파일을 하단에 표시: 첨부 파일을 노트 본문 아래에 표시
• 첨부 파일 미리보기: 노트 안에서 미리보기 표시
• 코드 블록 단어 줄 바꿈: 자동 줄 바꿈 활성화·해제
• 코드 블록 줄 번호: 코드 블록에 줄 번호 표시

설정 > 마크다운에서 기본 보기 모드, 마크다운 편집기 글꼴, 마크다운 영역 테두리, 왼쪽에서 미리보기, 마크다운 구문 색상 표시를 설정할 수 있습니다.

기타 설정 구역:

• 설정 > 내 계정: UI 언어, 시간대, 날짜 및 시간 형식
• 설정 > 작업: 수정 이력(자동 보관 일수 및 편집 보호 개수), 오프라인 노트
• 설정 > 일기: 일기 항목 형식(서식 있는 텍스트 또는 마크다운), 일기 입력 날짜 형식
• 설정 > 화면 요소 표시: 쓰지 않는 UI 요소 숨김 (아래 화면 요소 표시 참고)

(참고: 노트 정렬은 설정이 아닌 사이드바 제목 행의 정렬 버튼에서 전체 트리의 정렬 방식을 변경합니다.)

테마는 별도 카드가 아닙니다. 왼쪽 아이콘 모음 맨 아래 버튼으로 순환하며 관리자는 설정 > 관리자 도구 > 테마 목록에서 제공할 테마를 고릅니다.

설정 > 작업 공간의 배경 작업에서 이미지를 올리고 불투명도를 조절하면 작업 공간마다 다른 배경을 사용할 수 있습니다.

쓰지 않는 요소를 숨겨 화면을 간결하게 만들 수 있습니다.

설정 > 화면 요소 표시에서 설정하세요.

• 세부 제어: 홈 카드, 도구 모음, 슬래시 메뉴 등을 숨깁니다. 생성일 표시와 폴더별 노트 수 표시도 여기서 조절합니다.
• 사용자별 설정: 각자 다른 화면 구성을 사용 가능
• 관리자: “나” 옆에 “사용자” 열이 표시되어 관리자 외 모든 사용자에게 요소 숨김 적용 가능
• 검색: 설정 창 필터로 숨길 요소 검색

Poznote에는 기본 글꼴로 Inter가 포함되어 있으며 기기에 설치된 글꼴도 사용할 수 있습니다. Google Fonts에서 내려받은 글꼴처럼 다른 글꼴을 사용하려면 관리자가 글꼴 파일을 한 번 업로드하면 되며, 이후 모든 사용자가 해당 글꼴을 선택할 수 있습니다.

설정 > 관리자 도구 > 사용자 지정 글꼴에서 업로드한 뒤 설정 > 화면 표시 > 앱 글꼴 또는 설정 > 마크다운 > 마크다운 편집기 글꼴에서 글꼴을 선택하세요.

참고 사항:

• 지원 형식은 WOFF2, WOFF, TTF, OTF이며 파일당 최대 10MB
• 글꼴은 여러 스타일 파일(일반체, 굵은체, 이탤릭체 등) 또는 가변 글꼴 파일 하나로 구성됩니다. 같은 글꼴에 속한 파일을 한 번에 모두 선택해 업로드하면 글꼴 이름으로 묶입니다.
• 글꼴은 사용 중인 인스턴스에서 직접 제공하며 Google 등 제3자에서 불러오는 것은 없습니다. 먼저 Google Fonts(Get font > Download all) 또는 google-webfonts-helper에서 글꼴 파일을 내려받으세요.
• 굵은체 파일이 없는 글꼴은 굵은 텍스트와 제목에 기본 글꼴을 유지하므로 굵은체 파일도 함께 업로드하세요.
• 파일은 Docker 볼륨의 data/fonts/에 저장되어 이미지 업데이트 후에도 유지됩니다. 직접 복사해 넣은 파일은 사용자 지정 글꼴 창을 열 때 인식됩니다.
• 글꼴은 사용자마다 따로 선택합니다. 등록된 글꼴을 삭제하면 그 글꼴을 선택했던 사용자는 기본 글꼴로 돌아갑니다.
• 업로드와 삭제는 관리자만 가능

기본 옵션 이외의 글꼴·간격·모양을 바꾸려면 모든 사용자의 HTML 페이지에 적용할 스타일시트를 업로드할 수 있습니다.

설정 > 관리자 도구 > 사용자 지정 CSS 경로에서 설정하세요.

참고 사항:

• CSS 파일 업로드로 컴퓨터의 .css 선택
• 업로드 파일을 모두 보관하므로 여러 테마를 다시 올리지 않고 전환 가능
• 목록에서 전체 사용자에게 적용할 파일 또는 사용자 CSS 없음을 선택한 뒤 저장
• 같은 이름의 파일을 올리면 기존 테마 교체
• Docker 볼륨의 data/css/에 저장되어 이미지 업데이트 후에도 유지
• 테마 옆 휴지통으로 볼륨의 파일 삭제
• 캐시 갱신용 v= 매개변수 자동 추가
• <head> 끝부분에 넣어 기본 스타일을 덮어쓸 수 있음
• 업로드·적용·삭제는 관리자만 가능

테마 목록

설정 > 관리자 도구 > 테마 목록은 아이콘 모음 맨 아래 테마 버튼의 순환 순서를 정합니다. 한 번 누를 때 다음 테마로 이동합니다.

• 사용할 기본 테마만 선택
• 저장한 CSS를 선택하면 색상표 아이콘과 파일명으로 별도 테마 제공
• 화살표로 순서 변경
• 사용자 테마는 밝은·어두운 기본 테마 위에 적용합니다. CSS 자체로 판단할 수 없으므로 파일 옆에서 선택하세요. 이 값이 data-theme가 되며 다크 모드 CSS는 다크를 선택해야 합니다.
• 목록은 전역 설정이지만 적용할 테마는 사용자마다 선택
• 목록에서 제거한 테마를 쓰던 사용자는 첫 테마로 즉시 전환
• 사용자 테마를 선택하면 인스턴스 전체 CSS 대신 본인에게만 해당 파일 적용
• CSS를 삭제하면 목록에서도 제거
• 테마가 하나뿐이면 관리자에게 목록을 열고 다른 사용자에게는 아무 동작도 하지 않음

CSS 작성 전 기본 테마가 원하는 기능을 제공하는지 확인하세요. 버튼으로 밝게, 어둡게, 검정, 라벤더, 세피아, 터미널을 순환합니다.

예시

색상, 간격, 모서리, 글꼴 두께는 디자인 토큰이므로 대부분 선택자 수정 대신 변수 몇 개를 덮어쓰면 됩니다. 전체 목록은 src/public/css/tokens.css에 있습니다.

강조 색상 변경

:root {
    --pz-accent: #d6336c;
    --pz-accent-hover: #a61e4d;
    --pz-accent-rgb: 214, 51, 108;   /* same colour, channels only, used for tints */
}
html[data-theme='dark'] {
    --pz-accent-text: #f783ac;       /* lighter, because it sits on a dark ground */
}

채우기와 글자색은 같을 수 없어 두 토큰을 사용합니다. --pz-accent는 버튼 배경, --pz-accent-text는 글자·아이콘·외곽선입니다. 밝은 테마는 자동으로 --pz-accent를 따르지만 어두운 배경은 더 밝은 값이 필요합니다. 테마마다 --pz-* 이름은 같고 값만 달라집니다. 이전 --dm-* 이름도 계속 작동합니다.

노트 도구 모음 아이콘 색상 변경

.note-edit-toolbar .toolbar-btn i,
.note-edit-toolbar .toolbar-btn [class*="lucide-"],
.note-edit-toolbar .toolbar-btn:hover i,
.note-edit-toolbar .toolbar-btn:hover [class*="lucide-"] {
    color: #e5322d !important;
}

아이콘은 background-color: currentColor인 CSS 마스크라 color만 설정하면 됩니다. 즐겨찾기 별, 공개 공유, 첨부 파일 클립처럼 상태에 따른 자체 색상이 있어 여기에는 !important가 필요합니다.

아이콘 하나의 색상은 CSS 없이 도구 모음이나 사이드바에서 오른쪽 클릭으로 변경할 수 있습니다. 사용자별로 저장되며 위 상태 색상은 유지됩니다.

화면 전체에 따뜻한 색감 적용

:root {
    --pz-bg: #f6ecd8;          /* page and note background */
    --pz-surface: #efe0c4;     /* panels, cards, menus */
    --pz-text: #3b2c1a;
    --pz-border: #d4bd94;
}

전체 테마 작성

밝은 테마는 :root, 어두운 테마는 :root[data-theme='dark']의 토큰만 덮어쓰세요. src/public/css/README.md에 전체 설명과 예시가 있습니다. src/public/css/tokens.css의 라벤더·세피아·터미널도 같은 방식입니다.

일부 기능은 사용자가 입력한 주소로 Poznote 서버가 직접 연결합니다. 웹훅, Git Sync, 사용자의 개인 AI·전사·MCP 서버가 그렇습니다. 요청은 사용자의 브라우저가 아니라 서버에서 나갑니다. 제한이 없으면 어떤 계정이든 Poznote를 통해 서버 자체, 다른 Docker 컨테이너, 로컬 네트워크, 클라우드 메타데이터 서비스처럼 스스로는 닿을 수 없는 곳에 접근할 수 있습니다.

그래서 규칙은 주소를 입력한 사람에 따라 달라집니다.

• 관리자는 제한이 없습니다. 이미 서버를 제어하고 있기 때문입니다.
• 다른 사용자는 공개 인터넷 호스트만 사용할 수 있습니다. 로컬 또는 사설 주소는 거부됩니다. localhost와 127.0.0.1, 10.x.x.x, 172.16.x.x~172.31.x.x, 192.168.x.x, 169.254.x.x, 로컬 IPv6 주소(fc00::/7, fe80::/10), 그리고 이 중 하나를 가리키는 모든 이름(예: 다른 Docker 서비스 이름)이 해당합니다.

관리자가 인스턴스 전체에 설정한 항목(AI 어시스턴트, 전사, 관리자 웹훅, S3, OIDC, SMTP)은 영향을 받지 않습니다.

가족·팀 인스턴스에서는 사용자가 네트워크 안의 서버를 써야 할 수 있습니다. 예를 들어 개인 AI용 Ollama 서버나 웹훅용 n8n입니다. 이런 호스트를 설정 > 관리자 도구 > 연동 > 로컬 네트워크 접근에 한 줄에 하나씩 입력하세요.

항목 하나는 해당 호스트의 모든 포트를 허용합니다. 잘못된 항목은 저장할 때 거부되며 고쳐야 할 항목이 표시됩니다. 목록이 비어 있으면 카드에 공개 호스트만이, 그렇지 않으면 항목 수가 표시됩니다.

알아 두기:

• 목록의 호스트 이름은 내 컴퓨터뿐 아니라 Poznote 컨테이너 안에서도 확인할 수 있어야 합니다. 내 컴퓨터나 공유기만 아는 이름은 Poznote가 확인할 수 없어 알 수 없는 이름처럼 거부됩니다. 대신 주소나 네트워크를 입력하세요.
• 주소는 저장할 때만이 아니라 연결할 때마다 다시 확인됩니다. 항목을 지우면 바로 적용되고, 나중에 로컬 주소를 가리키게 된 이름도 거부됩니다.
• 일반 사용자의 경우 Poznote는 리디렉션을 따라가지 않습니다. 단, Git Sync는 리디렉션의 각 단계를 다시 확인하며 따라갑니다.

공유 관리 정보는 마스터 DB data/master.db, 실제 노트는 사용자별 DB와 파일에 저장합니다.

data/
├── master.db                    # Profiles, global settings, shared links, account access, edit locks
├── css/                         # Custom CSS files uploaded by an administrator
├── fonts/                       # Custom fonts uploaded by an administrator
├── backups/                     # Scheduled local backups, one folder per user ID
└── users/
    ├── 1/                       # User ID 1 (default admin)
    │   ├── database/poznote.db  # User's notes database
    │   ├── entries/             # User's note files (HTML/MD)
    │   ├── attachments/         # User's attachments
    │   ├── snapshots/           # Earlier versions of the user's notes (revisions)
    │   ├── backgrounds/         # Workspace background images
    │   └── backups/             # Backup archives prepared for download
    ├── 2/                       # User ID 2
    └── ...

1단계: 관리자 활성화(설정 > 관리자 도구)

설정의 관리자 도구에서 Git 동기화를 켜면 전역으로 활성화되고 각 사용자 설정에 카드가 나타납니다.

2단계: 사용자별 저장소 설정(설정 > 작업 > Git 동기화)

🔒 토큰은 AES-256-GCM으로 암호화해 저장합니다. 암호화 키는 data/.app_secret에 자동 생성합니다.

자동 동기화

사용자가 켜면 자동으로 다음을 수행합니다.

• 로그인 시 가져오기(풀)
• 노트 생성·수정·삭제 시 푸시(보내기)

왼쪽 아이콘 모음의 푸시·가져오기 버튼으로 수동 실행도 가능합니다.

동기화할 작업 공간

기본적으로 모든 공간을 동기화합니다. 사용자는 설정 > 작업 > Git 동기화에서 일부 공간만 선택할 수 있습니다.

• 선택한 공간의 노트와 첨부 파일만 보내고 가져옴
• 가져오기는 다른 공간의 노트를 변경하지 않음
• 보내기는 선택 범위 밖의 파일을 저장소에서 제거하여 정확히 선택한 데이터만 반영
• 동기화 대상 공간에서만 사이드바 버튼, 자동 보내기, 가져오기 안내 표시

관리자 전용 설정 > 관리자 도구 > S3 첨부 파일에서 설정하세요.

• 설정: 엔드포인트 URL, 리전, 버킷, 액세스 키, 비밀 키, 경로 방식 주소 지정 및 연결 시험
• 이동: 모든 사용자의 첨부 파일을 로컬과 버킷 사이에서 양방향 이동. 일괄 처리하며 중단·재개 가능
• 개인정보: 버킷의 attachments/{user id}/에 저장하고 항상 Poznote를 통해 제공하므로 버킷은 비공개 유지 가능
• 사용 한도: 사용자별 S3 한도와 관리자 저장 공간 통계 지원
• 백업: 백업 창, REST API, 자동 S3 백업의 ZIP은 기본적으로 S3 첨부를 즉시 가져와 포함합니다. 백업 창에서 제외해 크기를 줄일 수 있습니다. 생성 중 버킷을 읽지 못하면 파일이 빠진 백업 대신 오류로 실패합니다.

S3가 켜져 있으면 참조된 첨부 파일 일부가 없는 백업의 복원을 거부합니다. 전체 복원이 버킷 내용을 교체해 누락 파일을 잃을 수 있기 때문입니다. 다음 중 하나로 복원하세요.

• 간단한 방법: 인증 정보는 유지하고 “S3에 첨부 파일 저장”을 끈 뒤 복원하고 다시 켜세요. 로컬 복원은 버킷을 건드리지 않으며 기존 S3 파일도 계속 제공합니다. 버킷이 정상인 새 서버에서도 적합합니다. 다음 방법의 첨부 내보내기는 노트 정보를 가진 인스턴스가 필요합니다.
• 완전한 백업 다시 구성:
  1. 백업 창에서 첨부 파일 내보내기 다운로드. 계정의 모든 첨부를 files/에 포함합니다.
  2. 백업을 풀고 files/ 내용을 attachments/에 복사한 뒤 다시 ZIP으로 만드세요. 상위 폴더 대신 내부 내용(database/, entries/, attachments/, ...)을 선택해 압축해야 합니다. ZIP 루트에 해당 폴더가 없으면 database/poznote_backup.sql 누락 오류가 발생합니다.
  3. 새 ZIP을 일반 방식으로 복원하세요.

S3 저장이 켜져 있으면 Git 동기화는 첨부 파일을 제외합니다.

해당 계정의 모든 작업 공간 DB, 노트, 첨부 파일을 ZIP 하나에 포함합니다.

• 루트의 index.html로 오프라인 탐색
• 작업 공간과 폴더별 노트 정리
• 링크로 첨부 파일 접근

요청 중이 아닌 백그라운드 작업자가 생성하므로 큰 계정도 브라우저·프록시 시간 제한에 걸리지 않습니다. 페이지에서 진행률을 표시하며 준비되면 자동 다운로드합니다. 페이지를 떠나도 계속되며 돌아와 확인할 수 있습니다. 완성 파일은 24시간 보관하고 버튼으로 즉시 지울 수도 있습니다.

사용자별 백업과 시스템 전체 백업

위 방법은 모두 사용자별 백업을 만듭니다. 아카이브 하나에는 계정 하나의 데이터(DB, 노트, 첨부 파일)만 들어 있습니다. 모든 사용자는 본인 계정을 백업·복원할 수 있고, 관리자는 어떤 계정이든 고를 수 있습니다. 관리자의 아카이브에는 업로드한 인스턴스 로고도 들어 있으며, 관리자 계정에 복원하면 그 로고가 다시 적용됩니다.

주 설정(계정, 전역 설정, 공유 링크)과 모든 사용자를 한 번에 담는 전체 시스템 백업은 /data 디렉터리 전체를 복사해서 만듭니다.

# CLI로 시스템 전체 백업
tar -czvf poznote-full-backup.tar.gz data/

관리자는 "Poznote ZIP 파일로 백업"으로 다운로드하는 것과 같은 사용자별 ZIP을 서버의 폴더에 수동 또는 예약으로 저장하고 최신 백업만 보관하도록 설정할 수 있습니다. Poznote 외에는 아무것도 필요하지 않습니다. 버킷도, cron 작업도, 스크립트도 필요 없습니다.

관리자 전용 설정 > 관리자 도구 > 서버 백업에서 설정하세요.

• 백업 폴더: 서버의 절대 경로입니다(Docker를 사용하는 경우 컨테이너 내부 경로). 비워 두면 아카이브는 이미 데이터 볼륨에 포함된 data/backups에 저장됩니다. 폴더는 필요하면 자동으로 만들어지며 웹 서버 사용자가 쓸 수 있어야 합니다.
• 사용자 선택: 체크박스로 백업 대상 사용자를 고릅니다. 기본으로 모두 선택되어 있으며, 모두 선택된 동안에는 새 계정도 자동으로 포함됩니다.
• 수동 백업: "지금 백업" 버튼은 선택한 사용자마다 새 아카이브를 한 명씩 저장하고 사용자별 진행 상황을 보여 줍니다. 자동 백업이 꺼져 있어도 동작합니다.
• 자동 백업: 켜면 백그라운드 worker가 선택한 주기(매일, 매주, 매월)로 선택한 사용자를 백업합니다. 첫 실행은 켠 뒤 몇 분 안에, 이후 실행은 선택한 간격마다 이루어집니다. 페이지에는 마지막 실행 결과와 다음 실행 날짜가 표시됩니다.
• 보관: 사용자별로 최신 아카이브 N개만 보관하고, 더 오래된 것은 백업할 때마다 폴더에서 삭제합니다(0은 모두 보관).
• 탐색: 페이지에 폴더에 있는 아카이브가 나열되며 다운로드와 삭제를 할 수 있습니다.
• 복원: 아카이브는 백업 폴더의 {user id}/ 아래에 저장되며 표준 복원 / 가져오기 페이지에서 복원할 수 있습니다.
• 계정 삭제: 계정을 삭제하면 백업 폴더에 있는 해당 계정의 아카이브도 삭제됩니다.

백업을 다른 디스크나 네트워크 공유에 보관하려면 컨테이너에 마운트하고 컨테이너 쪽 경로(이 예에서는 /backups)를 백업 폴더로 입력하세요.

services:
  webserver:
    volumes:
      - "./data:/var/www/html/data"
      - "/mnt/nas/poznote-backups:/backups"

애플리케이션 자체 안에 있는 폴더는 data/backups를 제외하고 거부됩니다. 첨부 파일을 S3에 저장하는 경우(S3 첨부 파일 저장) 아카이브에 포함되며 버킷에서 바로 가져옵니다.

관리자는 “Poznote ZIP 파일로 백업”으로 다운로드하는 것과 같은 사용자별 ZIP을 S3 호환 버킷에 수동 또는 예약으로 보낼 수 있습니다. 첨부 저장과 독립된 설정이라 다른 버킷·제공업체를 사용할 수 있습니다.

관리자 전용 설정 > 관리자 도구 > S3 백업에서 설정하세요.

• 전체 스위치: 끄면 자동 백업이 중지되고 모든 사용자에게 S3 백업·복원 영역이 사라집니다. 서버도 직접 요청을 거부합니다.
• 설정: 엔드포인트 URL, 리전, 버킷, 액세스 키, 비밀 키, 경로 방식 주소 지정 및 연결 시험
• 사용자 선택: 기본은 전체 선택이며 전체 선택 상태에서는 새 계정도 자동 포함
• 수동 백업: “지금 백업”으로 선택한 사용자별 새 백업을 순서대로 올리고 진행률 표시. 연결만 설정되면 자동 백업이 꺼져 있어도 사용 가능
• 자동 백업: 백그라운드 작업자가 일·주·월 간격으로 실행. 최초는 활성화 후 몇 분 안에, 이후는 선택한 간격마다 실행
• 보관: 사용자별 최근 N개만 유지하고 매 백업 후 오래된 파일 삭제. 0은 모두 유지
• 목록: 버킷의 백업 조회·다운로드·삭제
• 복원: backups/{user id}/에 저장하며 일반 복원 / 가져오기 페이지에서 복원
• 사용자 직접 관리: 버킷 설정 후 각 사용자의 백업 페이지에 “S3에 백업”이 나타나 본인 계정의 생성·다운로드·삭제가 가능합니다. 복원 페이지의 “S3에서 복원”은 해당 파일에서 직접 복원합니다.
• 사용자 기능 제한: “백업 페이지의 S3 백업”과 “복원 페이지의 S3 복원”으로 일반 사용자 기능을 차단합니다. 직접 호출도 서버에서 거부합니다.

첨부가 S3에 있으면 기본적으로 백업에 포함합니다. 제외 옵션으로 크기를 줄이고 실행을 빠르게 할 수 있습니다.

API 예약 백업에는 포함된 backup-poznote.sh를 사용할 수 있습니다.

중요: API 백업 생성은 관리자만 가능합니다. 인증할 관리자 프로필의 현재 비밀번호를 사용하세요. 새 설치는 변경 전 admin이며 변경 후에는 지정한 비밀번호가 필요합니다.

위치: 저장소 tools 폴더의 backup-poznote.sh

관리자 사용 방법:

관리자는 사용자 ID를 몰라도 사용자 이름만으로 모든 프로필을 백업할 수 있습니다.

# 본인 프로필 백업
bash backup-poznote.sh 'https://poznote.example.com' 'admin' 'admin_password' 'admin' '/backups' '30'

# 다른 사용자 프로필(Nina) 백업
bash backup-poznote.sh 'https://poznote.example.com' 'admin' 'admin_password' 'Nina' '/backups' '30'

사용법:

bash backup-poznote.sh '<poznote_url>' '<admin_username>' '<admin_password>' '<target_username>' '<backup_directory>' '<retention_count>'

crontab 예시(관리자가 Nina 백업):

# 하루 두 번 자동 백업하도록 crontab에 추가
0 0,12 * * * bash /root/backup-poznote.sh 'https://poznote.example.com' 'admin' 'admin_password' 'Nina' '/root/backups' '30'

매개변수:

• 'https://poznote.example.com': 인스턴스 URL
• 'admin': 관리자 사용자 이름
• 'admin_password': 현재 관리자 비밀번호. 변경 전 admin, 이후 지정한 값
• 'Nina': 백업할 사용자 이름
• '/root/backups': 백업 상위 경로. backups-poznote-<username> 폴더 생성
• '30': 유지할 개수. 오래된 백업 자동 삭제

처리 순서:

1. 관리자 인증
2. 사용자 이름으로 ID 자동 조회
3. API로 백업 생성
4. X-User-ID 헤더를 포함해 REST API v1의 POST /api/v1/backups 호출
5. 로컬 backups-poznote-<username>/에 ZIP 다운로드
6. 지정한 최근 개수만 유지하도록 자동 관리

참고: 사용자별 별도 폴더에 저장합니다(backups-poznote-Nina, backups-poznote-Tim 등).

노트 도구 모음의 내보내기를 사용하세요.

• 서식 있는 텍스트: HTML 또는 이미지를 내장한 단일 HTML
• 마크다운: 마크다운, HTML, 이미지 내장 단일 HTML
• 할 일 목록: 같은 형식과 원본 JSON

전체 백업 ZIP을 올려 복원하세요.

• DB 교체 및 모든 노트·첨부 파일 복원
• 모든 작업 공간을 한 번에 처리

실질적인 크기 제한은 없습니다. 조각 업로드 중 실패한 조각만 재시도하며 서버에서 합친 뒤 백그라운드 작업자가 압축 해제·복원합니다. 브라우저나 앞단 프록시의 요청 시간 제한에 복원이 중단되지 않습니다. 업로드·압축 해제·DB·노트·첨부 파일 전체 진행률을 표시하고 완료 후 열 작업 공간을 묻습니다.

S3 백업의 버킷 복원도 같은 백그라운드 방식이라 큰 파일을 받거나 복원할 때 단일 요청 유지에 의존하지 않습니다.

업로드가 전혀 안 되면 “직접 복사로 복원”을 사용할 수 있습니다. SSH로 컨테이너의 정확한 경로 /tmp/backup_restore.zip에 복사하고 페이지를 다시 불러와 복원하세요.

HTML·마크다운·텍스트 노트를 하나 이상 직접 가져오세요.

• .html, .md, .markdown, .txt, .json 지원
• 한 번에 기본 50개. 설정 > 관리자 도구 > 가져오기 제한에서 변경 가능

여러 노트가 담긴 ZIP을 가져오세요.

• .html, .md, .markdown, .txt 지원
• 기본 300개까지. 설정 > 관리자 도구 > 가져오기 제한에서 변경 가능
• 폴더 구조 자동 감지·재생성

실질적인 ZIP 크기 제한은 없습니다. 전체 복원처럼 조각 업로드·실패 조각 재시도·서버 병합 후 백그라운드 처리하므로 브라우저나 프록시 시간 제한으로 중단되지 않습니다. 업로드·이미지와 첨부·노트 처리의 전체 진행률을 표시합니다.

Obsidian 보관함은 마크다운 파일 폴더이므로 ZIP 하나로 그대로 가져올 수 있습니다.

순서

1. 보관함 폴더를 ZIP으로 압축하세요. .obsidian, .trash 같은 숨긴 폴더는 무시하므로 먼저 정리할 필요가 없습니다.
2. 설정 > 작업 > 복원/가져오기의 파일·ZIP 가져오기에서 대상 작업 공간을 선택하고 ZIP을 가져오세요. 새 빈 공간이면 결과 확인이 쉽습니다. 기본 페이지의 노트 목록에 ZIP을 끌어다 놓아도 같습니다.
3. 완료 요약에서 노트·폴더·이미지·PDF 개수와 가져오지 못한 파일 이름을 확인하세요.

ZIP에는 기본 300개 노트를 포함할 수 있습니다(이미지·PDF 제외). 관리자는 설정 > 관리자 도구 > 가져오기 제한에서 늘릴 수 있습니다. 크기 제한은 없습니다. ZIP 가져오기를 참고하세요.

가져오는 항목

• 노트: .md마다 파일명 또는 front matter의 title을 제목으로 마크다운 노트 생성
• 폴더: 하위 폴더까지 구조 재생성. ZIP의 최상위 폴더 하나에 모두 들어 있으면 해당 폴더는 생략
• 태그: front matter의 tags 및 노트 맨 위 #tags 행. 태그 공백은 밑줄로 변경
• Front matter: title, folder, tags, favorite, created, updated. 마크다운 Front Matter 참고
• 노트 간 링크: [[Note title]]를 제목으로 연결하고 내부 링크·백링크·그래프에 반영
• 이미지: ![[image.png]], ![[image.png|caption]], ![caption](image.png)를 첨부하고 원래 위치에 표시. 노트 옆·하위 폴더·attachments 등 저장 위치 무관
• PDF: ![[file.pdf]], [[file.pdf]], 마크다운 링크로 참조하면 해당 노트에 첨부하고 링크를 변경합니다. 노트 옆이나 attachments 폴더의 나머지 PDF는 파일명 제목의 새 노트를 보관함의 대응 폴더에 생성하고 첨부합니다.

가져오지 않는 항목

• 별칭·제목 링크([[Note|alias]], [[Note#Heading]])는 텍스트에 남지만 연결되지 않음
• 노트 임베드(![[Other note]])와 플러그인 콘텐츠: Dataview 쿼리, .canvas, Obsidian Excalidraw 그림
• 본문 중간 태그는 일반 텍스트 유지
• 노트 옆 오디오·동영상·Office 문서 등은 무시. 가져온 뒤 직접 첨부

이미지와 PDF는 경로가 아닌 파일명으로 찾습니다. 이름이 같은 파일이 둘이면 먼저 하나를 바꾸세요.

마크다운에 YAML front matter로 메타데이터를 지정할 수 있습니다. 지원 키:

• title: 제목 변경. 기본은 확장자 없는 파일명
• folder: 대상 폴더 변경. 단일 이름은 기존 폴더와 일치해야 하며 Projects/2026 같은 경로는 필요한 폴더 생성
• tags: 태그 배열. [tag1, tag2] 및 여러 줄 문법 지원
• favorite: 즐겨찾기 표시(true 또는 false)
• created: 생성 시각(YYYY-MM-DD HH:MM:SS)
• updated: 수정 시각(YYYY-MM-DD HH:MM:SS)

한 줄 배열 예시:

---
title: My Important Note
folder: Projects
tags: [important, work]
favorite: true
created: 2024-01-15 10:30:00
updated: 2024-01-20 15:45:00
---

여러 줄 예시:

---
title: My Important Note
folder: Projects
tags:
  - important
  - work
favorite: true
created: 2024-01-15 10:30:00
updated: 2024-01-20 15:45:00
---

최근 5일간 수정한 노트가 사용하는 브라우저마다 보관되고 저장할 때마다 갱신됩니다. 교실·기차 등 Wi-Fi가 없는 곳에서도 평소 주소로 접속하면 같은 사이드바·편집기·도구 모음·검색·탭의 오프라인 화면이 열리고 보관한 노트만 표시됩니다. 두 번 클릭이나 가운데 클릭으로 새 탭을 열 수 있으며 온라인에서 열었던 탭도 복원됩니다.

• 로그인: 이 브라우저에서 마지막 로그인한 비밀번호를 서버 없이 확인합니다. SSO·자동 로그인 등으로 입력한 적이 없으면 해당 사용자로 계속 버튼으로 마지막 계정을 엽니다.
• 읽기·편집: 서식 있는 텍스트, 마크다운, 할 일 목록은 일반 편집기로 열며 새 노트도 만들 수 있습니다. /와 오른쪽 클릭 메뉴도 작동하지만 업로드·템플릿·그림·다른 노트 링크처럼 서버가 필요한 명령은 제외합니다. 그림 등 다른 유형은 온라인 전용입니다. 변경은 전송 전까지 브라우저에 보관합니다.
• 오프라인 보관: 즐겨찾기는 항상 보관합니다. 노트·폴더 메뉴의 오프라인 보관은 날짜와 관계없이 하위 폴더와 파일당 25 MB까지 모든 첨부(PDF·오디오·파일)를 보관합니다. 메뉴 및 노트·폴더 페이지에 현재 브라우저의 보관 상태를 표시합니다. 노트 페이지의 일괄 작업으로 여러 노트의 보관을 켜거나 끌 수 있습니다.
• 오프라인 페이지: 사이드바의 오프라인에서 폴더 트리, 보관 이유(직접·폴더·즐겨찾기·최근 수정), 필터, 보관·해제 버튼을 제공합니다. 아직 이 브라우저에 없는 노트는 경고 아이콘으로 표시합니다.
• 재연결: 변경을 자동 전송합니다. 그동안 서버에서도 수정했으면 가능할 때 병합하고, 아니면 오프라인 버전을 “... (offline copy)”라는 별도 노트로 보관합니다. 서버에서 삭제된 노트는 다시 생성합니다.
• 설정: 설정 > 작업 > 오프라인 노트에서 보관 일수(기본 5, 최대 30, 0은 비활성화)와 현재 브라우저 보관 내용을 확인합니다.
• 한도: 최근 수정순 최대 300개, 본문 50 MB입니다. 표시 이미지와 즐겨찾기·직접 보관 노트의 모든 첨부는 파일당 25 MB, 최대 400개·200 MB이며 브라우저 여유 공간의 절반을 넘지 않습니다. 큰 파일은 온라인 전용이고 오프라인 열기 시 안내합니다.
• 요구 사항: HTTPS 또는 http://localhost로 제공하고, 브라우저에서 온라인 로그인 후 한 번 열어 사본을 만들어야 합니다.
• 개인정보: 공유받은 계정·공간이 아닌 본인 노트만 보관하며 브라우저에 암호화 없이 저장합니다. 로그아웃하면 미전송 변경까지 경고 후 삭제합니다. 공용 컴퓨터에서는 떠날 때 로그아웃하세요. 오프라인에서도 즉시 사본을 삭제하고 다음 온라인 접속 시 서버 세션도 종료합니다.

📦 Poznote ZIP 파일로 백업은 독립된 읽기 전용 사본을 만듭니다. ZIP을 풀고 브라우저에서 index.html을 여세요. 노트는 읽을 수 있지만 Poznote의 전체 기능이나 편집은 제공하지 않습니다.

백엔드

• PHP 8.5: 서버 스크립트 언어
• SQLite 3: 가벼운 파일 기반 관계형 DB

프런트엔드

• HTML5: 문서 구조와 마크업
• CSS3: 스타일과 반응형 디자인
• JavaScript (Vanilla): 대화형 기능과 동적 콘텐츠
• Vite: Excalidraw(React)와 CodeMirror 빌드 도구(IIFE 번들)
• AJAX: 비동기 데이터 로드

라이브러리

• CodeMirror 6: 마크다운용 확장 가능한 코드·텍스트 편집기
• Excalidraw: 다이어그램과 그림을 그리는 화이트보드
• Mermaid: 텍스트로 다이어그램·흐름도를 생성하는 브라우저 라이브러리
• KaTeX: 빠른 수식 조판·렌더링 라이브러리
• Sortable.js: 끌어서 놓기 정렬
• Lucide: 인터페이스 전체의 아이콘
• Devicon: 코드 블록의 프로그래밍 언어 아이콘
• highlight.js: 코드 구문 강조
• Swagger UI: 대화형 API 문서·시험 화면

저장

• HTML/Markdown 파일: 파일시스템에 표준 HTML·마크다운으로 노트 저장
• SQLite DB: 메타데이터, 태그, 관계, 사용자 데이터
• 첨부 파일: 로컬 또는 선택적 S3 호환 저장소

실행 환경

• Nginx + PHP-FPM: FastCGI Process Manager 기반 웹 서버
• Alpine Linux: 안전하고 가벼운 기본 이미지
• Docker: 배포와 이동을 쉽게 하는 컨테이너
• Supervisor: Nginx, PHP-FPM, 백그라운드 워커(알림, 예약 백업) 실행
• Python 3.12 (Alpine): httpx, uvicorn, fastmcp를 사용하는 AI 연결용 MCP 서버 실행 환경