Documentação

Esta documentação é para administradores que hospedam o Wanmory num NAS, servidor doméstico ou computador pessoal. Ela cobre instalação, configuração, implantação do serviço de IA, uso diário, configurações do sistema e manutenção. Para o design do sistema e os algoritmos, veja Arquitetura.

O Wanmory é uma biblioteca de fotos privada com IA, de código aberto e auto-hospedada. Ele é formado por quatro contêineres: o backend em Go (server), o serviço de inferência de IA em Python (ml), o banco de dados PostgreSQL + pgvector (postgres) e o mdns, que anuncia o domínio local. Todas as fotos, metadados, vetores e a fila de tarefas ficam armazenados localmente, sem depender de nenhum serviço em nuvem.

• Gestão de fotos: linha do tempo agrupada por mês, álbuns e álbuns inteligentes, limpeza de sequências e fotos parecidas, mapa de viagens e apresentações de slides.
• Recursos de IA: detecção e agrupamento de rostos, busca em linguagem natural (Chinese-CLIP), reconhecimento de texto (PP-OCR) e nota estética (escolhas da IA).
• Vários membros: contas individuais, permissão de exclusão conforme quem enviou e histórico de acessos.

Opção 1: script de instalação (recomendado)

Numa máquina de 64 bits com Docker instalado, rode:

curl -fsSL https://wanmory.com/install.sh | bash

O script faz o seguinte, nesta ordem:

• Verificação do ambiente: arquitetura da CPU (amd64 / arm64) e espaço de usuário de 64 bits, se o Docker e o Docker Compose v2 estão disponíveis, memória e espaço em disco livres.
• Configuração interativa: pasta de instalação (padrão ~/wanmory), porta de acesso (padrão 8080, verifica se está ocupada), domínio local (padrão wanmory.local), senha do banco de dados (aleatória por padrão) e local do banco (padrão: volume Docker pgdata, ou uma pasta num disco local) e fuso horário (digite uma cidade ou região para buscar, como shanghai, tokyo ou 北京, e escolha um número se houver várias correspondências).
• Locais de armazenamento: pasta de dados (miniaturas, prévias e fotos enviadas, padrão ./data) e pasta de modelos de IA (padrão ./models).
• As perguntas e mensagens do script são em inglês para aparecerem corretamente em qualquer terminal de NAS.
• Pastas de fotos existentes: adicione quantas quiser, escolhendo para cada uma montagem só para leitura (recomendado) ou de leitura e gravação.
• Cria o .env (permissão 600); se houver pastas de fotos, cria também o docker-compose.override.yml, que o Docker Compose combina automaticamente.
• Baixa o docker-compose.yml oficial (pelo Gitee se o GitHub não responder), valida a configuração, baixa as imagens, inicia os serviços e mostra o endereço quando tudo estiver pronto.

# Exemplo: instalação não interativa em /opt/wanmory, na porta 9000, com pastas de fotos do NAS
curl -fsSL https://wanmory.com/install.sh | WANMORY_PORT=9000 WANMORY_PHOTOS=/volume1/photo,/volume2/family bash -s -- -y --dir /opt/wanmory

Opção 2: instalação manual

1. 1
   Crie uma pasta e baixe o arquivo Compose

   Crie uma pasta para o arquivo Compose, os dados e os modelos, e baixe o docker-compose.yml oficial:

   bashCopiar

   mkdir -p ~/wanmory && cd ~/wanmory
   curl -fsSLO https://raw.githubusercontent.com/i-dj/wanmory/main/docker/docker-compose.yml

2. 2
   (Opcional) Escreva um .env

   Crie um .env na mesma pasta para mudar os valores padrão. Em produção, troque sem falta a senha do banco de dados:

   .envCopiar

   WANMORY_DB_PASSWORD=troque-por-uma-sequencia-aleatoria
   WANMORY_PORT=8080
   WANMORY_TZ=America/Sao_Paulo
   WANMORY_VERSION=latest

