env.example

# SoulNexus 环境变量配置示例
# 复制此文件为 .env 并修改相应的配置值

# 基础配置
MODE=dev
ADDR=:7072

# 服务器信息配置（可选）
MACHINE_ID=1
SERVER_NAME=SoulNexus
SERVER_DESC=AI Voice Assistant Platform
SERVER_URL=http://localhost:7072
SERVER_LOGO=
SERVER_TERMS_URL=

# ===================
# 数据库配置
# ===================
# SQLite 配置（默认）
DB_DRIVER=sqlite
DSN=./ling.db

# PostgreSQL 配置（生产环境推荐）
# DB_DRIVER=postgres
# DSN=postgres://lingecho:your-password@localhost:5432/lingecho?sslmode=disable

# MySQL 配置
# DB_DRIVER=mysql
# DSN=lingecho:your-password@tcp(localhost:3306)/lingecho?charset=utf8mb4&collation=utf8mb4_unicode_ci&parseTime=True&loc=Local

# ===================
# API 配置
# ===================
API_PREFIX=/api
DOCS_PREFIX=/api/docs

# ===================
# 流量控制（限流 / 熔断 / IP 黑白名单，预留可配）
# ===================
# 四维限流：全局 / 模块(路径首段) / 接口(JSON) / 用户(鉴权后)
ENABLE_RATE_LIMIT=true
RATE_LIMIT_GLOBAL_RPS=10000
RATE_LIMIT_GLOBAL_BURST=20000
RATE_LIMIT_GLOBAL_WINDOW=1m
RATE_LIMIT_USER_RPS=1000
RATE_LIMIT_USER_BURST=2000
RATE_LIMIT_USER_WINDOW=1m
RATE_LIMIT_IP_RPS=500
RATE_LIMIT_IP_BURST=1000
RATE_LIMIT_IP_WINDOW=1m
RATE_LIMIT_MODULE_DEFAULT_RPS=2000
RATE_LIMIT_MODULE_DEFAULT_BURST=4000
# 模块级覆盖 JSON，例：{"knowledge":{"rps":100,"burst":200},"auth":{"rps":50,"burst":100}}
RATE_LIMIT_MODULE_RULES=
# 接口级覆盖 JSON，例：{"/api/login":{"rps":10,"burst":10}}
RATE_LIMIT_API_RULES=

# 超时与熔断（dev 默认熔断关闭；prod 建议开启）
ENABLE_TIMEOUT=true
ENABLE_CIRCUIT_BREAKER=false
ENABLE_DEGRADE=false
DEFAULT_TIMEOUT=60s
CIRCUIT_BREAKER_FAILURE_THRESHOLD=10
CIRCUIT_BREAKER_SUCCESS_THRESHOLD=5
CIRCUIT_BREAKER_TIMEOUT=60s
CIRCUIT_BREAKER_OPEN_TIMEOUT=60s
CIRCUIT_BREAKER_MAX_CONCURRENT=1000

# HTTP IP 黑白名单（默认关闭；开启后黑名单优先，白名单非空则仅允许列表内 IP）
HTTP_IP_ACL_ENABLE=false
HTTP_ALLOWED_IPS=
HTTP_BLOCKED_IPS=

# ===================
# OpenTelemetry（可选；未设置则不启用 tracing）
# ===================
# OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318
# OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

# ===================
# 平台全局管理员（与租户用户使用同一 POST {API_PREFIX}/login；JWT Issuer：lingvoice.platform）
# 仅在 platform_admins 表为空时种入；优先读下方环境变量，未设置则用括号内默认值。
# 首次登录后请立即修改密码。
# ===================
PLATFORM_ADMIN_EMAIL=admin@lingecho.com
PLATFORM_ADMIN_PASSWORD=admin123
PLATFORM_ADMIN_DISPLAY_NAME=Platform Admin

# ===================
# 会话配置
# ===================
# SESSION_SECRET 留空时启动会使用进程级临时密钥（每次重启踢人，仅 dev 可用）。
# 生产必须设置一个足够长（32+ 字节）的随机字符串。
SESSION_SECRET=your-super-secret-session-key-change-this-in-production
SESSION_EXPIRE_DAYS=7

