打开 Demo

配置#

DEEIX Chat 把静态启动配置和运行时业务配置分开。本文说明每项配置放在哪里、优先级如何生效，以及生产部署前必须改哪些内容。

配置模型#

DEEIX Chat 读取三类配置。把它们分开，部署、迁移和密钥轮换才有清晰边界。

配置层管理内容存储位置变更方式
启动配置应用、品牌、HTTP 服务、安全、数据库、缓存、存储、GeoIP、Traceconfig.yaml 与环境变量修改后重启
运行时业务配置登录、会话、模型、文件、RAG、MCP、计费、公告数据库 system_settings后台管理
前端构建配置浏览器请求后端的地址构建时的 NEXT_PUBLIC_API_BASE_URL重新构建前端

优先级固定为 环境变量 > config.yaml > 代码内置默认值。

配置文件查找#

后端按运行目录查找配置文件：

  • 从仓库根目录启动：./config.yaml
  • 从 backend/ 启动：../config.yaml
  • Docker：/app/config.yaml，由 deploy/config.yaml 挂载
  • 自定义路径：用 CONFIG_FILE 指向进程或容器可读取的路径

config.yaml#

config.yaml 只放服务启动前必须确定的内容。模型、路由、价格、订阅、RAG、MCP 和文件策略属于运行时业务配置，不写进静态 YAML。

应用与品牌#

config.yaml

字段用途
app.name应用名称，用于日志和 Trace。
app.envdev/development 或 prod/production；未配置时默认 prod。dev 会启用 Swagger 并放宽生产校验。
branding.*前端标题、短名称、描述、Logo、favicon、PWA 图标和 Apple 触摸图标。重启后生效，无需重新构建前端。

HTTP 服务#

config.yaml

字段用途生产要求
server.http_portAPI 监听端口。修改后同步 Compose 端口映射。
server.cors_allow_origin允许调用 API 的前端来源。精确域名，* 会被拒绝。
server.trusted_proxies允许设置转发头的 CIDR。只填写真实代理来源。
server.public_api_base_url对外 API 地址，用于链接和回调。HTTPS。
server.public_web_base_url对外 Web 地址，用于链接和跳转。HTTPS。
server.frontend_dist_dirGo 服务托管前端静态文件的目录。Docker 镜像中为 /app/frontend/out。
server.shutdown_timeout_seconds优雅关停时等待在途请求的窗口。小于编排系统的终止宽限期。

安全#

config.yaml

密钥最低要求用途
security.jwt_secret / JWT_SECRET16 字符签名登录态和访问令牌。
security.data_encryption_key / DATA_ENCRYPTION_KEY32 字符派生 AES-GCM 密钥，保护上游 API Key、SSO Secret、MCP Token、敏感设置和 TOTP Secret。上线后必须保持稳定。
security.mcp_user_context_secret-签名 ${DEEIX_SIGNED_USER_CONTEXT}。仅当 MCP 服务使用它时必填。
security.ssrf_protection_enabled-拦截对私网和元数据网络的出站请求。默认 false。
security.ssrf_allowed_hosts-部署级集成可信的精确主机名。
security.ssrf_allowed_cidrs-部署级集成可信的 CIDR 网段。
security.turnstile_siteverify_url-Cloudflare Turnstile 校验端点。仅在兼容代理场景下覆盖。

安全密钥生成器

security.jwt_secret

JWT_SECRET

security.data_encryption_key

DATA_ENCRYPTION_KEY

仅在浏览器本地生成，不收集、不存储、也不会发送密钥。

生产模式会拒绝空的 JWT_SECRET、内置开发默认值、短于 16 字符的密钥，以及短于 32 字符的 DATA_ENCRYPTION_KEY。更换 data_encryption_key 后已有密文无法解密，轮换前先规划重新加密。

数据库、缓存与存储#

config.yaml

