GeeseFS

Последнее изменение: 29 сентября 2025

GeeseFS — это программа, с помощью которой можно примонтировать бакет на устройство или сервер и работать с ним как с обычной папкой. GeeseFS подходит для работы с большим количеством объектов, объем которых до 1 МБ у каждого. С GeeseFS можно работать на Linux, Windows и macOS.

Настроить GeeseFS

1. Настроить доступ.
2. Установить клиент.
3. Создать конфигурацию.

1. Настроить доступ

Настроить доступ может Владелец аккаунта или пользователь с ролью iam_admin.

1. Создайте сервисного пользователя с ролью с доступом в S3. Если вы используете сервисного пользователя с ролью object_storage_user, в бакете должна быть настроена политика доступа.
2. Выдайте пользователю S3-ключ.

2. Установить клиент

Linux

1. Убедитесь, что утилиты для работы с FUSE установлены по умолчанию:

   apt list --installed | grep fuse

2. Если утилиты не установлены, установите их:

   sudo apt-get install fuse

3. Скачайте и установите GeeseFS:

   wget https://github.com/yandex-cloud/geesefs/releases/latest/download/geesefs-linux-amd64
   chmod a+x geesefs-linux-amd64
   sudo cp geesefs-linux-amd64 /usr/bin/geesefs

Windows

1. Если у вас не установлен WinFSP, скачайте и установите его.

2. Скачайте файл geesefs-win-x64.exe, но не устанавливайте его.

3. Опционально: для удобства переименуйте файл в geesefs.exe.

4. Создайте папку geesefs.

5. Перенесите файл geesefs.exe в папку geesefs.

6. Добавьте папку geesefs в переменную PATH:

   6.1. В поиске Windows введите Изменение системных переменных среды.

   6.2. Нажмите Переменные среды.

   6.3. Выберите параметр PATH.

   6.4. Нажмите Изменить → Создать.

   6.5. Добавьте путь к папке в список.

   6.6. Нажмите ОК → ОК.

7. Чтобы настройки переменных сред применились, перезапустите PowerShell или перезагрузите устройство.

macOS

1. Подготовьте и установите пакет macFUSE:

   1.1. Установка macFUSE требует вмешательства в настройки безопасности macOS, для этого используйте инструкцию Getting Started на Github.

   1.2. Установите пакет macFUSE.

2. Откройте Terminal.

3. Установите GeeseFS:

   platform='arm64'
   if [[ $(uname -m) == 'x86_64' ]]; then platform='amd64'; fi
   wget https://github.com/yandex-cloud/geesefs/releases/latest/download/geesefs-mac-$platform
   chmod a+x geesefs-mac-$platform
   sudo cp geesefs-mac-$platform /usr/local/bin/geesefs

3. Создать конфигурацию

Linux

1. Откройте CLI.

2. Создайте директорию, в которой будет хранится файл с S3-ключом:

   mkdir ~/.aws

3. Создайте файл credentials:

   nano ~/.aws/credentials

4. Добавьте S3-ключ:

   [default]
   aws_access_key_id = <access_key>
   aws_secret_access_key = <secret_key>

   Укажите:

   • <access_key> — значение поля Access key из S3-ключа;
   • <secret_key> — значение поля Secret key из S3-ключа.

5. Нажмите Ctrl + X → Y → Enter.

Windows

1. Откройте PowerShell.

2. Создайте файл credentials:

   New-Item -Type Directory -Path "$env:USERPROFILE\.aws" -Force | Out-Null
   notepad "$env:USERPROFILE\.aws\credentials"

3. Добавьте S3-ключ:

   [default]
   aws_access_key_id = <access_key>
   aws_secret_access_key = <secret_key>

   Укажите:

   • <access_key> — значение поля Access key из S3-ключа;
   • <secret_key> — значение поля Secret key из S3-ключа.

4. Нажмите Файл → Сохранить

