Configuration

配置说明

配置优先级

客户端 API_ENDPOINT（构建时）

shared/build.gradle.kts 的读取顺序：

1. 根目录 .env 中的 API_ENDPOINT
2. 进程环境变量 API_ENDPOINT
3. 代码默认值 https://ubaa.mofrp.top

.env.sample 当前给出的示例值是 https://ubaa.mofrp.top:2021。本地联调后端时应改成 http://127.0.0.1:5432 或你的本地服务地址。

这是构建时常量，不是运行时热切换配置。修改后必须重新构建客户端模块。

服务端运行时配置

多数服务端配置通过 helper 读取：

1. 根目录 .env
2. 同名系统环境变量
3. 代码默认值

例外：SERVER_PORT 和 SERVER_BIND_HOST 当前在 Application.kt 中只从 .env 读取，缺省分别为 5432 和 0.0.0.0。部署 fat jar 时如果要改监听地址/端口，应在运行目录提供 .env，或同步调整代码读取方式。

.env.sample 变量总览

变量	样例/默认	说明
API_ENDPOINT	sample: https://ubaa.mofrp.top:2021；代码默认: https://ubaa.mofrp.top	客户端构建时写入 BuildKonfig.API_ENDPOINT
SERVER_PORT	5432	后端监听端口；当前只读 .env
SERVER_BIND_HOST	0.0.0.0	后端绑定地址；当前只读 .env
UPDATE_DOWNLOAD_URL	GitHub Releases	客户端版本不一致时的下载地址
JWT_SECRET	开发 fallback: ubaa-dev-secret-unsafe	生产和多节点必须显式设置同一个安全密钥
USE_VPN	false	服务端访问上游时是否启用 WebVPN URL 转写
BYKC_DEBUG_RAW_API_LOG	false	临时输出 BYKC 原始接口响应，排障后关闭
BYKC_DEBUG_PARSED_COURSE_LOG	false	临时输出 BYKC 课程解析结果，排障后关闭
INSTANCE_ID	ubaa-server-1	节点标识；未设置时回退到 HOSTNAME，再回退到 JVM 名称
ENABLE_FORWARDED_HEADERS	true	是否信任 X-Forwarded-*
CORS_ALLOWED_ORIGINS	空	逗号分隔白名单；* 表示放开
ACCESS_TOKEN_TTL_MINUTES	30	access token TTL
REFRESH_TOKEN_TTL_DAYS	7	refresh token TTL
SESSION_TTL_DAYS	7	服务端会话与 Cookie TTL
PRELOGIN_TTL_MINUTES	5	预登录会话 TTL
SESSION_COOKIE_SYNC_INTERVAL_MS	5000	已提交会话 Cookie 回源同步间隔
LOGIN_MAX_CONCURRENCY	6	fresh login 并发上限
AUTH_DISTRIBUTED_LOCK_TTL_MS	20000	认证分布式锁 TTL
AUTH_DISTRIBUTED_LOCK_WAIT_MS	5000	分布式锁等待上限
AUTH_VALIDATION_TIMEOUT_MS	3000	认证状态校验超时预算
AUTH_PRELOAD_TIMEOUT_MS	3000	preload 超时预算
AUTH_LOGIN_TIMEOUT_MS	18000	fresh login 总超时预算
REDIS_URI	redis://localhost:6379	Redis 地址
REDIS_HEALTH_TIMEOUT_MS	1000	/health/ready Redis 探测超时

额外环境变量

变量	说明
HTTP_PROXY / HTTPS_PROXY	服务端上游请求代理
TRUST_ALL_CERTS	仅开发/调试场景，放宽证书校验
UBAA_SERVER_VERSION	可覆盖服务端版本号探测来源

CORS 配置

本地 Web/Wasm 联调通常需要：

CORS_ALLOWED_ORIGINS=http://localhost:8080

如果 dev server 端口变化，按实际 origin 调整。临时调试可设为 *，生产不建议放开。

认证相关约束

• AUTH_DISTRIBUTED_LOCK_TTL_MS 必须 >= max(AUTH_LOGIN_TIMEOUT_MS, AUTH_PRELOAD_TIMEOUT_MS) + 2000ms，启动时会校验。
• 多节点部署至少保证：
  1. 共享同一个安全 JWT_SECRET
  2. 共享同一个 REDIS_URI
  3. 每个节点不同 INSTANCE_ID

常见误区

• 改了 API_ENDPOINT 但客户端仍请求旧地址：通常是没重新构建客户端模块。
• 复制 .env.sample 后直接本地联调：客户端会指向 sample 中的线上地址，需要改成本地后端地址。
• 只用 SERVER_PORT=xxxx java -jar ... 改端口：当前监听端口只读 .env，应提供 .env。
• USE_VPN 未设置时不会自动启用环境探测流程；当前代码没有接线自动探测入口。