localcraft.env.example

# ============================================================
# localcraft 生产环境变量（安装到 /etc/localcraft/localcraft.env）
# 权限要求: 0640 root:localcraft
# 修改后:   systemctl restart localcraft
# ------------------------------------------------------------
# ⚠ 语法限制（docs/05 §6.2）：systemd 的 EnvironmentFile 只支持简单的
#   KEY=VALUE，**不支持 export、不支持 $(...)、不支持变量引用**。
#   含空格的值要写成 KEY="a b"。
# ⚠ ExecStart 里用到了 ${LOCALCRAFT_HOST} / ${LOCALCRAFT_PORT} / ${LOCALCRAFT_LOG_LEVEL}，
#   systemd 会对这些做展开。**变量未定义会让 unit 直接启动失败**
#   （Referenced but unset environment variable），所以这三项必须保留。
# ============================================================

# ---------- 前端托管方式 ----------
# 这一项**应用本身不读**，只被 scripts/precheck.sh 与 install.sh 用来决定检查哪些前置条件。
#   nginx  —— nginx 反代：负责 TLS、限流、静态加速（LOCALCRAFT_HOST 保持 127.0.0.1）
#   direct —— 直连：后端自己托管前端构建产物，直接 IP:PORT 访问，**不需要 nginx**
#             （LOCALCRAFT_HOST 必须是 0.0.0.0，否则只有本机能访问）
# 两种方式应用都会自行下发安全响应头（CSP / X-Frame-Options / nosniff …），
# 区别只在于 nginx 模式多一层 TLS 与限流。
LOCALCRAFT_WEB_MODE=nginx

# ---------- 基础运行参数 ----------
# 监听地址。两种部署方式的要求不同：
#   nginx  模式：127.0.0.1 —— 只让本机 nginx 进来，应用不直接对外
#   direct 模式：0.0.0.0   —— 否则别的机器访问不到
LOCALCRAFT_HOST=127.0.0.1
LOCALCRAFT_PORT=8000
LOCALCRAFT_DEBUG=false

# 日志级别要分**两个**变量设，它们管的东西不一样，只设一个会导致"改了没反应"：
#   LOCALCRAFT_LOG_LEVEL → systemd 传给 uvicorn 的 --log-level（框架与访问日志）
#   LOG_LEVEL            → 应用自身的 JSON 结构化日志级别
LOCALCRAFT_LOG_LEVEL=info
LOG_LEVEL=info

LOCALCRAFT_VERSION=1.0.0

# ---------- 数据库 ----------
# 绝对路径需要**四个斜杠**（见 backend/.env.example 的说明）
DATABASE_URL=sqlite+aiosqlite:////var/lib/localcraft/localcraft.db
DB_ECHO=false
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=5
# SQLite 写锁等待毫秒数
DB_BUSY_TIMEOUT=5000

# ---------- 数据目录 ----------
DATA_DIR=/var/lib/localcraft

# ---------- 安全 / 会话 ----------
# 必须用 `openssl rand -hex 32` 生成：
#     SECRET="$(openssl rand -hex 32)"
#     sed -i "s|^SECRET_KEY=.*|SECRET_KEY=${SECRET}|" /etc/localcraft/localcraft.env
SECRET_KEY=REPLACE_WITH_openssl_rand_hex_32
JWT_ALGORITHM=HS256
ACCESS_TOKEN_MINUTES=30
REFRESH_TOKEN_DAYS=7
# 生产走 HTTPS，**必须** true，否则 refresh Cookie 会在明文连接上传输
# 是否给 refresh Cookie 加 Secure 标记。**两种部署方式取值相反**：
#   nginx + TLS（默认）：true —— 浏览器只会在 https 下带上这个 Cookie
#   direct 明文 HTTP   ：false —— 若保持 true，刷新页面就会掉登录态
# 判断标准很简单：用户访问的是不是 https:// —— 是则 true，否则 false。
COOKIE_SECURE=true
LOGIN_MAX_FAILURES=5
LOCKOUT_MINUTES=15

# ---------- 接口文档 ----------
# 生产关闭；排障时临时置 true 再 systemctl restart
API_DOCS_ENABLED=false

# ---------- 可观测性（M7）----------
# 慢请求告警阈值（毫秒）。超过它的请求会单独打一条 `warn`，
# 日志里带 request_id / duration_ms / sql_count，便于与访问日志对账。
#   0 = 关闭该告警。
# 默认 1000：NFR-PERF-01 的验收线是「100 并发 P95 < 300ms」，
# 1000 是它的三倍多，只报真正异常的单请求，假阳性接近零。
SLOW_REQUEST_MS=1000

# Prometheus 指标端点 GET /metrics。**默认关闭**。
# 开启后它位于 /api/v1 契约面之外，不进入 openapi.json。
# 注意：指标按**进程**统计，多 worker 时每个 worker 各报一份，
# 需要由 Prometheus 侧按 label 聚合。
LOCALCRAFT_METRICS_ENABLED=false

# /metrics 的 Bearer Token。**留空时只允许 127.0.0.1 / ::1 来源读取**，
# 非本机来源一律 401（绝不裸奔 —— 指标里含端点名与用量分布）。
# 一旦配置了它，**包括本机在内都必须带对 token**。
# 生成方式：openssl rand -hex 32
LOCALCRAFT_METRICS_TOKEN=

# 每个路由保留的耗时样本数上限（分位数是进程内蓄水池估计值，不是精确分位数）。
# 内存占用约为「路由数 × 该值 × 8 字节」，1024 对几十个路由是 KB 级。
LOCALCRAFT_METRICS_SAMPLE_MAX=1024

# 每请求 SQL 条数的计数开关。**默认关闭**（关闭时连 SQLAlchemy 的事件监听器
# 都不挂，生产零开销）。排障或压测时置 1，响应头会多出 `X-SQL-Count`。
# LOCALCRAFT_SQL_COUNT=1

# 门户分类/类型分面（facets）的 30 秒进程内缓存。**默认开启**。
# 置 1 绕过缓存，有两个用途：
#   1) 跨版本的性能 A/B 对比 —— 不绕过时测到的是缓存命中率，不是查询本身；
#   2) 排障 —— 怀疑分类计数陈旧时，临时关掉就能确认是不是缓存造成的。
# 生产不要设（它只影响读路径的性能，不影响正确性）。
# LOCALCRAFT_DISABLE_FACET_CACHE=1