Апдейтер: автоматическое обновление справочников

Утилита обновления (апдейтер) сама скачивает и отдаёт «Подсказкам», «Фактору» и «Единому клиенту» новые версии справочников. Вам остаётся только настроить работу по расписанию.

Установка

Требуется доступ с сервера:

К ресурсам HFLabs fs.hflabs.ru и maven.hflabs.ru для скачивания дистрибутивов и справочников.
К интернет-ресурсам для установки питонячих пакетов:
```
files.pythonhosted.org
pythonhosted.org
pypi.python.org
pypi.org
```

Если апдейтер будет запускаться не на сервере приложения, потребуются дополнительные права. Прочитайте раздел «Запуск с другой машины» ниже.

Утилита работает на Linux и требует наличия Python 2.7 или Python 3.5+. Скорее всего, в вашем дистрибутиве он есть, проверьте:

$ python --version
Python 2.7.15

Если версия Python < 2.7.9, предварительно установите pip (команды для CentOS 7):

sudo yum install epel-release
sudo yum install python-pip
sudo pip install 'pip==20.3.4'

Архив с утилитой (последняя версия): https://fs.hflabs.ru/sgt-flight/updater/updater-24.2.zip

Установка (Python 2):

unzip updater-24.2.zip -d /opt/updater
cd /opt/updater
sudo pip install 'virtualenv==16.7.9'
python -m virtualenv env
env/bin/pip install -r requirements.txt

Установка (Python 3):

unzip updater-24.2.zip -d /opt/updater
cd /opt/updater
python -m venv env
env/bin/pip install --upgrade pip
env/bin/pip install -r requirements.txt

Настройка

Для работы утилите надо знать базовый путь к справочникам, а также пользователя, под которым они работают. Настройки по умолчанию — в файле updater.env. Лучше всего их и использовать.

updater.env

# Путь к Artifactory
# Если есть локальное зеркало Artifactory, достаточно перекрыть эту переменную,
# чтобы апдейтер переключился с maven.hflabs.ru на локальное зеркало, например:
# export ARTIFACTORY_PATH="http://maven.mycorp.ru/artifactory/hflabs-maven-remote"
export ARTIFACTORY_PATH="https://maven.hflabs.ru/artifactory/list/ext-releases-{}"

# Путь к каталогу user_lib Фактора, включая сам user_lib
export FACTOR_DICTIONARY_HOME="..."

# Имя пользователя, под которым работает Фактор
export FACTOR_USERNAME="..."

# Версия Фактора
export FACTOR_BUILD="..."

# Путь к каталогу справочников Подсказок
export SUGGESTIONS_DICTIONARY_HOME="..."

# Имя пользователя, под которым работают Подсказки
export SUGGESTIONS_USERNAME="..."

# Порт, на котором работает API Подсказок
export SUGGESTIONS_API_PORT="..."

# Пароль для доступа к API Подсказок 22.10+ 
export SUGGESTIONS_API_PASSWORD="..."

# Путь к каталогу справочников Единого клиента
export CDI_DICTIONARY_HOME="..."

# Имя пользователя, под которым работает Единый клиент
export CDI_USERNAME="..."

# Имя пользователя API Единого клиента
export CDI_API_USERNAME="..."

# Пароль пользователя API Единого клиента
export CDI_API_PASSWORD="..."

# Порт, на котором работает API Единого клиента
export CDI_API_PORT="..."

Файл подключается командой «.»:

. updater.env

Если вы хотите поменять настройки по умолчанию, не меняйте файл updater.env — он будет затёрт при очередном обновлении. Вместо этого создайте собственный файл с настройками и подключайте его после updater.env:

 . updater.env && . custom.env && env/bin/fab название_команды название_справочника

В custom.env укажите только те настройки, которые меняются по сравнению с умолчательными.

Запуск

Утилиту можно запускать с самого сервера приложения, либо с любой другой машины, с которой есть доступ по SSH к серверу приложения.

Запуск с сервера приложения

Синтаксис следующий:

env/bin/fab название_команды название_справочника

Запуск с другой машины

В этом варианте утилита использует настройки ~/.ssh/config для подключения к серверу приложения. Например:

~/.ssh/config

Host 10.0.1.34
    User root
    IdentityFile ~/.ssh/suggestions_rsa

Для пользователя, под которым происходит подключение, должен быть настроен paswordless sudo.

Допустим, апдейтер подключается к серверу приложения под пользователем updater. Тогда для него на сервере приложения следует создать приватный файл:

visudo -f /etc/sudoers.d/updater

И прописать в нём:

updater ALL=(ALL) NOPASSWD: /usr/bin/chown
updater ALL=(ALL) NOPASSWD: /usr/bin/touch

Указав вместо «IP_АДРЕС» ip-адрес машины с апдейтером.

Авторизацию рекомендуем настроить по сертификату. В противном случае придётся каждый раз вводить пароль, и настроить автоматический запуск утилиты не получится.

Синтаксис запуска следующий:

env/bin/fab -H IP_адрес_сервера название_команды название_справочника

