120 lines
6.6 KiB
Markdown
120 lines
6.6 KiB
Markdown
# 2026-matrix-csonac
|
||
|
||
Реализация CSoNaC (Centralized System of Notification and Control) для Matrix.
|
||
Раньше был бот с таким же функционалом, но для Telegram. Telegram больше не в
|
||
почёте, и теперь у меня всё в локальном Matrix, поэтому бот тоже перенесён сюда.
|
||
|
||
## Для запуска рекомендуется `docker`
|
||
|
||
1. [Скачайте образ](https://git.tyukalov.su/nikita/-/packages/container/2026-matrix-csonac) (измените версию на нужную вам):
|
||
```bash
|
||
sudo docker pull git.tyukalov.su/nikita/2026-matrix-csonac:0.2
|
||
```
|
||
2. Выполните первый запуск в интерактивном режиме
|
||
```bash
|
||
sudo mkdir runtime
|
||
sudo chown 1000:1000 runtime
|
||
sudo docker run -v ./runtime:/runtime -ti git.tyukalov.su/nikita/2026-matrix-csonac:0.2
|
||
```
|
||
3. В папке `runtime` появится файл `config.json`. Внесите туда нужные настройки
|
||
4. Запустите ещё раз в интерактивном режиме, чтобы авторизоваться
|
||
```bash
|
||
sudo docker run -v ./runtime:/runtime -ti git.tyukalov.su/nikita/2026-matrix-csonac:0.2
|
||
```
|
||
5. Дальше можно запускать контейнер в фоне
|
||
```bash
|
||
sudo docker run -p 127.0.0.1:4980:4980 -v ./runtime:/runtime --detach git.tyukalov.su/nikita/2026-matrix-csonac:0.2
|
||
```
|
||
> Рекомендуется запускать контейнер при помощи `docker compose`.
|
||
|
||
## Запуск без `docker`
|
||
|
||
1. Клонируйте репозиторий и перейдите в его директорию
|
||
```bash
|
||
git clone https://git.tyukalov.su/nikita/2026-matrix-csonac.git
|
||
cd 2026-matrix-csonac
|
||
```
|
||
2. Создайте `venv`, активируйте его
|
||
```bash
|
||
python3 -m venv .venv
|
||
. .venv/bin/activate
|
||
```
|
||
5. Запустите приложение чтобы сгененерировать конфиг
|
||
```bash
|
||
python main.py
|
||
```
|
||
6. Отредактируйте конфиг
|
||
7. Запустите приложение ещё раз, чтобы авторизоваться
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
## Как работает бот
|
||
|
||
Для каждой службы (канала уведомлений) создаётся своя собственная комната и в
|
||
такие комнаты добавляется бот. Затем вся работа с ботом производится при помощи
|
||
команд - текстовых сообщений, начинающихся с *восклицательного знака*.
|
||
Поддерживаются следующие команды:
|
||
- `!help` - получить справку
|
||
- `!info` - получить сведения о комнате
|
||
- `!tokens` - получить список токенов
|
||
- `!auth [SERVICE_NAME]` - создать новый токен (если указать имя сервиса, то
|
||
приложение, использующее токен, не сможет самостоятельно указывать имя
|
||
сервиса - всегда будет использовано имя, указанное вами)
|
||
- `!deauth <TOKEN>` - удалить токен
|
||
- `!name <TOKEN> [SERVICE_NAME]` - указать (или удалить) имя сервиса для токена
|
||
- `!ban <IP> <SECONDS> [REASON]` - забанить указанный IP на указанное число секунд (можно указать причину)
|
||
- `!unban <IP>` - разбанить указанный IP адрес
|
||
- `!bans` - получить список забаненных IP адресов
|
||
|
||
## Как работает веб-сервер
|
||
|
||
Этот бот запускает веб-сервер, используя `web_host` и `web_port` из файла
|
||
конфигурации.
|
||
|
||
> Не открывайте доступ к серверу напрямую! Используйте reverse proxy, например,
|
||
> `nginx`. Это также позволит вам использовать защищённое соединение, что
|
||
> исключит возможность применения атаки Man-in-the-Middle для перехвата токена.
|
||
|
||
Все запросы к веб-серверу являются GET-запросами и требуют авторизации.
|
||
Авторизоваться можно двумя путями:
|
||
1. Использовать HTTP-заголовок `Authorization` и схему `Bearer`. Например:
|
||
```plain
|
||
Authorization: Bearer 1234567890abcdef
|
||
```
|
||
2. Использовать URL параметр `token`. Например:
|
||
```plain
|
||
https://csonac.su/api/notify?token=f1829e94d...
|
||
```
|
||
Рекомендуется использовать первый способ (HTTP-заголовок), так как это позволяет
|
||
избежать раскрытия токена в логах сервера и других местах, где можно посмотреть
|
||
URL прошлых запросов.
|
||
|
||
> Для каждого сервиса, использующего бота, рекомендуется генерировать свой
|
||
> собственный токен. Это позволит отозвать токен только для одного серсива, если
|
||
> токен будет украден.
|
||
|
||
Доступные эндпоинты:
|
||
- `GET /api/notify`
|
||
- **Описание.** Используется, чтобы отправить уведомление в канал.
|
||
- **Параметры запроса**
|
||
- `channel` - код канала, получаемый при помощи команды `!info`,
|
||
выполненной в комнате Matrix
|
||
- `service` - имя сервиса (учитывается, только если для токена не было
|
||
настроено имя сервиса через бота)
|
||
- `text` - текст уведомления (форматирование не поддерживается)
|
||
- **Ответ**
|
||
- В случае успеха сервер вернёт `200` и JSON следующего формата:
|
||
```json
|
||
{
|
||
"notification_id": "Notification ID will be here"
|
||
}
|
||
```
|
||
> В текущей версии `notification_id` не имеет практической пользы и его
|
||
> формат будет меняться.
|
||
- В случае ошибки сервер вернёт JSON следующего формата:
|
||
```json
|
||
{
|
||
"detail": "Error description in English"
|
||
}
|
||
``` |