打开 Demo
这不是示例文件逐行说明，而是一份部署配置指南。它关注配置应该放在哪里、优先级如何生效，以及生产部署前必须稳定下来的关键项。

配置模型#

DEEIX Chat 的配置分为三类：启动配置、运行时业务配置和前端构建配置。启动配置决定服务能否连接数据库、缓存、存储并完成启动。

运行时业务配置决定模型、路由、计费、RAG、MCP 和文件处理策略。

前端构建配置决定浏览器请求哪个 API。将三类配置拆开，是为了让部署、迁移、密钥轮换和问题排查都有清晰边界。

配置层管理内容存储位置变更方式
启动配置端口、公开地址、数据库、缓存、存储、密钥、GeoIP、Traceconfig.yaml 与环境变量修改后重启服务
业务配置登录策略、模型、上游、路由、文件处理、RAG、MCP、计费、公告数据库 system_settings后台管理中修改
前端构建配置浏览器请求后端 API 的公开地址构建环境变量重新构建前端

配置优先级固定为 环境变量 > config.yaml > 代码默认值。如果容器环境变量里注入了 POSTGRES_DSN、REDIS_ADDR 或密钥，它会覆盖 config.yaml 中的同名配置。

部署形态#

先选部署形态，再复制对应模板。三个模板对应不同依赖模型，不建议混用。轻量部署用于快速验证。

标准部署适合接入已有基础设施。

全量部署适合单机运行完整依赖栈。

部署形态适合场景复制模板Compose 文件数据与缓存
轻量部署本地试用、演示、小型单机config.sqlite.example.yamldocker-compose.sqlite.ymlSQLite + memory cache
标准部署已有 PostgreSQL、Redis 或平台基础设施config.example.yamldocker-compose.yml外部 PostgreSQL + Redis
全量部署单机运行应用、数据库和缓存config.full.example.yamldocker-compose.full.ymlCompose 内 PostgreSQL + Redis
  1. 选择部署形态。
  2. 复制对应模板为 config.yaml。
  3. 修改公开地址、安全密钥、数据库、缓存和存储。
  4. 启动服务后，在后台管理中配置模型、路由、文件、计费和登录策略。

terminal

后端默认读取 config.yaml。从仓库根目录或 Docker /app 启动时读取 ./config.yaml。

从 backend/ 启动时读取 ../config.yaml。自定义路径使用 CONFIG_FILE，Docker 中必须填写容器内路径。

config.yaml#

config.yaml 只负责服务启动前必须确定的基础设施配置。它应该回答这些问题：服务监听哪里，公开地址是什么，连接哪套数据库和缓存，文件写到哪里，以及使用什么安全密钥。模型、上游、路由、价格、订阅、RAG、MCP 和文件处理策略属于后台管理，不应该写进静态 YAML。

服务地址#

公开部署时，API 地址、Web 地址、CORS 和反向代理必须一起检查。

  • 数据库 DSN 面向容器网络。
  • public_api_base_url 面向浏览器、回调和链接生成。
  • public_web_base_url 面向分享、跳转和通知链接。
  • 前后端分离时，还要同步前端构建变量 NEXT_PUBLIC_API_BASE_URL。

config.yaml

字段用途生产要求
app.env开启生产配置校验使用 prod 或 production
server.http_portGo 服务监听端口修改后同步 Compose 端口映射
server.cors_allow_origin允许调用 API 的前端来源精确域名，不使用通配符
server.trusted_proxies可信反向代理 CIDR只填写真实代理来源
server.public_api_base_url对外 API 地址生产必须是 HTTPS
server.public_web_base_url对外 Web 地址生产必须是 HTTPS

安全密钥#

示例密钥只能用于本地开发，公开部署前必须替换。生产模式下，后端会拒绝空值、默认开发值和过短密钥。

如果使用环境变量，它们会覆盖 config.yaml 中的同名字段。

密钥最低要求说明
security.jwt_secret
JWT_SECRET		16 字符用于签名登录态和访问令牌，可以按密钥轮换流程更新。
security.data_encryption_key
DATA_ENCRYPTION_KEY		32 字符用于派生 AES-GCM 密钥，保护上游 API Key、SSO Secret、MCP Token、敏感设置和 TOTP Secret。上线后必须稳定保存，不能随意更换。

