Миграция из SharePoint

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

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

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

---

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

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

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

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

---

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. Пройдите шаги мастера

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

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

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

---

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

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

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

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

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

./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. Что происходит по этапам (фазам)

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

Этап	Простыми словами
nodes	Подсайты → узлы Portal
schemas	Списки, библиотеки, поля
items	Строки списков
attachments	Файлы, прикреплённые к строкам
folders	Папки в библиотеках
files	Файлы библиотек
lookups	Поля «подстановка» и «сотрудник» (вторым проходом)
permissions	Права (если включили перенос прав)
verify	Сверка количества объектов

---

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

1. В мастере или в YAML включите перенос прав (migratePermissions), если права нужны.
2. Заранее настройте соответствие «учётка/группа в SharePoint → пользователь/группа в Portal» (principalMap в конфиге или экран мастера).
3. Поля «сотрудник» и «подстановка» заполняются на этапе lookups — после того, как основные данные уже на месте. Без AD-sync и карты соответствий поля могут остаться пустыми.

---

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

Не переносится	Комментарий
Версии файлов (история)	Только актуальный файл
Workflows, типы содержимого, управляемые метаданные	Вне текущей версии
Современные страницы сайта и веб-части SharePoint	Вне объёма миграции
Права на уровне списка в SharePoint Online	Через Graph обычно только права сайта/веба

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

---

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

Что видите	Что сделать
Ошибка входа в Portal (401)	Проверьте логин/пароль; нужна учётка администратора портала
Облако «тормозит» / отказы Microsoft	Уменьшите размер пакета и число параллельных загрузок в настройках, затем resume
On-Prem: ошибка входа	Проверьте домен и формат ДОМЕН\пользователь
Пустые поля «сотрудник» / подстановка	Сначала AD-sync, заполните карту соответствий, перезапустите этап lookups
Вложения Online: отказ доступа	У приложения в Microsoft должны быть права на чтение SharePoint
Мастер без оформления / 404	Рядом с программой должен быть каталог wwwroot/
Повторный запуск «ещё раз всё копирует»	Обычно нет: уже перенесённое пропускается по файлу состояния

---

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
  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

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

---

См. также

• Маппинг полей SharePoint → Portal
• Группы доступа и AD
• Словарь: миграция, principalMap