配置说明
配置以环境变量为主，示例见仓库：
- 本地：
.env.example→ 复制为.env - 生产：
.env.production.example
完整说明见仓库 docs/config.md、docs/security.md。下文是入门级必知项。
1. HTTP 与运行环境
| 变量（示例名） | 含义 |
|---|---|
APP_ENVIRONMENT | development / production 等 |
HTTP_ADDR | 监听地址，如 :8080 |
HTTP_NETWORK | 通常 tcp |
HTTP_SHUTDOWN_TIMEOUT_SECONDS | 优雅退出超时 |
FRONTEND_BASE_URL | 前端基址（邮件链接、CORS 相关） |
CORS_ALLOWED_ORIGINS | 允许的跨域来源 |
2. 数据库
| 变量 | 含义 |
|---|---|
REPOSITORY_DRIVER | 如 sql；本地也可能走 SQLite 默认路径（以代码/文档为准） |
DATABASE_URL | MySQL 等连接串；迁移与生产几乎总是需要 |
DB_MAX_OPEN_CONNS 等 | 连接池参数 |
生产：数据库由外部提供，部署路径不负责替你建库实例。
3. 认证与加密
| 变量 | 含义 |
|---|---|
JWT_SECRET | 令牌密钥，生产必须替换 |
JWT_TTL_SECONDS | 令牌有效期 |
DATA_ENCRYPTION_ACTIVE_KEY 等 | 字段级加密密钥（与 JWT 分离） |
AUTH_COOKIE_* | Cookie 安全属性 |
危险
生产环境禁止使用示例里的 dev-secret / change-me。
密钥轮换与 cookie 策略见仓库 security 文档。
4. 邮件
| 变量 | 含义 |
|---|---|
EMAIL_DRIVER | 本地常用 dev；生产期望 smtp |
SMTP_* | 真实 SMTP |
EMAIL_TEMPLATE_DIR | 模板目录，默认 templates/email |
5. 设备与命令（IoT）
常见前缀（名称以 .env.example 为准）：
DEVICE_SECRET_PEPPERDEVICE_COMMAND_*（TTL、重试、worker）DEVICE_OFFLINE_THRESHOLD_SECONDS等
改这些会直接影响设备在线判定与命令投递行为，生产变更要当配置发布管理。
6. 任务与后台
JOBS_WORKER_CONCURRENCYJOBS_WORKER_JOB_TIMEOUT_SECONDSJOBS_WORKER_LEASE_SECONDS
控制 jobs 模块的并发与租约，避免重叠执行与租约过短。
7. 管理端与其它开关
ADMIN_API_ENABLED：默认应false；开启须有会话与平台角色授权，且网络暴露面可控MQTT_*：本地run-mqtt-dev时使用SNOWFLAKE_WORKER_ID：多实例时保持唯一
8. 配置纪律
- 本地
.env不进库 - 生产用 shared env 文件 + 部署脚本引用（见 构建与部署）
- 预发与生产关键项不一致视为配置漂移风险
- 变更配置等同变更发布：可回滚、可观察
下一步：API 与鉴权导读。