Если вы всё-таки выберете авторизацию по паролю, укажите дополнительный ключ:

env/bin/fab -H IP_адрес_сервера --prompt-for-login-password название_команды название_справочника

Работа через прокси-сервер

Чтобы апдейтер работал через прокси-сервер, требуется прописать его настройки в двух местах. Во-первых, в updater.env:

updater.env

export HTTP_PROXY="http://proxy_server_ip:port"
export HTTPS_PROXY="https://proxy_server_ip:port"

Во-вторых, в ~/.wgetrc для пользователя, под которым запускается апдейтер:

~/.wgetrc

use_proxy=yes
http_proxy=http://proxy_server_ip:port
https_proxy=https://proxy_server_ip:port
no_proxy=localhost

Команды и справочники

Утилита умеет:

Команда	Описание
download	Скачать справочник на сервер приложения
download-to	Скачать справочник на локальную машину
scp	Скопировать справочник с локальной машины на сервер приложения
update	Обновить справочник, предварительно скачанный на сервер приложения
download-outward	Скачать внешний справочник на сервер приложения
update-outward	Обновить внешний справочник, предварительно скачанный на сервер приложения

Поддерживаются справочники «Фактора»:

Код	Описание	Размер	Версия
factor_dispemail	Одноразовые адреса эл. почты	2M
factor_fias	ФИАС до дома	1600M
factor_fiasrooms	ФИАС с квартирами	—	20.9–20.12
factor_fiasfull	ФИАС с квартирами и зем. участками	4800M	21.1+
factor_flatarea	Площади квартир	260M
factor_flatprice	Стоимости квартир	5M
factor_geocode	Геокоординаты	180M
factor_invpassport	Недействительные паспорта	490M
factor_oktmo	ОКТМО	110M	21.2+
factor_rossvyaz	Справочник Россвязи	3M	21.2+
factor_tld	Домены верхнего уровня	0M	21.2+
factor_transphone	Перенесённые телефонные номера	60M

Справочники «Подсказок»:

Код	Описание	Размер	Версия
suggestions_address	Адреса России (только адм. деление)	9100M	до 22.11
suggestions_eas	Адреса России (адм. + мун. деление)	4500M	22.4+
suggestions_geo	координаты	1300M
suggestions_house	дополнительные дома	65M
suggestions_stead	земельные участки	—	21.12+
suggestions_flat	квартиры	—	21.2+
suggestions_iso3166	ISO-коды	1M
suggestions_address_foreign	Адреса стран мира	90M	23.11+
suggestions_geonames	Города мира (кроме Белоруссии)	290M	до 23.9
suggestions_osm	Адреса Белоруссии	70M	до 23.9
suggestions_fias	ФИАС	9100M
suggestions_bank	Банки	5M
suggestions_email	Эл. почта	20M
suggestions_fio	ФИО	40M
suggestions_ip	IP-адреса	7M
suggestions_party	Компании	19050M
suggestions_partyext	Компании (ранжирование + реестры)	200M

Справочники «Единого клиента»:

Код	Описание
cdi_egr	ЕГРЮЛ в плоском виде
cdi_egrnorm	ЕГРЮЛ в нормализованном виде
cdi_egrnorminc	ЕГРЮЛ в нормализованном виде (инкремент)

И все внешние справочники.

Скачивание справочников

Если на сервере приложения разрешён доступ к репозиторию HFLabs, для скачивания справочника достаточно команды download:

# Команды выполняются на сервере приложения

# - скачать справочники Подсказок
env/bin/fab download suggestions_bank
env/bin/fab download suggestions_email
env/bin/fab download suggestions_fio
env/bin/fab download suggestions_ip

env/bin/fab download suggestions_eas
env/bin/fab download suggestions_geo
env/bin/fab download suggestions_house
env/bin/fab download suggestions_iso3166
env/bin/fab download suggestions_geonames
env/bin/fab download suggestions_osm

env/bin/fab download suggestions_party
env/bin/fab download suggestions_partyext

# - скачать справочники Фактора
env/bin/fab download factor_geocode
env/bin/fab download factor_fias
env/bin/fab download factor_flatarea
env/bin/fab download factor_flatprice
env/bin/fab download factor_invpassport
env/bin/fab download factor_transphone

# - скачать справочники Единого клиента
env/bin/fab download cdi_egr

Если же на сервере приложения внешний доступ полностью закрыт, воспользуйтесь командами download-to и scp:

# Команды выполняются на внешней машине
# 10.0.1.34 — адрес сервера приложения

# 1) скачать справочник локально в каталог /tmp/dictionaries/email
env/bin/fab download-to suggestions_email /tmp/dictionaries/email

# 2) затем скопировать скачанный справочник на сервер приложения
env/bin/fab -H 10.0.1.34 scp suggestions_email /tmp/dictionaries/email

Обновление справочников

Обновление справочника всегда выполняется командой update, предварительно справочник должен быть скопирован на сервер приложения.

Если утилита выполняется на сервере приложения:

# Команды выполняются на сервере приложения