# ===================
# 跨域 (CORS)
# ===================
# 逗号分隔的允许跨域来源（必须精确匹配 Origin 头）。
# 留空 → 反射任意 Origin + 启用凭据（启动会 WARN，仅 dev 可用）。
# 生产强烈建议显式列出，例如：
#   CORS_ALLOWED_ORIGINS=https://console.example.com,https://api.example.com
CORS_ALLOWED_ORIGINS=

# ===================
# 录音访问 ACL
# ===================
# /uploads/voice/recordings/* 默认需要 Bearer JWT。
# UPLOADS_RECORDINGS_PUBLIC=true 让这些 URL 公开（启动会 WARN）。仅用于 dev/本地。
# 生产环境（GIN_MODE=release 或 APP_ENV=production）若设为 true 将拒绝启动。
UPLOADS_RECORDINGS_PUBLIC=

# ===================
# 租户自助注册 / AKSK
# ===================
# 自助注册开关已迁移至系统配置 TENANT_SELF_REGISTER（/system-configs），不再使用环境变量。
# CREDENTIAL_ALLOW_EMPTY_ALLOW_IP=true 允许 API Key 不填 IP 白名单（仅 dev）。
CREDENTIAL_ALLOW_EMPTY_ALLOW_IP=

# ===================
# 性能观测 / 自动 pprof / Pyroscope
# ===================
# StartSystemMonitor 默认开启（CPU/Mem/Disk 每 5s 采样，供 /system/status 与
# listeners 读取）；下面两个仅控制可选的 profile 链路。
#
# PROFILE_AUTO_PPROF=true 时，CPU 使用率超过 PerformanceMonitorConfig.CPUThreshold
# (默认 90%) 会自动 dump 10s CPU pprof 到 ./pprof/cpu-<ts>.pprof。
# 注意：触发后 30s 才会重新评估，磁盘自行轮换。
PROFILE_AUTO_PPROF=

# Pyroscope 持续 profile 服务地址；留空则跳过（不影响主流程）。
# PYROSCOPE_APP_NAME 默认 ling-voice；PYROSCOPE_BASIC_AUTH_USER / _PASSWORD 可选。
# PYROSCOPE_MUTEX_RATE / _BLOCK_RATE 控制 runtime 的 mutex/block profiler 采样率（默认 5）。
PYROSCOPE_URL=
PYROSCOPE_APP_NAME=
PYROSCOPE_BASIC_AUTH_USER=
PYROSCOPE_BASIC_AUTH_PASSWORD=
PYROSCOPE_MUTEX_RATE=
PYROSCOPE_BLOCK_RATE=

# ===================
# OpenAI（仅 lingllm 示例/单测；租户 LLM 在控制台配置，生产勿依赖）
# ===================
# OPENAI_API_KEY=

# ===================
# 腾讯云配置（语音服务）
# ===================
QCLOUD_APP_ID=your-qcloud-app-id
QCLOUD_SECRET_ID=your-qcloud-secret-id
QCLOUD_SECRET=your-qcloud-secret

# ===================
# 讯飞配置（语音服务）
# ===================
# 一句话复刻训练 API 凭证（来自讯飞控制台「一句话复刻（多风格版）」应用，不是在线 TTS 的 API Secret）
# 训练鉴权使用 AppID + APIKey（apiKey 字段，32 位左右字符串）
XUNFEI_APP_ID=your-xunfei-app-id
XUNFEI_API_KEY=your-xunfei-api-key
# 若训练与 TTS 分属不同应用可单独配置（须为真实 AppID，勿把 APIKey 填进 TRAIN_APP_ID）：
# XUNFEI_TRAIN_APP_ID=
# XUNFEI_TRAIN_API_KEY=
XUNFEI_BASE_URL=http://opentrain.xfyousheng.com
XUNFEI_WS_APP_ID=your-xunfei-ws-app-id
XUNFEI_WS_API_KEY=your-xunfei-ws-api-key
XUNFEI_WS_API_SECRET=your-xunfei-ws-api-secret
XUNFEI_TIMEOUT=30
# Voice clone provider: xunfei | volcengine
VOICE_CLONE_PROVIDER=volcengine
# Volcengine clone (when VOICE_CLONE_PROVIDER=volcengine)
VOLCENGINE_CLONE_APP_ID=
VOLCENGINE_CLONE_TOKEN=
VOLCENGINE_CLONE_CLUSTER=volcano_icl
VOLCENGINE_CLONE_RESOURCE_ID=seed-icl-2.0
VOLCENGINE_CLONE_MODEL_TYPE=4
VOLCENGINE_CLONE_VOICE_TYPE=
VOLCENGINE_CLONE_ENCODING=pcm
VOLCENGINE_CLONE_FRAME_DURATION=20ms
VOLCENGINE_CLONE_SAMPLE_RATE=16000
VOLCENGINE_CLONE_BIT_DEPTH=16
VOLCENGINE_CLONE_CHANNELS=1
VOLCENGINE_CLONE_SPEED_RATIO=1.0
VOLCENGINE_CLONE_TRAINING_TIMES=1

