Миграция из SharePoint

Эта инструкция для администратора, которому нужно перенести списки, библиотеки, файлы и права из SharePoint в Portal.

В дистрибутиве Portal есть программа portal-sp-migrate: у неё два режима — веб-мастер (рекомендуется) и команды в терминале. Собирать программу из исходников не нужно — берите готовый файл из поставки.

Читайте сверху вниз. На каждом шаге — что сделать и что должно появиться на экране.

0. Что вы получите в итоге

После успешной миграции:

Подсайты SharePoint станут узлами Portal.
Списки и библиотеки появятся с полями и данными.
Файлы и вложения будут в библиотеках / у элементов.
При включённом переносе прав — сотрудники получат доступ по сопоставлению групп/пользователей.

Таблица «какой тип поля куда попадает»: Маппинг полей.

1. Где запускать программу

Программа — отдельный клиент на вашем компьютере (или jump-хосте). Это не служба SharePoint и не модуль внутри Portal.

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

SharePoint Online — нужен доступ в интернет к Microsoft 365 и до вашего Portal.
SharePoint на своих серверах (On-Premises) — нужна сеть/VPN до фермы SharePoint и до Portal.

2. Что подготовить заранее

Что	Зачем
Установленный Portal	Куда переносим данные
Учётка администратора портала	Программа входит в Portal от её имени
Доступ к сайту SharePoint	Чтение списков и файлов
Синхронизация пользователей из AD (служба ad-sync), если пользуетесь доменом	Чтобы люди и группы нашлись в Portal при переносе прав и полей «сотрудник»
Бинарник `portal-sp-migrate` из дистрибутива	Сам инструмент

Где лежит программа в поставке

Как установлен Portal	Путь
Native Linux	`opt/portal/bin/portal-sp-migrate`
Native Windows	`opt/portal/bin/portal-sp-migrate.exe`
Docker-бандл	`tools/portal-sp-migrate` (+ примеры в `sharepoint-migrate-config/`)

Рядом с программой должен быть каталог wwwroot/ — без него веб-мастер откроется «без стилей» или с ошибкой.

Доступ к SharePoint Online (облако)

Обычно заводят приложение в каталоге Microsoft (App Registration) с правами на чтение сайтов и файлов. Это делает администратор Microsoft 365 / Entra ID.
В мастере понадобятся: адрес сайта, идентификаторы приложения и секрет.

Доступ к SharePoint On-Premises

Учётная запись Windows (NTLM) с доступом к нужной коллекции сайтов. Формат логина часто ДОМЕН\пользователь.

3. Рекомендуемый путь: веб-мастер

Шаг 3.1. Запустите мастер

На машине с доступом к SharePoint и Portal откройте терминал в каталоге с программой:

./portal-sp-migrate ui

На Windows — portal-sp-migrate.exe ui.

Шаг 3.2. Откройте в браузере

Адрес по умолчанию: http://127.0.0.1:5088.

Браузер может открыться сам. Если нет — вставьте адрес вручную.

По умолчанию мастер слушает только этот компьютер. Если открываете с другой машины:

./portal-sp-migrate ui --host 0.0.0.0 --token СЕКРЕТНАЯ_СТРОКА

Токен нужно будет ввести при входе в мастер.

Шаг 3.3. Пройдите шаги мастера

На экране порядок примерно такой:

Источник — SharePoint Online или On-Premises, адрес сайта, учётные данные.
Portal — адрес вашего Portal, логин и пароль администратора. Родительский узел выбирается из списка: кнопка Загрузить узлы показывает дерево, дочерние узлы сдвинуты под родителя. Пункт Корень портала кладёт сайт SharePoint на верхний уровень.
Область — какие сайты/списки включать (инвентаризация).
План — сколько объектов будет перенесено (без записи или с подтверждением — по экрану мастера).
Запуск — сам перенос; можно смотреть прогресс.
Итог — отчёт: что перенесено, где ошибки.

