# kio-s3

## Introdução

O KIO S3 é um worker do KIO que permite navegar e gerenciar arquivos armazenados no Amazon S3 e em serviços de armazenamento compatíveis com S3 (como Cloudflare R2, DigitalOcean Spaces, MinIO e outros) diretamente do Dolphin e de outros aplicativos do KDE.

Com o KIO S3, você pode:

- Navegar pelos buckets e pastas

- Enviar e baixar arquivos

- Copiar, renomear e excluir arquivos e pastas

- Criar pastas dentro dos buckets

- Conectar-se a vários serviços compatíveis com S3 simultaneamente usando perfis nomeados

## Configurar perfis

O KIO S3 suporta a conexão com vários serviços de armazenamento compatíveis com S3 por meio de perfis nomeados. Cada perfil armazena as configurações de conexão para um serviço. Você pode gerenciar os perfis em Configurações do sistema Rede Backends S3.

### Adicionando um perfil

Clique no botão Adicionar perfil... e preencha os seguintes campos:

Nome

- Um nome descritivo para este perfil (obrigatório), ⪚ `Meu Armazenamento na Nuvem`.

URL do ponto de saída

- O URL do serviço compatível com S3, ⪚ `https://s3.example.com`. Deixe em branco para usar o endpoint padrão do Amazon S3.

Região

- A região de armazenamento, por exemplo, `us-east-1` ou `auto`. Deixe em branco para usar a região da sua configuração da AWS.

Perfil AWS

- O nome do perfil de credenciais de `~/.aws/credentials`. Se deixado em branco, o identificador do perfil será usado como nome do perfil de credenciais.

Usar URLs S3 no estilo de caminho

- Habilite esta opção para serviços que não suportam endereçamento no estilo virtual-hospedado, como MinIO ou algumas implementações do Ceph. A maioria dos serviços, incluindo Amazon S3 e Cloudflare R2, não precisa disso.

Após adicionar um perfil, clique em Aplicar para salvar. O novo perfil aparecerá como um atalho no painel Locais do Dolphin.

### Editar e excluir perfis

Cada perfil na lista possui uma ação de edição e uma ação de exclusão. A edição abre a mesma caixa de diálogo com os valores atuais preenchidos previamente. A exclusão solicita a confirmação antes de remover o perfil. Lembre-se de clicar em Aplicar para salvar suas alterações.

## Credenciais AWS

O KIO S3 usa a cadeia de credenciais padrão da AWS para autenticar com os serviços do S3. As credenciais são lidas de `~/.aws/credentials`, que pode conter vários perfis nomeados:

    [default]
    aws_access_key_id = SUA_CHAVE
    aws_secret_access_key = SUA_SENHA

    [minhanuvem]
    aws_access_key_id = SUA_CHAVE_NUVEM
    aws_secret_access_key = SUA_SENHA_NUVEM

Cada perfil do KIO S3 usa o campo Perfil AWS para selecionar qual seção de credenciais usar. Por exemplo, um perfil com Perfil AWS definido como `minhanuvem` usará as credenciais da seção `[minhanuvem]` acima.

