This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Добро пожаловать в SHM

SHM - это открытая, бесплатная универсальная биллинговая система с действиями по событиям.

Принцип работы:

  • Вы создаете услуги, назначаете им цену, период действия и другие свойства
  • Регистрируйте своих клиентов и оказывайте им услуги
  • Биллинговая система SHM будет выполнять назначенные команды для этих услуг на ваших серверах, в зависимости от событий

SHM хорошо подходит для оказания разовых и периодических услуг, таких как:

  • Услуги хостинга
  • Услуги по продаже сервисов, таких как VPN
  • Интернет услуги и услуги связи с безлимитными (пакетными) тарифами
  • Оказание услуг по подписке

SHM не приспособлен для учёта потребленных услуг, таких как трафик, минуты, звонки и т.п..

SHM состоит из:

  • Ядро системы (API)
  • БД: MySQL
  • Личного кабинета администратора
  • Личного кабинета пользователя

1 - Установка

1.1 - Docker

Прежде чем начать, убедитесь, что на вашем сервере запущен демон синхронизации времени (NTP)

Установка Docker

Docker - Самый простой способ запустить SHM на вашем сервере.

Установите docker:

https://docs.docker.com/install/

Установите docker-compose:

apt install docker-compose

Активируйте автозапуск:

systemctl enable docker

Настройка и запуск SHM:

Скачайте файлы docker-compose.yml и .env

wget https://raw.githubusercontent.com/danuk/shm/master/docker-compose.yml
wget https://raw.githubusercontent.com/danuk/shm/master/.env

Сгенерируйте пароли для БД и измените их в файле .env

Так же Вы можете указать в файле .env временную зону в которой будет работать SHM. В дальнейшем эту зону менять нельзя!

Запустите SHM:

docker-compose up -d

SHM будет доступен по адресу:

http://127.0.0.1:8081

Логин: admin

Пароль: admin

Web сервер и доменные имена

Чтобы открыть SHM внешнему миру установите Nginx на ваш сервер, и настройте как написано ниже.

Настройте DNS вашего домена:

admin IN A ПУБЛИЧНЫЙ_IP_ВАШЕГО_СЕРВЕРА
bill  IN A ПУБЛИЧНЫЙ_IP_ВАШЕГО_СЕРВЕРА

Установка nginx

apt install nginx

Настройка nginx

Создайте файл /etc/nginx/sites-available/admin.conf на сервере:

(Замените $DOMAIN на ваш реальный домен)

server {
  listen 80;
  server_name admin.$DOMAIN;

  location / {
    proxy_pass         http://127.0.0.1:8081;
    proxy_redirect     off;
    proxy_set_header   Host             $host;
    proxy_set_header   X-Real-IP        $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
  }
}

Создайте файл /etc/nginx/sites-available/bill.conf на сервере:

(Замените $DOMAIN на ваш реальный домен)

server {
  listen 80;
  server_name bill.$DOMAIN;

  location / {
    proxy_pass         http://127.0.0.1:8082;
    proxy_redirect     off;
    proxy_set_header   Host             $host;
    proxy_set_header   X-Real-IP        $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
  }
}

Включите ваши сайты:

ln -s /etc/nginx/sites-available/admin.conf /etc/nginx/sites-enabled/
ln -s /etc/nginx/sites-available/bill.conf /etc/nginx/sites-enabled/
service nginx reload

Добавление SSL сертификата (https)

Установите certbot:

apt install certbot python3-certbot-nginx

Создайте сертификаты для ваших доменов:

certbot --nginx -d admin.$DOMAIN
certbot --nginx -d bill.$DOMAIN

Проверьте, что всё работает:

https://admin.$DOMAIN

Логин: admin

Пароль: admin

Настройка SHM

В Административном интерфейсе необходимо прописать актуальные настройки.

  1. Зайдите в интерфейс администратора: https://admin.$DOMAIN
  2. Перейдите в раздел: “Настройки” -> “Конфигурация” и выполните соответствующие настройки, например:
  • В настройке api укажите реальный адрес, например: https://admin.$DOMAIN
  • В настройке cli укажите реальный адрес, например: https://bill.$DOMAIN
  • В настройке mail укажите ваш реальный обратный адрес from
  • В настройке company укажите реальное название компании в поле name

2 - Настройка системы

2.1 - Биллинг

Биллинг (автоматизированная система расчётов (АСР)) - система, програмный комплекс, для тарификации оказываемых услуг.

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

