Общая архитектура

aihelpme.ru состоит из веб-фронтенда, основного сервиса на Go и сервиса разбора документов на Python; бизнес-данные хранятся в базе данных, а асинхронные задачи планируются через Redis. Векторное хранилище, объектное хранилище, граф знаний и сервисы моделей настраиваются в соответствии с требованиями развёртывания.

Состав системы

aihelpme.ru использует трёхпроцессную базовую архитектуру «основной сервис + фронтенд + микросервис разбора документов», плюс две инфраструктурные зависимости — PostgreSQL и Redis; остальные компоненты (векторное хранилище, граф знаний, поиск в интернете и т. д.) опциональны и включаются по мере необходимости через профили Docker Compose.

Основные сервисы (запускаются по умолчанию)

Сервис	Образ / сборка	Порт	Назначение
app	wechatopenai/weknora-app (docker/Dockerfile.app, Go)	8080	Основной бэкенд: REST API, RAG-поиск, движок агентов, worker асинхронных задач, подключение каналов IM/Embed. Проверка здоровья GET /health
frontend	wechatopenai/weknora-ui (frontend/, NGINX + статические артефакты Vue3)	80	Веб-интерфейс; NGINX одновременно выступает обратным прокси и перенаправляет /api на app (APP_HOST/APP_BACKEND_PORT/APP_SCHEME могут указывать на удалённый бэкенд)
docreader	wechatopenai/weknora-docreader (docker/Dockerfile.docreader, Python)	50051 (expose только внутри сети compose, на хост не маппится)	Микросервис разбора документов: сервер gRPC, разбор и рендеринг страниц в 25+ форматах PDF/DOCX/Excel/EPUB/веб-страницы и др. Проверка здоровья grpc_health_probe
postgres	paradedb/paradedb:v0.25.11-pg17	5432 (внутри сети)	Основная БД. Дистрибутив ParadeDB включает полнотекстовый поиск BM25 и векторные возможности pgvector, поэтому при развёртывании по умолчанию отдельное векторное хранилище не требуется (RETRIEVE_DRIVER=postgres)
redis	redis:7.0-alpine (appendonly + requirepass)	6379 (внутри сети)	Очередь задач Asynq, управление SSE-потоками (межэкземплярное), pub/sub system_settings, ограничение скорости и распределённый шлюз конкурентности моделей
sandbox	wechatopenai/weknora-sandbox (docker/Dockerfile.sandbox)	—	Стандартный рабочий образ платформы; может напрямую использоваться как Docker-бэкенд пространства, а при подключении CubeSandbox/E2B автоматически регистрируется через template API и используется для навыков агента

app и docreader дополнительно передают изображения — продукты разбора — через общий том docreader-tmp (монтируется в /tmp/docreader); локальный том файлового хранилища app — data-files (/data/files).

Опциональные компоненты (профиль Compose)

Сервис	profile	Назначение
searxng (+ одноразовый searxng-init)	searxng / full	Самостоятельно размещаемый метапоисковик, предоставляющий агенту Web Search (по умолчанию привязка 127.0.0.1:8888)
neo4j	neo4j / full	Хранилище графа знаний (GraphRAG), переключатель NEO4J_ENABLE, протокол Bolt 7687
minio	minio / full	Объектное хранилище (STORAGE_TYPE=minio)
qdrant / milvus / weaviate	соответствующие одноимённые профили	Отдельные векторные хранилища (переключается через RETRIEVE_DRIVER)
doris-fe + doris-be	doris	Поисковый движок Apache Doris 4.1 (FE MySQL 9030 / FE HTTP 8030 Stream Load / BE 8040)
odl-hybrid	odl-hybrid	Гибридный бэкенд разбора PDF OpenDataLoader (docreader вызывает его по HTTP :5002)
dex	dex / full	Тестовый IdP OIDC (совместно с OIDC_AUTH_ENABLE)
langfuse-* (web/worker/clickhouse/minio/db-init)	langfuse	Самостоятельный стек наблюдаемости LLM, переиспользует postgres платформы (новая БД langfuse) и redis (DB 1)

Кроме того, бэкенд на Go может напрямую подключаться к внешним движкам, не входящим в compose: Elasticsearch v7/v8, OpenSearch, облачный VectorDB, а также 8 видов объектного хранилища (local/MinIO/COS/TOS/S3/OSS/KS3/OBS).

Формы развёртывания

Помимо стандартного развёртывания через Docker Compose, репозиторий поддерживает:

• Режим Lite: DB_DRIVER=sqlite (встроенное векторное расширение sqlite-vec)+ без настройки REDIS_ADDR (Asynq вырождается во внутрипроцессный SyncTaskExecutor), работа одним бинарником, статические ресурсы фронтенда встроены (при handler.Edition == "lite" их обслуживает сам процесс Go);
• Десктопная версия: cmd/desktop упакован в десктопное приложение на базе Wails v2, сессии могут выполняться в песочнице локальной операционной системы (сейчас только macOS, на базе Seatbelt);
• Kubernetes: чарт helm/; bare-metal: юниты systemd в deploy/.

