av
91138dd39a
- main.go и journal_route_test.go переехали в cmd/transcriber без правок содержимого; образ собирает ./cmd/transcriber поимённо - cmd/oidcstub отвечает на /authorize, /token и /userinfo, проверок не делает и слушает петлевой адрес: войти без Authelia стало чем - ступень сборки приложения переехала на node:24 с alpine — musl ждёт ответа на AAAA, которого нет, и npm ci висел вместо отказа
139 lines
7.1 KiB
Markdown
139 lines
7.1 KiB
Markdown
# Transcriber Service
|
||
|
||
Сервис расшифровки аудиозаписей. Вход один — HTTP API.
|
||
|
||
## Возможности
|
||
|
||
- Приём аудиофайлов через HTTP API
|
||
- Конвертация в ogg через ffmpeg
|
||
- Распознавание речи через Yandex SpeechKit
|
||
- Отслеживание статуса задач расшифровки
|
||
- Встроенная PocketBase для метаданных, файлов и панели владельца; метрики Prometheus
|
||
|
||
## Технологии
|
||
|
||
- **Язык**: Go 1.26, CGO не нужен
|
||
- **Веб-фреймворк**: gin-gonic/gin
|
||
- **Распознавание**: Yandex SpeechKit + Yandex Object Storage (S3)
|
||
- **Конвертация**: ffmpeg
|
||
- **Хранилище, файлы и панель**: встроенная PocketBase
|
||
- **База данных**: SQLite внутри PocketBase (через modernc.org/sqlite, CGO не нужен)
|
||
- **Метрики**: prometheus/client_golang
|
||
|
||
## Установка и запуск
|
||
|
||
1. Клонируйте репозиторий
|
||
2. Установите зависимости:
|
||
```bash
|
||
go mod tidy
|
||
```
|
||
3. Скопируйте образец конфига и заполните его:
|
||
```bash
|
||
cp config.example.toml config.toml
|
||
```
|
||
4. Запустите приложение:
|
||
```bash
|
||
go run ./cmd/transcriber -c config.toml
|
||
```
|
||
|
||
Сервер запустится на порту из `[server] port`, по умолчанию 8080. Нужен
|
||
установленный `ffmpeg`.
|
||
|
||
### Кого пускают
|
||
|
||
Приём и опрос закрыты сессией OIDC. Что её выдаёт и чем она предъявляется —
|
||
[docs/security.md](docs/security.md), «Что разграничивает доступ»; известные
|
||
прорехи образца конфига — [docs/conventions/config.md](docs/conventions/config.md).
|
||
|
||
Локально провайдера нет, и войти при выдуманных адресах нельзя — вместо него
|
||
поднимается заглушка:
|
||
|
||
```bash
|
||
go run ./cmd/oidcstub
|
||
```
|
||
|
||
Значения `[auth]` под неё стоят строками в `config.example.toml`.
|
||
|
||
## Деплой
|
||
|
||
Деплой запускается из `pet-project-server`:
|
||
|
||
```bash
|
||
inv pl -- transcriber
|
||
```
|
||
|
||
Плейбук сам зовёт `task image` (контракт роли `app_image`): образ собирается
|
||
локально и едет на сервер через `docker save`/`load`, реестр не участвует.
|
||
Локально образ можно собрать и руками — `task image` даст `transcriber:dev`.
|
||
|
||
## HTTP API
|
||
|
||
Семь адресов приложения: `POST /api/audio` — приём записи, `GET /api/status/:id`
|
||
— готовность задачи, `GET /auth/login`, `GET /auth/callback` и
|
||
`POST /auth/logout` — вход через провайдера
|
||
([access](openspec/specs/access/spec.md)), `GET /metrics` — метрики Prometheus с
|
||
префиксом `transcriber_`, `GET /health` — проверка живости. Сверх них тем же
|
||
портом отдаётся собственная поверхность встроенного хранилища и панель `/_/` —
|
||
[docs/security.md](docs/security.md), «Из чего строятся пути и ключи».
|
||
|
||
Контракт приёма и опроса нормативен и живёт в
|
||
[openspec/specs/intake/spec.md](openspec/specs/intake/spec.md): поля запроса и
|
||
ответа, коды и условия. Менять его — необратимое действие
|
||
([CLAUDE.md](CLAUDE.md), «Работа»), и второго описания у него быть не должно.
|
||
|
||
## Состояния задач
|
||
|
||
Перечень состояний, переходы между ними и число воркеров —
|
||
[docs/database.md](docs/database.md), разделы «Коллекции» и «Представление
|
||
данных»; как сложен конвейер целиком — [docs/architecture.md](docs/architecture.md).
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
transcriber/
|
||
├── cmd/
|
||
│ ├── transcriber/ # Точка входа сервиса: конфиг, миграции, сборка зависимостей, запуск
|
||
│ └── oidcstub/ # Подставной провайдер OIDC для локального входа
|
||
├── internal/
|
||
│ ├── entity/ # Модели: задача, файл, результат распознавания
|
||
│ ├── contract/ # Интерфейсы адаптеров и репозиториев, типы ошибок
|
||
│ ├── config/ # Разбор config.toml
|
||
│ ├── metrics/ # Метрики Prometheus
|
||
│ ├── service/ # Конвейер расшифровки
|
||
│ ├── controller/
|
||
│ │ ├── http/ # HTTP-обработчики
|
||
│ │ └── worker/ # Фоновые воркеры
|
||
│ └── adapter/
|
||
│ ├── converter/ffmpeg/ # Конвертация аудио
|
||
│ ├── metaviewer/ffmpeg/ # Длительность аудио
|
||
│ ├── recognizer/yandex/ # SpeechKit + Object Storage
|
||
│ └── repo/pocketbase/ # Репозитории, схема коллекций, правила панели
|
||
└── data/ # Каталог данных: база и файлы записей вместе
|
||
├── data.db # База хранилища (создаётся автоматически)
|
||
└── storage/ # Файлы записей в раскладке хранилища
|
||
```
|
||
|
||
## Хранилище
|
||
|
||
Коллекции хранилища — аудиозапись и её приложения. Поля, ключи, правило времени и
|
||
идентификаторов, а также механика захвата задачи воркером —
|
||
[docs/database.md](docs/database.md). Панель владельца — по адресу `/_/` того же
|
||
порта; пароль от неё задаёт сам владелец по приглашению, которое сервис печатает
|
||
в журнал при первом запуске.
|
||
|
||
## Разработка
|
||
|
||
Схему двигают шаги миграций PocketBase на Go —
|
||
`internal/adapter/repo/pocketbase/migrations`, файл на шаг. Непринятые шаги
|
||
накатываются при подъёме хранилища, прежде чем стартуют воркеры и сервер.
|
||
Применённый шаг не переписывается: изменение — только новым файлом шага.
|
||
|
||
Проверки перед коммитом — одной командой:
|
||
|
||
```bash
|
||
task gate
|
||
```
|
||
|
||
Что она гоняет, чем краснеет и какой отказ считается объявленным долгом —
|
||
[CLAUDE.md](CLAUDE.md), раздел «Гейт».
|