Функции биллинга SHM:

  • Оказание платных услуг
  • Вычисление даты окончания услуг, в зависимости от системы расчёта и периода оплаты
  • Возврат средств за преждевременно завершенные услуги
  • Генерация событий для возможности привязки внешних команд

Биллинг SHM всегда округляет деньги до сотого знака (до копеек).

SHM поддерживает несколько систем расчетов.

Система расчета с фиксированным кол-вом дней в месяце

SHM использует по-умолчанию именно эту систему расчетов.

Считаем, что в месяце всегда 30 дней.

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

Стоимость дня будет вычислена по формуле: 100р./30дней = 3.33 руб/день.

При заказе услуги дата окончания будет вычислена как текущая дата плюс 30 дней.

Дата окончания услуг плавающая из-за разного кол-ва дней в месяцах.

Этот способ расчетов самый простой и понятный для клиентов.

Календарная система расчетов

Самая сложная и самая честная система расчетов стоимости услуг.

Стоимость дня зависит от кол-ва дней в месяце.

Например, стоимость услуги за месяц 100р.:

в Январе 31 день, поэтому, стоимость услуги за день: 100р./31дней = 3.32 руб/день,

в Феврале 28 дней, поэтому, стоимость услуги за день: 100р./28дней = 3.57 руб/день,

Если клиент заказал услугу на месяц 1-ого Января, то дата окончания услуги будет 31-ого Января, тут всё ожидаемо.

Но если клиент заказал услугу на месяц 10 января, то дата окончания услуги будет 9 февраля (а не 10, как ожидалось). Это связано с тем, что стоимость услуги в январе меньше, чем в феврале (из-за разного кол-ва дней в месяцах). Однако, особо внимательным клиентам кажется, что у них украли день. Но бывают и обратные случаи, когда мы “дарим” дни: например, если клиент закажет услугу 27 февраля, то дата окончания будет 29 марта. Клиентам приходится объяснять, что “крадут/дарят” дни не мы, а календарь.

Дата окончания услуг плавающая из-за разного кол-ва дней в месяцах.

Расчет по последнему дню месяца

Данная система расчетов очень удобна для оказания услуг юридическим лицам, так как бухгалтерия выставляет закрывающие документы в конце каждого месяца.

При заказе услуги 10 января, первый платеж будет за период с 10 по 31 января. Следующий платеж будет с 1 февраля по 28 февраля, затем, с 1 марта по 31 марта и так далее.

Дата окончания услуги всегда последний день месяца.

2.2 - Услуги

Услуги

Для того, чтобы оказать/продать услугу, её необходимо создать и настроить.

Создавать и управлять услугами удобно через интерфейс Администратора, либо через API. Полное описание полей и настроек услуг вы можете посмотреть на странице API.

Описание полей услуг:

Поле Тип Обязательное default Описание
name Integer Да - Название услуги. Например: "Тариф простой"
category String Да - Служит для группировки услуг. События для услуг создаются по этому полю
cost Double Да - Стоимость услуги за период
period_cost Integer Нет 1 Кол-во месяцев. Например, для продажи доменных имён обычно используется период в 12 месяцев
next Integer Нет - Идентификатор следующей услуги. `-1` - удалить услугу после истечения
children Array Нет - Дочерние услуги. Массив из идентификаторов дочерних услуг
allow_to_order Integer Нет - Установите 1, для разрешения услуги к заказу клиентом
pay_in_credit Integer Нет - Установите 1, для разрешения кредита для услуги
config JSON Нет - Произвольные данные в формате JSON

Пользовательские услуги

Пользовательская услуга - это такая услуга, которая уже оказана пользователю.

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

Дочерние услуги (подуслуги)

Бывают случаи, когда для одной платной услуги, нужно создать несколько услуг, на различных серверах.

Например:

  • Услуга “Виртуальный хостинг”, подразумевает создание таких услуг как: “Web хостинг”, “Хостинг БД” и “Хостинг почты”. Это три совершенно разные услуги, которые оказывются как дочерние к основной.

  • Услуга “DNS хостинг”, подразумевает под собой первычный и вторичный DNS-ы. Это тоже удобно оформить ввиде дочерних услуг.

2.2.1 - События

События генерируются SHM, для возможности привязки команд.

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

Список cобытий

