Quick Start

快速开始

本页目标：让你在本地跑通 Redis + 后端 + 一个客户端入口，并定位到主要开发目录。

前置环境

组件	版本要求	说明
JDK	21	所有 Gradle 模块统一基于 JDK 21
Gradle	使用仓库 Wrapper	使用 ./gradlew / gradlew.bat
IDE	Android Studio / IntelliJ IDEA	Kotlin Multiplatform 开发
Xcode	16+（仅 iOS）	iOS 壳工程调试需要
Redis	本地可用	认证会话主路径依赖 Redis

一次性初始化

git clone <your-repo-url>
cd UBAA
cp .env.sample .env

Windows PowerShell：

Copy-Item .env.sample .env

.env.sample 中的 API_ENDPOINT 是线上示例。本地前后端联调时，把 .env 改成：

API_ENDPOINT=http://127.0.0.1:5432
CORS_ALLOWED_ORIGINS=http://localhost:8080

API_ENDPOINT 是构建时常量，修改后必须重新构建客户端。

启动 Redis

已有本地 Redis 可跳过。用 Docker 启动的最小命令：

docker run --name ubaa-redis -p 6379:6379 redis:7

如果容器已存在：

docker start ubaa-redis

启动后端

macOS/Linux:

./gradlew :server:run -Pdevelopment

Windows:

.\gradlew.bat :server:run -Pdevelopment

默认监听 .env 中的 SERVER_BIND_HOST:SERVER_PORT，样例为 0.0.0.0:5432。

健康检查：

curl http://127.0.0.1:5432/health/live
curl http://127.0.0.1:5432/health/ready

ready 依赖 Redis；Redis 不可用时会返回 503。

启动客户端

推荐先跑桌面客户端：

macOS/Linux:

./gradlew :composeApp:run

Windows:

.\gradlew.bat :composeApp:run

Web/Wasm 开发：

./gradlew :composeApp:wasmJsBrowserDevelopmentRun

Windows:

.\gradlew.bat :composeApp:wasmJsBrowserDevelopmentRun

Wasm 只支持服务器中转模式，确保 API_ENDPOINT 指向本地后端，且服务端允许 dev server 的 origin。

其他平台入口

平台	命令 / 入口
Android	./gradlew :androidApp:installDebug
Web (Wasm)	./gradlew :composeApp:wasmJsBrowserDevelopmentRun
Web (JS)	./gradlew :composeApp:jsBrowserDevelopmentRun
iOS	Xcode 打开 iosApp/iosApp.xcodeproj

首次开发建议

1. 先看 架构总览。
2. 再看你要改的模块：
   • UI 改动：composeApp
   • 接口/DTO/直连逻辑：shared
   • 后端逻辑：server
3. 开始前执行最小验证命令：

./gradlew :server:test :shared:jvmTest :composeApp:jvmTest

关键注意

• API_ENDPOINT 在 shared/build.gradle.kts 构建时注入到 BuildKonfig.API_ENDPOINT；改了地址要重新构建客户端产物。
• 认证不是纯 JWT：服务端还维护 Redis 中的上游会话/Cookie。
• Android/iOS/JVM 支持直连、WebVPN、服务器中转；JS/Wasm 只支持服务器中转。