.env.example

# go-skeleton .env example.
#
# 复制到 .env 后按需修改。生产环境前请按 README 的 "Production Checklist" 逐项核对。
# 所有 .env / cmd/*/.env 都被 .gitignore 兜底，不会入库。

# ---------- Environment ----------

# 部署环境：development / production。默认 development。
# 设 production 会启用启动期安全 guard：JWT_SECRET 若是占位值/空/过短（<32B）、
# AUTH_DEV_TOKEN_ENABLED=true、GIN_MODE!=release、LOG_FORMAT!=json，进程直接
# fail-fast 拒绝启动；不限流 / TRUSTED_PROXIES 空 / METRICS_ADDR 空则打 warn。
# 注意：这与 GIN_MODE 是两回事——GIN_MODE 控制 gin 框架行为，APP_ENV 控制安全严格度。
APP_ENV=development

# ---------- HTTP Server ----------

# API 进程监听地址。冒号前可填 IP（如 127.0.0.1:3000）只绑回环；
# 单纯 :PORT 表示监听所有网卡。
SERVER_PORT=:3000

# Gin 运行模式：debug / release / test。
# 生产必须 release，否则会打 debug 日志并暴露内部信息。
GIN_MODE=release

# 信任的代理 CIDR 列表（逗号分隔），gin 仅在源 IP 在白名单内时才认
# X-Forwarded-For / X-Real-IP 头取真实客户端 IP。空（默认）= gin 信任
# 所有代理头，**生产裸暴露公网时会让 c.ClientIP() 被伪造**，限流和审计
# 日志都失真——非裸直连场景务必填实际 LB / Ingress 网段。空值在
# APP_ENV=production 下会打 warn。
TRUSTED_PROXIES=

# 单次 HTTP 请求的业务超时。middleware 会用它做 context 超时；
# http.Server 的 Read/Write 在此基础上加 5s slack。
REQUEST_TIMEOUT=30s

# 启动阶段 DB/Redis Ping 的硬超时；超时即 fail-fast 退出。
# 5s 适合裸机/同机房；跨可用区可调到 10s。
STARTUP_PROBE_TIMEOUT=5s

# 收到 SIGTERM 后让 /health 先返 503 的窗口，让 LB 摘流。
# 默认 10s；如果 LB 健康检查间隔 > 10s 需调高，避免摘流不及时。
# 设 0 = 不 drain，直接 Shutdown（开发环境用）。
GRACEFUL_DRAIN=10s

# pprof 调试端点。**生产默认 false**；排障时打开 + SSH 隧道访问，
# 不要直接把 PPROF_ADDR 绑到公网。APP_ENV=production 且 PPROF_ENABLED=true
# 且地址不在 loopback（127.0.0.1 / ::1 / localhost）会触发启动期 warn。
PPROF_ENABLED=false
PPROF_ADDR=127.0.0.1:6060

# systemd Watchdog 心跳周期（仅 Linux + Type=notify 才生效）。
# unit 里设 WatchdogSec=30s 时，心跳间隔建议为它的 1/3。
WATCHDOG_INTERVAL=10s

# 在所有响应写一组对 JSON API 安全的标配响应头：
# X-Content-Type-Options: nosniff / X-Frame-Options: DENY / Referrer-Policy: no-referrer。
# 关掉只是用于本地调试想看裸响应；生产保持默认 true。
SECURITY_HEADERS_ENABLED=true

# 单次请求 body 上限（字节，0 = 不限）。1MB 对 JSON API 已经富余；
# header 由 net/http 的 MaxHeaderBytes 单独限制（代码侧固定 1MB）。
BODY_MAX_BYTES=1048576

# 暴露 Prometheus 抓取端点 /metrics + 挂 HTTP 指标中间件。
# 生产保持 true；通过网络层（不暴露公网 + LB allowlist）控制访问，
# 不走 BearerAuth（Prometheus 抓数据不应带业务身份）。
METRICS_ENABLED=true

# /metrics 暴露位置：
#   空（默认）= 挂在业务 engine 同端口，靠网络层保护；
#   非空（如 127.0.0.1:9090 / 10.0.0.5:9090）= 起独立 http.Server 监听该地址，
#     业务 engine 不再挂 /metrics。生产推荐绑 loopback 或内网地址，让指标
#     与业务端口在 L4 上就隔离开。空值在 production 会触发启动期 warn。
METRICS_ADDR=

# ---------- API Docs (/docs, Stoplight Elements) ----------
# /docs 是基于 Stoplight Elements 的在线文档页，渲染同域 /openapi.json。
# 这些值在启动期一次性读入并预渲染进 HTML，运行时不变。资源走外网 unpkg CDN，
# 内网/离线环境无法渲染。下面各项只影响文档 UI 展示，不进 OpenAPI 契约。