安全密钥生成器

security.jwt_secret

JWT_SECRET

security.data_encryption_key

DATA_ENCRYPTION_KEY

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

  • ssrf_protection_enabled 默认是 false。
    公网部署可根据上游、MCP、文件处理和内网访问需求评估后开启。
  • 如果用 Kubernetes、Cloudflare、Docker Secret 或平台环境变量注入密钥，仍然要满足同样的长度要求。
  • data_encryption_key 变更前必须先规划数据迁移或重新加密，否则已有密文会无法解密。

config.yaml

数据、缓存与存储#

长期多用户环境建议使用 PostgreSQL + Redis。SQLite + memory cache 适合轻量单机和演示，不适合多实例、强并发或运维边界严格的生产环境。

config.yaml

模块推荐生产配置说明
DatabasePostgreSQL用户、会话、模型、计费、审计、文件索引和系统设置
CacheRedis多实例部署必须使用 Redis，memory 只适合单进程
StorageS3-compatible多实例或长期生产建议使用对象存储
SQLite/app/data/deeix.db只建议用于轻量部署，必须挂载持久化卷
Local storage/app/storage保存上传文件和生成文件，必须备份

GeoIP 与 Trace#

GeoIP 和 OpenTelemetry 不影响基础启动，但会影响审计、追踪和问题定位。

  • 稳定审计建议使用 MMDB，而不是依赖外部 HTTP 查询。
  • Trace 应在有 Collector、采样率和日志关联策略后再开启。
  • 没有采样策略时，不建议直接打开全量 Trace。

config.yaml

Docker Compose#

Compose 负责运行拓扑：镜像、端口、卷、网络、配置挂载和部署级环境变量。它描述“容器如何运行”，不是“产品策略如何配置”。模型、路由、价格和文件策略应该在后台管理里维护。

app 容器契约#

三套 Compose 都围绕 app 服务展开。

  • 默认只绑定本机端口，公网访问建议放在反向代理之后。
  • config.yaml 只读挂载，避免容器内配置漂移。
  • app_storage 和 app_data 必须持久化。
  • 可选文件处理服务接入同一个 deeix-chat-network。

docker-compose.yml

全量部署覆盖#

docker-compose.full.yml 会启动 PostgreSQL 和 Redis，并通过环境变量覆盖连接配置。这是有意设计，用来保证 app 容器连接 Compose 内部服务。

docker-compose.full.yml

生产使用全量部署时，至少替换 PostgreSQL 密码、Redis 密码、jwt_secret 和 data_encryption_key。

环境变量与上线检查#

环境变量适合容器平台、CI/CD 和密钥管理系统。推荐规则是：密钥可以用环境变量注入，稳定结构性配置写在 config.yaml，运行时业务配置放在后台管理。不要在多个位置维护同一个值。

如果必须覆盖，应明确记录覆盖来源。

常用覆盖变量#

领域常用环境变量对应配置
配置文件CONFIG_FILE配置文件路径
服务APP_ENV、HTTP_PORT、PUBLIC_API_BASE_URL、PUBLIC_WEB_BASE_URL、CORS_ALLOW_ORIGINapp.*、server.*
安全JWT_SECRET、DATA_ENCRYPTION_KEY、SSRF_PROTECTION_ENABLEDsecurity.*
数据库DATABASE_DRIVER、POSTGRES_DSN、SQLITE_PATHdatabase.*
缓存CACHE_DRIVER、REDIS_ADDR、REDIS_PASSWORD、REDIS_DBcache.*、database.redis.*
存储STORAGE_BACKEND、STORAGE_ROOT_DIR、STORAGE_S3_BUCKET、STORAGE_S3_SECRET_ACCESS_KEYstorage.*
观测OTEL_ENABLED、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_TRACES_SAMPLER_ARGobservability.tracing.*

生产检查清单#

  • 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 兼容存储，而不是每个实例各自 local storage。
  • Compose 中 PostgreSQL 和 Redis 默认密码已替换。
  • OpenTelemetry 已配置 Collector、采样率和日志关联策略后再开启。