Файлы заданий мастер кладёт в каталог ./migration-jobs/ рядом с программой.

Шаг 3.4. Вернуться к незаконченному переносу

Если закрыли страницу, мастер перестал отвечать, SharePoint или Portal не ответили, или перезагрузился компьютер, уже перенесённые объекты остаются в задании. На шаге Источник мастер сам показывает блок Незаконченные переносы: сайт, адрес Portal, последний этап и сколько объектов уже записано.

Кнопка Вернуться открывает это же задание на шаге Запуск. Поля и пароли заново вводить не нужно. Дальше нажмите Продолжить: программа проходит этапы снова и пропускает то, что уже есть в файле состояния.

Задание пропадает из списка, когда этап проверки завершился успешно. Из терминала то же самое делает resume (раздел 4).

Шаг «Источник»: SharePoint Online

Шаг «Portal»: URL и учётная запись

Источник On-Premises

4. Альтернатива: команды в терминале

Если мастер неудобен (автоматизация, сервер без GUI):

Скопируйте пример конфига:

cp sharepoint-migrate-config/migration.example.yaml migration.yaml

Откройте migration.yaml в редакторе: адрес SharePoint, Portal, логины, что включать.
Выполните по порядку:

./portal-sp-migrate discover -c migration.yaml   # что есть в источнике
./portal-sp-migrate plan -c migration.yaml       # подсчёт без записи
./portal-sp-migrate run -c migration.yaml        # перенос

Если перенос прервался:

./portal-sp-migrate resume -c migration.yaml
./portal-sp-migrate status -c migration.yaml

Кратко о командах

Команда	Зачем
`ui`	Веб-мастер
`discover`	Инвентаризация источника
`plan`	План без записи в Portal
`run`	Полный перенос
`run --phase …`	Только один этап (см. ниже)
`resume`	Продолжить с места остановки
`status`	Прогресс и ошибки

5. Что происходит по этапам (фазам)

Программа идёт по этапам. Повторный запуск не дублирует уже перенесённое (состояние хранится в файле задания).

Повторный запуск этапа files дописывает историю уже скопированным файлам, если в Portal ещё нет своих версий. Если файл уже правили в Portal, старые версии SharePoint не подмешиваются.

Этап	Простыми словами
nodes	Подсайты → узлы Portal
schemas	Списки, библиотеки, поля (в т.ч. колонки библиотек документов)
items	Строки списков
attachments	Файлы, прикреплённые к элементам списка
folders	Папки в библиотеках + значения простых полей
files	Файлы библиотек, простые поля и предыдущие версии (содержимое и дата). Комментарий к версии переносится с On-Prem. Автор версии в Portal — учётка, под которой шла миграция
lookups	Поля «подстановка» и «сотрудник» у элементов и у файлов/папок (вторым проходом)
permissions	Права (если включили перенос прав)
verify	Сверка количества объектов

6. Права, сотрудники и подстановки