Event Статус ДО Статус ПОСЛЕ Описание
create INIT ACTIVE Услуга создана и оплачена (впервые)
not_enough_money INIT NOT_PAID Не хватает денег для создания услуги
prolongate ACTIVE ACTIVE Услуга продлена (хватило денег для продления активной услуги)
block ACTIVE BLOCK Услуга заблокирована (нехватка денег для продления, либо вручную)
activate BLOCK ACTIVE Услуга активирована (возобновлена после блокировки)
remove BLOCK REMOVED Услуга удалена

Если для события настроена команда, то пользовательской услуге будет присвоен промежуточный статус: PROGRESS, а после выполнения команды пользовательской услуге будет присвоен результирующий статус.

Вот так будет выглядеть создание услуги с настроеным событием:

INIT -> PROGRESS (выполнение команды) -> ACTIVE

Настройка событий

Для события необходимо указать “Категорию” услуги и “Группу серверов”, для выполнения команд.

Категория события должна соответвовать категории услуги, для которой создается это событие.

В зависимости от выбранной группы серверов, могут быть использованы дополнительные настройки, зависящие от Транспорта группы.

Например, если выбрана группа серверов, транспорт которой определен как “SSH”, то будет предложено выбрать шаблон в качестве скрипта, который должен быть выполнен на конечном сервере. Используйте Шаблоны для написания команд.

А если выбрана группа серверов, транспорт которой определен как “Mail”, то можно настроить поле “Шаблон” (template_id), по которому будет сформировано письмо, а так-же другие поля, такие как “Тема письма” (subject) и прочие.

Настройки серверов можно переопределять настройками событий.

2.3 - Сервера

SHM использует Ваши сервера для управления услугами. Способ взаимодействия с Вашими серверами мы назаваем “Транспорт”.

Для удобства, все сервера добавляются в “Группы Серверов”. Каждой группе серверов назначается транспорт.

Все доступные настройки для серверов можно увидеть в API.

Группы серверов

Группы серверов используются для объеденения однотипных серверов в группу.

При первом создании услуги, сервер выбирается из группы серверов по определенным правилам, и сохраняется как server_id в settings-ах услуги пользователя (us.settings.server_id).

Все последущие команды для этой услуги будут выполняться на выбранном сервере.

Все доступные настройки для групп серверов можно увидеть в API.

2.3.1 - Транспорт

Транспорт - способ (протокол) взаимодействия с Вашими серверами.

2.3.1.1 - Mail

Транспорт “Mail” служит для отправки писем.

Письма формируются с помощью Шаблонов, а шаблоны привязываются к Событиям услуг

Настройки

Хост (host)
адрес сервера, например: smtp.mailgun.org:587
user
Имя пользователя для авторизации на почтовом сервере (не обязательное)
password
Пароль для авторизации на почтовом сервере (не обязательное)
from
Адрес отправителя письма. По-умолчанию берется из config->mail->from
from_name
Поле “От-кого”. По-умолчанию берется из config->mail->from_name или “SHM”
subject
Тема письма. По-умолчанию берется из config->mail->subject или “SHM”
to
email адресата. Пытается получить это поле автоматически из логина клиента или его профиля
bcc
email адрес скрытой копии. Можно использовать в отладочных целях, для контроля отправляемых писем (не обязательное)
template_id
Идентификатор шаблона, по которому формируется тело письма
message
Простое текстовое сообщение для отправки. Используется только, если template_id не задан

2.3.1.2 - SSH

SSH (Secure Shell) - выполнение команд на Ваших серверах по средствам протокола SSH.

В этом разделе описывается способ настройки транспорта SSH.

Настройки

Хост (host)
адрес сервера SSH, например: root@1.2.3.4
port
порт SSH сервера. По-умолчанию 22
timeout
Таймаут SSH сервера в секундах. По-умолчанию 10 сек
Ключ (key_id)
SSH ключ для доступа на сервер
Команда (cmd)
Произвольная shell команда. Используется как команда по-умолчанию и для тестирования работы SSH. Реальную команду удобно прописывать в События услуги
proxy_jump
Если ваш сервер находится внутри другого сервера (виртуальный сервер: OpenVZ, LXC, KVM…), то эту настройку можно использовать для указания реального, внешнего сервера. Сначала SHM подключиться к этому серверу, после чего, подключиться к Хост (host).

2.3.1.3 - Telegram

