Миграция из SharePoint

Инструмент portal-sp-migrate переносит списки, библиотеки, вложения и права из SharePoint Online или On-Premises в Portal. В дистрибутиве — один бинарник: веб-мастер и CLI.

Простая инструкция

1. Установите Portal и войдите как portal_admin.
2. На машине, которая видит и SharePoint, и Portal, возьмите portal-sp-migrate из дистрибутива.
3. Запустите мастер:

./portal-sp-migrate ui

4. Откройте в браузере http://127.0.0.1:5088.
5. Пройдите шаги: Источник → Portal → Область → План → Запуск → Итог.

По умолчанию UI слушает только localhost. Если открываете с другой машины: --host 0.0.0.0 --token СЕКРЕТ.

Где запускать

Инструмент — удалённый клиент, а не служба SharePoint и не модуль Portal.

Вопрос	Ответ
На сервере SharePoint?	Нет
На сервере Portal?	Не обязательно (часто хуже: у API может не быть маршрута до On-Prem SP)
Где правильно?	Любая машина с доступом к SharePoint и Portal: ноутбук, jump-host, VPN

• Online — HTTPS до Microsoft 365 и до Portal
• On-Premises — сеть/VPN до фермы SharePoint и до Portal

Требования

• Portal с учётной записью portal_admin
• SharePoint Online: App Registration с Graph Sites.Read.All, Files.Read.All и SharePoint Sites.Read.All (для вложений)
• SharePoint On-Premises: NTLM-учётная запись с доступом к site collection
• Рекомендуется предварительно синхронизировать пользователей AD (ad-sync)

Расположение в дистрибутиве

Канал	Путь
Native Linux	opt/portal/bin/portal-sp-migrate
Native Windows	opt/portal/bin/portal-sp-migrate.exe
Docker bundle	tools/portal-sp-migrate + sharepoint-migrate-config/

В дистрибутиве — готовый бинарник и примеры конфигов. Собирать инструмент из исходников клиенту не нужно.

Быстрый старт

Веб-интерфейс (рекомендуется)

./portal-sp-migrate ui
# http://127.0.0.1:5088

Мастер: источник → Portal → область (Discover) → план → запуск. Сессии и state лежат в ./migration-jobs/.

CLI

cp sharepoint-migrate-config/migration.example.yaml migration.yaml
# отредактируйте migration.yaml

./portal-sp-migrate discover -c migration.yaml
./portal-sp-migrate plan -c migration.yaml
./portal-sp-migrate run -c migration.yaml

Команды

Команда	Описание
ui	Локальный веб-мастер (--host, --port, --token, --jobs-dir, --no-browser)
discover -c FILE	Инвентаризация источника, JSON-отчёт
plan -c FILE	Dry-run: подсчёт объектов без записи
run -c FILE	Полная миграция
run -c FILE --phase items	Одна фаза (nodes, schemas, items, attachments, folders, files, lookups, permissions, verify)
resume -c FILE	Продолжить с checkpoint (SQLite state)
status -c FILE	Прогресс и ошибки

Конфигурация

SharePoint Online (Graph)

source:
  type: graph
  siteUrl: https://contoso.sharepoint.com/sites/hr
  tenantId: "..."
  clientId: "..."
  clientSecret: "..."
  # deviceCode: true   # только CLI; в UI — client secret

target:
  portalUrl: https://portal.local
  username: admin
  password: "..."
  authType: local
  parentNodeId: null   # null = корень Portal

scope:
  includeSubsites: true
  includeLists: []     # пусто = все списки
  excludeLibraries:
    - Form Templates
  migratePermissions: true
  principalMap:
    "CONTOSO\\hr-managers": "portal-group-uuid"
    "ivanov@company.local": "portal-user-uuid"

options:
  batchSize: 100
  uploadConcurrency: 4
  stateFile: ./migration-state.db
  logFile: ./migration.log

SharePoint On-Premises

source:
  type: onprem
  siteUrl: https://sp.contoso.local/sites/hr
  auth: ntlm
  username: CONTOSO\\sp_admin
  password: "..."
  domain: CONTOSO

Полный пример On-Prem: файл migration.onprem.example.yaml в каталоге sharepoint-migrate-config/ дистрибутива (рядом с примером для Online).

Фазы миграции

1. nodes — subsites SharePoint → узлы Portal
2. schemas — списки, библиотеки, поля
3. items — элементы списков (батчи через quick-edit)
4. attachments — вложения элементов списков
5. folders — папки в библиотеках
6. files — файлы (параллельная загрузка)
7. lookups — lookup- и person-поля
8. permissions — ACL (если migratePermissions: true)
9. verify — сравнение counts

Состояние в SQLite (options.stateFile / каталог job в UI). Повторный run / resume пропускает уже замапленные объекты.

Права доступа

Включите migratePermissions в мастере или в YAML. Инструмент читает role assignments из SharePoint, резолвит principal через principalMap и API search, затем вызывает POST /api/v1/permissions.

Lookup и Person

Поля lookup/person пропускаются в фазе items и заполняются в lookups. Нужны AD-sync и principalMap.

Вложения элементов

Фаза attachments после items:

• On-Premises — CSOM AttachmentFiles
• Online — SharePoint REST (Graph не отдаёт содержимое вложений)
• Идемпотентность через state; параллелизм — uploadConcurrency

Ограничения

• UUID и item_number назначает Portal — маппинг в state
• Graph Online: list-level ACL не мигрируется (только site/web)
• Версии файлов — вне текущей версии
• Calculated fields, Managed Metadata — пропускаются
• Modern Site Pages / WebParts — вне scope

Таблица маппинга полей: sharepoint-field-mapping.md.

Troubleshooting

Проблема	Решение
401 при login в Portal	Проверьте логин/пароль, используйте portal_admin
Graph throttling	Уменьшите batchSize / uploadConcurrency, затем resume
On-Prem auth failed	Проверьте domain, формат DOMAIN\\user
Lookup/person пустые	AD-sync до миграции, principalMap
Вложения Online: 401/403	SharePoint permission Sites.Read.All у приложения
UI без стилей / 404 на /	Рядом с бинарником должен быть каталог wwwroot/
Дубли при повторном run	Нормально — state пропускает импортированное