配置可选值说明
database.driverpostgres、sqlite多节点和高并发使用 PostgreSQL；SQLite 只适合单节点。
database.postgres.dsn-PostgreSQL 连接字符串。
database.sqlite.path-SQLite 文件路径。Docker 轻量方案使用 /app/data/deeix.db。
cache.driverredis、memorymemory 只适用于单进程。
database.redis.*-Redis 地址、用户名、密码、DB 和 TLS。
storage.backendlocal、s3多实例部署使用 S3 兼容存储。
storage.local.root_dir-本地文件目录。Docker 方案使用 /app/storage。
storage.s3.*-Endpoint、region、bucket、prefix、凭据和 path-style。backend 为 s3 时 region 和 bucket 必填。

GeoIP 与 Trace#

config.yaml

配置可选值说明
geoip.providernone、ipwhois、ipinfo、mmdbmmdb 使用本地 GeoLite2 数据库。
geoip.base_url、geoip.token-GeoIP HTTP 服务地址和 Token，默认地址是 https://ipwho.is。
geoip.database_url、geoip.database_path、geoip.database_max_bytes、geoip.refresh_interval_hours-MMDB 下载地址、本地路径、最大下载字节数和刷新间隔。
observability.tracing.endpoint-配置 OTLP 地址后会自动启用 Trace。
observability.tracing.protocolgrpc、http默认 grpc。
observability.tracing.sampling_rate0 到 1开启 Trace 前先设置采样率。

环境变量#

环境变量会覆盖 config.yaml 中的同名配置，适合容器平台、CI/CD 和密钥管理系统。

所属域环境变量对应配置
前端构建NEXT_PUBLIC_API_BASE_URL浏览器 API 地址，构建时写入
配置文件CONFIG_FILE配置文件路径
应用APP_NAME、APP_ENVapp.*
HTTP 服务HTTP_PORT、CORS_ALLOW_ORIGIN、TRUSTED_PROXIES、PUBLIC_API_BASE_URL、PUBLIC_WEB_BASE_URL、FRONTEND_DIST_DIRserver.*
HTTP 超时HTTP_READ_HEADER_TIMEOUT_SECONDS、HTTP_READ_TIMEOUT_SECONDS、HTTP_IDLE_TIMEOUT_SECONDS、HTTP_MAX_HEADER_BYTES、HTTP_SHUTDOWN_TIMEOUT_SECONDSserver.*
安全JWT_SECRET、MCP_USER_CONTEXT_SECRET、DATA_ENCRYPTION_KEY、SSRF_PROTECTION_ENABLED、SSRF_ALLOWED_HOSTS、SSRF_ALLOWED_CIDRS、TURNSTILE_SITEVERIFY_URLsecurity.*
数据库DATABASE_DRIVERdatabase.driver
PostgreSQLPOSTGRES_DSN、POSTGRES_MAX_OPEN_CONNS、POSTGRES_MAX_IDLE_CONNS、POSTGRES_CONN_MAX_LIFETIME_MINUTES、POSTGRES_CONN_MAX_IDLE_TIME_MINUTESdatabase.postgres.*
SQLiteSQLITE_PATH、SQLITE_DSN、SQLITE_MAX_OPEN_CONNS、SQLITE_BUSY_TIMEOUT_MS、SQLITE_CACHE_SIZE_KB、SQLITE_MMAP_SIZE_BYTES、SQLITE_SYNCHRONOUS、SQLITE_TEMP_STOREdatabase.sqlite.*
缓存CACHE_DRIVERcache.driver
RedisREDIS_ADDR、REDIS_USERNAME、REDIS_PASSWORD、REDIS_DB、REDIS_TLS_ENABLED、REDIS_TLS_INSECURE_SKIP_VERIFYdatabase.redis.*
存储STORAGE_BACKEND、STORAGE_ROOT_DIRstorage.backend、storage.local.root_dir
S3 存储STORAGE_S3_ENDPOINT、STORAGE_S3_REGION、STORAGE_S3_BUCKET、STORAGE_S3_PREFIX、STORAGE_S3_ACCESS_KEY_ID、STORAGE_S3_SECRET_ACCESS_KEY、STORAGE_S3_FORCE_PATH_STYLEstorage.s3.*
GeoIPGEOIP_PROVIDER、GEOIP_BASE_URL、GEOIP_TOKEN、GEOIP_TIMEOUT_MS、GEOIP_DATABASE_URL、GEOIP_DATABASE_PATH、GEOIP_DATABASE_MAX_BYTES、GEOIP_REFRESH_INTERVAL_HOURSgeoip.*
OpenTelemetryOTEL_ENABLED、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS、OTEL_EXPORTER_OTLP_INSECURE、OTEL_EXPORTER_OTLP_PROTOCOL、OTEL_TRACES_SAMPLER_ARG、OTEL_SAMPLING_RATEobservability.tracing.*