3. 3
   Inicie os serviços

   A primeira inicialização baixa as imagens e roda as migrações do banco automaticamente:

   bashCopiar

   docker compose up -d
   docker compose ps        # confira se os quatro serviços estão running / healthy

4. 4
   Acesse e configure

   Abra http://wanmory.local:8080 (ou http://<IP da máquina>:8080) no navegador, crie a conta de administrador como indicado e baixe os modelos em "Configurações do sistema → IA". Depois do download, as fotos existentes entram sozinhas na fila de IA.

O arquivo Compose oficial define quatro serviços: o banco de dados postgres, o backend server, o anunciador do domínio local mdns e o serviço de IA embutido ml. A função de cada configuração está anotada no próprio arquivo:

# Arquivo Compose oficial do Wanmory: rode docker compose up -d na pasta deste arquivo
# Variáveis no formato ${VAR:-padrão} são lidas do .env da mesma pasta; sem valor, vale o padrão
services:
  # ── Banco de dados: PostgreSQL 17 + pgvector ─────────────────────
  # Guarda metadados das fotos, pessoas, álbuns, configurações, fila de tarefas e vetores (índice HNSW)
  # Nenhuma porta publicada; acessível só pela rede interna do Compose
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: wanmory
      POSTGRES_PASSWORD: ${WANMORY_DB_PASSWORD:-wanmory}   # em produção, troque sem falta no .env
      POSTGRES_DB: wanmory
    volumes:
      - ${WANMORY_DB_DIR:-pgdata}:/var/lib/postgresql/data  # volume nomeado pgdata por padrão; com WANMORY_DB_DIR, essa pasta. Inclua nos backups
    healthcheck:                             # o server espera esta verificação e inicia quando o banco estiver pronto
      test: ["CMD", "pg_isready", "-U", "wanmory", "-d", "wanmory"]
      interval: 5s
      timeout: 3s
      retries: 20
    restart: unless-stopped
  # ── Backend: binário Go com o app web embutido ───────────────────
  # Cuida da API, uploads (tus), agendamento de tarefas, miniaturas e permissões; migra o banco ao iniciar
  server:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    environment:
      DATABASE_URL: postgres://wanmory:${WANMORY_DB_PASSWORD:-wanmory}@postgres:5432/wanmory
      WANMORY_ML_URL: http://ml:3003         # endereço do serviço de IA embutido; um remoto é configurado em "Configurações de IA"
      TZ: ${WANMORY_TZ:-Asia/Shanghai}       # fuso usado quando o EXIF não informa
      WANMORY_MDNS: "off"                    # este contêiner não recebe multicast na rede bridge; o serviço mdns abaixo anuncia o domínio
      WANMORY_HTTP_PUBLIC_PORT: ${WANMORY_PORT:-8080}   # porta exibida no app web; mantenha igual ao mapeamento de portas
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # domínio local inicial; depois de alterado nas configurações web, vale a configuração
    ports:
      - "${WANMORY_PORT:-8080}:8080"         # porta da máquina:porta do contêiner
    volumes:
      - ${WANMORY_DATA_DIR:-./data}:/data    # upload/ guarda os originais enviados, thumbs/ as miniaturas e prévias de 1440 px
      # Monte as pastas de fotos existentes como subpastas de /photos, quantas quiser; :ro = só leitura; varridas a cada 15 minutos
      # - /mnt/nas/photos:/photos/nas:ro
      # - /media/usb/camera:/photos/usb:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
  # ── Anúncio do domínio local (mDNS) ──────────────────────────────
  # Mesma imagem do server, roda só o subcomando mdns; anuncia wanmory.local (pode ser alterado no app web)
  mdns:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    command: ["mdns"]
    network_mode: host                       # é preciso a rede da máquina para enviar e receber multicast local
    environment:
      WANMORY_URL: http://127.0.0.1:${WANMORY_PORT:-8080}   # consulta periodicamente o server sobre o domínio atual
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # anunciado enquanto o server não responder
    depends_on:
      - server
    restart: unless-stopped
  # ── Serviço de IA embutido: FastAPI + ONNX Runtime, só CPU ───────
  # Sem estado; recebe as prévias do server e devolve rostos, vetores e texto; nenhuma porta publicada
  ml:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-ml:${WANMORY_VERSION:-latest}
    volumes:
      - ${WANMORY_MODELS_DIR:-./models}:/models  # guarda os modelos, assim recriar o contêiner não baixa tudo de novo
    environment:
      WANMORY_MODEL_DIR: /models
      WANMORY_AUTO_DOWNLOAD: "0"             # sem download automático; um administrador confirma licenças e espaço no app web antes
    restart: unless-stopped