# ===================
# 声纹识别（独立模块，VOICEPRINT_PROVIDER）
# ===================
# 留空=未开启；仅支持 http | xunfei | volcengine
VOICEPRINT_PROVIDER=
# HTTP 微服务（VOICEPRINT_PROVIDER=http，独立 voiceprint 服务默认 :8005）
# 须与 SoulNexus 主库共用 voiceprints 表，见 voiceprint/README.md
VOICEPRINT_BASE_URL=http://localhost:8005
VOICEPRINT_API_KEY=dev-voiceprint-key
VOICEPRINT_TIMEOUT=30s
VOICEPRINT_CONNECT_TIMEOUT=10s
VOICEPRINT_SIMILARITY_THRESHOLD=0.6
VOICEPRINT_MAX_CANDIDATES=10
# 讯飞声纹可复用 XUNFEI_WS_*；也可单独配置：
# XUNFEI_VOICEPRINT_APP_ID=
# XUNFEI_VOICEPRINT_API_KEY=
# XUNFEI_VOICEPRINT_API_SECRET=
# 火山声纹（VOICEPRINT_PROVIDER=volcengine）
# VOLCENGINE_ACCESS_KEY=
# VOLCENGINE_SECRET_KEY=
# VOLCENGINE_REGION=cn-north-1

# ===================
# 其他 TTS（可选，按需在 lingllm synthesizer 中启用）
# ===================
# AZURE_SUBSCRIPTION_KEY=  AZURE_REGION=
# ELEVENLABS_API_KEY=  ELEVENLABS_VOICE_ID=
# FISHSPEECH_API_KEY=  FISHSPEECH_REFERENCE_ID=

# ===================
# 日志配置
# ===================
LOG_LEVEL=info
LOG_FILENAME=data/logs/soulnexus.log
LOG_MAX_SIZE=100
# 日志保留天数（超过后删除 logs 目录下过期文件；默认 7 天）
LOG_RETENTION_DAYS=7
# 可选：lumberjack 轮转保留天数（未设置时与 LOG_RETENTION_DAYS 一致）
# LOG_MAX_AGE=7
LOG_MAX_BACKUPS=5
LOG_DAILY=true

# ===================
# 知识库配置（向量库 + 向量化 + 混合检索）
# ===================
# 向量库：qdrant | milvus | postgres | elasticsearch | weaviate | ragflow | aliyun
KNOWLEDGE_VECTOR_PROVIDER=qdrant

# --- Qdrant（默认）---
QDRANT_BASEURL=http://localhost:6333
QDRANT_API_KEY=

# --- Milvus ---
# MILVUS_ADDRESS=127.0.0.1:19530
# MILVUS_USERNAME=
# MILVUS_PASSWORD=
# MILVUS_TOKEN=
# MILVUS_DB=

# --- PostgreSQL + pgvector ---
# POSTGRES_DSN=postgresql://user:pass@localhost:5432/lingecho?sslmode=disable

# --- Elasticsearch 8+（dense_vector kNN）---
# ELASTICSEARCH_URL=http://127.0.0.1:9200
# ELASTICSEARCH_API_KEY=
# ELASTICSEARCH_INDEX_PREFIX=lingkb