APP_ENV 支持 dev/development 和 prod/production，内部规范化为 dev 或 prod；未配置时默认 prod。OTEL_TRACES_SAMPLER_ARG 优先于 OTEL_SAMPLING_RATE。

后台管理中的运行时业务配置#

认证、注册、会话行为、模型参数策略、文件处理、RAG、Embedding、MCP、计费、支付和公告都存在 system_settings，请在后台管理修改，不要写进 config.yaml。

后台板块管理内容指南
统计按用户、权限组和模型查看用量。-
账户用户、角色、状态、订阅、余额和安全操作。账户
权限组倍率、成员用户和可访问模型。-
上游渠道、Base URL、API Key、协议、超时和熔断。上游
模型平台模型、来源、路由、能力和原生工具。模型
工具MCP 服务、工具同步、启停、排序和执行限制。工具
计费计费方式、模型价格、工具价格、订阅、支付、兑换码和调用日志。计费
公告登录后展示的公告，包含类型、置顶和 Markdown 内容。公告
日志审计、调用、认证和系统事件。日志
内容审核审核服务和输入/输出策略，仅超级管理员可配置。-
登录认证登录页、注册、邮箱验证、身份源、Turnstile、令牌有效期和限流。登录认证
会话配置默认模型、任务模型、系统提示词、交互式组件、上下文管理和参数透传。会话配置
文件与检索上传限制、内容提取、OCR、全文注入、Embedding 和 RAG。文件与检索
知识库知识库总开关和内置知识库。-
关于版本、更新检查、官方链接和许可证。关于

Docker Compose#

所有 compose 文件都围绕 app 服务。它默认绑定 127.0.0.1:8080，把 ./config.yaml 只读挂载到 /app/config.yaml，并持久化两个卷。

数据容器路径
SQLite 数据库/app/data/deeix.db
上传文件和生成文件/app/storage
PostgreSQL 数据/var/lib/postgresql/data，仅全量方案
Redis 数据/data，仅全量方案

docker-compose.full.yml 会为内置服务注入连接配置：

docker-compose.full.yml

生产使用前替换 PostgreSQL 和 Redis 密码。要使用本地镜像，先在仓库根目录构建，再设置 DEEIX_CHAT_IMAGE。

Web、App 与桌面端 OAuth 回调#

启用第三方登录前，把 PUBLIC_API_BASE_URL 设置为外部可访问的 API 地址。每个 OIDC/OAuth2 身份源都需要登记：

text

Web、App 与桌面端都复用这个实例回调。桌面端使用回环回调（RFC 8252），不需要自定义 URL scheme。见桌面端。

生产检查清单#

  • app.env 已设置为 prod 或 production。
  • jwt_secret 和 data_encryption_key 是强随机值，并纳入密钥管理。
  • public_api_base_url 和 public_web_base_url 使用 HTTPS。
  • cors_allow_origin 只列精确域名，没有通配符。
  • trusted_proxies 只包含真实反向代理地址段。
  • 数据库使用 PostgreSQL，缓存使用 Redis。
  • /app/data 和 /app/storage 挂载到持久化卷并有备份。
  • 多实例部署使用 S3 兼容存储。
  • 内置 PostgreSQL 和 Redis 的默认密码已替换。
  • 只有在有 Collector 和采样率时才开启 Trace。

相关#