配置详解

WeKnora 的配置由四层组成，优先级从低到高：

最后一层容易被忽略，却是排查「改了 env 没生效」的第一现场：注册模式、空间策略与配额、SSRF 白名单、各 worker pool 并发、模型并发上限这些键一旦在界面上改过，数据库里就留下一行记录，此后环境变量不再起作用；把该项重置（DELETE /api/v1/system/admin/settings/:key）才会回落到环境变量或内置默认值。完整键表与语义见租户、用户与认证授权的「运行时可改的系统设置」。

下文对照 internal/config/config.go 中的结构体逐段解读，并在末尾汇总环境变量。

配置加载机制

internal/config/config.go 的 LoadConfig() 流程：

1. viper 按顺序查找 config.yaml：当前目录 → ./config → $HOME/.appname → /etc/appname/；
2. 环境变量展开：对文件内容做正则替换，${ENV_VAR} 会被同名环境变量的值替换；变量未设置时保留字面量 ${ENV_VAR} 原样（便于暴露配置错误）；
3. viper 开启 AutomaticEnv() 且 key 分隔符 . 映射为 _（即 server.port 可被环境变量 SERVER_PORT 覆盖）；
4. 从 config/prompt_templates/*.yaml 加载提示词模板，并按 xxx_prompt_id 字段回填到 conversation 配置（backfillConversationDefaults）；
5. 加载 builtin_agents.yaml（内置 Agent）与 agent_type_presets.yaml（Agent 类型预设），并解析其中的 system_prompt_id 引用；
6. 应用环境变量覆盖（OIDC、Agent、KnowledgeBase、Auth/Tenant、Audit 各组）并执行 ValidateConfig 校验。

flowchart LR
    Y["config/config.yaml"] --> EXP["展开 dollar-brace 环境变量引用"]
    EXP --> V["viper Unmarshal 为 Config 结构体"]
    PT["config/prompt_templates/*.yaml"] --> BF["backfillConversationDefaults (按 *_prompt_id 解析为文本)"]
    V --> BF
    BA["config/builtin_agents.yaml"] --> LD["LoadBuiltinAgentsConfig"]
    AP["config/agent_type_presets.yaml"] --> LD2["LoadAgentTypePresetsConfig"]
    BF --> OV["applyOIDCEnvOverrides / applyAgentEnvOverrides / applyKnowledgeBaseEnvOverrides / applyAuthAndTenantDefaults / applyAuditDefaults"]
    LD --> OV
    LD2 --> OV
    OV --> VC["ValidateConfig"] --> CFG["最终 *config.Config"]

config/config.yaml 逐段解读

server（ServerConfig）

conversation（ConversationConfig）——检索问答管线

conversation.summary（SummaryConfig，答案生成参数）：

knowledge_base（KnowledgeBaseConfig）——全局默认分块

每个知识库的 ChunkingConfig 会覆盖这里的全局默认值。

extract（ExtractManagerConfig）——知识图谱抽取模板

extract.extract_graph / extract.extract_entity / extract.fabri_text 定义图谱抽取的说明文（description）、允许的关系标签（tags，默认 Author、Alias）与 few-shot 示例（examples：text + node + relation）。初始化向导中的「试抽取 / 生成示例文本」即使用这些配置（fabri_text.with_tag / with_no_tag 中的 %s 会被标签列表替换）。

tenant（TenantConfig）

结构体支持但默认文件未写出的段

以下段落在 Config 结构体中存在，可按需追加到 config.yaml（多数也有环境变量入口）：

重要环境变量

以下变量来自 docker-compose.yml 的 app/docreader environment 段、.env.example 与代码中的 os.Getenv。生产部署至少要改：DB_USER/DB_PASSWORD/DB_NAME、REDIS_PASSWORD、JWT_SECRET、SYSTEM_AES_KEY。

运行时基础

APP_EXTERNAL_URL 影响 IM 渠道能否渲染知识库图片。IM 平台需要拿到公网 http(s) URL，二选一：

1. 存储后端本身公网可达（对象存储用公网 endpoint，或把 MINIO_ENDPOINT 设成公网 host），此时 resource:// 回退到后端预签名 URL，不需要本变量；
2. 设置 APP_EXTERNAL_URL，resource:// 图片被改写成 <APP_EXTERNAL_URL>/r/<token> 走 WeKnora 自身（需要 nginx 代理 /r/，官方前端镜像已内置该 location）。

默认的 MinIO 内网部署与 local 后端都只能走第二种。IM 渠道已启用但本变量为空时，服务启动会打印一次 WARN；改写结果若不是 http(s) URL 会保留原引用并记录可操作的告警，而不是发出 IM 端无法访问的链接。

四种 URL 形式与各渠道的取法见图片与文件的对外访问。

数据库与队列

检索引擎与向量库

文件存储

AWS S3 的 S3_ACCESS_KEY / S3_SECRET_KEY 可以同时留空，此时走 AWS SDK 默认凭证链，支持 EC2/ECS/EKS IAM Role、IRSA/Web Identity、环境变量与共享配置文件——在 AWS 上部署时不必再往环境变量里塞长期密钥。两者必须同填或同空。S3_ENDPOINT 留空则使用 Region 对应的标准端点。

模型与推理

认证、租户与安全

Docreader 解析（docreader 容器）

Agent、Skills 与附件

可观测性（Langfuse）

LANGFUSE_PUBLIC_KEY + LANGFUSE_SECRET_KEY 同时设置即自动启用；LANGFUSE_HOST（默认 https://cloud.langfuse.com，自建栈填 http://langfuse-web:3000）、LANGFUSE_ENABLED、LANGFUSE_RELEASE、LANGFUSE_ENVIRONMENT、LANGFUSE_SAMPLE_RATE、LANGFUSE_FLUSH_AT/FLUSH_INTERVAL/QUEUE_SIZE/REQUEST_TIMEOUT/DEBUG 为调优项；--profile langfuse 自建栈另有 LANGFUSE_SALT、LANGFUSE_ENCRYPTION_KEY、LANGFUSE_NEXTAUTH_SECRET、LANGFUSE_INIT_*（首启自动建组织/项目/管理员）等，见 .env.example I1/I2 节。

可选服务：SearXNG 与 MCP Server

这两组变量只在启用对应 compose profile 时才需要，独立于主服务。

SearXNG（自托管元搜索，--profile searxng / full）：

自建 SearXNG 时记得把 127.0.0.1 加进 SSRF_WHITELIST，否则后端的 SSRF 防护会拦掉本机地址。用法见网络搜索与网页抓取。

MCP Server（把 WeKnora 暴露给 Claude Desktop 等 MCP 客户端，--profile full）：

完整说明见 MCP 集成。

config/prompt_templates/：提示词模板

每类 Prompt 一个 YAML 文件，统一结构为 templates: 列表；单个模板字段（PromptTemplate 结构体，internal/config/config.go）：

各文件用途与内含模板 ID：

可定制点：直接编辑模板 content，或新增模板条目并把 config.yaml 中对应 *_prompt_id 改为新 ID；重启（compose 已挂载 ./config/config.yaml，模板目录随镜像/挂载）即生效。ID 找不到时启动日志会输出 Warning: xxx_prompt_id not found。

config/agent_type_presets.yaml：Agent 类型预设

为 smart-reasoning 模式的自定义 Agent 提供「一键预填」：每个预设（AgentTypePresetEntry，internal/types/agent_type_preset.go）包含 id、i18n（label/description 多语言）、config（预填值，零值不生效）与可选 kb_filter（限定可选知识库的能力谓词 any_of / all_of / none_of，能力名：vector、keyword、wiki、graph、faq）。前端经 GET /agents/type-presets 读取。

内置五种预设：

config/builtin_agents.yaml：内置 Agent

定义随系统分发、对所有租户可见的 Agent（BuiltinAgentEntry，internal/types/builtin_agent_config.go）。每条含 id、avatar、is_builtin: true、i18n（default/zh-CN/zh-TW/ja-JP/ko-KR 的名称与描述）与完整 config（CustomAgentConfig）。文件内置五个 Agent：

• builtin-quick-answer：agent_mode: quick-answer，引用 system_prompt_id: default_kb 与 context_template_id: default_context，带完整检索参数（embedding_top_k: 10、vector_threshold: 0.5、rerank_threshold: 0.3、FAQ 直答阈值 0.9 等）；
• builtin-smart-reasoning：agent_mode: smart-reasoning、agent_type: rag-qa、max_iterations: 50；
• builtin-data-analyst、builtin-wiki-researcher、builtin-wiki-fixer：分别面向表格分析与 Wiki 场景。

config 中的 system_prompt_id 在启动时由 resolveBuiltinAgentPromptIDs 解析为 agent_system_prompt.yaml 中的实际内容。修改此文件并重启即可调整内置 Agent 行为。

config/builtin_models.yaml.example：声明式内置模型

复制为 config/builtin_models.yaml（或用 BUILTIN_MODELS_CONFIG 指定路径）后，其中条目会在每次启动时写入 models 表并标记 is_builtin=true，对所有租户可见（compose 中取消 - ./config/builtin_models.yaml:/app/config/builtin_models.yaml:ro 挂载行的注释）。格式：

builtin_models:
  - id: builtin-llm-default        # 稳定 ID，重复启动按 ID 幂等更新
    type: KnowledgeQA              # KnowledgeQA | Embedding | Rerank | VLLM | ASR
    source: remote                 # remote（默认）| local
    is_default: true               # 是否设为该类型默认模型
    name: ${LLM_MODEL_NAME}        # 字符串字段均支持 ${ENV} 引用（.env 经 env_file 注入容器）
    parameters:
      base_url: ${LLM_BASE_URL}
      api_key: ${LLM_API_KEY}
      provider: ${LLM_PROVIDER}    # openai | generic | aliyun | moonshot | ...
      embedding_parameters:        # 仅 Embedding 类型
        dimension: 1536
        truncate_prompt_tokens: 0

注意：未设置的 ${ENV} 会保留字面量以便暴露配置错误；非字符串字段（type、source、is_default、dimension 等）必须写字面值；从文件删除条目不会自动删库，需手动清理。

配置优先级速记

对同一语义的配置，生效优先级为：数据库 system_settings（仅注册在表内的键）> 环境变量 > config.yaml > 代码内置默认值；租户/知识库级配置（RetrievalConfig、ChunkingConfig 等，存于数据库）在运行时覆盖全局默认。修改 .env 后需重启容器（docker compose up -d app）；开发模式 air 热重载不会重读 .env，需重启 dev 脚本。