# - обновить справочники Подсказок
env/bin/fab update suggestions_bank
env/bin/fab update suggestions_email
env/bin/fab update suggestions_fio
env/bin/fab update suggestions_ip

env/bin/fab update suggestions_address
env/bin/fab update suggestions_flat
env/bin/fab update suggestions_stead
env/bin/fab update suggestions_geonames
env/bin/fab update suggestions_osm

env/bin/fab update suggestions_party

# - обновить справочники Фактора
env/bin/fab update factor_geocode
env/bin/fab update factor_fias
env/bin/fab update factor_flatarea
env/bin/fab update factor_flatprice
env/bin/fab update factor_invpassport
env/bin/fab update factor_transphone

# - обновить справочники Единого клиента
env/bin/fab update cdi_egr

Если утилита выполняется с внешней машины:

# Команды выполняются на внешней машине
# 10.0.1.34 — адрес сервера приложения

# - обновить справочники Подсказок
env/bin/fab -H 10.0.1.34 update suggestions_address
...

# - обновить справочники Фактора
env/bin/fab -H 10.0.1.34 update factor_geocode
...

# - обновить справочники Единого клиента
env/bin/fab -H 10.0.1.34 update cdi_egr

Скачивание и обновление внешних справочников HFLabs

Внешние справочники можно скачивать только непосредственно на сервер приложения. Если с сервера приложения нет доступа к репозиторию HFLabs, создайте каталог справочников на машине, с которой доступ есть, и подключите этот каталог на сервере приложения (по SSHFS или NFS, например).

Скачать и обновить внешний справочник (на примере справочника fms_unit):

env/bin/fab download-outward public fms_unit
env/bin/fab update-outward public fms_unit

Скачивание и обновление внешних справочников заказчика

Если внешний справочник создан заказчиком, скачать через апдейтер его не получится. Скопируйте конфигурацию и содержимое справочника на сервер «Подсказок» по инструкции.

После того, как справочник скопирован на сервер, его можно обновить командой update-outward (замените NAME на название справочника):

env/bin/fab update-outward public NAME

Проверка версии

Чтобы проверить версию утилиты, выполните команду version:

env/bin/fab version

Работа по расписанию

Если у вас версия 21.7 или раньше

Обновляйте справочники только последовательно, по одному за раз. Никогда не запускайте одновременно индексацию двух и более справочников.

В версиях 21.8+ можно запускать обновление одновременно — «Подсказки» все равно будут индексировать справочники последовательно.

Чтобы регулярно скачивать и обновлять справочники, добавьте задачи в крон.

Пример для запуска с сервера приложения (строго для версий 21.8+), если полный путь к утилите /opt/updater:

00 21 * * 6  cd /opt/updater && . /opt/updater/updater.env && /opt/updater/download-dictionaries.sh
00 01 * * 0  cd /opt/updater && . /opt/updater/updater.env && /opt/updater/update-dictionaries.sh

/opt/updater/download-dictionaries.sh

/opt/updater/env/bin/fab download suggestions_bank
/opt/updater/env/bin/fab download suggestions_email
/opt/updater/env/bin/fab download suggestions_fio
/opt/updater/env/bin/fab download suggestions_ip
 
/opt/updater/env/bin/fab download suggestions_eas
/opt/updater/env/bin/fab download suggestions_geo
/opt/updater/env/bin/fab download suggestions_house
/opt/updater/env/bin/fab download suggestions_iso3166
/opt/updater/env/bin/fab download suggestions_geonames
/opt/updater/env/bin/fab download suggestions_osm

/opt/updater/env/bin/fab download suggestions_party
/opt/updater/env/bin/fab download suggestions_partyext

/opt/updater/env/bin/fab download factor_geocode
/opt/updater/env/bin/fab download factor_fias

/opt/updater/update-dictionaries.sh

/opt/updater/env/bin/fab update suggestions_bank
/opt/updater/env/bin/fab update suggestions_email
/opt/updater/env/bin/fab update suggestions_fio
/opt/updater/env/bin/fab update suggestions_ip

/opt/updater/env/bin/fab update suggestions_address
/opt/updater/env/bin/fab update suggestions_flat
/opt/updater/env/bin/fab update suggestions_stead
/opt/updater/env/bin/fab update suggestions_geonames
/opt/updater/env/bin/fab update suggestions_osm

/opt/updater/env/bin/fab update suggestions_party

/opt/updater/env/bin/fab update factor_geocode
/opt/updater/env/bin/fab update factor_fias

Пример для запуска с внешней машины (строго для версий 21.8+), если полный путь к утилите /opt/updater, а 10.0.1.34 — адрес сервера приложения:

00 21 * * 6  cd /opt/updater && . /opt/updater/updater.env && /opt/updater/download-dictionaries.sh
00 23 * * 6  cd /opt/updater && . /opt/updater/updater.env && /opt/updater/copy-dictionaries.sh
00 01 * * 0  cd /opt/updater && . /opt/updater/updater.env && /opt/updater/update-dictionaries.sh