Sharely — Documentação Técnica

Versão: 1.0.0 · Licença: MIT · Node.js: ≥ 18

Índice

1. Visão geral do projeto

2. Arquitetura

3. Stack tecnológico

4. Estrutura de diretórios

5. Configuração e variáveis de ambiente

6. Modelos de dados

7. API REST

8. API WebSocket

9. Rotas de serviço de arquivos

10. Autenticação e segurança

11. Sistema de upload

12. Geração de miniaturas

13. E-mail e SMTP

14. Internacionalização

15. Frontend (React SPA)

16. Painel de administração

17. LGPD / Privacidade

18. Jobs em segundo plano

19. Implantação

20. Ambiente de desenvolvimento

21. Migrações e scripts

22. Testes end-to-end

1. Visão geral do projeto

Sharely é uma plataforma de compartilhamento de arquivos auto-hospedada com uma interface web limpa, integração com ShareX e acesso via API. Os usuários fazem upload de capturas de tela, arquivos e mídias e os compartilham instantaneamente por meio de links curtos.

Funcionalidades principais

2. Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                        Browser / Client                      │
│            React 18 SPA  ·  Vite  ·  Tailwind CSS           │
│   ┌──────────────────────────────────────────────────────┐   │
│   │  HTTP REST (/api/*)            WebSocket (/ws)       │   │
│   └──────────────────────────────────────────────────────┘   │
└───────────────────────────┬────────────────────┬─────────────┘
                            │ HTTP               │ WS
┌───────────────────────────▼────────────────────▼─────────────┐
│                    Express.js (app.js)                        │
│                                                               │
│  ┌──────────────┐  ┌───────────┐  ┌──────────┐  ┌────────┐  │
│  │  /api/auth   │  │  /api/*   │  │   /f/*   │  │  /s/*  │  │
│  │  /api/install│  │  routes   │  │  files   │  │ shares │  │
│  └──────────────┘  └───────────┘  └──────────┘  └────────┘  │
│                                                               │
│  Middleware: session · rate-limit · CSRF · CSP · auth        │
│                                                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  multer  │  │  ws.js   │  │  mailer  │  │ retention  │  │
│  │  upload  │  │ WebSocket│  │ nodemailer│  │  cleanup   │  │
│  └──────────┘  └──────────┘  └──────────┘  └────────────┘  │
└───────────────────────────┬───────────────────────────────────┘
                            │
┌───────────────────────────▼───────────────────────────────────┐
│                      MongoDB (Mongoose)                        │
│  User · File · Collection · ShareLink · SiteSettings          │
│  AuditLog                                                      │
└───────────────────────────────────────────────────────────────┘
                            │
              ┌─────────────▼───────────────┐
              │     Dateisystem (uploads/)   │
              │  {folderName}/  ·  .chunks/  │
              │  .thumbnails/   ·  .avatars/ │
              └─────────────────────────────┘

Fluxo de dados: Upload padrão

Browser → POST /api/web-upload (multipart/form-data)
       → multer: Datei in uploads/{folderName}/
       → File.createUnique() → MongoDB
       → generateThumbnail() (async, non-blocking)
       → logAudit()
       → broadcast('file:uploaded') via WebSocket
       ← JSON: { files: [...] }

Fluxo de dados: Upload ShareX

ShareX → POST /upload (token im Formular-Body)
       → multer: Datei temporär in uploads/
       → requireApiKey: Token-Lookup → User
       → fs.renameSync → uploads/{folderName}/
       → File.create() → MongoDB
       ← JSON: { url, delete_url }

3. Stack tecnológico

4. Estrutura de diretórios

sharely/
├── app.js                          # Ponto de entrada Express, sequência de inicialização
├── package.json
├── .env.example                    # Modelo para todas as variáveis de ambiente
├── Dockerfile
├── docker-compose.yml
│
├── src/
│   ├── config/
│   │   └── db.js                   # Conexão MongoDB (Mongoose)
│   ├── middleware/
│   │   ├── auth.js                 # requireLogin / requireAdmin / requireApiKey
│   │   └── upload.js               # Configuração Multer, lista de bloqueio
│   ├── models/
│   │   ├── AuditLog.js             # Eventos de auditoria (TTL 90 dias)
│   │   ├── Collection.js           # Coleções de arquivos
│   │   ├── File.js                 # Metadados de arquivos
│   │   ├── ShareLink.js            # Links de compartilhamento por arquivo
│   │   ├── SiteSettings.js         # Singleton: configurações do operador
│   │   └── User.js                 # Contas de usuário + chaves API
│   ├── routes/
│   │   ├── api.js                  # API principal (upload, galeria, admin, ...)
│   │   ├── auth.js                 # Login / Registro / Redefinição de senha
│   │   ├── files.js                # Serviço de arquivos, embeds OG, requisições de intervalo
│   │   ├── import.js               # Migração XBackBone
│   │   ├── install.js              # Endpoint de instalação inicial
│   │   └── shares.js               # Serviço de arquivos via link de compartilhamento
│   ├── jobs/
│   │   └── retentionCleanup.js     # Exclusão diária de arquivos expirados
│   ├── migrations/
│   │   ├── migrateApiKeyHashes.js  # Única vez: textos simples → hashes SHA-256
│   │   └── migrateUserFolders.js   # Única vez: mover arquivos para pastas de usuário
│   ├── utils/
│   │   ├── audit.js                # Função auxiliar logAudit()
│   │   ├── generateThumbnail.js    # Integração ffmpeg / ghostscript
│   │   ├── mailer.js               # Wrapper Nodemailer + templates de e-mail i18n
│   │   └── sanitizeFilename.js     # Sanitização do nome de arquivo
│   └── ws.js                       # Servidor WebSocket + despachador de ações
│
├── client/                         # Frontend React
│   ├── index.html
│   ├── package.json
│   ├── vite.config.js
│   ├── tailwind.config.js
│   └── src/
│       ├── main.jsx                # Ponto de entrada React
│       ├── App.jsx                 # Configuração do roteador
│       ├── index.css               # Estilos globais
│       ├── context/
│       │   └── AuthContext.jsx     # Estado de autenticação global
│       ├── hooks/
│       │   ├── use-toast.js        # Hook de notificações toast
│       │   └── useWebSocket.js     # Conexão WS + manipuladores de eventos
│       ├── components/
│       │   ├── Layout.jsx          # Shell do app (barra de navegação, sidebar)
│       │   ├── ProtectedRoute.jsx  # Guarda de autenticação
│       │   ├── ShareLinkDialog.jsx # Diálogo de criação de link de compartilhamento
│       │   ├── AddToCollectionDialog.jsx
│       │   ├── CookieBanner.jsx
│       │   ├── LanguageSelector.jsx
│       │   ├── RequireEmailDialog.jsx
│       │   ├── UserAvatar.jsx
│       │   └── ui/                 # Componentes base shadcn/ui
│       ├── pages/
│       │   ├── Upload.jsx          # Página de upload
│       │   ├── Gallery.jsx         # Galeria de arquivos
│       │   ├── FileView.jsx        # Visualização detalhada de arquivo
│       │   ├── Collections.jsx     # Visão geral de coleções
│       │   ├── CollectionView.jsx  # Coleção individual
│       │   ├── ShareView.jsx       # Página pública do link de compartilhamento
│       │   ├── Settings.jsx        # Configurações do usuário
│       │   ├── Login.jsx
│       │   ├── Register.jsx
│       │   ├── ForgotPassword.jsx
│       │   ├── ResetPassword.jsx
│       │   ├── Install.jsx         # Instalação inicial
│       │   ├── PrivacyPolicy.jsx
│       │   ├── TermsOfService.jsx
│       │   └── admin/
│       │       ├── Dashboard.jsx   # Página inicial do admin
│       │       ├── Users.jsx       # Gerenciamento de usuários
│       │       ├── Files.jsx       # Gerenciamento de arquivos
│       │       ├── AuditLog.jsx    # Visualização do log de auditoria
│       │       ├── SiteSettings.jsx# Configurações do operador
│       │       └── Import.jsx      # Importação XBackBone
│       ├── i18n/
│       │   ├── index.js            # Configuração i18next
│       │   └── locales/
│       │       ├── de.json
│       │       ├── en.json
│       │       ├── es.json
│       │       ├── fr.json
│       │       ├── it.json
│       │       ├── ja.json
│       │       ├── pt.json
│       │       └── zh.json
│       └── lib/
│           └── utils.js            # Utilitário Tailwind (cn())
│
├── scripts/
│   ├── setup-db.js
│   ├── mongo-init.js               # Script de inicialização MongoDB
│   ├── migrate-uploads-to-user-folders.js
│   └── generate-missing-thumbnails.js
│
├── e2e/                            # Testes Playwright
│   ├── admin.spec.js
│   ├── bulk-actions-fixes.spec.js
│   ├── gallery.spec.js
│   ├── sharelink.spec.js
│   ├── tags.spec.js
│   ├── upload.spec.js
│   ├── helpers.js
│   └── global-setup.js
│
├── uploads/                        # Arquivos enviados (runtime)
│   ├── .thumbnails/
│   ├── .avatars/
│   └── .chunks/                    # Partes temporárias
│
└── docs/assets/                    # Capturas de tela e logotipo

5. Configuração e variáveis de ambiente

Todas as variáveis são carregadas de .env (via dotenv). O arquivo .env.example contém o modelo completo.

Campos obrigatórios

Todas as variáveis de ambiente

6. Modelos de dados

User (src/models/User.js)

{
  username:                    String (3–32, único, alfanumérico + _-)
  password:                    String (bcrypt, 12 rounds)
  role:                        'admin' | 'user'
  apiKey:                      String (legado, vazio após migração)
  apiKeyHash:                  String (SHA-256, único, sparse)
  apiKeyPrefix:                String (primeiros 8 caracteres do texto simples)
  folderName:                  String (único, sparse, máx. 64)
  avatarExt:                   String | null (.jpg/.png/.gif/.webp)
  embedMode:                   'embed' | 'raw'
  isActive:                    Boolean
  email:                       String (minúsculas, único, sparse)
  emailVerified:               Boolean
  emailVerificationToken:      String | null (hash SHA-256 do texto simples)
  emailVerificationExpires:    Date | null
  passwordResetToken:          String | null (hash SHA-256)
  passwordResetExpires:        Date | null
  language:                    'en'|'de'|'fr'|'es'|'it'|'pt'|'ja'|'zh'
  predefinedTags:              [String] (máx. 100 tags × 50 caracteres)
  createdAt:                   Date
}

Métodos importantes:

• user.comparePassword(candidate) — comparação bcrypt
• user.regenerateApiKey() — gera novo texto simples, armazena o hash, retorna o texto simples (visível apenas uma vez)
• User.findByApiKey(plaintext) — busca por hash SHA-256, somente usuários ativos

File (src/models/File.js)

{
  shortId:      String (8 caracteres hexadecimais: 6 timestamp + 2 aleatórios, único)
  deleteToken:  String (32 caracteres hexadecimais, único)
  originalName: String (sanitizado)
  storedName:   String (caminho relativo: "folderName/8hex.ext")
  mimeType:     String
  size:         Number (bytes)
  uploader:     ObjectId → User
  views:        Number
  tags:         [String] (máx. 20 × 50 caracteres)
  createdAt:    Date
}

Propriedades virtuais:

• sizeHuman — tamanho legível (B / KB / MB / GB)
• displayType — classificação: image|video|audio|pdf|code|text|file

Algoritmo Short ID:

shortId = hex(seconds_since_2024-01-01, 6 chars) + randomBytes(2).hex()

Collection (src/models/Collection.js)

{
  shortId:     String (8 Hex, único)
  name:        String (máx. 100)
  description: String (máx. 500)
  owner:       ObjectId → User
  files:       [ObjectId → File]
  password:    String | null (bcrypt)
  expiresAt:   Date | null
  createdAt:   Date
}

As coleções expiradas são excluídas automaticamente pelo índice TTL do MongoDB 7 dias após a expiração.

ShareLink (src/models/ShareLink.js)

{
  token:         String (32 Hex, único)
  file:          ObjectId → File
  createdBy:     ObjectId → User
  label:         String (máx. 100)
  password:      String | null (bcrypt)
  expiresAt:     Date | null
  downloadLimit: Number (-1 = ilimitado)
  downloadCount: Number
  createdAt:     Date
}

Como as coleções: período de carência de 7 dias após expiração via índice TTL.

SiteSettings (src/models/SiteSettings.js)

Documento singleton (_id: 'singleton'):

{
  operatorName:        String
  operatorAddress:     String
  operatorEmail:       String
  cloudflareAnalytics: Boolean
  fileRetentionDays:   Number (0 = desativado)
  encryptionAtRest:    Boolean
  sessionDurationDays: Number (padrão: 7)
  allowRegistration:   Boolean
}

AuditLog (src/models/AuditLog.js)

{
  timestamp: Date (índice TTL: 90 dias)
  userId:    ObjectId → User | null
  username:  String | null
  action:    String
  ip:        String | null
  meta:      Mixed (metadados específicos da ação)
}

7. API REST

URL base: /api

Todos os endpoints JSON retornam Content-Type: application/json. Erros: { "error": "mensagem" }.

Autenticação (/api/auth)

Requisição de login:

POST /api/auth/login
{ "username": "max", "password": "meinPasswort123" }

Resposta de login:

{
  "user": {
    "id": "...", "username": "max", "role": "user",
    "avatarUrl": null, "email": "[email protected]",
    "emailVerified": true, "language": "de"
  }
}

Upload de arquivos

Resposta de upload via API:

{
  "url": "https://example.com/f/a1b2c3d4",
  "raw": "https://example.com/f/a1b2c3d4/raw",
  "delete_url": "https://example.com/api/delete/a1b2c3d4",
  "short_id": "a1b2c3d4",
  "filename": "screenshot.png",
  "size": 102400
}

Fluxo de upload em partes

1. POST /api/chunk/init → { uploadId: "32hex" }

2. POST /api/chunk/:uploadId (Body: chunkIndex=N, Arquivo: chunk) → { received: N }

Em paralelo com 3–5 partes simultâneas

3. POST /api/chunk/:uploadId/complete → { files: [fileObject] }

Gerenciamento de arquivos

Parâmetros de consulta da galeria:

• q — busca no nome do arquivo (seguro para regex)
• type — all|image|video|audio|pdf|code
• tag — filtro de tag exato
• page — número da página (padrão: 1)

Configurações do usuário

Links de compartilhamento

Criar link de compartilhamento:

POST /api/file/a1b2c3d4/share-links
{
  "label": "Para colegas",
  "password": "secreto",
  "expiresAt": "2025-12-31T23:59:59Z",
  "downloadLimit": 10
}

Coleções

Endpoints de administração

Configurações do site (públicas)

GET /api/site-settings
{
  "operatorName": "Musterfirma GmbH",
  "operatorAddress": "Musterstr. 1, 12345 Musterstadt",
  "operatorEmail": "[email protected]",
  "cloudflareAnalytics": false,
  "fileRetentionDays": 365,
  "encryptionAtRest": false,
  "sessionDurationDays": 7
}

8. API WebSocket

Conexão: wss://example.com/ws (somente para usuários conectados, cookie de sessão obrigatório)

Protocolo

Cliente → Servidor (Requisição):

{ "id": "req-abc123", "action": "file:list", "payload": { "type": "image", "page": 1 } }

Servidor → Cliente (Resposta):

{ "id": "req-abc123", "data": { ... } }

Servidor → Cliente (Erro):

{ "id": "req-abc123", "error": "Forbidden", "status": 403 }

Servidor → Cliente (Broadcast):

{ "event": "file:uploaded", "data": { "shortId": "a1b2c3d4", "uploaderId": "..." } }

Ações disponíveis

Eventos de broadcast

9. Rotas de serviço de arquivos

/f/:shortId — Visualizador de arquivos

• Requisição do navegador: Passa para a React SPA (index.html) — a SPA renderiza o visualizador.
• Bot de redes sociais (Discord, Telegram, Twitter, etc.): Retorna uma página HTML mínima com meta tags Open Graph / Twitter Card.

- embedMode = 'embed': HTML OG com redirecionamento

- embedMode = 'raw' + imagem/vídeo/áudio: HTTP 302 → /f/:shortId/raw

/f/:shortId/raw — Acesso direto

Serve o arquivo como resposta HTTP com suporte a requisições de intervalo (206 Partial Content). Imagens/vídeos/áudio: Content-Disposition: inline, outros: attachment.

/f/:shortId/download — Download forçado

Como /raw, mas sempre Content-Disposition: attachment.

/f/:shortId/thumb — Miniatura

Retorna a miniatura JPEG (para vídeos e PDFs). Cache-Control: public, max-age=86400.

/f/:shortId/delete/:token — Exclusão ShareX

Exclui o arquivo sem sessão usando um token de exclusão único.

/s/:token — Serviço de arquivos via link de compartilhamento (src/routes/shares.js)

Verifica a senha (via flag de sessão), a data de expiração e o limite de downloads, e então serve o arquivo.

10. Autenticação e segurança

Autenticação por sessão

• Sessão Express com armazenamento MongoDB (connect-mongo)
• Cookie de sessão: httpOnly: true, sameSite: 'strict', secure: true em produção
• Duração da sessão: configurável via SiteSettings.sessionDurationDays (padrão: 7 dias), com cache ao vivo de 60 segundos

Autenticação por chave API

• As chaves API são armazenadas como hashes SHA-256, nunca em texto simples
• Os primeiros 8 caracteres são armazenados como apiKeyPrefix (para exibição)
• Busca: User.findByApiKey(plaintext) calcula o hash e busca em apiKeyHash
• Ao baixar a configuração do ShareX, a chave é regenerada — o texto simples fica visível apenas naquele momento

Cadeia de middleware (src/middleware/auth.js)

requireLogin    → verifica req.session.user → 401 se não conectado
requireAdmin    → como requireLogin, adicionalmente role === 'admin' → 403
requireApiKey   → verifica o cabeçalho Authorization ou req.body.token

Proteção CSRF

requireSameOrigin() em app.js compara o cabeçalho Origin com o cabeçalho Host para todas as rotas da API. Complementa os cookies sameSite: 'strict'.

Política de Segurança de Conteúdo

default-src 'self';
script-src 'self' 'unsafe-inline' https://static.cloudflareinsights.com;
style-src 'self' 'unsafe-inline';
img-src 'self' data: blob:;
media-src 'self' blob:;
connect-src 'self' https://cloudflareinsights.com;
frame-ancestors 'self';

Cabeçalhos de segurança

• X-Frame-Options: SAMEORIGIN
• X-Content-Type-Options: nosniff

Limitação de taxa

Lista de bloqueio de arquivos

Os seguintes tipos MIME e extensões são rejeitados no upload:

Tipos MIME bloqueados: application/x-executable, application/x-sh, application/x-csh, application/x-bat

Extensões bloqueadas: .bat, .cmd, .com, .ps1, .psm1, .psd1, .sh, .bash, .csh, .zsh, .fish, .vbs, .vbe, .jse, .scr, .pif, .application, .gadget, .hta, .php, .php3–5, .phtml, .asp, .aspx, .jsp, .jspx, .cfm

Proteção contra path traversal

Todos os acessos a arquivos via resolveUploadPath() verificam se o caminho resolvido está dentro de UPLOAD_DIR.

11. Sistema de upload

Upload padrão (Multer)

• Armazenamento: multer.diskStorage → uploads/{folderName}/{8hex}{.ext}
• Nome do arquivo: crypto.randomBytes(4).hex() + extensão-original
• Limite: MAX_FILE_SIZE_MB (padrão: 100 MB)
• Localização: Pasta específica do usuário (user.folderName)

Upload em partes (>250 MB)

O cliente frontend muda automaticamente para o modo de partes para arquivos grandes.

Estrutura de diretórios no servidor:

uploads/.chunks/{uploadId}/
  meta.json          { filename, mimeType, totalSize, totalChunks, userId, createdAt }
  chunk-0
  chunk-1
  ...
  chunk-N

Tamanho da parte: 10–20 MB (máx. 51 MB aceito para compatibilidade com versões anteriores)

Paralelismo: 3–5 uploads de partes simultâneos

Montagem: Baseada em streams (sem carregamento completo na RAM)

Upload de avatar

• Armazenamento: multer.memoryStorage() (sem buffer em disco)
• Localização: uploads/.avatars/{userId}{.ext}
• Limite: 2 MB
• Formatos: JPEG, PNG, GIF, WebP

12. Geração de miniaturas

As miniaturas são geradas de forma assíncrona após o upload (.catch(() => {}) — erros são ignorados silenciosamente).

Miniaturas de vídeo (ffmpeg)

ffmpeg -y -i <file> -ss 00:00:01 -vframes 1 \
  -vf "scale=320:320:force_original_aspect_ratio=increase,crop=320:320" \
  -q:v 3 uploads/.thumbnails/<shortId>.jpg

Miniaturas de PDF (Ghostscript)

gs -dNOPAUSE -dBATCH -dSAFER \
  -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 \
  -r72 -dJPEGQ=85 \
  -sOutputFile=uploads/.thumbnails/<shortId>.jpg \
  <file>

Tempo limite: 30 segundos por geração de miniatura

Fallback: Se ffmpeg/ghostscript não estiver disponível, a geração é ignorada silenciosamente.

Script de preenchimento retroativo

npm run migrate:thumbnails
# ou no contêiner:
docker exec -it <container> npm run migrate:thumbnails

13. E-mail e SMTP

Configuração

O SMTP é ativado quando SMTP_HOST está definido. mailer.isConfigured() verifica esse valor.

Templates de e-mail

Todos os e-mails são enviados no idioma do usuário (8 idiomas). Os templates estão incorporados em src/utils/mailer.js.

Tipos de e-mails enviados:

Segurança dos tokens

• Tokens: crypto.randomBytes(32).hex() (64 caracteres hexadecimais)
• Armazenados: hash SHA-256 do token
• O e-mail contém o token em texto simples como parâmetro de URL
• Verificação: hash do token recebido comparado com o hash armazenado

14. Internacionalização

Biblioteca: i18next + react-i18next + i18next-browser-languagedetector

Idiomas suportados:

Seleção de idioma:

1. Detecção do idioma do navegador (automática)

2. Preferência do usuário no banco de dados (user.language)

3. Persistência via PATCH /api/user/language

Arquivos de tradução: client/src/i18n/locales/{code}.json

15. Frontend (React SPA)

Configuração do roteador (client/src/App.jsx)

Contexto de autenticação (client/src/context/AuthContext.jsx)

Estado global para o usuário conectado. Inicializado na inicialização do app via GET /api/auth/me.

Hook WebSocket (client/src/hooks/useWebSocket.js)

Gerencia a conexão WS persistente. Fornece sendMessage() e registro de manipuladores de eventos. Lógica de reconexão em caso de queda da conexão.

Componentes UI

Baseado em shadcn/ui (Radix UI Primitives + Tailwind CSS):

• Dialog, AlertDialog, DropdownMenu, ContextMenu, Popover
• Select, Checkbox, Input, Textarea, Label
• Card, Badge, Button, Separator, Tabs, Table
• Toast / Toaster para notificações
• Calendar / DateTimePicker para seleção de data de expiração
• Pagination para listas paginadas
• ScrollArea, Tooltip

16. Painel de administração

O painel de administração (/admin/*) é acessível apenas para usuários com role: 'admin'.

Painel de controle (/admin)

• Número total de usuários, arquivos, uso de armazenamento
• 10 arquivos carregados mais recentemente
• Atualizações ao vivo via WebSocket (stats:invalidate)

Gerenciamento de usuários (/admin/users)

• Todos os usuários com contagem de arquivos e uso de armazenamento
• Criar usuários, ativar/desativar, alterar papel
• Redefinir senha, regenerar chave API
• Alterar nome da pasta (arquivos físicos são movidos no servidor)
• Excluir usuário (todos os arquivos são excluídos)

Gerenciamento de arquivos (/admin/files)

• Todos os arquivos de todos os usuários, paginado
• Busca por nome de arquivo
• Excluir arquivo

Log de auditoria (/admin/audit-log)

• Log paginado de todas as ações (50/página)
• Filtrar por nome de usuário e ação
• Exportação CSV para fins regulatórios

Configurações do site (/admin/site-settings)

• Informações do operador (nome, endereço, e-mail)
• Ativar Cloudflare Analytics
• Período de retenção de arquivos
• Duração das sessões
• Ativar/desativar registro de usuários

Importação XBackBone (/admin/import)

• Pré-visualização e importação do banco de dados SQLite do XBackBone
• Usuários são correspondidos pelo nome de usuário
• Idempotente (arquivos já importados são ignorados)

17. LGPD / Privacidade

Fluxo de exclusão LGPD/GDPR

Na exclusão da conta (user:delete-account / DELETE /api/user/account):

1. Todos os arquivos do usuário são excluídos do disco

2. As miniaturas são excluídas

3. O avatar é excluído

4. As entradas do log de auditoria são anonimizadas (username: '[deleted]', ip: null, userId: null)

5. O documento de usuário é excluído

6. A sessão é destruída

18. Jobs em segundo plano

Limpeza por retenção (src/jobs/retentionCleanup.js)

• Execução: Na inicialização e depois diariamente (setInterval(runRetentionCleanup, 24h))
• Ação: Se SiteSettings.fileRetentionDays > 0, os arquivos mais antigos que esse valor são excluídos
• Exclui: arquivo em disco, miniatura, documento MongoDB
• Transmite stats:invalidate para os admins

Índices TTL do MongoDB (automáticos)

19. Implantação

Docker (recomendado)

git clone https://github.com/Christianoooooo/sharely.git
cd sharely
cp .env.example .env
# Editar .env (SESSION_SECRET, senhas MONGO, BASE_URL)
docker compose up -d

Serviços:

• app — Aplicação Node.js (porta 3000)
• mongo — MongoDB 7 (porta 127.0.0.1:27017, não acessível externamente)

Volumes:

• uploads — armazenamento persistente de arquivos
• mongo_data — dados MongoDB

Verificações de saúde: O app verifica HTTP 200 em /, o MongoDB verifica db.adminCommand('ping').

Proxy reverso Nginx

server {
    listen 443 ssl;
    server_name files.example.com;

    client_max_body_size 2100M;  # Pelo menos tão grande quanto a maior parte + buffer

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Suporte WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

BASE_URL em .env deve corresponder ao domínio público.

Primeira inicialização

O primeiro usuário registrado recebe automaticamente o papel admin (User.countDocuments() === 0).

20. Ambiente de desenvolvimento

Pré-requisitos

• Node.js ≥ 18
• MongoDB (local ou via Docker)
• Opcional: ffmpeg, ghostscript (para miniaturas)

Configuração

# Backend
npm install
cp .env.example .env
# Editar .env

# Frontend
cd client
npm install

Inicialização

# Backend (porta 3000, com nodemon)
npm run dev

# Frontend (porta 5173, terminal separado)
cd client
npm run dev

O servidor de desenvolvimento Vite faz proxy das requisições da API para localhost:3000 automaticamente.

Build

npm run build   # Compila client/dist/, o backend permanece inalterado
npm start       # Inicia o servidor Express de produção

21. Migrações e scripts

Migrações automáticas (a cada inicialização)

Essas migrações são executadas na inicialização do app em app.js e são idempotentes:

Scripts manuais

# Gerar miniaturas para arquivos já existentes
npm run migrate:thumbnails
# ou:
node scripts/generate-missing-thumbnails.js

# Mover uploads para pastas de usuário (manual)
npm run migrate:user-folders
# ou:
node scripts/migrate-uploads-to-user-folders.js

Inicialização do banco de dados (Docker)

scripts/mongo-init.js é executado na primeira inicialização do contêiner MongoDB e cria o usuário de aplicação com as permissões corretas.

22. Testes end-to-end

Framework: Playwright (@playwright/test)

Arquivos de teste

Execução

# Todos os testes
npm run test:e2e

# Com interface gráfica
npm run test:e2e:ui

Configuração Playwright: playwright.config.js

Configuração global: e2e/global-setup.js (cria usuários de teste, admin, etc.)

Utilitários: e2e/helpers.js (funções auxiliares compartilhadas)

Apêndice: Ações do log de auditoria

*Documentação gerada a partir do código-fonte de sharely v1.0.0*