Se nenhum perfil estiver configurado, o KIO S3 usa a cadeia de credenciais padrão da AWS, que inclui variáveis ​​de ambiente (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`), a seção `[default]` em `~/.aws/credentials` e funções de instância do EC2.

Você pode, opcionalmente, definir a região usando `~/.aws/config`:

    [default]
    region = eu-west-1

    [profile minhanuvem]
    region = auto

Em `~/.aws/config`, os perfis nomeados usam o prefixo `profile` (por exemplo, `[profile minhanuvem]`), enquanto em `~/.aws/credentials` o prefixo não é usado (por exemplo, `[minhanuvem]`). Esta é uma convenção do AWS SDK.

## Esquema da URL

O KIO S3 usa o esquema de URL `s3://`. Você pode digitar esses URLs diretamente na barra de endereços do Dolphin ou usá-los com ferramentas de linha de comando como `kioclient`.

`s3://`

- Lista todos os buckets disponíveis com as credenciais padrão da AWS.

`s3://`meubucket`/`

- Lista o conteúdo de `meubucket`.

`s3://`meubucket`/`caminho/para/arquivo.txt``

- Acessa um arquivo específico no bucket.

`s3://@`perfil`/`

- Lista todos os buckets disponíveis no perfil especificado.

`s3://`meubucket`@`perfil`/`

- Lista o conteúdo de `meubucket` no perfil nomeado.

`s3://`meubucket`@`perfil`/`caminho/para/arquivo.txt``

- Acessa um arquivo específico no perfil nomeado.

Ao adicionar um perfil em Configurações do sistema, um atalho é criado automaticamente no painel Locais do Dolphin. Basta clicar nele para navegar pelos buckets desse perfil.

## Navegação de arquivos

Abra o Dolphin e digite `s3://` na barra de endereços para visualizar seus buckets do S3. Clique em um bucket para navegar pelo seu conteúdo. Pastas e arquivos aparecem exatamente como em um sistema de arquivos local.

Para navegar em um perfil específico, digite `s3://@`perfil`/` ou clique no atalho do perfil no painel Locais.

A navegação funciona como esperado: você pode usar a barra de navegação, os botões de voltar e avançar e a barra de localização. Você também pode abrir locais do S3 em novas abas.

## Operações com arquivos

### Enviar arquivos

Arraste arquivos do seu sistema de arquivos local e solte-os em uma pasta S3 no Dolphin. Você também pode usar copiar e colar. Arquivos grandes são carregados automaticamente usando o recurso de envio multi-partes para evitar o uso excessivo de memória.

### Baixar arquivos

Arraste arquivos de uma pasta S3 para uma pasta local ou use copiar e colar. Você também pode abrir arquivos S3 diretamente em aplicativos — o arquivo será baixado para um local temporário e aberto.

### Copiar

Você pode copiar arquivos dentro do mesmo serviço S3 usando copiar e colar ou arrastar e soltar. A cópia é realizada no servidor, portanto, não requer o download e o reenvio do arquivo.

### Renomear

Pressione F2 no Dolphin para renomear um arquivo ou pasta. Como o S3 não possui uma operação de renomeação nativa, o KIO S3 realiza uma cópia no servidor para o novo nome e, em seguida, exclui o original. Para pastas, todos os arquivos dentro da pasta são copiados e excluídos individualmente.

### Excluir

Selecione os arquivos ou pastas e pressione Delete. Ao excluir uma pasta, todos os arquivos e subpastas dentro dela serão excluídos recursivamente.

### Criar pastas

Pressione F10 ou use Criar novo Pasta... para criar uma nova pasta dentro de um bucket.

## Trabalhar com múltiplos perfis

Se você utiliza vários serviços compatíveis com S3 (por exemplo, um para backups e outro para ativos do site), pode configurar um perfil para cada um e alternar entre eles sem alterar nenhum arquivo de configuração ou variável de ambiente.

Cada perfil aparece como um atalho separado no painel Locais do Dolphin. Clicar no atalho de um perfil exibe os buckets disponíveis nesse serviço. Todas as operações (enviar, baixar, copiar, renomear, excluir) funcionam independentemente dentro de cada perfil.

A cópia ou renomeação de arquivos entre perfis diferentes não é suportada. A cópia no servidor S3 funciona apenas dentro de um único serviço. Para mover arquivos entre perfis, copie-os primeiro para uma pasta local e, em seguida, faça o upload para o outro perfil.

## Limitações conhecidas

- A criação e exclusão de buckets não são suportadas. Use o console web ou as ferramentas de linha de comando (CLI) do provedor para gerenciar buckets.

- As permissões de arquivo exibidas no Dolphin são meramente cosméticas. O S3 utiliza seu próprio modelo de controle de acesso (políticas do IAM e políticas de bucket), que não corresponde às permissões do Unix.