# --- Weaviate ---
# WEAVIATE_URL=http://127.0.0.1:8080
# WEAVIATE_API_KEY=

EMBED_TYPE=openai
# openai 类型已兼容 Gitee AI（模力方舟）：逐条发送 string input，避免 array 导致 400
EMBED_MODEL=Qwen3-Embedding-8B
EMBED_BASEURL=https://ai.gitee.com/v1
EMBED_API_KEY=
EMBED_TIMEOUT_SECONDS=180
# 可选：显式指定向量维度（不填则由 embedder 默认值决定）
# EMBED_DIMENSION=1024
#
# 本地 Ollama（无需 EMBED_API_KEY；Docker 内请用 host.docker.internal）：
# EMBED_TYPE=ollama
# EMBED_MODEL=quentinz/bge-small-zh-v1.5
# EMBED_BASEURL=http://127.0.0.1:11434
# EMBED_DIMENSION=512
# 换 embedding 模型后必须重建知识库（旧 collection 维度不兼容）

# 文档分片（规则分块：按标题/段落切分，带重叠）
KNOWLEDGE_CHUNK_MAX_CHARS=1200
KNOWLEDGE_CHUNK_MIN_CHARS=80
KNOWLEDGE_CHUNK_OVERLAP_CHARS=144
# Async vector index worker pool size (pkg/task scheduler)
KNOWLEDGE_INGEST_WORKERS=4

# LLM 智能分片（router 检测到非结构化文本时使用；需配置 Chat 模型）
# KNOWLEDGE_CHUNK_LLM_ENABLED=true
# KNOWLEDGE_CHUNK_LLM_PROVIDER=openai
# KNOWLEDGE_CHUNK_LLM_MODEL=deepseek-v3.1
# KNOWLEDGE_CHUNK_LLM_BASEURL=https://ai.gitee.com/v1
# KNOWLEDGE_CHUNK_LLM_API_KEY=

# --- 检索策略 ---
# hybrid = Bleve 关键词 + 向量双路召回 + RRF 融合（推荐）
# vector | keyword | hybrid
KNOWLEDGE_RETRIEVE_STRATEGY=hybrid
# 语音/级联路径默认用 vector（跳过 hybrid+远端 rerank）。3s 级延迟通常来自 embed API / rerank，不是 Qdrant ANN。
# KNOWLEDGE_VOICE_RETRIEVE_STRATEGY=vector
# 需要语音也走 rerank 时再打开：
# KNOWLEDGE_VOICE_RERANK_ENABLED=true
KNOWLEDGE_SEARCH_INDEX_DIR=./data/knowledge-search
KNOWLEDGE_SEARCH_QUERY_TIMEOUT_SECONDS=10
# Qdrant：与业务同 docker network，用服务名而非宿主机端口转发，例如 http://qdrant:6333
# QDRANT_BASEURL=http://qdrant:6333
# 可选启动参数（内存/HNSW）：QDRANT__STORAGE__OPTIMIZERS_THRESHOLD=10000 等，见 docs/knowledge-latency.md
# 兼容旧配置；RRF 权重优先使用 KNOWLEDGE_RRF_* 两项
KNOWLEDGE_HYBRID_VECTOR_WEIGHT=0.65

# --- 召回 / RRF 融合（WeKnora 默认值）---
KNOWLEDGE_EMBEDDING_TOP_K=50
KNOWLEDGE_VECTOR_THRESHOLD=0.15
# Bleve BM25 for short CJK queries is often << 0.3; 0 keeps keyword hits for hybrid/RRF.
KNOWLEDGE_KEYWORD_THRESHOLD=0
KNOWLEDGE_RRF_K=60
KNOWLEDGE_RRF_VECTOR_WEIGHT=0.7
KNOWLEDGE_RRF_KEYWORD_WEIGHT=0.3
KNOWLEDGE_OVER_RETRIEVE_MULTIPLIER=5
KNOWLEDGE_OVER_RETRIEVE_MIN=50
KNOWLEDGE_OVER_RETRIEVE_MAX=500

