174 lines
7.5 KiB
Markdown
174 lines
7.5 KiB
Markdown
<!-- ⚠️ ЛЕГАСИ — НЕ ИСПОЛЬЗОВАТЬ КАК РУКОВОДСТВО.
|
||
Старая памятка для агента/нового чата (апрель 2026).
|
||
Перенесена из корня репозитория в doc/legacy 2026-08-13.
|
||
Описывает устаревший k8s-деплой и порядок работы. -->
|
||
|
||
# ONBOARDING.md — Памятка для нового чата / агента
|
||
# Дата: 2026-04-10
|
||
# Автор: GitHub Copilot (Claude Opus 4.6)
|
||
|
||
---
|
||
|
||
## Что это за проект
|
||
|
||
**SQS-service** — multi-tenant сервис очередей сообщений, совместимый с AWS SQS API.
|
||
Единственный в open source проект такого рода (подтверждено поиском по GitHub: 0 результатов по `multi-tenant sqs compatible`).
|
||
|
||
Ближайшие аналоги — ElasticMQ (Scala) и GoAws (Go), но оба **single-tenant** и предназначены только для local dev/testing.
|
||
|
||
---
|
||
|
||
## Откуда взялся код
|
||
|
||
Основан на **GoAws** (https://github.com/Admiral-Piett/goaws).
|
||
Первый коммит в `sless`: `shared-sqs: Этап 1 — клон GoAWS, удаление SNS, go build OK`
|
||
Затем поверх GoAws построены: мультитенантность, auth, admin API, WebUI, Redis persistence.
|
||
|
||
---
|
||
|
||
## Текущая версия
|
||
|
||
**v0.1.14** — работает в кластере iot-naeel
|
||
|
||
| Параметр | Значение |
|
||
|----------|---------|
|
||
| Endpoint | `https://qu.kube5s.ru` |
|
||
| IP | `185.247.187.151` |
|
||
| Admin token | `sqs-admin-7a7d8bd0c060a75c198d48680f34077a` |
|
||
| Demo Access Key | `SSAK-demo-shared-sqs` |
|
||
| Demo Secret Key | `demo-secret-key-shared-sqs-ngcloud-2026` |
|
||
| Docker image | `naeel/shared-sqs:v0.1.14` |
|
||
| Redis | `rfrm-redisk8s.54467f74-67f5-4ca7-9b4a-bdd50e8c23d6.svc.cluster.local:6379` |
|
||
| Kubeconfig | `/home/naeel/.kube/iot-naeel.yaml` (на ВМ) |
|
||
| Namespace | `shared-sqs` |
|
||
|
||
---
|
||
|
||
## Инфраструктура — ВАЖНО
|
||
|
||
### ВМ и монтирование
|
||
|
||
- **ВМ**: `naeel@5.172.178.213`
|
||
- **SSH-ключ**: `~/.ssh/naeel_vm_id_ed25519`
|
||
- **Реальный путь на ВМ**: `/home/naeel/terra/SQS-service`
|
||
- **Смонтировано как**: `/home/naeel/remote_dev/SQS-service` (sshfs)
|
||
|
||
### ⛔ КРИТИЧЕСКОЕ ПРАВИЛО
|
||
|
||
`/home/naeel/remote_dev/SQS-service` — это **СМОНТИРОВАННАЯ ПАПКА**.
|
||
Физически файлы на ВМ. **ВСЕ команды выполнять ТОЛЬКО через SSH на ВМ:**
|
||
|
||
```bash
|
||
ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 \
|
||
naeel@5.172.178.213 'cd /home/naeel/terra/SQS-service && <КОМАНДА>'
|
||
```
|
||
|
||
Через IDE — ТОЛЬКО редактирование файлов. Терминальные команды — ТОЛЬКО SSH.
|
||
|
||
---
|
||
|
||
## Архитектура кода
|
||
|
||
```
|
||
app/
|
||
├── cmd/goaws.go — точка входа, HTTP сервер
|
||
├── cmd/seed.go — загрузка демо-данных
|
||
├── models/ — Queue, Message, Tenant, SyncQueues (глобальный мьютекс!)
|
||
├── gosqs/ — реализация SQS API (CreateQueue, SendMessage, ReceiveMessage и т.д.)
|
||
├── admin/admin.go — Admin API: создание/получение тенантов
|
||
├── tenant/tenant_store.go — хранилище тенантов (access key → tenant)
|
||
├── auth/auth_middleware.go — AWS Signature V4 парсинг credential
|
||
├── persistence/redis.go — Redis write-through adapter
|
||
├── router/router.go — маршруты HTTP
|
||
├── ui/index.html — WebUI (встроен через embed.go)
|
||
└── utils/, interfaces/ — утилиты
|
||
```
|
||
|
||
---
|
||
|
||
## Известные проблемы (не трогать пока не попросят)
|
||
|
||
1. **Глобальный мьютекс** `models.SyncQueues` — Lock/Unlock на ВСЕ операции. Bottleneck при нагрузке.
|
||
2. **Нет DLQ** (Dead Letter Queue)
|
||
3. **Long Polling naïve** — sleep loop вместо push
|
||
4. **Нет rate limiting** per tenant
|
||
5. **Нет метрик** (Prometheus)
|
||
6. **Single pod** — нет горизонтального масштабирования
|
||
|
||
---
|
||
|
||
## Что делать дальше (от пользователя)
|
||
|
||
### 1. Статистика для биллинга
|
||
|
||
Нужен сбор метрик по каждому тенанту:
|
||
- Количество отправленных/полученных сообщений
|
||
- Количество созданных очередей
|
||
- Объём данных (bytes in/out)
|
||
- Время жизни сообщений
|
||
|
||
**Где встраивать**: `app/gosqs/send_message.go`, `app/gosqs/receive_message.go`, `app/gosqs/create_queue.go`
|
||
**Где хранить**: Новый пакет `app/billing/` или расширить `app/persistence/redis.go`
|
||
**Формат**: Redis HINCRBY per tenant per day, или отдельная таблица в PostgreSQL
|
||
|
||
### 2. Защита конфиденциальности
|
||
|
||
- Тела сообщений не должны логироваться
|
||
- Admin API должен быть доступен только из внутренней сети (или по отдельному порту)
|
||
- Тенанты не должны видеть друг друга (уже реализовано на уровне auth)
|
||
- Рассмотреть шифрование тел сообщений at rest (в Redis)
|
||
- Audit log: кто, когда, что делал
|
||
|
||
**Где встраивать**: middleware в `app/router/router.go`, новый пакет `app/audit/`
|
||
|
||
### 3. Рекомендации по порядку
|
||
|
||
1. Сначала **биллинг** — простой счётчик в Redis, можно сделать за 1 сессию
|
||
2. Затем **audit log** — middleware логирует tenant_id + action + timestamp
|
||
3. Затем **encryption at rest** — обёртка над Redis get/set
|
||
4. В последнюю очередь — rate limiting (зависит от биллинга)
|
||
|
||
---
|
||
|
||
## Тесты
|
||
|
||
| Скрипт | Описание | Как запускать |
|
||
|--------|----------|--------------|
|
||
| `tests/quick_test.sh` | 6 базовых тестов | `bash tests/quick_test.sh` |
|
||
| `tests/hardcore_test.sh` | Суровые тесты | `bash tests/hardcore_test.sh` |
|
||
| `tests/shared_sqs_test.sh` | E2E тесты | `bash tests/shared_sqs_test.sh` |
|
||
|
||
**ВАЖНО**: В `tests/quick_test.sh` используются demo credentials (`SSAK-demo-shared-sqs`).
|
||
В `tests/hardcore_test.sh` может быть admin token — НЕ КОММИТИТЬ в публичные репы!
|
||
|
||
---
|
||
|
||
## Git workflow
|
||
|
||
- Репо: `https://gitea.services.ngcloud.ru/Nail/SQS-service`
|
||
- Ветка: `main`
|
||
- Коммитить и пушить после каждого завершённого этапа (правило из copilot-instructions)
|
||
- Все команды git — через SSH на ВМ
|
||
|
||
---
|
||
|
||
## Сборка и деплой
|
||
|
||
```bash
|
||
# На ВМ:
|
||
cd /home/naeel/terra/SQS-service
|
||
|
||
# Сборка
|
||
docker build -t naeel/shared-sqs:v0.1.15 .
|
||
docker push naeel/shared-sqs:v0.1.15
|
||
|
||
# Деплой
|
||
export KUBECONFIG=/home/naeel/.kube/iot-naeel.yaml
|
||
kubectl set image deployment/shared-sqs shared-sqs=naeel/shared-sqs:v0.1.15 -n shared-sqs
|
||
kubectl rollout status deployment/shared-sqs -n shared-sqs
|
||
```
|
||
|
||
---
|
||
|
||
*Создано: 2026-04-10. Обновлять при значимых изменениях.*
|