Список технологического стека

Слой	Технология	Версия/примечание
Язык бэкенда	Go	go.mod объявляет go 1.26.0
Веб-фреймворк	github.com/gin-gonic/gin	v1.12.0
ORM	gorm.io/gorm + драйвер postgres/sqlite	v1.31.1; SQLite поставляется с векторным расширением sqlite-vec
Внедрение зависимостей	go.uber.org/dig	v1.19.0 (инъекция через конструкторы, см. раздел о дизайне бэкенда)
Асинхронные задачи	github.com/hibiken/asynq	v0.26.0 (на базе Redis, 6 пулов worker)
Кэш/очередь	github.com/redis/go-redis/v9	v9.14.1
Аутентификация	github.com/golang-jwt/jwt/v5 + OIDC	три состояния: JWT Bearer / X-API-Key / OIDC
Миграции БД	github.com/golang-migrate/migrate/v4	migrations/versioned/*.up.sql, при запуске автоматически выполняется AUTO_MIGRATE
Логирование	github.com/sirupsen/logrus + ротация lumberjack	собственный formatter, сквозной request_id
Конфигурация	github.com/spf13/viper + config/config.yaml + переменные окружения	—
Наблюдаемость	OpenTelemetry + Langfuse (internal/tracing/langfuse)	trace на уровне вызовов LLM
gRPC	google.golang.org/grpc v1.81.0	вызов docreader
Подключение LLM	собственный слой протоколов internal/models/api (по одному пакету на проводной формат OpenAI / Anthropic / Gemini / DashScope и т. д.), Ollama, LKE SDK и др.	27 вендоров объявлены в internal/models/providers, см. Управление моделями
Векторы/поиск	pgvector, ES v7/v8, OpenSearch, Qdrant, Milvus, Weaviate, Doris, VectorDB, sqlite-vec	динамически собираются по RETRIEVE_DRIVER и таблице vector_stores
Граф знаний	neo4j-go-driver/v6	опционально
Анализ данных	DuckDB (duckdb-go/v2), валидация SQL pg_query_go	инструмент анализа данных агента
Пул горутин	panjf2000/ants/v2	пул параллелизма обработки документов (CONCURRENCY_POOL_SIZE)
MCP	mark3labs/mcp-go v0.52.0	внешние MCP-инструменты агента (включая OAuth)
Документация API	swaggo/gin-swagger	в не-release режиме открывает /swagger
Фронтенд-фреймворк	Vue 3 (^3.5)+ TypeScript + Vite 7	frontend/package.json
UI/состояние фронтенда	TDesign Vue Next, Pinia, Vue Router 4, vue-i18n	Marked/KaTeX/Mermaid/highlight.js для рендеринга форматированного текста
Сервис разбора документов	Python + grpcio	docreader/main.py; парсеры в docreader/parser/ (pdf/docx/excel/epub/web/image/markitdown/opendataloader и др.)
Десктоп	Wails v2	cmd/desktop

Способы межпроцессного взаимодействия

Канал	Протокол	Описание
Браузер → frontend(NGINX) → app	HTTP/HTTPS (REST + SSE)	NGINX обратный прокси /api; чат идёт через потоковый ответ SSE
app → docreader	gRPC (по умолчанию docreader:50051, DOCREADER_TRANSPORT=grpc, поддерживает TLS/mTLS и GRPC_AUTH_TOKEN)	proto определён в docreader/proto/; большие файлы идут потоковым ReadStream
app → postgres	PostgreSQL wire (GORM/pgx)	бизнес-данные + BM25 + pgvector
app ↔ redis	RESP (поддержка TLS)	① очередь задач Asynq (разбор/обогащение/Wiki/память и др.); ② Stream Manager для возобновления SSE-потока после разрыва (STREAM_MANAGER_TYPE); ③ Pub/Sub изменений system_settings; ④ ограничение скорости каналов Embed; ⑤ распределённый семафор конкурентности per-model
app → neo4j	Bolt (bolt://neo4j:7687)	доступ к сущностям/связям GraphRAG
app → searxng / провайдер веб-поиска	HTTP	проверка по белому списку SSRF (SSRF_WHITELIST_EXTRA по умолчанию пропускает внутри compose searxng,qdrant,milvus,weaviate,doris-fe,doris-be,minio; после включения SSRF_DNS_WHITELIST_ONLY разрешён исходящий трафик только по белому списку)
app → векторное хранилище/объектное хранилище/провайдер LLM	соответствующие SDK (HTTP/gRPC/протокол MySQL)	Doris работает по протоколу MySQL + Stream Load HTTP
app → бэкенд песочницы	Docker Engine API / control plane и data plane Cube/E2B	выполнение сессий, установка навыков и файловые артефакты; выбор по конфигурации песочницы пространства
MCP-клиент → app	Streamable HTTP (/mcp/:endpoint_id, у каждого эндпоинта отдельный Bearer Token)	встроенный MCP Server, предоставляющий внешним MCP-клиентам возможности вроде поиска по базам знаний пространства, см. Интеграция MCP
Расширение Chrome ↔ app	WebSocket (/api/v1/local-browser/extension, при удалённом развёртывании требуется WSS)	возможности локального браузера: процесс app ведёт демон BrowserSkill, расширение выполняет веб-задачи в браузере пользователя, см. Локальный браузер
app ↔ платформы IM	HTTP webhook / SDK длительного соединения	WeChat, WeCom, Feishu, DingTalk, Slack, Telegram, QQ, Mattermost, Yunzhijia (internal/im/)

Общая схема архитектуры

Типичная цепочка запроса: загрузка документа и его разбор с индексацией

На схеме ниже показан полный путь документа от загрузки до готовности к поиску, охватывающий большинство взаимодействий между компонентами (синхронное API, асинхронные задачи Asynq, разбор по gRPC, Embedding и запись векторов, подзадачи обогащения):

Цепочка диалога (POST /api/v1/knowledge-chat/:session_id или agent-chat)— синхронный SSE: Handler → SessionService → конвейер плагинов chat_pipeline (понимание запроса → параллельный поиск → rerank → слияние → сборка Prompt → потоковое дополнение LLM) → через Stream Manager (Redis/память) поток токенов возвращается клиенту, подробности в разделе о дизайне бэкенда.

Обзор каталогов верхнего уровня репозитория

Каталог	Назначение
cmd/	Исполняемые точки входа. cmd/server: основной сервис (main/bootstrap/listen + обработка сигналов платформы); cmd/desktop: десктопная версия Wails; cmd/download: вспомогательный инструмент загрузки моделей/ресурсов
internal/	Весь бизнес-код бэкенда на Go (слоистая структура описана в разделе о дизайне бэкенда): handler, application/service, application/repository, container (DI), router, middleware, types, agent, im, mcp, stream, sandbox и др.
frontend/	Веб-фронтенд Vue3 + Vite + TDesign, артефакты сборки обслуживаются NGINX или встроены в режиме Lite
docreader/	Микросервис разбора документов на Python gRPC: точка входа сервера main.py, 25+ парсеров в parser/, разделители в splitter/, определения протокола в proto/, отдельная сборка Dockerfile.docreader
cli/	Командная строка weknora: операции с ресурсами — базы знаний, документы, поиск, сессии, агенты, модели, MCP, навыки и т. д., а также диагностика doctor, см. CLI
client/	Go SDK: оборачивает API платформы в виде HTTP-клиента для интеграции при вторичной разработке
mcp-server/	MCP Server, реализованный на Python (weknora_mcp_server.py), предоставляет API платформы как MCP-инструменты MCP-клиентам вроде Claude
miniprogram/	Клиент в виде мини-программы WeChat (WXML/WXSS/JS)
migrations/	Миграции БД golang-migrate: versioned/ (основная линия Postgres NNNNNN_*.up/down.sql), sqlite/ (режим Lite), paradedb/, mysql/
config/	Конфигурация выполнения: основной конфиг config.yaml, встроенные агенты builtin_agents.yaml, пресеты агентов agent_type_presets.yaml, декларативные встроенные модели builtin_models.yaml.example, наложение каталога вендоров моделей models.json.example, шаблоны промптов prompt_templates/
docker/	Dockerfile каждого образа (app/docreader/sandbox/odl-hybrid) и конфигурация searxng
deploy/	Ресурсы развёртывания на bare-metal (юниты служб systemd и др.)
helm/	Helm-чарт Kubernetes (Chart.yaml / values.yaml / templates/)
examples/	Примеры кода использования API; examples/skills/ — примеры пакетов навыков агента
dataset/	Наборы QA-данных для оценки и скрипты их генерации
scripts/	Вспомогательные скрипты сборки/запуска/миграции (например start_all.sh; build_frontend_dist.sh для сборки Lite / десктопа, образ UI собирается многоэтапно через frontend/Dockerfile)
tests/, testdata/	Интеграционные тесты и тестовые данные
misc/	Разное (например dex-config.yaml — тестовая конфигурация OIDC)
packages/	Отдельно публикуемые интеграционные пакеты, например плагин DeepSeek Harness packages/dsh-weknora, см. DeepSeek Harness
docs/	Устаревшие документы, снятые с сопровождения; временно хранит сгенерированные пакеты Swagger, релизные ресурсы и исторические изображения

Примечание: имя модуля Go — aihelpme.ru; в корне также лежат docker-compose.yml (продакшн-оркестрация) и docker-compose.dev.yml (оркестрация для разработки), Makefile, VERSION и т. д.

Следующая статья «Дизайн бэкенда на Go» подробно разбирает внутреннее устройство internal/: слоистая архитектура, внедрение зависимостей dig, процесс запуска, маршрутизация и RBAC, middleware, доменные модели и соглашения об ошибках/логировании.