# --- Rerank（可选，需配置 provider）---
KNOWLEDGE_RERANK_ENABLED=true
KNOWLEDGE_RERANK_PROVIDER=jina
KNOWLEDGE_RERANK_MODEL=jina-reranker-v2-base-multilingual
KNOWLEDGE_RERANK_API_KEY=
# KNOWLEDGE_RERANK_BASEURL=https://api.jina.ai/v1
KNOWLEDGE_RERANK_TOP_K=10
KNOWLEDGE_RERANK_THRESHOLD=0.2
KNOWLEDGE_RERANK_TIMEOUT_SECONDS=30
# Composite rerank: final = modelWeight*modelScore + baseWeight*normalizedBaseScore
KNOWLEDGE_RERANK_MODEL_WEIGHT=0.6
KNOWLEDGE_RERANK_BASE_WEIGHT=0.3
# KNOWLEDGE_RERANK_COMPOSITE_DISABLED=true

# --- Langfuse 检索链路追踪（可选）---
# KNOWLEDGE_TRACE_LANGFUSE_ENABLED=true
# LANGFUSE_ENABLED=true
# LANGFUSE_HOST=https://cloud.langfuse.com
# LANGFUSE_PUBLIC_KEY=pk-lf-...
# LANGFUSE_SECRET_KEY=sk-lf-...

# --- MMR 多样性 / 去重（WeKnora merge 阶段）---
KNOWLEDGE_MMR_LAMBDA=0.7
# KNOWLEDGE_MMR_DISABLED=true
# KNOWLEDGE_DEDUP_DISABLED=true
KNOWLEDGE_OVERLAP_THRESHOLD=0.85

# --- 离线检索评估（cmd/kb-eval）---
# 标注数据集为 JSONL，每行一条：
# {"query":"问题","relevant_ids":["chunk_id_1","chunk_id_2"],"gold_answer":"可选标准答案"}
# 运行示例（需 Qdrant/Embed 等已配置）：
# go run ./cmd/kb-eval -dataset testdata/kb-eval/sample.jsonl -namespace YOUR_NS
# go run ./cmd/kb-eval -dataset eval.jsonl -namespace YOUR_NS -compare vector,keyword,hybrid
# go run ./cmd/kb-eval -dataset eval.jsonl -namespace YOUR_NS -format json -per-query -ks 1,3,5,10

# ===================
# 备份配置
# ===================
BACKUP_ENABLED=true
BACKUP_PATH=./backups
BACKUP_SCHEDULE=0 2 * * *
BACKUP_RETENTION_DAYS=7

# ===================
# 监控 / API 签名
# ===================
API_SECRET_KEY=your-api-secret-key-change-this-in-production
# Prometheus /metrics IP 白名单（逗号分隔 CIDR；留空默认拒绝）
METRICS_ALLOWED_IPS=127.0.0.1,::1

# ===================
# GitHub OAuth（可选）
# ===================
# GITHUB_CLIENT_ID=
# GITHUB_CLIENT_SECRET=
# GitHub OAuth App 回调地址，默认 {SERVER_URL}{API_PREFIX}/oauth/github/callback
# GITHUB_OAUTH_REDIRECT_URL=http://localhost:8082/api/oauth/github/callback
# OAuth 完成后跳转的前端根地址，默认 SERVER_URL 或 http://localhost:5173
# OAUTH_FRONTEND_BASE_URL=http://localhost:5173

# CDR / 链路 trace 落盘目录（默认 ./logs/trace）
# SOULNEXUS_CDR_DIR=./logs/trace

# ===================
# 文件上传配置
# ===================
UPLOAD_DIR=./data/uploads

# 音色目录（scripts/voices/*.json）与试听缓存
VOICES_CATALOG_DIR=./scripts/voices
VOICE_PREVIEW_CACHE_DIR=./data/voice-preview-cache

# ===================
# 媒体缓存
# ===================
MEDIA_CACHE_ROOT=./media_cache
MEDIA_CACHE_DISABLED=false

# ===================
# JWT（租户/平台登录）
# ===================
JWT_ALGORITHM=RS256
JWT_KEY_FILE=./data/keys/jwks.json
JWT_ROTATION_DAYS=30
JWT_KEEP_OLD_KEYS=2