volumes:
  pgdata:

.env (variáveis do Compose)

Estas variáveis são usadas no docker-compose.yml; coloque-as no .env da mesma pasta para aplicá-las:

Contêiner server (opcional)

DATABASE_URL, WANMORY_ML_URL, WANMORY_MDNS e WANMORY_HTTP_PUBLIC_PORT já estão no arquivo Compose, com a finalidade anotada. As variáveis a seguir não estão no arquivo padrão; adicione-as ao environment do server se precisar:

Fotos que já estão num NAS ou disco externo não precisam ser enviadas. Monte a pasta como subpasta de /photos dentro do contêiner: ela é varrida a cada 15 minutos e os arquivos novos são importados no lugar (sem copiar nem mover); depois passam pela leitura de metadados, pelas miniaturas e pela IA como as fotos enviadas.

  server:
    volumes:
      - ./data:/data
      - /mnt/nas/photos:/photos/nas:ro       # :ro monta só para leitura
      - /media/usb/camera:/photos/usb:ro
      - /home/eu/Imagens:/photos/pictures     # montagem de leitura e gravação

Depois da mudança, rode docker compose up -d. A primeira varredura começa cerca de 20 segundos após o reinício do contêiner.

• Recomenda-se montar só para leitura (:ro): o sistema não grava nada nessas pastas. Apagar uma foto no app só a move para "Apagadas recentemente", a exclusão definitiva nunca apaga o arquivo original e as varreduras seguintes não o importam de novo. Em pastas de leitura e gravação, a exclusão definitiva também apaga o arquivo original.
• Arquivos com conteúdo idêntico são importados uma só vez (comparação pela soma SHA-1), incluindo arquivos já enviados e duplicatas entre pastas.
• Pastas ocultas e pastas de sistema do NAS (.xxx, @eaDir, #recycle etc.) são ignoradas automaticamente.
• Fotos importadas das pastas não pertencem a nenhum membro; só os administradores podem apagá-las.

O serviço mdns roda no modo de rede da máquina e anuncia o domínio de acesso na rede local (padrão wanmory.local). macOS, iOS, iPadOS e Windows 10 ou posterior acessam em http://wanmory.local:8080 sem configurar o roteador. O domínio pode ser trocado em "Configurações do sistema → Domínio de acesso" e precisa terminar em .local.

Os uploads web usam o protocolo retomável tus (/api/uploads/) com blocos de 16 MB. Atrás de um proxy reverso, libere o limite de tamanho das requisições e desligue o buffer de requisições. Exemplo com Nginx:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}
location /api/uploads/ {
    proxy_pass http://127.0.0.1:8080;
    client_max_body_size 0;          # sem limite de tamanho (no mínimo 20m)
    proxy_request_buffering off;     # repassar em fluxo, sem gravar no disco do proxy
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

O serviço de IA é um serviço HTTP sem estado: recebe prévias de 1440 pixels do backend e devolve rostos, vetores e texto reconhecido. Ele nunca acessa o banco de dados nem guarda arquivos. O backend tem dois modos, trocados em "Configurações do sistema → IA → Modo de execução da IA":

Quando o serviço de IA não está disponível, as tarefas de IA ficam na fila e deixam de ser pegas, sem gastar repetições; o processamento continua sozinho quando o serviço volta. Navegação, uploads e o resto não são afetados.

Opção 1: direto num Mac ou máquina com GPU (recomendado)

Rodando direto, o serviço usa aceleração de hardware: no Apple Silicon, os modelos de rosto usam CoreML e o Chinese-CLIP usa MPS; em GPUs NVIDIA, o Chinese-CLIP usa CUDA em meia precisão (cerca de 1,9 GB de VRAM / memória). Instale antes o uv.

git clone https://github.com/i-dj/wanmory.git
cd wanmory/ml
uv sync --extra torch                 # instalar as dependências do PyTorch (busca semântica acelerada por GPU)
# Gere um token de acesso; o backend e o serviço de IA usam o mesmo valor
export WANMORY_ML_TOKEN=$(openssl rand -hex 24)
echo $WANMORY_ML_TOKEN
WANMORY_FACE_MODEL_PRELOAD=1 uv run --extra torch python -m wanmory_ml
# Escuta em 0.0.0.0:3003 por padrão; mude com WANMORY_ML_HOST / WANMORY_ML_PORT

Opção 2: a imagem Docker em outra máquina

Para uma máquina x86 mais potente sem GPU utilizável; a imagem usa só a CPU:

docker run -d --name wanmory-ml --restart unless-stopped \
  -p 3003:3003 \
  -e WANMORY_ML_TOKEN=<token-de-acesso> \
  -v $PWD/models:/models \
  ghcr.io/i-dj/wanmory-ml:latest

Ativar o serviço remoto no backend

1. 1
   Abra as configurações de IA

   Como administrador, vá em "Configurações do sistema → IA → Modo de execução da IA" e escolha "Serviço remoto".

2. 2
   Informe o endereço e o token

   O endereço tem o formato http://192.168.1.20:3003; informe o token gerado no passo anterior. Antes de salvar, a conexão é testada e a latência e a versão do serviço são exibidas.

3. 3
   Confirme o nível e os modelos

   Depois de conectar, um nível "Automático" é recalculado pelo hardware da máquina remota; baixe os modelos necessários em "Nível de modelos".

O nível define quais modelos são usados para rostos e busca semântica. No "Automático", o sistema recomenda um nível conforme o hardware da máquina do serviço de IA: "Alta precisão" se houver GPU utilizável; só com CPU, "Leve" abaixo de 6 GB de memória e "Equilibrado" nos demais casos.

• O reconhecimento de texto usa o PP-OCRv6 (RapidOCR); os modelos vêm com as dependências e não precisam ser baixados à parte.
• Depois de trocar o nível, os rostos de todas as fotos são detectados de novo e os vetores semânticos recalculados com os novos modelos; enquanto isso, a busca continua usando os vetores antigos, e as pessoas com nome são mantidas.
• Os modelos são baixados na pasta montada ./models, e os que não forem mais usados podem ser apagados para liberar espaço (o modelo em uso não pode ser apagado).
• Os modelos faciais do InsightFace são só para uso não comercial; troque-os ou obtenha uma licença antes de qualquer uso comercial.

1. 1
   Crie o administrador

   No primeiro acesso, o sistema percebe que não há contas e orienta a criação de um administrador. Administradores podem adicionar membros e mudar as configurações do sistema.

2. 2
   Baixe os modelos

   Vá em "Configurações do sistema → IA", confirme o nível de modelos e baixe-os. As tarefas de IA esperam na fila até os modelos ficarem prontos.

3. 3
   Importe fotos

   Envie pelo app web ou conecte as fotos do NAS como descrito em Montar pastas de fotos existentes.

4. 4
   Adicione membros

   Em "Configurações do sistema → Membros", crie contas para outras pessoas e escolha o papel "Membro" ou "Administrador".

• O envio web aceita fotos, vídeos, HEIC, RAW (como DNG) e mais, com seleção múltipla; o envio é feito em blocos pelo protocolo tus e retoma após uma queda de rede ou ao recarregar a página.
• Os arquivos enviados ficam guardados por ano e mês na pasta de envios (padrão data/upload). A pasta pode ser trocada em "Configurações do sistema → Pasta de envios" e vale só para envios novos.
• Depois da importação, roda nesta ordem: leitura de metadados (ExifTool) → miniaturas e prévia de 1440 pixels (libvips / FFmpeg) → vetores semânticos, rostos e texto (serviço de IA) → geocodificação reversa.
• O indicador de tarefas no topo da barra lateral mostra, em número de fotos, o progresso e o tempo restante estimado de "Importar fotos" e "Reconhecimento por IA".

As informações de pessoas (nomes, mesclagens) são comuns a todos os membros; o número de fotos, as capas e as páginas de pessoas são calculados com as fotos que cada membro pode ver, e as fotos ocultas só aparecem para quem as ocultou.

• Membros: ao adicionar, defina nome, senha inicial (mínimo de 4 caracteres) e papel; é possível redefinir a senha de um membro ou removê-lo.
• Histórico de acessos: registra a hora, o aparelho e o IP de cada acesso, com o local estimado offline pelo IP (ip2region), e guarda os últimos seis meses. Só os administradores veem.
• Em "Minha conta", cada membro pode trocar a senha e o avatar e ver em quais aparelhos está conectado.

O topo do cartão mostra ao vivo o estado da IA (rodando ou o motivo da pausa). As mudanças valem na hora, sem reiniciar.

"Configurações do sistema → Atualização do sistema" mostra as versões atuais do backend e do serviço de IA e avisa quando há versão nova. Para atualizar, rode na pasta onde está o docker-compose.yml:

docker compose pull && docker compose up -d

As migrações do banco rodam sozinhas quando o server inicia. Se você fixou uma versão com WANMORY_VERSION, mude antes a tag no .env.

São três tipos de dados para guardar no backup:

# Exportar o banco de dados
docker compose exec -T postgres pg_dump -U wanmory -Fc wanmory > wanmory-$(date +%F).dump
# Restaurar numa instalação nova (rode antes docker compose up -d postgres)
docker compose exec -T postgres pg_restore -U wanmory -d wanmory --clean < wanmory-2026-11-10.dump

Quando um membro esquece a senha, um administrador a redefine em "Configurações do sistema → Membros". Se o administrador esquecer a própria, rode na máquina onde o app funciona, na pasta onde está o docker-compose.yml:

docker compose exec server wanmory reset-password            # listar as contas e escolher uma
docker compose exec server wanmory reset-password <nome>      # indicar a conta diretamente

• O comando lista todas as contas (nome, papel, data de criação, último acesso); escolha uma pelo número e digite a nova senha duas vezes.
• Depois da redefinição, a conta é desconectada de todos os aparelhos; fotos e álbuns não mudam.
• Isso só pode ser feito na máquina; o app web não tem essa opção. Sem Docker, rode wanmory reset-password com as mesmas variáveis de ambiente do servidor, como a DATABASE_URL.

Veja os logs de cada serviço com docker compose logs -f server e docker compose logs -f ml. Se o problema continuar, conte para nós na página Relatar um problema, com o número da versão e os logs relevantes.

Rode o script de desinstalação na máquina onde o Wanmory funciona:

curl -fsSL https://wanmory.com/uninstall.sh | bash

O script lê primeiro o .env da pasta de instalação e lista os contêineres, o banco de dados, a pasta de dados e os modelos de IA com o espaço que ocupam, além das pastas de fotos montadas. Em seguida, para e remove os contêineres e a rede e pergunta, item por item, se deve apagar (por padrão, tudo é mantido):

• As pastas de fotos montadas (NAS, discos externos) nunca são apagadas.
• Para apagar o banco de dados ou a pasta de dados, é preciso digitar DELETE para confirmar.
• Se você remover só os contêineres e manter os dados, rodar de novo o install.sh na mesma pasta recupera tudo; se apagar o .env mas manter o banco, anote antes o WANMORY_DB_PASSWORD que está nele.