UBA Appendix: Ports, Glossary, Known Limitations & FAQ
1. Port Reference
| Service / Component | Service listening port | docker-compose host mapping | Notes |
|---|---|---|---|
| Admin Service REST | 5600 | 5600 | Same |
| Admin Service SSE | 5601 | 5601 | Same |
| Collector Service HTTP | 5700 | 5700 | Same |
| Core Service gRPC | Dynamic (etcd discovery) | (not mapped) | Discovered via etcd inside containers |
| PostgreSQL | 5432 | 5432 | Same |
| Redis | 6379 | 6379 | Same |
| Kafka | 9092 | 9092 | Accessed as kafka:9092 inside containers |
| Etcd | 2379, 2380 | 2379, 2380 | Same |
| MinIO API / Console | 9000 / 9001 | 9001 / 9002 | Same |
| Jaeger UI | 16686 | 16686 | Same |
| Doris FE (MySQL / HTTP) | 9030 / 8030 | 9030, 8030, 9010 | Same |
| Doris BE | 8040, 9050 | 8040, 9050 | Same |
| Superset | 8088 | 8088 | Same |
The docker-compose port mappings have been unified with the service listening ports (admin
5600/5601, collector5700), so the host machine can access services directly via their listening ports. See Configuration Reference for details.
2. Glossary
| Term | Meaning |
|---|---|
| UBA | User Behavior Analytics |
| UEBA | User and Entity Behavior Analytics (an evolution of UBA, extended to entities such as devices/apps/endpoints) |
| Collector | Ingestion BFF; receives SDK reports and forwards them to Kafka |
| Core | Core business service; ingestion/modeling/queries/risk/tags |
| Admin | Admin console BFF; HTTP gateway + SSE, thin forwarding |
| OLAP | Columnar analytics engine; UBA supports Doris (default) or ClickHouse |
| events_fact | Behavior event fact table (core analytics data source) |
| sessions_fact | Session-level aggregated fact table |
| cohort | A queue of users from the same period, used in retention analysis |
| appId / appSecret | Application-level authentication credentials, created in the admin console's "App Management" |
| tenantId | Tenant ID; authoritatively identified server-side by appId, never reported by clients |
| super properties | Common properties; once set, every event carries them automatically |
| UseClickHouse | Compile-time constant that decides the OLAP engine (false = Doris, the default) |
| Asynq | Redis-based asynchronous task queue |
| Connect-RPC | Frontend TypeScript API client protocol (generated from proto) |
3. Known Limitations & Roadmap
This section honestly records the current state of the code, to help evaluate production readiness and plan secondary development.
Known Gaps
Note: Kafka consumption into storage is already a default capability and is not a gap. By default, the OLAP engine consumes Kafka via virtual tables (ClickHouse Kafka engine tables / Doris Routine Load) and loads the data; a microservice consumption interface is also reserved on the Core side, to be enabled when throughput is insufficient. See System Architecture · Kafka Consumption Mechanism.
| Item | Current state | Impact | Planned direction |
|---|---|---|---|
| WAU / MAU hourly granularity | Daily wau/mau already output as true values based on HLL rolling windows; only HOUR granularity degrades to equal DAU due to lack of hourly state | Weekly/monthly actives at hourly granularity are inaccurate | Pre-aggregate hourly uv state |
| Risk detection engine | Only storage/retrieval of risk events/rules is implemented (CRUD; queries like RiskEventService.Get are usable) | No "events matching rules with automatic scoring" | Implement a rule evaluation engine, wired to risk event generation |
Database Consistency Reminders
- docker-compose has unified
POSTGRES_DB=gw_uba, consistent withdbname=gw_ubain the services'data.yaml. - The collector's
data.yamldefaults kafka to127.0.0.1:9092; change it tokafka:9092for containerized deployment. - PostgreSQL table structures are generated by Ent (no hand-written schema.sql);
sql/postgresql/contains only seed/demo data.
Security Defaults (must be rotated)
- JWT key
some_api_key, AES keyf51d66a73d8a0927. - Middleware passwords
*Abcd123456, Doris root with empty password, Superset admin/admin. - CORS
origins: ["*"], no TLS.
See Configuration Reference · Security Checklist for details.
4. FAQ
Q1: How much data can UBA handle?
A: Based on the Doris / ClickHouse columnar engines, it is designed to handle hundreds of millions of events. Actual throughput depends on the engine specs and the Kafka cluster.
Q2: How soon after reporting can data be queried?
A: Within seconds. After the Collector writes to Kafka, the OLAP engine's virtual tables (ClickHouse Kafka engine tables) / Routine Load (Doris) consume and load the data continuously; under normal conditions, data appears in events_fact within seconds. If data cannot be queried for a long time, first check whether the OLAP engine's consumption jobs (Routine Load status / materialized views) are running properly.
Q3: How do I switch between ClickHouse / Doris?
A: Modify the UseClickHouse constant in app/core/service/internal/data/data.go and recompile Core (this is not a runtime configuration).
Q4: Are there native iOS / Android SDKs?
A: Not currently. Only the Web SDK (TypeScript) and C# SDK (Unity/Godot/.NET) are available. Mobile games can use the C# SDK (Unity); purely native apps need to integrate directly via POST /uba/v1/report.
Q5: Is multi-tenancy supported?
A: Yes. tenantId is authoritatively identified and overridden server-side by appId; clients need not care about it, and isolation is natural.
Q6: How do I build custom BI reports?
A: Deploy Superset, connect to Doris's gw_uba database, and build dashboards on the fact tables. See Superset Deployment.
Q7: Why doesn't the frontend update after changing proto?
A: You forgot make ts and to manually sync the TS artifacts, or you forgot make wire. See Code Generation Pipeline.
Q8: Does ent fail to compile with missing Modify?
A: You used the wrong ent generation command (without feature flags). For the correct command, see Code Generation Pipeline · Ent Pitfalls.