전체 아키텍처

WeKnora는 웹 프런트엔드, Go 메인 서비스, Python 문서 파싱 서비스로 구성됩니다. 데이터베이스에 비즈니스 데이터를 저장하고 Redis로 비동기 작업을 스케줄링합니다. 벡터 저장소, 객체 저장소, 지식 그래프, 모델 서비스는 배포 요구 사항에 맞게 구성할 수 있습니다.

시스템 구성

WeKnora는 "메인 서비스 + 프런트엔드 + 문서 파싱 마이크로서비스"의 3개 프로세스를 중심으로 구성되며, PostgreSQL과 Redis라는 두 가지 인프라에 의존합니다. 그 밖의 구성 요소(벡터 데이터베이스, 지식 그래프, 웹 검색 등)는 모두 선택 사항이며 Docker Compose profile로 필요할 때 활성화할 수 있습니다.

핵심 서비스(기본 실행)

서비스	이미지 / 빌드	포트	역할
`app`	`wechatopenai/weknora-app`(`docker/Dockerfile.app`, Go)	`8080`	메인 백엔드: REST API, RAG 검색, Agent 엔진, 비동기 작업 worker, IM/Embed 채널 연동. 상태 확인 `GET /health`
`frontend`	`wechatopenai/weknora-ui`(`frontend/`, NGINX + Vue3 정적 산출물)	`80`	Web UI. NGINX가 리버스 프록시 역할도 하며 `/api`를 `app`으로 전달합니다(`APP_HOST`/`APP_BACKEND_PORT`/`APP_SCHEME`으로 원격 백엔드 지정 가능).
`docreader`	`wechatopenai/weknora-docreader`(`docker/Dockerfile.docreader`, Python)	`50051`(compose 네트워크 내부에만 expose하며 호스트에는 매핑하지 않음)	문서 파싱 마이크로서비스: gRPC 서버로 PDF/DOCX/Excel/EPUB/웹페이지 등 25개 이상의 형식을 파싱하고 페이지를 렌더링합니다. 상태 확인 `grpc_health_probe`
`postgres`	`paradedb/paradedb:v0.22.2-pg17`	`5432`(네트워크 내부)	메인 데이터베이스. ParadeDB 배포판에는 BM25 전문 검색과 pgvector 벡터 기능이 포함되어 있어 기본 배포에는 별도의 벡터 데이터베이스가 필요하지 않습니다(`RETRIEVE_DRIVER=postgres`).
`redis`	`redis:7.0-alpine`(`appendonly` + `requirepass`)	`6379`(네트워크 내부)	Asynq 작업 큐, SSE 스트림 관리(인스턴스 간), system_settings 발행/구독, 속도 제한, 분산 모델 동시 실행 게이트
`sandbox`	`wechatopenai/weknora-sandbox`(`docker/Dockerfile.sandbox`)	—	WeKnora 표준 런타임 이미지. 공간의 Docker 백엔드에 직접 사용할 수 있으며, CubeSandbox/E2B 연동 시에는 템플릿 API를 통해 자동 등록되어 Agent Skills에 사용됩니다.

app과 docreader는 공유 볼륨 docreader-tmp(/tmp/docreader에 마운트)를 통해 파싱 결과 이미지를 전달합니다. app의 로컬 파일 저장 볼륨은 data-files(/data/files)입니다.

선택적 구성 요소(Compose profile)

