Git LFS
Каждый репозиторий Arkvory — это сервер Git LFS. Ваш git-репозиторий остаётся там, где он есть, например на GitHub, GitLab или Gitea. В Arkvory попадают только большие файлы, которые отслеживает Git LFS, и блокировки файлов. Объекты LFS — обычные артефакты, поэтому на них действуют права на репозиторий, квоты, проверки SHA-256, резервные копии и зеркала.
Настройка git-репозитория
Вам нужны адрес сервера с HTTPS (см. HTTPS), репозиторий Arkvory, например games, и ключ (см. Учётные записи и ключи).
- Установите Git LFS на каждом компьютере, который работает с репозиторием, и один раз для каждого пользователя выполните
git lfs install. - Создайте в корне git-репозитория файл
.lfsconfigи закоммитьте его. Он заставит всю команду использовать Arkvory:
[lfs]
url = https://arkvory.example/lfs/games- Укажите шаблоны файлов для отслеживания. Команда записывает
.gitattributes, который вы тоже коммитите:
git lfs track "*.psd" "*.fbx" "*.wav" "*.uasset" "*.umap"
git add .gitattributes .lfsconfig- Делайте коммиты и пуши как обычно. Первый запрос потребует учётные данные: см. Вход.
Адрес LFS репозитория всегда имеет вид https://<хост>/lfs/<репозиторий>.
Чтобы перенести файлы, которые уже находятся в LFS на другом сервере, сначала скачайте все объекты со старого сервера, затем переключите lfs.url и загрузите их:
git lfs fetch --all origin
git config lfs.url https://arkvory.example/lfs/games
git lfs push --all originВход
Arkvory принимает ключ в качестве пароля при HTTP Basic-аутентификации. Имя пользователя не проверяется: используйте любое. Ключ можно передать и как токен Bearer.
Git запрашивает имя пользователя и пароль через помощник учётных данных (credential helper), когда сервер впервые отвечает 401. Помощник их сохраняет: Git Credential Manager в Windows и macOS, credential.helper store или cache в Linux.
| Кто | Ключ |
|---|---|
| Разработчик | Персональный токен доступа. Область read-write — для push и блокировок, область read — только для clone и pull. |
| Сервер сборки, CI | Ключ сервиса с действиями из раздела Права |
Git хранит учётные данные отдельно для каждого хоста. Ключ для Arkvory не заменяет учётные данные для хоста вашего git-репозитория, например GitHub.
На раннере CI без помощника учётных данных поместите ключ в локальную конфигурацию рабочей копии. Тогда ключ хранится только в .git/config этого рабочего каталога и никогда не попадает в .lfsconfig:
git config lfs.url "https://ci:${ARKVORY_KEY}@arkvory.example/lfs/games"Не коммитьте ключ. Не выводите его в журналы. Удаляйте рабочий каталог после задания.
Повседневная работа
Git LFS работает так же, как с любым сервером LFS. Команды, которые вы используете:
| Команда | Что делает |
|---|---|
git push | Загружает новые объекты LFS в Arkvory перед отправкой коммитов |
git clone, git pull, git checkout | Скачивают объекты, нужные рабочему дереву |
git lfs fetch --all | Скачивает объекты всех веток |
git lfs ls-files | Перечисляет отслеживаемые файлы и их короткие ID |
git lfs push --all origin | Заново загружает все локальные объекты. Объекты, которые уже есть в Arkvory, не отправляются. |
Объект, который в Arkvory уже есть, с тем же ID и размером, повторно не отправляется. Push, повторённый после прерывания, отправляет только недостающее.
Блокировка файлов
Бинарные ресурсы нельзя слить. Блокировка сообщает команде, что файл редактирует один человек. Блокировки принадлежат репозиторию Arkvory, а не ветке.
git lfs lock Content/Maps/Level01.umap
git lfs locks
git lfs unlock Content/Maps/Level01.umap- Вторая команда
git lfs lockдля того же пути завершается ошибкой «already created lock» и называет владельца. - Владелец показывается по имени пользователя или сервисной учётной записи, под которыми создана блокировка. Для файлового ключа показывается его ID.
- Снять блокировку может только её владелец. Для
git lfs unlock --forceна чужой блокировке нужен ключ сервиса с действиемartifact.deleteв этом репозитории. Персональные токены не могут снимать чужие блокировки. - Путь блокировки — это путь в git-репозитории: до 1024 символов, с
/между папками, без пустых сегментов,.и.., обратной косой черты и двоеточия. git lfs locksпоказывает по 100 блокировок на странице.
Включите проверку перед push, чтобы git отказывался отправлять изменения файлов, заблокированных другими. Настройка задаётся для каждого адреса сервера:
git config lfs.https://arkvory.example/lfs/games.locksverify trueОтметьте типы файлов, которые нужно блокировать перед редактированием. Git LFS тогда держит их доступными только для чтения, пока вы их не заблокируете:
git lfs track --lockable "*.umap" "*.uasset"Проверка блокировок при push требует доступа на запись, поэтому токен только для чтения её использовать не может. Чтобы вывести список блокировок, используйте git lfs locks: для этого достаточно доступа на чтение.
Советы для Unity и Unreal
- Unity: храните текстовые ресурсы (
.unity,.prefab,.asset) в git и задайте для сериализации ресурсов режим Force Text. Крупные бинарные файлы отслеживайте в LFS, например*.png,*.psd,*.fbx,*.wav,*.mp4,*.exr. Текстовые файлы, которые вы отслеживаете в LFS, тоже принимаются. - Unreal Engine: отслеживайте
*.uasset,*.umapи крупные исходные файлы, а*.uassetи*.umapпомечайте как блокируемые (lockable). - Интеграции редакторов, которые вызывают команды блокировки LFS, используют стандартный протокол блокировки файлов Git LFS. Arkvory проверен с клиентами командной строки
gitиgit-lfs. - Не помещайте в LFS изменяющиеся результаты сборки размером в десятки гигабайт. Загружайте их как артефакты или обычные файлы с помощью
arkvoryctl. Правила хранения никогда не удаляют объекты LFS, поэтому они остаются навсегда. - Крупный переиспользуемый код или инструменты, общие для проектов Unity, удобнее раздавать как пакеты Unity.
Что хранится
- Объект LFS — это артефакт в репозитории Arkvory. Его имя и идентичность — SHA-256 его содержимого (
oidв LFS), и у него есть меткаlfs. Эти артефакты видны в консоли в разделе Артефакты. - Arkvory проверяет размер и SHA-256 в процессе приёма объекта. Если они отличаются от
oid, загрузка завершается ошибкой422и ничего не сохраняется. - Объект принадлежит репозиторию. Два репозитория Arkvory хранят собственные копии одного и того же файла.
- Правила хранения никогда не удаляют объекты LFS, потому что сервер не видит, какие коммиты их ещё используют. Команды удаления объекта LFS нет. Планируйте квоту репозитория с учётом всей истории ресурсов.
- Блокировки — это строки в базе данных. Резервные копии их включают.
Права
Персональные токены и файловые ключи получают доступ на чтение или запись к репозиторию. Ключи сервиса получают точные действия.
| Операция | Действия ключа сервиса | Персональный токен или файловый ключ |
|---|---|---|
Скачивание (clone, fetch, pull) | content.read | Доступ на чтение |
Загрузка (push) | upload.create | Доступ на запись, область токена read-write |
| Список блокировок | artifact.list | Доступ на чтение |
| Создание, проверка и снятие собственных блокировок | upload.create | Доступ на запись, область токена read-write |
Снятие чужой блокировки (--force) | artifact.delete | Невозможно |
Заданию CI, которое делает push и pull, нужны content.read, upload.create и artifact.list. Ключ, которому разрешён только push, всё равно узнаёт, что объект существует, поэтому не загружает его дважды.
Персональный токен только для чтения может делать clone и pull, хотя запрос списка скачивания — это POST. Делать push и блокировать он не может. Зеркало и шлюз чтения описаны в разделе Зеркала и шлюзы чтения.
Как работает передача
Для повседневной работы эти подробности не нужны. Они помогают при отладке прокси-сервера или межсетевого экрана.
- Git LFS отправляет один запрос
POST /lfs/<репозиторий>/objects/batchс операцией (downloadилиupload) и списком объектов. В одном запросе до 1000 объектов. По умолчанию Git LFS отправляет не больше 100. - Arkvory отвечает ссылкой для каждого объекта, который нужно передать, действительной один час. Для загрузки он исключает объекты, которые у него уже есть.
- Git LFS отправляет каждый объект запросом
PUTили скачивает его запросомGETпо адресу/lfs/<репозиторий>/objects/<oid>. Запрос содержит тот же ключ, что и пакетный запрос. - Для
PUTнужен заголовокContent-Length. Загрузка сchunked-кодированием отклоняется с422.
Поддерживается:
| Параметр | Значение |
|---|---|
| Адаптер передачи | Только basic |
| Алгоритм хеширования | Только sha256. Клиент, который запрашивает другой, получает 409. |
| Аутентификация | Basic (ключ как пароль) или Bearer |
| Скачивание | GET и HEAD с запросами Range |
| Тип содержимого | application/vnd.git-lfs+json для JSON-запросов. Тела объектов любого типа сохраняются как байты. |
Ошибки — это JSON-документы с message и request_id. Называйте request_id, когда обращаетесь за помощью к администратору.
Ссылки указывают на адрес, по которому клиент обратился к серверу. Когда HTTPS завершается на обратном прокси-сервере, он должен передавать заголовок Host и отправлять X-Forwarded-Proto: https, как в примере nginx из раздела установки, чтобы ссылки использовали https. Arkvory помещает ключ в ссылку, только если ссылка использует https или указывает на локальный компьютер. Если соединение с другим хостом идёт по обычному HTTP, git не может отправить ключ вместе с объектом, и передача завершается ошибкой.
Большие файлы и продолжение
- Git LFS отправляет каждый объект одним запросом
PUT. После сбоя он начинает объект заново с первого байта. Адаптерtus, который продолжает передачу внутри объекта, не поддерживается. - Запрос загрузки должен завершиться в течение 30 минут и не должен простаивать дольше 30 секунд (
ARKVORY_UPLOAD_DEADLINE_MS,ARKVORY_UPLOAD_IDLE_TIMEOUT_MS). Для файла в много гигабайт нужна быстрая и стабильная сеть. Для файлов крупнее используйтеarkvoryctl, который загружает по частям. - Скачивание принимает запросы
Range. - Объект может быть таким большим, как максимальный размер объекта в установке (
ARKVORY_MAX_OBJECT_BYTES, по умолчанию около 10 ТиБ). Более крупный объект отклоняется в пакетном ответе с422.
По умолчанию сервер выполняет одновременно 2 загрузки и 1 на ключ (ARKVORY_MAX_UPLOADS, ARKVORY_MAX_UPLOADS_PER_PRINCIPAL). Git LFS по умолчанию отправляет 8 объектов одновременно. Остальные загрузки ждут свободного места и сдаются через 20 секунд (ARKVORY_TRANSFER_QUEUE_TIMEOUT_MS) с ответом 503. Git LFS повторяет неудавшийся объект несколько раз, но push больших файлов надёжнее при меньшем числе параллельных передач:
git config lfs.concurrenttransfers 1Можно также попросить администратора поднять лимиты. Они описаны в разделе Переменные окружения.
Зеркала и шлюзы чтения
| Место | Clone и fetch | Push и блокировки |
|---|---|---|
| Основной сервер | Да | Да |
| Зеркало | Да. В зеркале есть объекты его источника, поэтому направьте lfs.url на него. | Отклоняется (409, причина mirror_read_only). Блокировки на зеркало не копируются. |
| Шлюз чтения | Нет. Список скачивания — это запрос POST, а шлюз чтения его не принимает. | Нет |
Всегда направляйте lfs.url на основной сервер или, для компьютеров только для чтения, на зеркало.
Устранение неполадок
| Сообщение или симптом | Причина | Что делать |
|---|---|---|
401 или ошибка авторизации | Нет ключа, неверный ключ либо токен истёк или отозван | Удалите сохранённые учётные данные в менеджере учётных данных и повторите push с действующим ключом |
403 с сообщением «Read-only personal access token» | У токена область read | Создайте токен с областью read-write |
403 | У ключа нет доступа для этой операции, или репозиторий ему не выдан | Добавьте действия из раздела Права |
Lock failed: already created lock | Блокировку держит кто-то другой | Попросите владельца снять блокировку или администратора — использовать --force |
422 «Object exceeds the maximum size» | Объект больше лимита установки | Для таких файлов используйте arkvoryctl |
422 при загрузке | Содержимое не совпадает с oid; файл изменился во время push | Снова выполните git lfs push |
503 или Retry-After | Слишком много одновременных передач | Уменьшите lfs.concurrenttransfers и повторите |
507 | Достигнута квота репозитория или ёмкость установки | Освободите место или запросите большую квоту |
409 при загрузке | Репозиторий — зеркало | Выполняйте push на основной сервер |
Файлы в рабочем дереве — небольшие текстовые файлы с oid | Объекты не скачаны, или не был выполнен git lfs install | Выполните git lfs install, затем git lfs pull |
x509: certificate signed by unknown authority | Клиент не доверяет сертификату | Добавьте центр сертификации в хранилище доверия системы или задайте http.sslCAInfo |
Не отключайте проверку TLS (GIT_SSL_NO_VERIFY): ключ отправляется с каждым запросом.