# ===================
# 存储配置（pkg/stores：头像 / 录音 / 欢迎语 WAV 等上传）
# STORAGE_KIND=local 时写入 UPLOAD_DIR（默认 ./data/uploads），由 /uploads 静态挂载访问
# 生产建议 qiniu | s3 | oss | minio | cos | tos | obs | ks3
# ===================
STORAGE_KIND=local

# 对象存储示例（任选其一，取消注释并设置 STORAGE_KIND）
# STORAGE_KIND=tos
# TOS_ENDPOINT=  TOS_REGION=  TOS_ACCESS_KEY_ID=  TOS_SECRET_ACCESS_KEY=  TOS_BUCKET=  TOS_DOMAIN=
# STORAGE_KIND=obs
# OBS_ENDPOINT=  OBS_REGION=  OBS_ACCESS_KEY_ID=  OBS_SECRET_ACCESS_KEY=  OBS_BUCKET=  OBS_PROXY_DOMAIN=
# STORAGE_KIND=ks3
# KS3_ENDPOINT=  KS3_REGION=  KS3_ACCESS_KEY_ID=  KS3_SECRET_ACCESS_KEY=  KS3_BUCKET=  KS3_DOMAIN=

# ===================
# 知识库文档解析（lingllm/parser，可选 build tag）
# 说明见 cmd/bootstrap/migrations/README.md
# ===================
# OCR：图片文字识别，需 -tags ocr 且系统安装 tesseract
# TESSERACT_LANG=eng
# ASR：音频转写，需 -tags asr、libvosk，并设置模型路径
# VOSK_MODEL=/path/to/vosk-model
# 构建示例：go build -tags "ocr,asr" -o bin/lingecho ./cmd/...

# 全站业务时区
SYSTEM_TIMEZONE=Asia/Shanghai

# ===================
# 媒体生成（图片 / 视频，Volcengine Ark Seedream + Seedance）
# ===================
# 火山引擎方舟控制台申请 API Key：https://console.volcengine.com/ark
# Seedream（文生图/图生图）与 Seedance（文生视频/图生视频）共用同一 Key
# 视频生成需在控制台单独开通 Seedance 模型；SEEDANCE_MODEL_ID 填模型 ID（如 doubao-seedance-1-5-pro-251215）
# 或「推理接入点」ID（ep- 开头）。若返回 HTTP 404，通常是模型未开通或 ID 填错。
# 生成结果会经 STORAGE_KIND（如 qiniu）持久化到对象存储，任务写入 execution_tasks + media_generate_jobs。
SEEDREAM_API_KEY=
# SEEDREAM_API_URL=https://ark.cn-beijing.volces.com/api/v3/images/generations
# SEEDREAM_MODEL_ID=doubao-seedream-5-0-260128
# SEEDANCE_API_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
# SEEDANCE_MODEL_ID=doubao-seedance-1-5-pro-251215
# SEEDANCE_GENERATE_AUDIO=true
# MEDIAGEN_VIDEO_POLL_INTERVAL_MS=10000
# MEDIAGEN_VIDEO_POLL_MAX_ATTEMPTS=120

# ===================
# SSL/TLS（HTTP 服务）
# ===================
SSL_ENABLED=false
SSL_CERT_FILE=./ssl/lingecho.com_bundle.pem
SSL_KEY_FILE=./ssl/lingecho.com.key
# Let's Encrypt（证书文件留空时可自动签发）
# SSL_ACME_DOMAINS=pbx.example.com
# SSL_ACME_CACHE_DIR=./ssl/acme
# SSL_ACME_EMAIL=admin@example.com
# SSL_ACME_HTTP_ADDR=:80
# SSL_ACME_DISABLE=false

# ===================
# 缓存 / 计费预占
# ===================
CACHE_TYPE=local
# REDIS_ADDR=localhost:6379
# 计费预占（多实例/生产强烈建议配置）。支持 redis:// 或 rediss:// URL。
# 留空则进程内内存预占（仅适合单实例 dev）。
# REDIS_URL=redis://127.0.0.1:6379/0