Telegram - популярный мессенджер (https://telegram.org/)

В этом разделе описывается способ настройки транспорта Telegram.

Транспорт Telegram умеет как просто отправлять уведомления, так и работать в качестве полноценного бота: регистрировать клиентов, услуги, пополнять баланс и т.п.

Telegram уведомления

Для того, чтобы SHM мог отправлять сообщения Вашим пользователям, необходимо:

  1. Создать Telegram Bot-а, с помощью бота @BotFather (https://telegram.me/BotFather)
  2. В админке, в “Настройки” -> “Конфигурация”, необходимо сохранить Telegram Token, полученный на предыдущем шаге
  3. Создайте шаблон сообщения в админке, которое вы хотите отправлять своим пользователям (“Настройки” -> “Шаблоны”)
  4. Создайте нужное событие. Привяжите Ваш шаблон к нужному событию. В качестве группы серверов необходимо указать “Telegram уведомления”, или любую другую группу, транспорт которой “telegram”
  5. Дайте Вашему пользователю ссылку на вашего бота, чтобы он мог его себе добавить. После добавления бота Ваш клиент сможет получать от него уведомления

В случаях, когда Ваш клиент регистрировался в SHM НЕ через Telegram bot-а, необходимо указать его логин telegram в его профиле (кабинете)

Telegram bot

Для работы полноценного бота нужно:

  • Выполнить все шаги из предыдущего раздела (Telegram уведомления), если еще не выполнены.
  • Настроить Telegram API, сообщить ему адрес, куда отправлять запросы от клиента (от бота). Для этого скачайте bash скрипт. Перед запуском скрипта необходимо его отредактировать, записать в него свой token и HTTP адрес SHM. Выполните скрипт.
  • Проверьте наличие шаблона telegram_bot. Внесите в него изменения по своему усмотрению.
  • Запустите бота (/start). Если всё настроено верно, вы увидите приветствие.

Telegram bot - использует шаблон telegram_bot. В шаблоне заложена вся логика бота.

Более подробно о шаблоне Telegram читайте здесь: Шаблон Telegram bot

2.4 - Шаблоны

Шаблоны

Шаблоны позволяют генерировать как однострочные команды, так и целые блоки текста. Эти механизмы являются основой построения взаимодействий SHM.

Синтаксис: {{ ОБЪЕКТ.ДАННЫЕ }}

Например, с помощью объекта user можно получить доступ к данным пользователя:

  • user.id - идентификатор пользователя
  • user.login - логин пользователя
  • user.balance - баланс пользователя

С помощью объекта us можно получить доступ к текущей услуге пользователя, и к ее данным:

  • us.id - идентификатор пользовательской услуги
  • us.expire - дата истечения услуги
  • us.service.cost - стоимость услуги
  • us.settings.КЛЮЧ - читаем произвольное поле (КЛЮЧ для примера) из данных услуги

Полный список объектов вы можете найти здесь: Объекты и функции

Пример выполнения shell команды:

add_new_vpn.sh --login=vpn_{{ us.id }} --password={{ us.gen_store_pass }}

В этом примере мы использовали:

  • Идентификатор пользовательской услуги us.id
  • специальную функцию us.gen_store_pass, которая сгенерирует случайный пароль и сохранит его в настройках пользовательской услуги (поле password).

Таким образом, на сервере будет выполнена такая команда (пример):

add_new_vpn.sh --login=vpn_1234 --password=abcdefjh

Пример выполнения shell скрипта:

Иногда удобнее выполнить целый скрипт, многострочный кусок кода. В таких случаях, можно создать отдельный шаблон, тогда в качестве команды мы можем указать следующий код:

bash <(curl -s -H 'session-id: {{ user.gen_session.id }}' {{ config.api.url }}/shm/v1/template/my_bash_script?format=plain)

Данная команда скачает шаблон с имененем my_bash_script на сервер и выполнит его.

Подробнее о создании и настройке шаблонов можно прочитать здесь и здесь

Условия и циклы

В шаблонах поддерживаются условия и циклы.

Примеры использования условий и циклов вы можете увидеть в примерах шаблонов, например здесь: Прогноз оплаты

Больше информации об условиях и циклах Вы можете узнать здесь

Объекты и функции

Метод Описание
user.id Идентификатор пользователя
user.login Логин пользователя
user.balance Баланс пользователя
user.credit Кредитный лимит пользователя
user.dogovor Договор пользователя
user.full_name ФИО пользователя
user.gen_session.id Специальная функция для генерации идентификатора сессии
user.pays.forecast Возвращает JSON прогноза оплат услуг
us.id Идентификатор пользовательской услуги
us.name Имя пользовательской услуги
us.created Дата создания пользовательской услуги
us.expire Дата истечения пользовательской услуги
us.status Статус пользовательской услуги
us.settings Параметры пользовательской услуги
us.parent. Ссылка на родительскую пользовательскую услугу
us.top_parent. Ссылка на самую верхнюю пользовательскую услугу
us.child_by_category( CATEGORY_NAME ). Ссылка на дочернюю услугу определенной категории
us.service.id Идентификатор услуги
us.service.name Название услуги
us.service.cost Базовая стоимость услуги
us.service.category Категория услуги
us.service.settings Параметры услуги
us.server.id Идентификатор сервера
us.server.name Имя сервера
us.server.host Host сервера
us.server.transport Транспорт сервера
us.server.settings. Параметры сервера
us.gen_store_pass Специальная функция для генерации пароля

2.4.1 - Регистрация услуг

2.4.2 - Прогноз оплаты

Метод user.pays.forecast возвращает JSON вида:

{
  "items": [
    {
      "name": "Тариф хостинга",
      "expire": "2017-01-31 23:59:50",
      "total": 123.45,
    },
    {
      "name": "Регистрация домена в зоне .RU: domain.ru",
      "expire": "2017-07-29 12:39:46",
      "total": 590,
    }
  ],
  "dept": 21.56,
  "total": 713.45
}

Мы можем построить шаблон письма о прогнозе опаты услуг следующим образом:

Уважаемый {{ user.full_name }}

Уведомляем Вас о сроках действия услуг:

{{ FOR item IN user.pays.forecast.items }}
- Услуга: {{ item.name }}
  Стоимость: {{ item.total }}
  Истекает: {{ item.expire }}
{{ END }}

{{ IF user.pays.forecast.dept }}
Погашение задолженности: {{ user.pays.forecast.dept }}
{{ END }}

Итого к оплате: {{ user.pays.forecast.total }} руб.

Подробнее о создании и настройке шаблонов можно прочитать здесь

2.4.3 - Пароли

2.4.4 - ЮMoney

ЮMoney - Российская платежная система. ЮMoney предоставляет платежную форму для приёма платежей от ваших клиентов. Для того, чтобы автоматически заполнять поле “Назначение платежа”, мы будем использовать шаблон SHM.

Скорее всего, этот шаблон уже создан в вашей системе и этот шаг можно пропустить.

Создайте платежную форму на сайте ЮMoney, а в назначении платежа укажите любое значение, ниже мы его изменим вручную.

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

  • target={{ user.id }}
  • account={{ config.pay_systems.yoomoney.account }}

Пример шаблона платежной формы:

<iframe
src="https://yoomoney.ru/quickpay/shop-widget?writer=seller&targets=%D0%9E%D0%BF%D0%BB%D0%B0%D1%82%D0%B0%20%D0%BF%D0%BE%20%D0%B4%D0%BE%D0%B3%D0%BE%D0%B2%D0%BE%D1%80%D1%83%20{{ user.id }}&targets-hint=&default-sum=100&label={{ user.id }}&button-text=12&payment-type-choice=on&hint=&successURL=&quickpay=shop&account={{ config.pay_systems.yoomoney.account }}" width="100%" height="198" frameborder="0" allowtransparency="true" scrolling="no">
</iframe>

Подробнее о создании и настройке шаблонов можно прочитать здесь

Информация о том, как принимать платежи, используя этот шаблон, читайте здесь

2.4.5 - Telegram bot

Введение

Этот шаблон используется для Telegram Bot.

Это двух-уровневый шаблон. Сначала используются теги <% ... %> для нахождения нужной секции шаблона, соответствующей команды. После нахождения нужной секции шаблонизатор будет использовать теги вида: {{ ... }}.

Для сопоставления команды пользователя/бота используется внутренняя переменная cmd. Так, при наборе команды /balance будет найдена секция: <% CASE '/balance' %>.

Команда USER_NOT_FOUND является встроенной в SHM, и вызывается автоматичеки, когда SHM не может найти у себя этого пользователя.

В каждой секции мы можем писать реальные команды Telegram. Например, команда sendMessage отправляет сообщение в Telegram. Вы можете использовать эту команду в соответсвии с документацией Telegram.

В каждой секции можно писать множество команд, через запятую (см. пример в секции /balance).

Для того, чтобы лучше понять, как строятся всевозможные кнопочки, читайте документацию Telegram. В этом шаблоне всего-лишь описаны вызовы этих методов.

Пример шаблона:

<% SWITCH cmd %>
<% CASE 'USER_NOT_FOUND' %>
{
    "sendMessage": {
        "text": "Для работы с Telegram ботом укажите Telegram логин в профиле личного кабинета"
    }
}
<% CASE ['/start', '/menu'] %>
{
    "sendMessage": {
        "text": "Я Ваш тестовый Telegram Bot",
        "reply_markup": {
            "inline_keyboard": [
                [
                    {
                        "text": "Баланс",
                        "callback_data": "/balance"
                    }
                ]
            ]
        }
    }
}
<% CASE '/balance' %>
{
    "deleteMessage": { "message_id": {{ message.message_id }} }
},
{
    "sendMessage": {
        "text": "Баланс: {{ user.balance }}",
        "reply_markup": {
            "inline_keyboard": [
                [
                    {
                        "text": "Назад",
                        "callback_data": "/menu"
                    }
                ]
            ]
        }
    }
}

Стандартные методы

chat_id - заполняется автоматически

Встроенные переменные SHM

  • cmd - Команда от бота или пользователя
  • message - сообщение от Telegram
  • args - массив аргументов, переданный в callback_data. Разделитель - пробел.

Встроенные методы SHM

  • shmRegister - метод позволяет зарегистрировать нового клиента

    "shmRegister": {
        "callback_data": "/menu",
        "error": "ОШИБКА: Логин {{ message.chat.username }} или chat_id {{ message.chat.id }} уже существует"
    }
    
  • shmServiceOrder - метод для регистрации новых услуг. Пример использования:

    "shmServiceOrder": {
        "service_id": "{{ args.0 }}",
        "callback_data": "/menu",
        "error": "ОШИБКА"
     }
    

    где: service_id - ID услуги

  • shmServiceDelete - метод для удаления услуг пользователя. Пример использования:

    "shmServiceDelete": {
        "usi": "{{ args.0 }}",
        "callback_data": "/menu",
        "error": "ОШИБКА"
     }
    

    где: usi - ID услуги пользователя

  • uploadDocumentFromStorage - метод загружает данные из Storage и отправляет их в виде файла

    "uploadDocumentFromStorage": {
        "name": "vpn{{ args.0 }}",
        "filename": "vpn{{ args.0 }}.conf"
    }
    
  • uploadPhotoFromStorage - метод загружает данные из Storage и отправляет их в виде картинки (QR code)

    "uploadPhotoFromStorage": {
        "name": "vpn{{ args.0 }}",
        "format": "qr_code_png"
    }
    

2.5 - Приём Платежей

Приём платежей пользователей осуществляется путем заполнения одного из шаблонов платежей.

Шаблон платежа содержит HTML форму платежной системы. Шаблон позволяет заполнить ряд полей этой формы автоматически. Например для того, чтобы понять какой пользователь совершил платеж, мы можем в поле “Назначение платежа” указать идентификатор пользователя.

В настройках платежной системы нужно указать URL, на который платежная система будет присылать информацию о поступлении платежа.

Вам необходимо взять готовый или написать свой скрипт, который будет принимать информацию от платежной системы о платеже и зачислять этот платеж вашему клиенту в SHM по средствам API.

2.5.1 - CryptoCloud.plus

Сервис позволяет принимать крипто-валюту от ваших клиентов.

SHM не умеет конвертировать валюты, поэтому в биллинге следует установить все цены для услуг в долларах, и принимать только крипто-валюту: USDT.

Настройка платежной системы CryptoCloud.plus

{
  "pay_systems": {
    "cryptocloud": {
      "name": "CryptoCloud"
      "api_key":"API_KEY"
      "shop_id":"Идентификтор магазина"
      "template_id": "crypto-cloud-plus"
      "show_for_client": true
    }
  }
}
  • Настройте URL для уведомлений: https://ВАШ_ДОМЕН/shm/pay_systems/cryptocloud.cgi
  • Создайте шаблон с именем crypto-cloud-plus вида:
<form action="/shm/pay_systems/cryptocloud.cgi" method="POST" target="_blank" name="userForm">
    <input type="hidden" name="action" value="create" />
    <div class="modal-header">
        <h4 class="modal-title">Оплата с помощью сервиса CryptoCloud.plus</h4>
    </div>
    <div class="modal-body" style="min-height: 0vh;">
        <div class="form-group">
            <label class="col-sm-4 control-label">Сумма в USDT:</label>
            <div class="col-sm-8">
                <input type="number" name="amount" class="form-control" value=10 required=1>
            </div>
        </div>
    </div>

    <div class="modal-footer">
        <input class="btn btn-primary" ng-disabled="userForm.$invalid" type="submit" value="Далее" />
    </div>
</form>

2.5.2 - ЮMoney

Настройка платежной системы ЮMoney

  • Сохраните в конфиг SHM следующие данные:
{
  "pay_systems": {
    "yoomoney": {
      "account":"АККАУНТ_ЮMONEY",
      "secret":"СЕКРЕТ_ЮMONEY"
    }
  }
}

Аккаунт можно посмотреть в платежной форме. Если форма еще не создана, введите любое значение в поле “Назначение платежа”, и платежная форма появится. Найдите в ней значение вашего аккаунта (account=). Секрет можно посмотреть здесь.

3 - Администрирование

3.1 - MySQL

Бэкапы и восстановление

Создание архивной копии (Backup)

docker-compose exec -T mysql /bin/bash -c 'MYSQL_PWD=${MYSQL_ROOT_PASSWORD} mysqldump -u root shm' > shm_backup.sql

Восстановление БД из архива (Restore)

docker-compose exec -T mysql /bin/bash -c 'MYSQL_PWD=${MYSQL_ROOT_PASSWORD} mysql -u root shm' < shm_backup.sql

Периодические бэкапы

mysql_backup.sh

DOCKER_COMPOSE_PATH="/opt/shm"
BACKUP_DIR="/opt/shm/backups"

mkdir -p ${BACKUP_DIR}
cd ${DOCKER_COMPOSE_PATH}
docker-compose exec -T mysql /bin/bash -c 'MYSQL_PWD=${MYSQL_ROOT_PASSWORD} mysqldump -u root shm' > ${BACKUP_DIR}/shm_$(date +%d%m%Y-%H%M%S).sql

3.2 - Обновление SHM

Как обновить версию SHM

Обновление версии SHM

Рекомендуем делать резервную копию БД SHM перед обновлением

  1. Перейдите в директорию с Вашим файлом: docker-compose.yml
  2. Скачайте новые имаджы: docker-compose pull
  3. Перезапустите контейнеры: docker-compose down && docker-compose up -d

4 - API

Все настройки SHM и всё управление системой осуществляется с помощью вызовов API.

Web интерфейс администратора и кабинет клиента работают на основе API.

HTTP Методы

SHM API использует стандартные методы протокола HTTP:

Метод Назначение
GET Чтение данных
POST Изменение данных
PUT Добавление данных
DELETE Удаление данных

SHM API v1 отвечает в следующем формате:

{
    data: [
        {
            item: 1
        },
        {
            item: 2
        }
    ],
    items: 2
}

HTTP коды ответов

При работе с SHM API рекомендуется проверять коды ответов HTTP.

200 - УСПЕХ для GET, POST, PUT запросов

201 - УСПЕХ для DELETE запросов (эти запросы не возвращают ответа в теле)

400 - ошибка запроса, неверные или недостающие аргументы

403 - не авторизован, требуется авторизация

404 - объект не найден

5xx - ошибки сервера

Аутентификация

Аутентификация через Cookies (session_id)

Получаем session_id:

curl -H "Content-Type: application/json" \
     -X POST http://$SERVER/shm/user/auth.cgi \
     -d '{"login": "admin", "password": "admin"}'

пример ответа:

{ "session_id": "3f928c835ff78f836c4066c112b292c5" }

Запрос с использованием cookies (session_id):

curl --cookie "session_id=3f928c835ff78f836c4066c112b292c5" http://$SERVER/shm/v1/user

Basic-аутентификация

curl -u "admin:admin" http://$SERVER/shm/v1/user

Аутентификация через header-ы

curl -H "session-id: 3f928c835ff78f836c4066c112b292c5" http://$SERVER/shm/v1/user
curl -H "login: admin" -H "password: admin" http://$SERVER/shm/v1/user

Аутентификация через Query string

curl http://$SERVER/shm/v1/user?session_id=3f928c835ff78f836c4066c112b292c5

Список ресурсов

Ресурс URL
Услуги /v1/admin/service
Услуги дочерние /v1/admin/service/children
События услуг /v1/admin/service/event
Пользователи /v1/admin/user
Смена пароля пользователя /v1/admin/user/passwd
Платежи пользователя /v1/admin/user/pay
Зачисление платежей /v1/admin/user/payment
Профиль пользователя /v1/admin/user/profile
Услуги пользователя /v1/admin/user/service
Услуги пользователя - списания /v1/admin/user/service/withdraw
Блокировка услуги пользователя /v1/admin/user/service/stop
Список текущих задач для услуги /v1/admin/user/service/spool

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

4.2 - Приём платежей

Пример зачисления платежа клиенту

Платеж возможно зачислить только из под прав администратора

curl -u "login:password" \
     -H "Content-Type: application/json" \
     -X PUT http://$SHM_URL/shm/v1/admin/user/payment \
     -d '{"user_id": 1, "money": 123.45, "pay_system_id": "manual"}'

Где:

  • user_id - идентификатор пользователя для зачисления
  • money - сумма для зачисления
  • pay_system_id - идентификатор платежной системы. Произвольное слово, длиной не более 16 символов

4.3 - Шаблоны

Пример обновления шаблона wg_manager

curl -u "admin:admin" \
     -X "POST" \
     -H "Content-Type: text/html; charset=utf-8" \
     http://$SHM_URL/shm/v1/admin/template/wg_manager \
     --data-binary @shm_actions_script.sh

5 - Сотрудничество

5.1 - Разработка

Для разработки SHM необходимо скачать все файлы из репозитория на свой компьютер.

База данных (БД) для разработчиков уже наполнена некоторыми тестовыми данными. Каждый раз, при запуске SHM в режимие разрабтки, БД сбрасывается в значения по-умолчанию.

Установка

Для разработки SHM сделайте следующее:

  1. Установите на свой компьютер: git, docker и docker-compose
  2. Создайте отдельную директорию shm-dev и перейдите в неё
  3. Скачайте docker-compose.yml файл для разрабтки:
    curl https://raw.githubusercontent.com/danuk/shm/master/contributing/docker-compose.yml
    
  4. Авторизуйтесь (или зарегистрируйтесь) на https://github.com и сделайте Fork для следующих репозиториев (этот шаг можно пропустить, если не планируете делиться вашими наработками):
  1. Выполните следующие команды для клонирования (скачки) основных репозиториев (вместо danuk используйте ваш логин на github, если делали Fork):
  • git clone git@github.com:danuk/shm.git
  • git clone git@github.com:danuk/shm-admin.git
  • git clone git@github.com:danuk/shm-client.git

Запуск и остановка SHM

Запуск и остановка SHM осуществляется из директории shm-dev

Для запуска SHM выполните команду: docker-compose up -d

После запуска всех контейнеров Вы можете использовать следующие URL:

  • http://127.0.0.1:8081 - Админский интерфейс SHM. Логин: admin, Пароль: admin
  • http://127.0.0.1:8082 - Интерфейс пользовелей SHM

Для остановки SHM выполните команду: docker-compose down

Редактирование файлов (разработка)

Ядро системы, файлы Админки и файлы Кабинета пользователей располагаются в отдельных репозиториях. На шаге “Установка” мы склонировали нужные репозитории. Таким образом:

  • Файлы ядра SHM находятся в: shm-dev/shm
  • Файлы Админки находятся в: shm-dev/shm-admin
  • Файлы Кабинета клиента находятся в: shm-dev/shm-client

Меняя нужные файлы в нужных директориях мы будем видеть соответствующий результат, без перезапуска docker контейнеров.

Например, изменив файл в директории shm-admin можно увидеть результат обновив страницу админки (http://127.0.0.1:8081).

Тестирование

Если Вы внесли изменения в ядро SHM, то обязательно запустите тесты, чтобы убедиться, что не сломан основной функционал:

docker exec -it shm-dev-core-1 bash -c 'prove t/*'

Делитесь Вашими наработками

Если Вы сделали что-то, чем хотели бы поделиться с другими людьми, закомитьте Ваши изменения и откройте Pull Request, чтобы внести Ваш код в основные репозитории SHM.

5.2 - Финансовая помощь

Если Вы хотите помочь проекту и поблагодарить разработчика, Вы можете сделать это путем перевода произвольной суммы через QR код, либо по ссылке. Спасибо.

Банковская карта

QR-code

https://www.tinkoff.ru/rm/firsov.daniil1/yX53F64253

Tether (TRC20) - USDT

QR-code

Мой публичный адрес для получения USDT: TYxksdjm3ji7q69ZPDcBLh7X7F7Lgds4m6

Ссылка для Trust Wallet