用最少的变量先跑通一套可用环境，再根据真实使用规模切换数据库、缓存、存储和文件处理服务。第一次部署建议从轻量安装开始。
面向长期多人使用时，建议使用 PostgreSQL + Redis。

开始之前#

DEEIX Chat 的部署需要先明确三件事：服务运行在哪里、浏览器访问哪个公开地址、数据和文件保存在哪里。不要同时在多个地方维护同一个配置值。

如果使用环境变量覆盖 config.yaml，应当把覆盖来源记录清楚，方便后续排查。

git clone https://github.com/DEEIX-AI/DEEIX-Chat.gitcd DEEIX-Chat

选择部署路径#

五条路径覆盖从试用到生产、从一体化运行到前后端分离的常见场景。先选择路径，再复制对应模板，不建议把不同模板的字段混合使用。

1. 轻量安装#

轻量安装只启动 app 容器，数据写入 SQLite，向量索引使用 sqlite-vec，缓存使用进程内 memory cache。它是最快的体验路径，适合验证功能、演示和小型单节点使用。

如果后续需要多人长期使用，建议迁移到 PostgreSQL + Redis。

准备配置#

cp config.sqlite.example.yaml config.yaml

首次公开部署前，至少替换 security.jwt_secret、security.data_encryption_key、server.public_api_base_url、server.public_web_base_url 和 server.cors_allow_origin。安全密钥可以在 配置指南 中生成。

启动应用#

docker compose -f docker-compose.sqlite.yml up -d

默认镜像是 ghcr.io/deeix-ai/deeix-chat:latest。如果要使用本地镜像或测试当前源码构建，可以覆盖镜像名。

DEEIX_CHAT_IMAGE=deeix-chat:local docker compose -f docker-compose.sqlite.yml up -d --build

打开服务#

2. 标准部署#

标准部署只启动应用容器，适合已经具备 PostgreSQL、Redis、对象存储或平台级基础设施的环境。容器内访问外部服务时，数据库和 Redis 地址必须是容器可解析、可连接的地址。

如果服务运行在 Docker 宿主机上，通常使用 host.docker.internal。

准备配置#

cp config.example.yaml config.yaml

检查连接参数#

启动应用#

docker compose up -d

默认 docker-compose.yml 不会启动 PostgreSQL 或 Redis。除非明确需要覆盖 config.yaml，不要在 Compose 环境变量里重复维护同名配置，避免实际生效来源变得不清晰。

3. 全量部署#

全量部署会在同一台机器上启动 App、PostgreSQL 和 Redis。它比轻量安装更接近生产依赖结构，适合单机长期运行，也更方便后续迁移到独立数据库、独立 Redis 或云托管服务。

准备配置#

cp config.full.example.yaml config.yaml

公开部署前仍然要替换安全密钥、公开访问地址、CORS、可信代理、PostgreSQL 密码、Redis 密码和存储配置。

启动完整栈#

docker compose -f docker-compose.full.yml up -d

docker-compose.full.yml 会通过环境变量注入 POSTGRES_DSN、REDIS_ADDR 和 REDIS_PASSWORD。环境变量优先级高于 config.yaml，因此这些值会覆盖配置文件里的数据库和 Redis 连接项。

这是为了保证 app 容器连接 Compose 内部服务。

检查依赖状态#

docker compose -f docker-compose.full.yml psdocker compose -f docker-compose.full.yml logs postgresdocker compose -f docker-compose.full.yml logs redis

如果 app 启动失败，优先确认 PostgreSQL 是否完成初始化、Redis 密码是否一致、config.yaml 是否成功挂载，以及 Compose 环境变量是否覆盖了预期字段。

4. 分离部署#

当前端和后端分别暴露在不同公网地址时使用分离部署。例如 Web 是 https://chat.example.com，API 是 https://api.example.com。这种路径对构建变量、CORS、公开 URL 和 CDN 路由回退都有要求，建议先阅读 配置指南。

对齐公开地址#

构建前端#

cd frontendpnpm installNEXT_PUBLIC_API_BASE_URL=https://api.example.com pnpm build

发布 frontend/out 时，CDN 或静态服务器需要支持路由回退，例如 /chat 回退到 /chat/index.html。API、健康检查和 Swagger 路径应绕过 CDN 缓存，并完整转发请求头、请求体和响应状态码。

部署后检查#

curl https://api.example.com/healthzcurl https://chat.example.com

如果页面能打开但接口失败，通常是 NEXT_PUBLIC_API_BASE_URL、cors_allow_origin 或反向代理路径没有对齐。前端构建变量已经写入静态产物，修改后需要重新构建前端。

5. 本地开发#

本地开发适合修改源码、调试前后端和验证界面交互，不是最短试用路径。默认配置连接本机 PostgreSQL 和 Redis，请先确认依赖已启动。

后端#

cp config.example.yaml config.yamlcd backendmake run

后端默认监听 http://localhost:8080，Swagger 地址是 http://localhost:8080/swagger/index.html。

前端#

cd frontendpnpm installcp .env.example .env.localpnpm dev

本地前端通常把 API 指向后端开发服务。

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8080

启动后检查#

应用启动后先检查健康状态、容器状态、配置挂载和启动日志。下面以轻量安装为例。

标准部署去掉 -f docker-compose.sqlite.yml，全量部署替换为 -f docker-compose.full.yml。

curl http://localhost:8080/healthzdocker compose -f docker-compose.sqlite.yml psdocker compose -f docker-compose.sqlite.yml exec app ls -l /app/config.yamldocker compose -f docker-compose.sqlite.yml logs app

首次登录#

数据库中没有超级管理员时，后端会在首次启动时自动创建初始管理员，并且只在创建当次输出一次初始密码。不要把初始密码写入配置文件，也不要长期使用初始凭据。

可选文件处理服务#

基础部署不强制启动文档解析和 OCR 服务。只有在后台或配置中启用对应能力时，才需要启动这些可选服务。它们通常和文件提取、OCR、RAG 构建链路有关，建议先完成基础应用部署，再逐项接入。

docker compose -f docker/tika/docker-compose.yml up -ddocker compose -f docker/tesseract/docker-compose.yml up -d --builddocker compose -f docker/docling/docker-compose.yml up -d --build

这些服务会接入 deeix-chat-network。请先启动任一根目录部署，或手动创建网络。

docker network create deeix-chat-network

下一步#

登录后先完成运行时业务配置，再开放给真实用户使用。模型、上游、路由、价格、文件策略、RAG 和 MCP 工具属于后台管理，不建议写死在部署配置里。