В мастере или в YAML включите перенос прав (migratePermissions), если права нужны.
Пользователи и группы сопоставляются автоматически: логин, почта и точное имя группы в Portal. Карта principalMap нужна только как исключение, если имя в Portal другое. Подстрока в названии группы не подходит: «HR» не станет «HR Owners».
Группы Active Directory при переносе не создаются. Если такой группы нет в Portal, в конце этапа permissions появляется отчёт на русском: какие группы не найдены и что их нужно импортировать из AD (ad-sync), затем повторить этап permissions. Права с этими группами не назначаются, повторный запуск их дописывает.
Локальные группы SharePoint, которых нет в Portal, мастер спрашивает во время этапа прав. Если подтвердить, программа создаёт группы и добавляет в них тот же состав пользователей, но только тех, у кого в Portal есть действующая учётная запись. В консоли без интерактивного ввода группы не создаются: в отчёте будет список и подсказка повторить этап. Чтобы создать их без вопроса, в YAML укажите createLocalGroups: true.
Поля «сотрудник» и «подстановка» заполняются на этапе lookups — после того, как основные данные уже на месте. Это касается и колонок библиотек документов. Если список на одном дочернем сайте ссылается на список другого сайта, целевой список переносится раньше. План показывает этот порядок по-русски. Пользователь ищется по логину и почте. Если учётки нет в Portal, поле может остаться пустым — сначала нужен ad-sync.
Если у списка или библиотеки в SharePoint свои права (наследование от сайта отключено), Portal тоже отключает наследование от узла и переносит только эти назначения. Списки, которые наследуют сайт, в Portal продолжают наследовать узел. Для SharePoint Online приложению нужно право читать RoleAssignments (обычно Sites.FullControl.All на SharePoint, не только Graph).
Папка или файл библиотеки переносится так же, как в SharePoint. Если у объекта свои права, Portal отключает наследование от родителя и записывает этот набор. Если наследование не отключали, папка или файл в Portal наследует родителя: файл — папку, папка — библиотеку или родительскую папку.
Элемент обычного списка переносится так же. Если у элемента свои права и он не наследует список, Portal отключает наследование и записывает этот набор. Если элемент наследует список, в Portal он тоже наследует список. Вложение отдельных прав не получает: оно наследует элемент. Свой набор прав у файла вложения в SharePoint в Portal не копируется.

7. Что программа сейчас не переносит

Вычисляемые колонки переносятся. Узкий набор формул SharePoint становится живым выражением Portal и пересчитывается при сохранении элемента. Если формула шире этого набора, колонка всё равно создаётся: в элементы пишется уже посчитанное значение, а исходный текст формулы сохраняется в настройках поля и сам не считается.

Не переносится	Комментарий
Workflows, типы содержимого, управляемые метаданные	Вне текущей версии
Современные страницы сайта и веб-части SharePoint	Вне объёма миграции

Подробный маппинг типов полей: sharepoint-field-mapping.md.

8. Типичные проблемы

Что видите	Что сделать
Ошибка входа в Portal (`401`)	Проверьте логин/пароль; нужна учётка администратора портала
Облако «тормозит» / отказы Microsoft	Уменьшите размер пакета и число параллельных загрузок в настройках, затем `resume`
On-Prem: ошибка входа	Проверьте домен и формат `ДОМЕН\пользователь`
Пустые поля «сотрудник» / подстановка	Сначала AD-sync, затем снова этап lookups. principalMap — только если логин в Portal другой
В отчёте «не найдены группы Active Directory»	Импортируйте эти группы службой ad-sync и повторите этап permissions
Вопрос про локальные группы SharePoint	Подтвердите создание в мастере: в группы попадут действующие пользователи Portal
Вложения Online: отказ доступа	У приложения в Microsoft должны быть права на чтение SharePoint
Мастер без оформления / 404	Рядом с программой должен быть каталог `wwwroot/`
Повторный запуск «ещё раз всё копирует»	Обычно нет: уже перенесённое пропускается по файлу состояния
Мастер, SharePoint, Portal или компьютер прервали работу	На шаге «Источник» нажмите Вернуться у этого задания, затем Продолжить. Пароли вводить заново не нужно
Библиотеки без колонок после старой миграции	Запустите `run --phase schemas`, затем `folders`, `files`, `lookups` — схема и значения колонок допишутся

9. Пример фрагментов конфигурации (для CLI)

SharePoint Online

source:
  type: graph
  siteUrl: https://contoso.sharepoint.com/sites/hr
  tenantId: "..."
  clientId: "..."
  clientSecret: "..."

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

scope:
  includeSubsites: true
  includeLists: []     # пусто = все списки
  excludeLibraries:
    - Form Templates
  migratePermissions: true
  # createLocalGroups: true   # создать локальные группы SharePoint без вопроса в мастере
  # principalMap нужен только если имя в Portal не совпадает с SharePoint
  # principalMap:
  #   "CONTOSO\\hr-managers": "portal-group-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

Полные примеры лежат в sharepoint-migrate-config/ дистрибутива.