配置详解
后端的全部配置集中在 backend/app/core/config.py 的 Settings（pydantic-settings）声明，桌面端另有少量进程级环境变量。本页给出配置优先级、环境变量全表，以及三个最常用的运行时开关（会员总开关、限流、BYOK 预设）。
配置优先级
同一配置项的生效顺序：
- 进程环境变量（最高优先）；
.env文件（后端工作目录下，Settings.Config.env_file = ".env"）；- 代码默认值（
config.py中各字段的默认值）。
字段名大小写敏感（case_sensitive = True）。桌面端由 Electron 主进程在拉起 sidecar 时注入环境变量，普通桌面用户不需要手工配置任何一项。
环境变量
基础与安全
| 变量 | 默认值 | 说明 |
|---|---|---|
ENV | development | 运行环境；production 时强制校验三密钥并关闭 DEBUG、关闭 /docs 等接口文档 |
SECRET_KEY | 空（开发态自动生成临时密钥并告警） | 会话签名密钥，生产必填，缺失直接拒绝启动 |
ADMIN_SECRET_KEY | 空（同上） | 管理端密钥，生产必填 |
DATABASE_ENCRYPT_KEY | 空（开发态跳过加密层） | 数据库加密密钥，生产必填 |
DATABASE_URL | sqlite:///./psb.db | 数据库连接串；桌面端由主进程指向数据目录 |
TRUSTED_PROXY_IPS | 空集合 | 可信反代 IP；命中才解析 X-Forwarded-For 做真实客户端限流。注意 pydantic 集合只认 JSON 数组写法，如 ["127.0.0.1"] |
生产校验逻辑见 config.py 的 validate_production：三密钥缺失即 ValueError 拒启；S3 凭证缺失只告警不拒启（桌面 frozen 端无 S3 是正常形态）。
本地模型与 RAG
| 变量 | 默认值 | 说明 |
|---|---|---|
OLLAMA_BASE_URL | http://localhost:11434 | Ollama 服务地址 |
OLLAMA_MODEL | qwen3.5:0.8b | 本地聊天模型 |
OLLAMA_EMBED_MODEL | bge-m3 | 嵌入模型，全库统一 1024 维；指向未安装模型会让向量通道静默退 mock，改后需确认 ollama list 里真实存在 |
OLLAMA_NUM_CTX | 16384 | Ollama 上下文窗口；Ollama 默认 4096 与模型卡宣传值是两回事，必须显式设（app/services/llm_service/service.py） |
RAG_GROUNDING_CHECK | true | 数字 grounding：回答关键数字须在当轮检索资料命中，未命中收紧重答一次、仍不收敛末尾标注 |
RAG_SPECULATION_CHECK | true | 推测标注：模型自认「通用知识」段落流末追加 ⚠️ 标注（纯规则零模型消耗，标注随正文落库） |
站点与跨域
| 变量 | 默认值 | 说明 |
|---|---|---|
API_BASE_URL | http://localhost:8000 | 后端对外地址（支付回调、邮件链接等使用） |
FRONTEND_URL | http://localhost:3000 | 前端对外地址 |
ALLOWED_ORIGINS | http://localhost:3000,http://127.0.0.1:3000 | CORS 允许来源，逗号分隔 |
桌面端专用（由 Electron 主进程注入）
| 变量 | 说明 |
|---|---|
PSB_DESKTOP | 置 1 进入桌面模式：自动唤起 Ollama（app/core/desktop_boot.py）、限流放宽到 600/min、启用桌面会员门等 |
PSB_DATA_DIR | 数据目录（数据库、上传、日志、密钥）；sidecar 启动时 chdir 到此，所有相对路径基于此 |
PSB_PORT | 内嵌后端监听端口；端口冲突时由主进程分配，记录在数据目录 backend-port.json |
手工从终端调试桌面后端的三要素：PSB_DESKTOP=1 + DATABASE_URL 指向数据目录 + SECRET_KEY 三件套（数据目录下 .desktop-secrets.json）。
运行时开关
会员总开关 membership_enabled
会员功能的总闸，存于 feature_flags 系统配置，默认开（缺键即开）：
- 云端判定在
app/services/billing_service.py的check_feature_access； - 桌面端判定在
app/core/desktop_gate.py的membership_enforced，断网时沿用云端缓存值，缓存为 NULL 时 fail-closed（按关闭处理）； - 开关关闭期间全员放行 Pro 功能。
限流默认值
限流按 IP 分桶，实现在 app/core/security_middleware.py：
| 形态 | 通用限流 | 说明 |
|---|---|---|
| 云端生产 | 100/min | 未配置 TRUSTED_PROXY_IPS 时全站共享 127.0.0.1 一个桶，反代部署必须配置 |
| 桌面端 | 600/min | 本机单用户所有请求同桶，放宽避免批量操作把自己 429 |
触发限流返回 429 并带 Retry-After 头。
BYOK 预设目录
BYOK（自带 Key）的厂商预设声明在 app/services/byok_presets.py 的 BYOK_PRESETS：23 家厂商预设（DeepSeek、Kimi、GLM、通义、OpenAI、Anthropic、Google、火山、硅基流动等）+ 1 个自定义中转站（custom）。用户在 /settings/byok 控制台逐家填 Key、点亮卡片；Key 只存用户级设置、读取接口一律掩码回显。BYOK 是 Pro 能力，且只认用户自己的 Key——未填 Key 的 BYOK 模型直接不通，不会回落平台或环境变量。