서비스	profile	용도
`searxng`(+ 일회성 `searxng-init`)	`searxng` / `full`	자체 호스팅 메타 검색 엔진으로 Agent에 Web Search를 제공합니다(기본 바인딩 `127.0.0.1:8888`).
`neo4j`	`neo4j` / `full`	지식 그래프 저장소(GraphRAG). 활성화 설정은 `NEO4J_ENABLE`, Bolt 프로토콜 포트는 `7687`입니다.
`minio`	`minio` / `full`	객체 저장소(`STORAGE_TYPE=minio`)
`qdrant` / `milvus` / `weaviate`	각각 같은 이름의 profile	독립형 벡터 데이터베이스(`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`	OpenDataLoader PDF 하이브리드 파싱 백엔드(docreader가 HTTP `:5002`로 호출)
`dex`	`dex` / `full`	OIDC 테스트용 IdP(`OIDC_AUTH_ENABLE`과 함께 사용)
`langfuse-*`(web/worker/clickhouse/minio/db-init)	`langfuse`	자체 구축 LLM 관측성 스택. WeKnora의 postgres(새 `langfuse` 데이터베이스 생성)와 redis(DB 1)를 재사용합니다.

또한 Go 백엔드는 compose에 포함되지 않은 외부 엔진에 직접 연결할 수 있습니다. Elasticsearch v7/v8, OpenSearch, Tencent Cloud VectorDB, Volcengine VikingDB와 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 기반 데스크톱 애플리케이션으로 패키징
Kubernetes: helm/ Chart, 베어메탈: deploy/ systemd 유닛, macOS: Formula/ Homebrew 포뮬러

기술 스택 목록

계층	기술	버전/설명
백엔드 언어	Go	`go.mod`에 `go 1.26.0` 선언
Web 프레임워크	`github.com/gin-gonic/gin`	v1.12.0
ORM	`gorm.io/gorm` + postgres/sqlite driver	v1.31.1, SQLite에 `sqlite-vec` 벡터 확장 포함
의존성 주입	`go.uber.org/dig`	v1.19.0(생성자 주입, 백엔드 설계 문서 참고)
비동기 작업	`github.com/hibiken/asynq`	v0.26.0(Redis 기반, worker 풀 6개)
캐시/큐	`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`)	LLM 호출 단위 trace
gRPC	`google.golang.org/grpc` v1.81.0	docreader 호출
LLM 연동	`sashabaranov/go-openai`, Ollama, Tencent Cloud LKE 등	18개 이상의 모델 제공자(OpenAI 호환 / Ollama / 클라우드 사업자 SDK)
벡터/검색	pgvector, ES v7/v8, OpenSearch, Qdrant, Milvus, Weaviate, Doris, Tencent VectorDB, sqlite-vec	`RETRIEVE_DRIVER`와 `vector_stores` 테이블로 동적 구성
지식 그래프	`neo4j-go-driver/v6`	선택 사항
데이터 분석	DuckDB(`duckdb-go/v2`), `pg_query_go` SQL 검증	Agent 데이터 분석 도구
고루틴 풀	`panjf2000/ants/v2`	문서 처리 동시 실행 풀(`CONCURRENCY_POOL_SIZE`)
MCP	`mark3labs/mcp-go` v0.52.0	Agent 외부 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/메모리 등의 작업), ② SSE 스트림 연결이 끊긴 뒤 이어받기 위한 Stream Manager(`STREAM_MANAGER_TYPE`), ③ `system_settings` 변경 Pub/Sub, ④ Embed 채널 속도 제한, ⑤ 분산형 모델별 동시 실행 세마포어
`app` → `neo4j`	Bolt(`bolt://neo4j:7687`)	GraphRAG 엔터티/관계 저장 및 조회
`app` → `searxng` / Web 검색 provider	HTTP	SSRF 허용 목록 검증(`SSRF_WHITELIST_EXTRA`는 compose 내부의 `searxng,qdrant,milvus,weaviate,doris-fe,doris-be`를 기본 허용)
`app` → 벡터 데이터베이스/객체 저장소/LLM 제공자	각 SDK(HTTP/gRPC/MySQL 프로토콜)	Doris는 MySQL 프로토콜 + Stream Load HTTP 사용
`app` → 샌드박스 백엔드	Docker Engine API / Cube/E2B 제어 영역 및 데이터 영역	세션 실행, 스킬 설치, 파일 산출물 처리. 공간의 샌드박스 설정에 따라 선택됩니다.
`app` ↔ IM 플랫폼	HTTP webhook / 장기 연결 SDK	WeChat, WeCom, Feishu, DingTalk, Slack, Telegram, QQ, Mattermost, Yunzhijia(`internal/im/`)