5. Если файл сохранился с расширением .txt, удалите расширение:

   Rename-Item "$env:USERPROFILE\.aws\credentials.txt"
               "$env:USERPROFILE\.aws\credentials" -Force`

macOS

1. Откройте Terminal.

2. Создайте директорию, в которой будет хранится файл с S3-ключом:

   mkdir ~/.aws

3. Создайте файл credentials:

   cat ~/.aws/credentials

4. Добавьте S3-ключ:

   [default]
   aws_access_key_id = <access_key>
   aws_secret_access_key = <secret_key>

   Укажите:

   • <access_key> — значение поля Access key из S3-ключа;
   • <secret_key> — значение поля Secret key из S3-ключа.

5. Нажмите Control + X → Y → Enter.

Монтировать бакет

Разовое монтирование

Linux

1. Создайте папку для монтирования:

   mkdir /mnt/<folder_name>

   Укажите <folder_name> — имя папки, к которой будет примонтирован бакет.

2. Монтируйте бакет:

   sudo geesefs
   --endpoint https://<s3_domain>
   --region <pool>
   --profile <profile_name>
   <bucket_name> /mnt/<folder_name>

   Укажите:

   • <s3_domain> — домен S3 API в зависимости от пула, в котором находится бакет;
   • <pool> — пул, в котором находится бакет;
   • <bucket_name> — имя бакета, который будет монтирован;
   • <profile_name> — имя профиля, по умолчанию default;
   • <folder_name> — имя папки, которую вы создали на шаге 1.

3. Убедитесь, что бакет монтирован:

   df -hT /mnt/<folder_name>

   Укажите <folder_name> — имя папки, которую вы создали на шаге 1.

Windows

1. Откройте PowerShell.

2. Монтируйте бакет:

   geesefs --endpoint <s3_domain> --region <pool>
   <bucket_name> <destination>

   Укажите:

   • <s3_domain> — домен S3 API в зависимости от пула, в котором находится бакет;

   • <pool> — пул, в котором находится бакет;

   • <bucket_name> — имя бакета, который будет монтирован;

   • <destination> — имя нового диска или путь до папки в Windows, куда будет монтирован бакет. Чтобы монтировать бакет:

     • как диск — используйте значение вида S:;
     • как папку — используйте путь до папки в кавычках, например "C:\Data\GeeseFS".

macOS

После монтирования папка будет подключена в Finder как внешний диск.

1. Откройте Finder или Terminal.

2. Создайте папку для монтирования:

   mkdir -p "<local_folder>"

   Укажите <local_folder> — путь до папки.

3. Скопируйте и сохраните путь к папке.

4. Монтируйте бакет:

   geesefs -o volname="<volume_name>"
       --endpoint https://<s3_domain>
       --region <pool>
       --profile <profile_name>
       <bucket_name> "<local_folder>"

   Укажите:

   • <volume_name> — имя внешнего диска в Finder, в качестве которого будет отображаться монтированный бакет;
   • <bucket_name> — имя бакета, который будет монтирован;
   • <local_folder> — путь до папки, которую вы создали на шаге 2;
   • <s3_domain> — домен S3 API в зависимости от пула, в котором находится бакет;
   • <pool> — пул, в котором находится бакет;
   • <profile_name> — имя профиля, по умолчанию default.

   При успешном монтировании вернется ответ:

   main.INFO File system has been successfully mounted

5. Если у вас возник конфликт из-за сертификата, удалите его:

   sed -i '' '/^[[:space:]]*ca_bundle[[:space:]]*=/d' ~/.aws/config

Автоматическое монтирование

Linux

1. Откройте файл /etc/fstab:

   sudo nano /etc/fstab

2. Добавьте команду для автоматического монтирования бакета:

   <bucket_name> /mnt/<folder_name> fuse.geesefs _netdev,allow_other,--endpoint=https://<s3_domain>,--region=<pool>,--profile=<profile_name> 0 0

   Укажите:

   • <bucket_name> — имя бакета, который будет монтирован;
   • <folder_name> — имя папки, к которой будет монтирован бакет;
   • <s3_domain> — домен S3 API в зависимости от пула, в котором находится бакет;
   • <pool> — пул, в котором находится бакет;
   • <profile_name> — имя профиля, по умолчанию default;

3. Примените настройки:

   sudo systemctl daemon-reload

4. Убедитесь, что бакет примонтирован:

   sudo mount -a
   df -hT

Windows

1. Откройте PowerShell.

2. Создайте службу Windows, которая будет запускаться вместе с ОС:

   $dir = Join-Path $env:USERPROFILE '<folder_name>'
   New-Item -ItemType Directory -Path $dir -Force | Out-Null
   $script = Join-Path $dir '<task_name>.cmd'
   @"
   @echo off
   cd /d "%USERPROFILE%\<TASK_FOLDER>"
   geesefs.exe --endpoint https://<s3_domain> --region <pool> <bucket_name> <destination> >> "%USERPROFILE%\<task_name>\mount.log" 2>&1
   "@ | Set-Content -Path $script -Encoding ASCII
   
   schtasks /Create /TN "<task_name>" /SC ONLOGON /RL HIGHEST /RU $env:USERNAME /TR "$script" /F

   Укажите:

   • <folder_name> — имя папки в профиле, где будут храниться .cmd и логи;

   • <task_name> — имя задачи, которая будет монтировать бакет;

   • <s3_domain> — домен S3 API в зависимости от пула, в котором находится бакет;

   • <pool> — пул, в котором находится бакет;

   • <bucket_name> — имя бакета, который будет монтирован;

   • <destination> — имя нового диска или путь до папки в Windows, куда будет монтирован бакет. Чтобы монтировать бакет:

     • как диск — используйте значение вида S:;
     • как папку — используйте путь до папки в кавычках, например "C:\Data\GeeseFS";

   • <task_name> — имя для задачи в службе Windows, которая будет запускать монтирование бакета при запуске системы.

3. Убедитесь, что бакет монтирован:

   schtasks /Run /TN "<task_name>"

   Укажите <task_name> — имя задачи в службе Windows, которая запускает монтирование бакета при запуске системы.

4. Перезагрузите устройство.

macOS

1. Откройте Finder или Terminal.

2. Создайте папку для монтирования:

   mkdir -p "<local_folder>"

   Укажите <local_folder> — путь до папки.

3. Скопируйте и сохраните путь к папке.

4. Скопируйте путь к GeeseFS:

   which geesefs

5. Создайте файл конфигурации агента автозапуска:

   mkdir -p "$HOME/Library/LaunchAgents"
   cat > "$HOME/Library/LaunchAgents/<agent_name>.plist" <<'PLIST'
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
   <key>Label</key>
   <string><agent_name></string>
   <key>ProgramArguments</key>
   <array>
       <string><geesefs_path></string>
       <string>-o</string><string>volname=<volume_name></string>
       <string>--endpoint</string><string><s3_domain></string>
   <string>--region</string><string><pool></string>
       <string>--profile</string><string><profile_name></string>
       <string><bucket_name></string>
   <string><local_folder></string>
   </array>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key>
   <dict>
       <key>NetworkState</key><true/>
   </dict>
   <key>StandardOutPath</key><string>/Users/<username>/Library/Logs/geesefs.out.log</string>
   <key>StandardErrorPath</key><string>/Users/<username>/Library/Logs/geesefs.err.log</string>
   </dict>
   </plist>
   PLIST
   
   chmod 644 "$HOME/Library/LaunchAgents/<agent_name>.plist"
   chmod 700 "$HOME/Library/LaunchAgents"
   plutil -lint "$HOME/Library/LaunchAgents/<agent_name>.plist"

   Укажите:

   • <agent_name> — имя файла для агента автозапуска;
   • <geesefs_path> — путь к GeeseFS, который вы скопировали на шаге 4;
   • <volume_name> — имя смонтированного бакета, который будет отображаться в Finder как внешний диск. Может совпадать с <local_folder> или отличаться;
   • <s3_domain> — домен S3 API в зависимости от пула, в котором находится бакет;
   • <pool> — пул, в котором находится бакет;
   • <local_folder> — путь до папки, которую вы создали на шаге 2;
   • <profile_name> — имя профиля AWS, по умолчанию default;
   • <bucket_name> — имя бакета, который будет монтирован к устройству;
   • <username> — имя пользователя в системе macOS.

6. Запустите агент:

   launchctl bootstrap gui/$(id -u) "$HOME/Library/LaunchAgents/<agent_name>.plist"
   launchctl enable gui/$(id -u)/<agent_name>
   launchctl kickstart -k gui/$(id -u)/<agent_name>

   Укажите <agent_name> — имя файла с агентом автозапуска, который вы создали на шаге 5;

7. Убедитесь, что бакет монтирован:

   mount | grep geesefs || echo "Пока не смонтировано"
   open "<local_folder>"

   Укажите <local_folder> — путь до папки, которую вы создали на шаге 2.

Отмонтировать бакет

Способ отмонтирования зависит от того, как был монтирован бакет — разово или автоматически.

Разовое монтирование

Linux

Отмонтируйте бакет:

sudo umount /mnt/<local_folder>

Укажите <local_folder> — путь до папки, к которой монтирован бакет.

Windows

1. Откройте PowerShell.

2. Нажмите Ctrl + C.

3. Убедитесь, что в командой строке появился ответ:

   main.INFO Flushing all changes
   main.INFO Successfully exiting

macOS

1. Откройте Terminal.

2. Отмонтируйте бакет:

   umount "<local_folder>" 2>/dev/null || diskutil unmount force "<local_folder>"

   Укажите <local_folder> — путь до папки, к которой монтирован бакет.

Автоматическое монтирование

Linux

1. Проверьте список монтирований:

   systemctl list-units --type=mount

2. В строке нужного монтирования скопируйте значение столбца UNIT.

3. Отключите автоматическое монтирование:

   sudo systemctl disable mnt-<folder_name>.mount

   Укажите <folder_name> — имя папки, к которой был примонтирован бакет.

4. Убедитесь, что бакет отмонтирован:

   df -hT

Windows

1. Откройте PowerShell.

2. Удалите службу с автоматическим монтированием бакета:

   schtasks /Delete /TN "<task_name>" /F

   Укажите <task_name> — имя задачи в службе Windows, которая запускает монтирование бакета при запуске системы.

3. Перезагрузите устройство.

4. Убедитесь, что бакет больше не монтируется автоматически.

macOS

1. Откройте Terminal.

2. Проверьте точку монтирования:

   mount | grep geesefs

3. Скопируйте адрес точки монтирования.

4. Принудительно отмонтируйте бакет:

   diskutil unmount force "<folder_path>"

   Укажите <folder_path> — путь до папки.

5. Остановите агент монтирования и удалите конфигурацию:

   launchctl bootout gui/$(id -u) "$HOME/Library/LaunchAgents/<agent_name>.plist"
   rm "$HOME/Library/LaunchAgents/<agent_name>.plist"

   Укажите <agent_name> — имя файла с агентом автозапуска.

6. Убедитесь, что в Finder смонтированный бакет не отображается как диск.