Agent skill

viewing-immich-photo

View immich photos: container→host path conversion, image display. Trigger: 'immich 사진 보여줘', 'immich 파일 보여줘', 'immich 사진 경로', 'upload-cache 파일 확인'. NOT for immich 컨테이너 관리 (use running-containers).

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/greenheadHQ/nixos-config/tree/main/.claude/skills/viewing-immich-photo

SKILL.md

Immich 사진 확인

macOS 또는 NixOS 환경에서 immich 사진 경로를 받아 이미지를 확인하는 방법입니다.

목적과 범위

Immich 저장 경로 검증, 플랫폼별 파일 접근, 이미지 표시 절차를 다룬다.

빠른 참조

항목 값
허용 루트 /mnt/data/immich/photos/, /var/lib/docker-data/immich/upload-cache/
macOS 동작 ssh minipc로 파일을 /tmp 복사 후 확인
NixOS 동작 로컬 경로를 직접 확인
비허용 패턴 .. 포함 경로

경로 검증 (보안)

요청된 경로가 immich 디렉토리 내부인지 먼저 확인:

  • 허용 경로: /mnt/data/immich/photos/ 또는 /var/lib/docker-data/immich/upload-cache/
  • .. 포함 경로는 거부 (path traversal 방지)

플랫폼 감지

환경 정보에서 플랫폼 확인:

  • <env> 블록의 Platform: darwin → macOS
  • <env> 블록의 Platform: linux → NixOS

macOS에서 실행 시

MiniPC에 저장된 파일이므로 SSH로 가져온 후 Read 도구로 확인합니다.

핵심 절차

  1. 경로가 /mnt/data/immich/photos 또는 /var/lib/docker-data/immich/upload-cache로 시작하는지 확인
  2. SSH로 파일을 /tmp에 복사 (확장자 유지)
  3. Read 도구로 이미지 확인
  4. 삭제 불필요 (/tmp는 시스템 자동 정리)

명령어

bash
# 파일명에서 확장자 추출 (Scriptable 업로드는 일반적으로 .jpg)
BASENAME="${FILE_PATH##*/}"
if [[ "$BASENAME" != *.* ]]; then
  echo "오류: 파일 확장자가 없습니다 (.jpg/.jpeg/.png/.webp/.gif 필요)." >&2
  exit 1
fi

EXT="${BASENAME##*.}"
case "$EXT" in
  jpg|jpeg|png|webp|gif|JPG|JPEG|PNG|WEBP|GIF) ;;
  *)
    echo "오류: 지원하지 않는 확장자: $EXT" >&2
    exit 1
    ;;
esac

ssh minipc "cat <원본경로>" > "/tmp/immich_photo_$(date +%s).$EXT"

주의: minipc는 SSH config에 정의된 호스트 alias.

NixOS에서 실행 시

로컬 파일이므로 경로를 직접 Read 도구에 전달합니다.

핵심 절차

  1. 경로 검증 규칙(허용 루트, .. 부재)을 먼저 확인
  2. 로컬 경로를 Read 도구에 직접 전달

경로 패턴

유형 경로 패턴
업로드 캐시 /var/lib/docker-data/immich/upload-cache/UUID/xx/xx/file.ext
라이브러리 /mnt/data/immich/photos/library/UUID/YYYY/MM/file.ext

경로 변환 (Immich API → 호스트)

Immich API 경로 호스트 경로
/usr/src/app/upload/upload/ /var/lib/docker-data/immich/upload-cache/
/usr/src/app/upload/ /mnt/data/immich/photos/

지원 파일 형식

Read 도구는 이미지를 시각적으로 표시:

  • 이미지: .jpg, .jpeg, .png, .webp, .gif
  • 동영상: 확인 불가 (메타데이터만 표시)

참고: Scriptable 업로드는 항상 .jpg로 저장됨

트러블슈팅

상황 대응
SSH 연결 실패 tailscale status 확인, ssh minipc "echo ok" 테스트
파일 없음 경로 오타 확인, Immich API 경로→호스트 경로 변환 확인
권한 없음 파일 소유자/권한 확인 (ls -la <path>)

참조

  • Immich 경로 변환 규칙은 본 문서의 경로 패턴/변환 표를 기준으로 유지한다.
  • 로컬 원본 기준: modules/nixos/programs/docker/immich.nix의 virtualisation.oci-containers.containers.immich-server.volumes (.../immich/photos:/usr/src/app/upload, .../immich/upload-cache:/usr/src/app/upload/upload)
  • 업스트림 기준: Immich 배포 템플릿 docker/docker-compose.yml의 immich-server.volumes (https://github.com/immich-app/immich/blob/main/docker/docker-compose.yml)

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

greenheadHQ/nixos-config

managing-mise

Manage mise runtime: Node.js, pnpm, shims. Trigger: 'mise 설정', 'pnpm not found', '.nvmrc', 'mise shims', 'mise activate', '런타임 버전 불일치'.

1 0
Explore
greenheadHQ/nixos-config

configuring-git

Configure Git via Home Manager: delta, lazygit, rerere. Trigger: 'git 설정 충돌', 'delta 설정', 'lazygit', 'rerere', 'git-cleanup', 'git 브랜치 정리'.

1 0
Explore
greenheadHQ/nixos-config

managing-tmux

Configure tmux: plugins (resurrect, thumbs, yank), Pane Notepad. Trigger: 'tmux 설정', 'tmux 플러그인', 'pane notepad', 'tmux-resurrect', 'tmux 단축키', 'tmux 세션 복원'. NOT for SSH (use managing-ssh). NOT for Atuin (use syncing-atuin).

1 0
Explore
greenheadHQ/nixos-config

configuring-neovim

Configure Neovim (LazyVim) via Nix: plugins, LSP, formatters, linters, themes, treesitter, im-select. Default editor skill — generic '에디터', '편집기', '코드 편집기' queries route here unless the request is explicitly about Zed or another editor-specific path. Trigger: 'neovim', 'LSP', 'lazy.nvim', 'treesitter', '한영 전환', 'im-select', '에디터', '코드 편집기', '편집기 설정', 'colorscheme', 'catppuccin', 'formatter', 'linter', 'extraPackages', '자동완성', 'syntax highlighting', 'language server', '코드 편집'. NOT for Zed/확장 (→ modules/darwin/programs/zed/). NOT for VSCode (제거됨, #329).

1 0
Explore
greenheadHQ/nixos-config

managing-secrets

Manage encrypted secrets with agenix: .age files, re-encryption, decryption failures. Trigger: '시크릿', '암호화', '복호화', 'agenix', 'secrets.nix', 'age key', '.age', '토큰 추가', 're-encrypt', '/run/agenix'. NOT for Vaultwarden 비밀번호 관리자 (use hosting-vaultwarden).

1 0
Explore
greenheadHQ/nixos-config

managing-ssh

Configure SSH, Tailscale VPN, mosh, sudo auth. Trigger: 'SSH 인증 실패', 'Tailscale', 'ssh-agent 문제', 'MagicDNS', 'mosh', 'authorized_keys 설정'. NOT for tmux (use managing-tmux). NOT for Atuin (use syncing-atuin).

1 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results