# 文档页 <title>。
DOCS_TITLE=API Docs
# 配色：light / dark / system（跟随系统 prefers-color-scheme）。非法值启动期拒绝。
DOCS_THEME=system
# 隐藏 Elements 的 TryIt 调试面板（设 true 则文档只读，不带在线调用）。
DOCS_HIDE_TRY_IT=false
# 隐藏左侧 Schemas 列表。
DOCS_HIDE_SCHEMAS=false
# 布局：sidebar（左侧导航）或 stacked（单列堆叠）。非法值启动期拒绝。
DOCS_LAYOUT=sidebar
# 左上角 logo 的 URL；留空则不显示。
DOCS_LOGO=

# ---------- Postgres ----------

# Postgres DSN。API 进程必填；worker 进程可选。
# 本地起 make dev-up 时默认值即可直接连。
POSTGRES=postgres://user:password@127.0.0.1:5432/app?sslmode=disable

# GORM 日志级别：silent / error / warn / info。生产推荐 warn。
GORM_LOG_LEVEL=warn

# 连接池上限。生产请按实例规格 + Postgres max_connections 调整。
DB_MAX_IDLE_CONNS=15
DB_MAX_OPEN_CONNS=30
DB_CONN_MAX_LIFETIME=30m
DB_CONN_MAX_IDLE_TIME=5m

# ---------- Redis ----------

# Redis 地址。API 可选（启用 cache / queue 发布需要）；worker 必填。
REDIS_ADDR=127.0.0.1:6379

# Redis 密码，没有就留空。
REDIS_PASSWORD=

# Redis 逻辑库分配。本项目用 0 做应用 cache、6 做异步任务队列，
# 避免 keyspace 冲突。如果 Redis 实例独占，可以都用 0。
REDIS_CACHE_DB=0
REDIS_QUEUE_DB=6

# 连接池上限（0 = 库默认，约 10 * CPU）。同时作用于 cache 客户端（go-redis）
# 和异步队列（asynq client/inspector/server）。高并发场景下单核机器默认值偏小
# 容易卡，按实例规格 + Redis maxclients 调整。
REDIS_POOL_SIZE=0
# 常驻空闲连接数（0 = 不预热）。设值可减少冷启动延迟，但占用 maxclients。
# 仅作用于 cache 客户端（go-redis）；asynq 的连接池不暴露这个参数。
REDIS_MIN_IDLE_CONNS=0

# ---------- Auth (JWT) ----------

# JWT HMAC 密钥。**生产必改**为高熵随机值：openssl rand -base64 48
# 至少 32 字节，避免暴力破解。APP_ENV=production 时这个占位默认值会被启动期
# guard 拒绝（fail-fast），逼你换成真随机值。
JWT_SECRET=change-me-in-production

# JWT iss 字段（issuer）。运行多个服务共用同一个 Redis 时用来区分。
JWT_ISSUER=go-skeleton

# JWT 有效期。短一些更安全（24h 是个折中），需要免登录持久可加 refresh token。
JWT_TTL=24h

# Exposes POST /api/v1/auth/token (dev-only: signs a token for any subject).
# MUST stay false in production. 关掉时路由仍注册，返回 SERVICE_DISABLED 以
# 对齐 OpenAPI 契约。
AUTH_DEV_TOKEN_ENABLED=false

# ---------- Logging ----------

# zap 日志级别：debug / info / warn / error。
LOG_LEVEL=info

# 日志输出格式：json / console。生产**必须** json，否则日志采集器解析不了。
LOG_FORMAT=json

# 触发 stacktrace 的最低级别（error 表示 warn 不带 stack）。
LOG_STACKTRACE_LEVEL=error

# 审计日志（每个请求一行 access log）。
AUDIT_LOG_ENABLED=true

# 不打 access log 的路径，逗号分隔。健康探针 + metrics 抓取每秒打一条没意义。
AUDIT_LOG_EXCLUDE_PATHS=/health,/livez,/metrics

# ---------- CORS / Rate limit ----------

# 允许跨域的 origin，逗号分隔。**生产请显式枚举**，不要留空也不要 *。
# 示例：CORS_ALLOW_ORIGINS=https://app.example.com,https://admin.example.com
CORS_ALLOW_ORIGINS=

# 是否回写 Access-Control-Allow-Credentials: true。骨架默认无状态 JWT
# 走 Authorization 头，**不需要** cookie，保持 false 更安全。仅当前端需要
# 从浏览器自动携带 cookie/session 时才打开。
CORS_ALLOW_CREDENTIALS=false

# IP 限流：每个 IP 每分钟最多多少请求。0 表示不限流。
# 生产建议设值，例如 600（每秒 10 QPS）。
RATE_LIMIT_PER_MINUTE=0

# ---------- Asynq Worker ----------

# Worker 进程的 goroutine 并发上限。
WORKER_CONCURRENCY=10

# 队列与权重，name:weight 用逗号分隔。worker 按权重比例从队列拉任务，
# 6:3:1 表示 60% 时间处理 critical、30% default、10% low。
WORKER_QUEUES=critical:6,default:3,low:1

# 失败任务重试 backoff：第 n 次重试延迟 = min(2^n * RetryBaseDelay, RetryMaxDelay)。
WORKER_RETRY_BASE_DELAY=5s
WORKER_RETRY_MAX_DELAY=1h