打开 Demo
本文从一台干净机器开始，带你启动一个可以登录的 DEEIX Chat 实例。先用轻量安装跑通，再在面向真实用户前切换到 PostgreSQL + Redis。

开始之前#

项目要求
容器安装Docker Engine 与 Docker Compose v2
本地开发Node.js 20.9+、pnpm 10.17.0、Go 1.26.8，以及本机 PostgreSQL 和 Redis
配置文件deploy/config.yaml，从对应方案模板复制
安全密钥公开部署前必须替换 security.jwt_secret 和 security.data_encryption_key

terminal

选择安装方案#

Docker 部署资源都在 deploy/，可以只把这个目录拷到服务器，不需要应用源码。以下 compose 命令都在 deploy/ 目录内执行。

方案适合场景配置模板Compose 文件依赖
轻量安装本地试用、个人部署、小型单节点deploy/config.sqlite.example.yamldeploy/docker-compose.sqlite.yml仅应用容器，SQLite + sqlite-vec + 内存缓存
默认安装已有 PostgreSQL 和 Redisdeploy/config.example.yamldeploy/docker-compose.yml仅应用容器
全量安装单机运行应用、PostgreSQL 和 Redisdeploy/config.full.example.yamldeploy/docker-compose.full.yml应用、PostgreSQL、Redis

1. 轻量安装（SQLite）#

轻量方案只启动 app 容器，数据和向量索引使用 SQLite，缓存使用进程内 memory。适合验证功能或运行小型单节点实例。

terminal

打开服务：

服务地址
Web 应用http://localhost:8080
存活探针http://localhost:8080/healthz
就绪探针http://localhost:8080/readyz
版本接口http://localhost:8080/api/v1/version
Swaggerhttp://localhost:8080/swagger/index.html

模板里 app.env: dev，因此 Swagger 默认可用。公开部署前，把 app.env 改为 prod，替换两个密钥，并设置公开地址和 CORS 来源。

SQLite + memory cache 只支持单进程。多节点或高并发部署请使用 PostgreSQL + Redis。

使用本地镜像#

默认镜像是 ghcr.io/deeix-ai/deeix-chat:latest。先在仓库根目录构建本地镜像，再选择它：

terminal

2. 默认安装（外部 PostgreSQL + Redis）#

适合 PostgreSQL 和 Redis 已在 compose 之外管理的环境。把数据库和 Redis 地址改成容器可访问的地址。如果服务运行在 Docker 宿主机上，通常使用 host.docker.internal。

terminal

docker-compose.yml 只启动应用容器。除非明确需要覆盖 config.yaml，否则不要额外写同名 environment。

3. 全量安装（PostgreSQL + Redis 容器）#

适合在一台机器上同时启动应用、PostgreSQL 和 Redis。

terminal

docker-compose.full.yml 会在 app 容器里设置 POSTGRES_DSN、REDIS_ADDR、REDIS_USERNAME 和 REDIS_PASSWORD。这些环境变量会覆盖 config.yaml 里的同名配置，让应用连接 Compose 内置服务。

检查容器状态：

terminal

4. 本地开发#

本地开发在仓库中启动前端和后端。默认配置连接本机 PostgreSQL 和 Redis，请先启动这两个服务。

terminal

make dev 启动各工作区的开发任务。如果只想运行 API 和 Web 应用，可在两个终端分别执行 make api 和 make web。make help 列出全部目标。

服务地址
前端http://localhost:3000
APIhttp://localhost:8080
存活探针http://localhost:8080/healthz
就绪探针http://localhost:8080/readyz
版本接口http://localhost:8080/api/v1/version
Swaggerhttp://localhost:8080/swagger/index.html

确认 apps/web/.env.local 指向后端：

env

5. 分离部署#

当前端和 API 使用不同公网地址时使用分离部署，例如 https://chat.example.com 和 https://api.example.com。先对齐前端构建变量、后端公开地址和 CORS，上线前再阅读配置。

terminal

静态产物在 apps/web/out，可由 CDN 或静态服务托管，也可以把 server.frontend_dist_dir 指向它，让 Go 服务直接托管。

启动后检查#

terminal

检查项期望结果异常时优先看什么
存活探针返回 {"status":"ok",...}配置解析、端口占用
就绪探针返回就绪状态数据库和缓存连接
配置挂载/app/config.yaml 存在运行目录、挂载路径、文件权限
启动日志无迁移或初始化错误数据库版本、密钥长度、环境变量覆盖

首次登录#

数据库中没有超级管理员时，后端会在首次启动时创建一个，并且只输出一次密码。

项目说明
初始用户名admin
初始密码在后端启动日志中搜索 bootstrap superadmin created，读取 password 字段。
首次登录引导流程要求设置新的用户名和密码，并可开启 2FA。
引导完成后使用新凭据重新登录，然后进入管理后台。

引导流程包含以下步骤：

  1. 欢迎页和界面语言。
  2. 账户：设置新的管理员用户名和密码。
  3. 两步验证：绑定验证器，或跳过。
  4. 主题。
  5. 个性化：时区和颜色模式。
  6. 已就绪：如果开启了 2FA，先保存恢复码，然后重新登录。

如果数据库中已有超级管理员，服务不会重新创建或再次输出初始密码。凭据不通过 config.yaml 管理。

可选安装服务#

文档提取和 OCR 不是必需服务。只有在后台启用对应能力时才需要启动。这些服务接入外部网络 deeix-chat-network，请先启动任一应用方案，或手动创建网络：

terminal

在 deploy/ 目录内执行：

terminal

服务地址用途
Tikahttp://127.0.0.1:9998文档文本提取
Tesseract OCRhttp://127.0.0.1:8004/ocrOCR 服务
Doclinghttp://127.0.0.1:8005/ocr文档和 OCR 提取

deploy/services/rapidocr 提供 Dockerfile 和服务入口，但没有 compose 文件。

桌面端#

如果不打算部署服务器，桌面端内置了 Go 后端。从 GitHub Releases 安装后，首次启动选择在本机使用进入本地模式，或选择连接服务器指向已有部署。见桌面端。

下一步#

在邀请用户前，先到管理后台完成运行时业务配置。

配置项操作
上游与模型添加上游渠道、平台模型和路由绑定。
文件与检索确认存储、提取、OCR、Embedding 和检索设置。
登录与安全检查公开地址、CORS、可信代理、注册和 2FA。
计费选择计费方式，并配置价格、订阅、支付和 Webhook。
运维检查日志、审计事件、备份、GeoIP 和 OpenTelemetry。

相关#